man/man1/pcomb.1

.\" RCSid "$Id: pcomb.1,v 1.5 2004/01/01 19:31:45 greg Exp $"
.TH PCOMB 1 8/31/96 RADIANCE
.SH NAME
pcomb - combine RADIANCE pictures
.SH SYNOPSIS
.B pcomb
[
.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.
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.
.PP
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' pic > pic.gam
.PP
To perform some special filtering:
.IP "" .2i
pcomb -f myfilt.cal -x xmax/2 -y ymax/2 input.pic > filtered.pic
.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 AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), icalc(1), pcompos(1), pfilt(1), rpict(1)
Revision:	1.6
Committed:	Tue Mar 1 22:55:21 2005 UTC (19 years, 2 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R7P2, rad3R7P1
Changes since 1.5:	+2 -2 lines
Log Message:	Updated pixel window size to match with code
#	Content
1	.\" RCSid "$Id: pcomb.1,v 1.5 2004/01/01 19:31:45 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 -w
9	][
10	.B "\-x xres"
11	][
12	.B "\-y yres"
13	][
14	.B "\-f file"
15	][
16	.B "\-e expr"
17	]
18	[
19	[
20	.B -o
21	][
22	.B "\-s factor"
23	][
24	.B "\-c r g b"
25	]
26	.B "input .."
27	]
28	.SH DESCRIPTION
29	.I Pcomb
30	combines equal-sized RADIANCE pictures and sends the result to the
31	standard output.
32	By default, the result is just a linear combination of
33	the input pictures multiplied by
34	.I \-s
35	and
36	.I \-c
37	coefficients,
38	but an arbitrary mapping can be assigned with the
39	.I \-e
40	and
41	.I \-f
42	options.
43	Negative coefficients and functions are allowed, and
44	.I pcomb
45	will produce color values of zero where they would be negative.
46	.PP
47	The variables
48	.I ro,
49	.I go
50	and
51	.I bo
52	specify the red, green and blue output values, respectively.
53	Alternatively, the single variable
54	.I lo
55	can be used to specify a brightness value for black and white output.
56	The predefined functions
57	.I ri(n),
58	.I gi(n)
59	and
60	.I bi(n)
61	give the red, green and blue input values for
62	picture
63	.I n.
64	To access a pixel that is nearby the current one, these functions
65	also accept optional x and y offsets.
66	For example,
67	.I ri(3,-2,1)
68	would return the red component of the pixel from picture 3
69	that is left 2 and up 1 from the current position.
70	Although x offsets may be as large as width of the picture,
71	y offsets are limited to a small window (+/- 32 pixels) due to efficiency
72	considerations.
73	However, it is not usually necessary to worry about this problem --
74	if the requested offset is not available, the next best pixel is
75	returned instead.
76	.PP
77	For additional convenience, the function
78	.I li(n)
79	is defined as the input brightness for picture
80	.I n.
81	This function also accepts x and y offsets.
82	.PP
83	The constant
84	.I nfiles
85	gives the number of input files present,
86	and
87	.I WE
88	gives the white efficacy (lumens/brightness) for pixel values,
89	which may be used with the
90	.I \-o
91	option or the le(n) values to convert to absolute
92	photometric units (see below).
93	The variables
94	.I x
95	and
96	.I y
97	give the current output pixel location for use in
98	spatially dependent functions, the constants
99	.I xmax
100	and
101	.I ymax
102	give the input resolution, and the constants
103	.I xres
104	and
105	.I yres
106	give the output resolution (usually the same, but see below).
107	The constant functions
108	.I "re(n), ge(n), be(n),"
109	and
110	.I le(n)
111	give the exposure values for picture
112	.I n,
113	and
114	.I pa(n)
115	gives the corresponding pixel aspect ratio.
116	Finally, for pictures with stored view parameters,
117	the functions
118	.I "Ox(n), Oy(n)"
119	and
120	.I Oz(n)
121	return the ray origin in world coordinates for the current pixel
122	in picture
123	.I n,
124	and
125	.I "Dx(n), Dy(n)"
126	and
127	.I Dz(n)
128	return the normalized ray direction.
129	In addition, the function
130	.I T(n)
131	returns the distance from the origin to the aft clipping plane
132	(or zero if there is no aft plane), and the function
133	.I S(n)
134	returns the solid angle of the current pixel in steradians
135	(always zero for parallel views).
136	If the current pixel is outside the view region,
137	.I T(n)
138	will return a negative value, and
139	.I S(n)
140	will return zero.
141	.PP
142	The
143	.I \-w
144	option can be used to suppress warning messages about invalid
145	calculations.
146	The
147	.I \-o
148	option indicates that original pixel values are to be used for the next
149	picture, undoing any previous exposure changes or color correction.
150	.PP
151	The
152	.I \-x
153	and
154	.I \-y
155	options can be used to specify the desired output resolution,
156	.I xres
157	and
158	.I yres,
159	and can be expressions involving other constants such as
160	.I xmax
161	and
162	.I ymax.
163	The constants
164	.I xres
165	and
166	.I yres
167	may also be specified in a file or expression.
168	The default output resolution is the same as the input resolution.
169	.PP
170	The
171	.I \-x
172	and
173	.I \-y
174	options must be present if there are no input files, when
175	the definitions of
176	.I ro,
177	.I go
178	and
179	.I bo
180	will be used to compute each output pixel.
181	This is useful for producing simple test pictures for various
182	purposes.
183	(Theoretically, one could write a complete renderer using just the
184	functional language...)
185	.PP
186	The standard input can be specified with a hyphen ('-').
187	A command that produces a RADIANCE picture can be given in place of a file
188	by preceeding it with an exclamation point ('!').
189	.SH EXAMPLES
190	To produce a picture showing the difference between pic1 and pic2:
191	.IP "" .2i
192	pcomb -e 'ro=ri(1)-ri(2);go=gi(1)-gi(2);bo=bi(1)-bi(2)' pic1 pic2 > diff
193	.PP
194	Or, more efficiently:
195	.IP "" .2i
196	pcomb pic1 -s -1 pic2 > diff
197	.PP
198	To precompute the gamma correction for a picture:
199	.IP "" .2i
200	pcomb -e 'ro=ri(1)^.4;go=gi(1)^.4;bo=bi(1)^.4' pic > pic.gam
201	.PP
202	To perform some special filtering:
203	.IP "" .2i
204	pcomb -f myfilt.cal -x xmax/2 -y ymax/2 input.pic > filtered.pic
205	.PP
206	To make a picture of a dot:
207	.IP "" .2i
208	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
209	.SH AUTHOR
210	Greg Ward
211	.SH "SEE ALSO"
212	getinfo(1), icalc(1), pcompos(1), pfilt(1), rpict(1)