man/man1/pcomb.1

.\" RCSid "$Id: pcomb.1,v 1.7 2006/09/08 21:38:25 greg Exp $"
.TH PCOMB 1 8/31/96 RADIANCE
.SH NAME
pcomb - combine RADIANCE pictures
.SH SYNOPSIS
.B pcomb
[
.B -h
][
.B -w
][
.B "\-x xres"
][
.B "\-y yres"
][
.B "\-f file"
][
.B "\-e expr"
]
[
[
.B -o
][
.B "\-s factor"
][
.B "\-c r g b"
]
.B "input .."
]
.SH DESCRIPTION
.I Pcomb
combines equal-sized RADIANCE pictures and sends the result to the
standard output.
By default, the result is just a linear combination of
the input pictures multiplied by
.I \-s
and
.I \-c
coefficients,
but an arbitrary mapping can be assigned with the
.I \-e
and
.I \-f
options.
Negative coefficients and functions are allowed, and
.I pcomb
will produce color values of zero where they would be negative.
.PP
The variables
.I ro,
.I go
and
.I bo
specify the red, green and blue output values, respectively.
Alternatively, the single variable
.I lo
can be used to specify a brightness value for black and white output.
The predefined functions
.I ri(n),
.I gi(n)
and
.I bi(n)
give the red, green and blue input values for
picture
.I n.
To access a pixel that is nearby the current one, these functions
also accept optional x and y offsets.
For example,
.I ri(3,-2,1)
would return the red component of the pixel from picture 3
that is left 2 and up 1 from the current position.
Although x offsets may be as large as width of the picture,
y offsets are limited to a small window (+/- 32 pixels) due to efficiency
considerations.
However, it is not usually necessary to worry about this problem --
if the requested offset is not available, the next best pixel is
returned instead.
.PP
For additional convenience, the function
.I li(n)
is defined as the input brightness for picture
.I n.
This function also accepts x and y offsets.
.PP
The constant
.I nfiles
gives the number of input files present,
and
.I WE
gives the white efficacy (lumens/brightness) for pixel values,
which may be used with the
.I \-o
option or the le(n) values to convert to absolute
photometric units (see below).
The variables
.I x
and
.I y
give the current output pixel location for use in
spatially dependent functions, the constants
.I xmax
and
.I ymax
give the input resolution, and the constants
.I xres
and 
.I yres
give the output resolution (usually the same, but see below).
The constant functions
.I "re(n), ge(n), be(n),"
and
.I le(n)
give the exposure values for picture
.I n,
and
.I pa(n)
gives the corresponding pixel aspect ratio.
Finally, for pictures with stored view parameters,
the functions
.I "Ox(n), Oy(n)"
and
.I Oz(n)
return the ray origin in world coordinates for the current pixel
in picture
.I n,
and
.I "Dx(n), Dy(n)"
and
.I Dz(n)
return the normalized ray direction.
In addition, the function
.I T(n)
returns the distance from the origin to the aft clipping plane
(or zero if there is no aft plane), and the function
.I S(n)
returns the solid angle of the current pixel in steradians
(always zero for parallel views).
If the current pixel is outside the view region,
.I T(n)
will return a negative value, and
.I S(n)
will return zero.
.PP
The
.I \-h
option may be used to reduce the information header size, which
can grow disproportionately after multiple runs of
.I pcomb
and/or
.I pcompos(1).
The
.I \-w
option can be used to suppress warning messages about invalid
calculations.
The
.I \-o
option indicates that original pixel values are to be used for the next
picture, undoing any previous exposure changes or color correction.
.PP
The
.I \-x
and
.I \-y
options can be used to specify the desired output resolution,
.I xres
and
.I yres,
and can be expressions involving other constants such as
.I xmax
and
.I ymax.
The constants
.I xres
and
.I yres
may also be specified in a file or expression.
The default output resolution is the same as the input resolution.
.PP
The
.I \-x
and
.I \-y
options must be present if there are no input files, when
the definitions of
.I ro,
.I go
and
.I bo
will be used to compute each output pixel.
This is useful for producing simple test pictures for various
purposes.
(Theoretically, one could write a complete renderer using just the
functional language...)
.PP
The standard input can be specified with a hyphen ('-').
A command that produces a RADIANCE picture can be given in place of a file 
by preceeding it with an exclamation point ('!').
.SH EXAMPLES
To produce a picture showing the difference between pic1 and pic2:
.IP "" .2i
pcomb \-e 'ro=ri(1)\-ri(2);go=gi(1)\-gi(2);bo=bi(1)\-bi(2)' pic1 pic2 > diff
.PP
Or, more efficiently:
.IP "" .2i
pcomb pic1 \-s \-1 pic2 > diff
.PP
To precompute the gamma correction for a picture:
.IP "" .2i
pcomb \-e 'ro=ri(1)^.4;go=gi(1)^.4;bo=bi(1)^.4' pic > pic.gam
.PP
To perform some special filtering:
.IP "" .2i
pcomb \-f myfilt.cal \-x xmax/2 \-y ymax/2 input.pic > filtered.pic
.PP
To make a picture of a dot:
.IP "" .2i
pcomb \-x 100 \-y 100 \-e 'ro=b;go=b;bo=b;b=if((x-50)^2+(y-50)^2\-25^2,0,1)' > dot
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), icalc(1), pcompos(1), pfilt(1), rpict(1)
Revision:	1.8
Committed:	Tue Sep 4 17:36:40 2007 UTC (16 years, 8 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R9
Changes since 1.7:	+6 -6 lines
Log Message:	Added backslashes in front of hyphens (thanks to Bernd Zeimetz for his effort)
#	User	Rev	Content
1	greg	1.8	.\" RCSid "$Id: pcomb.1,v 1.7 2006/09/08 21:38:25 greg Exp $"
2	greg	1.1	.TH PCOMB 1 8/31/96 RADIANCE
3			.SH NAME
4	greg	1.2	pcomb - combine RADIANCE pictures
5	greg	1.1	.SH SYNOPSIS
6			.B pcomb
7			[
8	greg	1.7	.B -h
9			][
10	greg	1.1	.B -w
11			][
12			.B "\-x xres"
13			][
14			.B "\-y yres"
15			][
16			.B "\-f file"
17			][
18			.B "\-e expr"
19			]
20			[
21			[
22			.B -o
23			][
24			.B "\-s factor"
25			][
26			.B "\-c r g b"
27			]
28			.B "input .."
29			]
30			.SH DESCRIPTION
31			.I Pcomb
32			combines equal-sized RADIANCE pictures and sends the result to the
33			standard output.
34			By default, the result is just a linear combination of
35			the input pictures multiplied by
36			.I \-s
37			and
38			.I \-c
39			coefficients,
40			but an arbitrary mapping can be assigned with the
41			.I \-e
42			and
43			.I \-f
44			options.
45			Negative coefficients and functions are allowed, and
46			.I pcomb
47			will produce color values of zero where they would be negative.
48			.PP
49			The variables
50			.I ro,
51			.I go
52			and
53			.I bo
54			specify the red, green and blue output values, respectively.
55			Alternatively, the single variable
56			.I lo
57			can be used to specify a brightness value for black and white output.
58			The predefined functions
59			.I ri(n),
60			.I gi(n)
61			and
62			.I bi(n)
63			give the red, green and blue input values for
64			picture
65			.I n.
66			To access a pixel that is nearby the current one, these functions
67			also accept optional x and y offsets.
68			For example,
69			.I ri(3,-2,1)
70			would return the red component of the pixel from picture 3
71			that is left 2 and up 1 from the current position.
72			Although x offsets may be as large as width of the picture,
73	greg	1.6	y offsets are limited to a small window (+/- 32 pixels) due to efficiency
74	greg	1.1	considerations.
75			However, it is not usually necessary to worry about this problem --
76			if the requested offset is not available, the next best pixel is
77			returned instead.
78			.PP
79			For additional convenience, the function
80			.I li(n)
81			is defined as the input brightness for picture
82			.I n.
83			This function also accepts x and y offsets.
84			.PP
85			The constant
86			.I nfiles
87			gives the number of input files present,
88			and
89			.I WE
90	greg	1.3	gives the white efficacy (lumens/brightness) for pixel values,
91			which may be used with the
92			.I \-o
93			option or the le(n) values to convert to absolute
94			photometric units (see below).
95	greg	1.1	The variables
96			.I x
97			and
98			.I y
99			give the current output pixel location for use in
100			spatially dependent functions, the constants
101			.I xmax
102			and
103			.I ymax
104			give the input resolution, and the constants
105			.I xres
106			and
107			.I yres
108			give the output resolution (usually the same, but see below).
109			The constant functions
110			.I "re(n), ge(n), be(n),"
111			and
112			.I le(n)
113			give the exposure values for picture
114			.I n,
115			and
116			.I pa(n)
117			gives the corresponding pixel aspect ratio.
118			Finally, for pictures with stored view parameters,
119			the functions
120			.I "Ox(n), Oy(n)"
121			and
122			.I Oz(n)
123			return the ray origin in world coordinates for the current pixel
124			in picture
125			.I n,
126			and
127			.I "Dx(n), Dy(n)"
128			and
129			.I Dz(n)
130			return the normalized ray direction.
131			In addition, the function
132			.I T(n)
133			returns the distance from the origin to the aft clipping plane
134			(or zero if there is no aft plane), and the function
135			.I S(n)
136			returns the solid angle of the current pixel in steradians
137			(always zero for parallel views).
138			If the current pixel is outside the view region,
139			.I T(n)
140			will return a negative value, and
141			.I S(n)
142			will return zero.
143			.PP
144			The
145	greg	1.7	.I \-h
146			option may be used to reduce the information header size, which
147			can grow disproportionately after multiple runs of
148			.I pcomb
149			and/or
150			.I pcompos(1).
151			The
152	greg	1.1	.I \-w
153			option can be used to suppress warning messages about invalid
154			calculations.
155			The
156			.I \-o
157			option indicates that original pixel values are to be used for the next
158			picture, undoing any previous exposure changes or color correction.
159			.PP
160			The
161			.I \-x
162			and
163			.I \-y
164			options can be used to specify the desired output resolution,
165			.I xres
166			and
167			.I yres,
168			and can be expressions involving other constants such as
169			.I xmax
170			and
171			.I ymax.
172			The constants
173			.I xres
174			and
175			.I yres
176			may also be specified in a file or expression.
177			The default output resolution is the same as the input resolution.
178			.PP
179			The
180			.I \-x
181			and
182			.I \-y
183			options must be present if there are no input files, when
184			the definitions of
185			.I ro,
186			.I go
187			and
188			.I bo
189			will be used to compute each output pixel.
190			This is useful for producing simple test pictures for various
191			purposes.
192			(Theoretically, one could write a complete renderer using just the
193			functional language...)
194			.PP
195			The standard input can be specified with a hyphen ('-').
196			A command that produces a RADIANCE picture can be given in place of a file
197			by preceeding it with an exclamation point ('!').
198			.SH EXAMPLES
199			To produce a picture showing the difference between pic1 and pic2:
200			.IP "" .2i
201	greg	1.8	pcomb \-e 'ro=ri(1)\-ri(2);go=gi(1)\-gi(2);bo=bi(1)\-bi(2)' pic1 pic2 > diff
202	greg	1.1	.PP
203			Or, more efficiently:
204			.IP "" .2i
205	greg	1.8	pcomb pic1 \-s \-1 pic2 > diff
206	greg	1.1	.PP
207			To precompute the gamma correction for a picture:
208			.IP "" .2i
209	greg	1.8	pcomb \-e 'ro=ri(1)^.4;go=gi(1)^.4;bo=bi(1)^.4' pic > pic.gam
210	greg	1.1	.PP
211			To perform some special filtering:
212			.IP "" .2i
213	greg	1.8	pcomb \-f myfilt.cal \-x xmax/2 \-y ymax/2 input.pic > filtered.pic
214	greg	1.1	.PP
215			To make a picture of a dot:
216			.IP "" .2i
217	greg	1.8	pcomb \-x 100 \-y 100 \-e 'ro=b;go=b;bo=b;b=if((x-50)^2+(y-50)^2\-25^2,0,1)' > dot
218	greg	1.1	.SH AUTHOR
219			Greg Ward
220			.SH "SEE ALSO"
221	greg	1.5	getinfo(1), icalc(1), pcompos(1), pfilt(1), rpict(1)