man/man1/rhpict.1

.\" RCSid "$Id: rhpict.1,v 1.5 2008/03/11 02:21:45 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.hdr
.PP
rpict \-S 1 \-o frame%02d.hdr 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.6
Committed:	Mon Nov 10 19:08:17 2008 UTC (16 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad5R2, rad5R3, rad5R0, rad5R1, rad4R2, rad6R0, rad4R1, rad4R0, rad4R2P1, rad4R2P2, HEAD
Changes since 1.5:	+3 -3 lines
Log Message:	Changed ".pic" extension to ".hdr" throughout
#	User	Rev	Content
1	greg	1.6	.\" RCSid "$Id: rhpict.1,v 1.5 2008/03/11 02:21:45 greg Exp $"
2	greg	1.1	.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	greg	1.5	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	greg	1.1	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	greg	1.5	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	greg	1.1	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	greg	1.4	A value of \-1 would be to the left.
175	greg	1.1	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	greg	1.3	which may be a picture or a file created by rvu (with the "view" command).
189	greg	1.1	.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	greg	1.6	rhpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.hdk > scene.hdr
225	greg	1.1	.PP
226	greg	1.6	rpict \-S 1 \-o frame%02d.hdr scene.hdk < keyframes.vf
227	greg	1.1	.SH AUTHOR
228			Greg Ward
229			.SH "SEE ALSO"
230			getinfo(1), pfilt(1), pinterp(1),
231	greg	1.3	printf(3), ra_rgbe(1), rholo(1), rpict(1), rvu(1)