man/man1/pcomb.1

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