man/man1/pcomb.1

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