man/man1/rhpict.1

.\" RCSid "$Id"
.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).
Two fisheye views are provided as well; 'h' yields a hemispherical fisheye
view and 'a' results in angular fisheye distortion.
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.
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 rview (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), rview(1)
Revision:	1.1
Committed:	Tue Mar 11 19:20:21 2003 UTC (21 years, 2 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R5
Log Message:	Added documentation to repository
#	User	Rev	Content
1	greg	1.1	.\" RCSid "$Id"
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			Two fisheye views are provided as well; 'h' yields a hemispherical fisheye
88			view and 'a' results in angular fisheye distortion.
89			A hemispherical fisheye is a projection of the hemisphere onto a circle.
90			The maximum view angle for this type is 180 degrees.
91			An angular fisheye view is defined such that distance from the center of
92			the image is proportional to the angle from the central view direction.
93			An angular fisheye can display a full 360 degrees.
94			Note that there is no space between the view type
95			option and its single letter argument.
96			.TP
97			.BI -vp " x y z"
98			Set the view point to
99			.I "x y z".
100			This is the focal point of a perspective view or the
101			center of a parallel projection.
102			.TP
103			.BI -vd " xd yd zd"
104			Set the view direction vector to
105			.I "xd yd zd".
106			.TP
107			.BI -vu " xd yd zd"
108			Set the view up vector (vertical direction) to
109			.I "xd yd zd".
110			.TP
111			.BI -vh \ val
112			Set the view horizontal size to
113			.I val.
114			For a perspective projection (including fisheye views),
115			.I val
116			is the horizontal field of view (in degrees).
117			For a parallel projection,
118			.I val
119			is the view width in world coordinates.
120			.TP
121			.BI -vv \ val
122			Set the view vertical size to
123			.I val.
124			.TP
125			.BI -vo \ val
126			Set the view fore clipping plane at a distance of
127			.I val
128			from the view point.
129			The plane will be perpendicular to the view direction for
130			perspective and parallel view types.
131			For fisheye view types, the clipping plane is actually a clipping
132			sphere, centered on the view point with radius
133			.I val.
134			Objects in front of this imaginary surface will not be visible.
135			This may be useful for seeing through walls (to get a longer
136			perspective from an exterior view point) or for incremental
137			rendering.
138			A value of zero implies no foreground clipping.
139			A negative value produces some interesting effects, since it creates an
140			inverted image for objects behind the viewpoint.
141			This possibility is provided mostly for the purpose of rendering
142			stereographic holograms.
143			.TP
144			.BI -va \ val
145			Set the view aft clipping plane at a distance of
146			.I val
147			from the view point.
148			Like the view fore plane, it will be perpendicular to the view
149			direction for perspective and parallel view types.
150			For fisheye view types, the clipping plane is actually a clipping
151			sphere, centered on the view point with radius
152			.I val.
153			Objects behind this imaginary surface will not be visible.
154			A value of zero means no aft clipping, and is the only way to see
155			infinitely distant objects such as the sky.
156			.TP
157			.BI -vs \ val
158			Set the view shift to
159			.I val.
160			This is the amount the actual image will be shifted to the right of
161			the specified view.
162			This is option is useful for generating skewed perspectives or
163			rendering an image a piece at a time.
164			A value of 1 means that the rendered image starts just to the right of
165			the normal view.
166			A value of -1 would be to the left.
167			Larger or fractional values are permitted as well.
168			.TP
169			.BI -vl \ val
170			Set the view lift to
171			.I val.
172			This is the amount the actual image will be lifted up from the
173			specified view, similar to the
174			.I \-vs
175			option.
176			.TP
177			.BI -vf \ file
178			Get view parameters from
179			.I file,
180			which may be a picture or a file created by rview (with the "view" command).
181			.TP
182			.BI -S \ seqstart
183			Instead of generating a single picture based only on the view
184			parameters given on the command line, this option causes
185			.I rhpict
186			to read view options from the standard input and for each line
187			containing a valid view specification, generate a corresponding
188			picture.
189			.I Seqstart
190			is a positive integer that will be associated with the first output
191			frame, and incremented for successive output frames.
192			By default, each frame is concatenated to the output stream, but it
193			is possible to change this action using the
194			.I \-o
195			option (described below).
196			Multiple frames may be later extracted from a single output stream using the
197			.I ra_rgbe(1)
198			command.
199			.TP
200			.BI -o \ fspec
201			Send the picture(s) to the file(s) given by
202			.I fspec
203			instead of the standard output.
204			If this option is used in combination with
205			.I \-S
206			and
207			.I fspec
208			contains an integer field for
209			.I printf(3)
210			(eg., "%03d") then the actual output file name will include
211			the current frame number.
212			.TP
213			.BR \-w
214			Turn off warning messages.
215			.SH EXAMPLE
216			rhpict -vp 10 5 3 -vd 1 -.5 0 scene.hdk > scene.pic
217			.PP
218			rpict -S 1 -o frame%02d.pic scene.hdk < keyframes.vf
219			.SH AUTHOR
220			Greg Ward
221			.SH "SEE ALSO"
222			getinfo(1), pfilt(1), pinterp(1),
223			printf(3), ra_rgbe(1), rholo(1), rpict(1), rview(1)