man/man1/pcomb.1

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