man/man1/rhpict.1

.\" RCSid "$Id: rhpict.1,v 1.4 2007/09/04 17:36:41 greg Exp $"
.TH RHPICT 1 3/10/99 RADIANCE
.SH NAME
rhpict - render a RADIANCE picture from a holodeck file
.SH SYNOPSIS
.B rhpict
[
.B options
]
.B holodeck
.SH DESCRIPTION
.I Rhpict
generates one or more pictures from the RADIANCE holodeck file
.I holodeck
and sends them to the standard output.
The
.I \-o
option may be used to specify an alternate output file.
Other options specify the viewing parameters and provide
some control over the calculation.
.PP
The view as well as some of the other controls
are shared in common with the
.I rpict(1)
command.
The options that are unique to
.I rhpict
are given first, followed by the more familiar ones.
.TP 10n
.BI -s
Use the smooth resampling algorithm, which amounts to linear interpolation
between ray samples with additional edge detection along color and object
boundaries.
This is the default.
.TP
.BI -r \ rf
Use random resampling, where
.I rf
is a fraction from 0 to 1 indicating the desired degree of randomness.
A random fraction of 0 is not the same as smooth resampling,
because there is no linear interpolation, just Voronoi regions.
Values greater than 1 produce interesting underwater effects.
.TP
.BI -x \ res
Set the maximum x resolution to
.I res.
.TP
.BI -y \ res
Set the maximum y resolution to
.I res.
.TP
.BI -pa \ rat
Set the pixel aspect ratio (height over width) to
.I rat.
Either the x or the y resolution will be reduced so that the pixels have
this ratio for the specified view.
If
.I rat
is zero, then the x and y resolutions will adhere to the given maxima.
.TP
.BI -pe \ expval
Set the exposure value for the output pictures to
.I expval.
Since filtering is performed by
.I rhpict,
there is little sense in passing the output through
.I pfilt(1),
other than changing the exposure.
This option eliminates that need.
The value may be specified either as a multiplier, or as a number
f-stops preceeded by a '+' or '-' character.
.TP
.BI -vt t
Set view type to
.I t.
If
.I t
is 'v', a perspective view is selected.
If
.I t
is 'l', a parallel view is used.
A cylindrical panorma may be selected by setting
.I t
to the letter 'c'.
This view is like a standard perspective vertically, but projected
on a cylinder horizontally (like a soupcan's-eye view).
Three fisheye views are provided as well; 'h' yields a hemispherical fisheye
view, 'a' results in angular fisheye distortion, and 's'
results in a planisphere (stereographic) projection.
A hemispherical fisheye is a projection of the hemisphere onto a circle.
The maximum view angle for this type is 180 degrees.
An angular fisheye view is defined such that distance from the center of
the image is proportional to the angle from the central view direction.
An angular fisheye can display a full 360 degrees.
A planisphere fisheye view maintains angular relationships between lines,
and is commonly used for sun path analysis.
This is more commonly known as a
"stereographic projection," but we avoid the term here so as not to
confuse it with a stereoscopic pair.
A planisphere fisheye can display up to (but not including) 360 degrees,
although distortion becomes extreme as this limit is approached.
Note that there is no space between the view type
option and its single letter argument.
.TP
.BI -vp " x y z"
Set the view point to
.I "x y z".
This is the focal point of a perspective view or the
center of a parallel projection.
.TP
.BI -vd " xd yd zd"
Set the view direction vector to
.I "xd yd zd".
.TP
.BI -vu " xd yd zd"
Set the view up vector (vertical direction) to
.I "xd yd zd".
.TP
.BI -vh \ val
Set the view horizontal size to
.I val.
For a perspective projection (including fisheye views),
.I val
is the horizontal field of view (in degrees).
For a parallel projection,
.I val
is the view width in world coordinates.
.TP
.BI -vv \ val
Set the view vertical size to
.I val.
.TP
.BI -vo \ val
Set the view fore clipping plane at a distance of
.I val
from the view point.
The plane will be perpendicular to the view direction for
perspective and parallel view types.
For fisheye view types, the clipping plane is actually a clipping
sphere, centered on the view point with radius
.I val.
Objects in front of this imaginary surface will not be visible.
This may be useful for seeing through walls (to get a longer
perspective from an exterior view point) or for incremental
rendering.
A value of zero implies no foreground clipping.
A negative value produces some interesting effects, since it creates an
inverted image for objects behind the viewpoint.
This possibility is provided mostly for the purpose of rendering
stereographic holograms.
.TP
.BI -va \ val
Set the view aft clipping plane at a distance of
.I val
from the view point.
Like the view fore plane, it will be perpendicular to the view
direction for perspective and parallel view types.
For fisheye view types, the clipping plane is actually a clipping
sphere, centered on the view point with radius
.I val.
Objects behind this imaginary surface will not be visible.
A value of zero means no aft clipping, and is the only way to see
infinitely distant objects such as the sky.
.TP
.BI -vs \ val
Set the view shift to
.I val.
This is the amount the actual image will be shifted to the right of
the specified view.
This is option is useful for generating skewed perspectives or
rendering an image a piece at a time.
A value of 1 means that the rendered image starts just to the right of
the normal view.
A value of \-1 would be to the left.
Larger or fractional values are permitted as well.
.TP
.BI -vl \ val
Set the view lift to
.I val.
This is the amount the actual image will be lifted up from the
specified view, similar to the
.I \-vs
option.
.TP
.BI -vf \ file
Get view parameters from
.I file,
which may be a picture or a file created by rvu (with the "view" command).
.TP
.BI -S \ seqstart
Instead of generating a single picture based only on the view
parameters given on the command line, this option causes
.I rhpict
to read view options from the standard input and for each line
containing a valid view specification, generate a corresponding
picture.
.I Seqstart
is a positive integer that will be associated with the first output
frame, and incremented for successive output frames.
By default, each frame is concatenated to the output stream, but it
is possible to change this action using the
.I \-o
option (described below).
Multiple frames may be later extracted from a single output stream using the
.I ra_rgbe(1)
command.
.TP
.BI -o \ fspec
Send the picture(s) to the file(s) given by
.I fspec
instead of the standard output.
If this option is used in combination with
.I \-S
and
.I fspec
contains an integer field for
.I printf(3)
(eg., "%03d") then the actual output file name will include
the current frame number.
.TP
.BR \-w
Turn off warning messages.
.SH EXAMPLE
rhpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.hdk > scene.pic
.PP
rpict \-S 1 \-o frame%02d.pic scene.hdk < keyframes.vf
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), pfilt(1), pinterp(1),
printf(3), ra_rgbe(1), rholo(1), rpict(1), rvu(1)
Revision:	1.5
Committed:	Tue Mar 11 02:21:45 2008 UTC (16 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad3R9
Changes since 1.4:	+11 -3 lines
Log Message:	Added planisphere view type (-vts option) as requested by Axel Jacobs
#	Content
1	.\" RCSid "$Id: rhpict.1,v 1.4 2007/09/04 17:36:41 greg Exp $"
2	.TH RHPICT 1 3/10/99 RADIANCE
3	.SH NAME
4	rhpict - render a RADIANCE picture from a holodeck file
5	.SH SYNOPSIS
6	.B rhpict
7	[
8	.B options
9	]
10	.B holodeck
11	.SH DESCRIPTION
12	.I Rhpict
13	generates one or more pictures from the RADIANCE holodeck file
14	.I holodeck
15	and sends them to the standard output.
16	The
17	.I \-o
18	option may be used to specify an alternate output file.
19	Other options specify the viewing parameters and provide
20	some control over the calculation.
21	.PP
22	The view as well as some of the other controls
23	are shared in common with the
24	.I rpict(1)
25	command.
26	The options that are unique to
27	.I rhpict
28	are given first, followed by the more familiar ones.
29	.TP 10n
30	.BI -s
31	Use the smooth resampling algorithm, which amounts to linear interpolation
32	between ray samples with additional edge detection along color and object
33	boundaries.
34	This is the default.
35	.TP
36	.BI -r \ rf
37	Use random resampling, where
38	.I rf
39	is a fraction from 0 to 1 indicating the desired degree of randomness.
40	A random fraction of 0 is not the same as smooth resampling,
41	because there is no linear interpolation, just Voronoi regions.
42	Values greater than 1 produce interesting underwater effects.
43	.TP
44	.BI -x \ res
45	Set the maximum x resolution to
46	.I res.
47	.TP
48	.BI -y \ res
49	Set the maximum y resolution to
50	.I res.
51	.TP
52	.BI -pa \ rat
53	Set the pixel aspect ratio (height over width) to
54	.I rat.
55	Either the x or the y resolution will be reduced so that the pixels have
56	this ratio for the specified view.
57	If
58	.I rat
59	is zero, then the x and y resolutions will adhere to the given maxima.
60	.TP
61	.BI -pe \ expval
62	Set the exposure value for the output pictures to
63	.I expval.
64	Since filtering is performed by
65	.I rhpict,
66	there is little sense in passing the output through
67	.I pfilt(1),
68	other than changing the exposure.
69	This option eliminates that need.
70	The value may be specified either as a multiplier, or as a number
71	f-stops preceeded by a '+' or '-' character.
72	.TP
73	.BI -vt t
74	Set view type to
75	.I t.
76	If
77	.I t
78	is 'v', a perspective view is selected.
79	If
80	.I t
81	is 'l', a parallel view is used.
82	A cylindrical panorma may be selected by setting
83	.I t
84	to the letter 'c'.
85	This view is like a standard perspective vertically, but projected
86	on a cylinder horizontally (like a soupcan's-eye view).
87	Three fisheye views are provided as well; 'h' yields a hemispherical fisheye
88	view, 'a' results in angular fisheye distortion, and 's'
89	results in a planisphere (stereographic) projection.
90	A hemispherical fisheye is a projection of the hemisphere onto a circle.
91	The maximum view angle for this type is 180 degrees.
92	An angular fisheye view is defined such that distance from the center of
93	the image is proportional to the angle from the central view direction.
94	An angular fisheye can display a full 360 degrees.
95	A planisphere fisheye view maintains angular relationships between lines,
96	and is commonly used for sun path analysis.
97	This is more commonly known as a
98	"stereographic projection," but we avoid the term here so as not to
99	confuse it with a stereoscopic pair.
100	A planisphere fisheye can display up to (but not including) 360 degrees,
101	although distortion becomes extreme as this limit is approached.
102	Note that there is no space between the view type
103	option and its single letter argument.
104	.TP
105	.BI -vp " x y z"
106	Set the view point to
107	.I "x y z".
108	This is the focal point of a perspective view or the
109	center of a parallel projection.
110	.TP
111	.BI -vd " xd yd zd"
112	Set the view direction vector to
113	.I "xd yd zd".
114	.TP
115	.BI -vu " xd yd zd"
116	Set the view up vector (vertical direction) to
117	.I "xd yd zd".
118	.TP
119	.BI -vh \ val
120	Set the view horizontal size to
121	.I val.
122	For a perspective projection (including fisheye views),
123	.I val
124	is the horizontal field of view (in degrees).
125	For a parallel projection,
126	.I val
127	is the view width in world coordinates.
128	.TP
129	.BI -vv \ val
130	Set the view vertical size to
131	.I val.
132	.TP
133	.BI -vo \ val
134	Set the view fore clipping plane at a distance of
135	.I val
136	from the view point.
137	The plane will be perpendicular to the view direction for
138	perspective and parallel view types.
139	For fisheye view types, the clipping plane is actually a clipping
140	sphere, centered on the view point with radius
141	.I val.
142	Objects in front of this imaginary surface will not be visible.
143	This may be useful for seeing through walls (to get a longer
144	perspective from an exterior view point) or for incremental
145	rendering.
146	A value of zero implies no foreground clipping.
147	A negative value produces some interesting effects, since it creates an
148	inverted image for objects behind the viewpoint.
149	This possibility is provided mostly for the purpose of rendering
150	stereographic holograms.
151	.TP
152	.BI -va \ val
153	Set the view aft clipping plane at a distance of
154	.I val
155	from the view point.
156	Like the view fore plane, it will be perpendicular to the view
157	direction for perspective and parallel view types.
158	For fisheye view types, the clipping plane is actually a clipping
159	sphere, centered on the view point with radius
160	.I val.
161	Objects behind this imaginary surface will not be visible.
162	A value of zero means no aft clipping, and is the only way to see
163	infinitely distant objects such as the sky.
164	.TP
165	.BI -vs \ val
166	Set the view shift to
167	.I val.
168	This is the amount the actual image will be shifted to the right of
169	the specified view.
170	This is option is useful for generating skewed perspectives or
171	rendering an image a piece at a time.
172	A value of 1 means that the rendered image starts just to the right of
173	the normal view.
174	A value of \-1 would be to the left.
175	Larger or fractional values are permitted as well.
176	.TP
177	.BI -vl \ val
178	Set the view lift to
179	.I val.
180	This is the amount the actual image will be lifted up from the
181	specified view, similar to the
182	.I \-vs
183	option.
184	.TP
185	.BI -vf \ file
186	Get view parameters from
187	.I file,
188	which may be a picture or a file created by rvu (with the "view" command).
189	.TP
190	.BI -S \ seqstart
191	Instead of generating a single picture based only on the view
192	parameters given on the command line, this option causes
193	.I rhpict
194	to read view options from the standard input and for each line
195	containing a valid view specification, generate a corresponding
196	picture.
197	.I Seqstart
198	is a positive integer that will be associated with the first output
199	frame, and incremented for successive output frames.
200	By default, each frame is concatenated to the output stream, but it
201	is possible to change this action using the
202	.I \-o
203	option (described below).
204	Multiple frames may be later extracted from a single output stream using the
205	.I ra_rgbe(1)
206	command.
207	.TP
208	.BI -o \ fspec
209	Send the picture(s) to the file(s) given by
210	.I fspec
211	instead of the standard output.
212	If this option is used in combination with
213	.I \-S
214	and
215	.I fspec
216	contains an integer field for
217	.I printf(3)
218	(eg., "%03d") then the actual output file name will include
219	the current frame number.
220	.TP
221	.BR \-w
222	Turn off warning messages.
223	.SH EXAMPLE
224	rhpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.hdk > scene.pic
225	.PP
226	rpict \-S 1 \-o frame%02d.pic scene.hdk < keyframes.vf
227	.SH AUTHOR
228	Greg Ward
229	.SH "SEE ALSO"
230	getinfo(1), pfilt(1), pinterp(1),
231	printf(3), ra_rgbe(1), rholo(1), rpict(1), rvu(1)