man/man1/pcomb.1

.\" RCSid "$Id: pcomb.1,v 1.14 2023/12/06 17:56:57 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
.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.15
Committed:	Sat Dec 9 23:46:50 2023 UTC (5 months, 3 weeks ago) by greg
Branch:	MAIN
Changes since 1.14:	+25 -19 lines
Log Message:	feat(pcomb): Added support for 1- and 3-component float matrix i/o
#	Content
1	.\" RCSid "$Id: pcomb.1,v 1.14 2023/12/06 17:56:57 greg Exp $"
2	.TH PCOMB 1 8/31/96 RADIANCE
3	.SH NAME
4	pcomb - combine RADIANCE pictures and/or float matrices
5	.SH SYNOPSIS
6	.B pcomb
7	[
8	.B -h
9	][
10	.B -w
11	][
12	.B -ff
13	][
14	.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	combines equal-sized RADIANCE pictures or raw float matrices
35	and sends the result to the standard output.
36	By default, the result is just a linear combination of
37	the input pixels multiplied by
38	.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	options, similar to
47	.I rcalc(1).
48	(The variable and function definitions in each
49	.I \-f source
50	file are read and compiled from the RADIANCE library
51	where it is found.)\0
52	Negative coefficients and functions are allowed, and
53	.I pcomb
54	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	.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	give the red, green and blue values for
74	input
75	.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	would return the red component of the pixel from input 3
81	that is left 2 and up 1 from the current position.
82	Although x offsets may be as large as width of the input,
83	y offsets are limited to a small window (+/- 32 pixels) due to efficiency
84	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	is defined as the input brightness for input
92	.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	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	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	give the exposure values for input
124	.I n,
125	and
126	.I pa(n)
127	gives the corresponding pixel aspect ratio.
128	Exposure values will be set to 1.0 for inputs with the
129	.I \-o
130	option set.
131	Finally, for inputs with stored view parameters,
132	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	in input
138	.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	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	.PP
159	The
160	.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	.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	input, undoing any previous exposure changes or color correction.
174	.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	This is useful for producing simple test inputs for various
206	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	A command that produces a RADIANCE picture or float matrix
212	can be given in place of a file
213	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	pcomb \-e 'ro=ri(1)\-ri(2);go=gi(1)\-gi(2);bo=bi(1)\-bi(2)' pic1 pic2 > diff
218	.PP
219	Or, more efficiently:
220	.IP "" .2i
221	pcomb pic1 \-s \-1 pic2 > diff
222	.PP
223	To precompute the gamma correction for a picture:
224	.IP "" .2i
225	pcomb \-e 'ro=ri(1)^.4;go=gi(1)^.4;bo=bi(1)^.4' inp.hdr > gam.hdr
226	.PP
227	To perform some special filtering:
228	.IP "" .2i
229	pcomb \-f myfilt.cal \-x xmax/2 \-y ymax/2 input.hdr > filtered.hdr
230	.PP
231	To make a picture of a dot:
232	.IP "" .2i
233	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	.SH ENVIRONMENT
235	RAYPATH the directories to check for auxiliary files.
236	.SH AUTHOR
237	Greg Ward
238	.SH "SEE ALSO"
239	getinfo(1), icalc(1), pcompos(1), pfilt(1), rcalc(1),
240	rmtxcomb(1), rmtxop(1), rpict(1)