man/man1/pcomb.1

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