man/man1/pcomb.1

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