rt operates on the indicated objects in the input
model.g and produces a color-shaded image as the output. By default,
the output is placed on the current framebuffer as it is computed. The
environment variable FB_FILE specifies the current framebuffer, see
brlcad(1). Alternatively, the output can be stored in a pixel file
(pix(5) format) by specifying -o output.pix or in a PNG
image file by specifying -o output.png in the option list. The
orientation of the rays to be fired may be specified by the -a and
-e options, in which case the model will be autosized, and the grid
will be centered on the centroid of the model, with ray spacing chosen to
span the entire set of objects. Alternatively, with the -M
option, a transformation matrix may be provided on standard input which maps
model-space to view-space. In this case, the grid ranges from -1.0 = X,Y =
+1.0 in view space, with the size of the grid (number of rays fired)
specified with -s. The -M option is most useful when rt
is being invoked from a shell script created by an mged(1)
saveview command.
The following options are recognized:
-. #
selects the factor used in NUgrid algorithm. Default is
1.5 .
-, #
selects which space partitioning algorithm to use
-a #
selects auto-sizing, and gives the view azimuth in
degrees. Used with -e and conflicts with -M .
-b "# #"
is sometimes useful for debugging. A single ray is fired
at the pixel coordinates specified. This is best when accompanied by debugging
options. Note that the standard getopt(3) routine only allows options
to have one parameter, so the X and Y pixel coordinates need to be combined
into one string parameter by enclosing them in double quotes. This option must
follow any viewing parameters.
-c "script_command"
supplies, on the command line, any command that can
appear in a -M command script. For example, -c "set"
will print the values of all settable variables.
-e #
selects auto-sizing, and gives the view elevation in
degrees. Used with -a and conflicts with -M .
-g #
sets the grid cell width, in millimeters. Ordinarily, the
cell width is computed by dividing the view size by the number of pixels of
width, so this option need not be used. To obtain exactly 1 inch ray spacing,
specify -g25.4 . If the grid cell width is specified and the grid cell
height (which would be set using -G) is not specified, the grid
cell height defaults to be the same as the width.
-m density,r,g,b
enables an exponential shading of the void between the
eye and the first hit location. This allows a cheap simulation of atmospheric
haze with lower performance impact than explicit modeling of the air volume.
The haze is computed using the form:
f = e^(-distance * density)
g = 1.0 - f
color = color * f + hazeRGB * g
The color values are optional. If not specified, they will have
the passable values 0.8 .9 .99 .
Example usage: -m '2.5e-8,.75,.95,.99'
-i
enables incremental mode processing. (First, a
single ray is fired. Then, the screen is subdivided into four parts by evenly
subdividing in the vertical and horizontal directions. The previously fired
ray was the lower left corner; three more rays are fired. This process
recurses until full resolution has been reached. Assumes square image. Also
assumes fast path between CPU and display hardware.)
-j xmin,ymin,xmax,ymax
enables processing of just a sub-rectangle,
located within the rectangle (0,0) (width-1,height-1), and whose screen
coordinates (lower left and upper right corners) are provided in the argument.
Ray-tracing will be limited to just those pixels within the sub-rectangle, and
only those pixels will be transmitted to the framebuffer. The corner pixels
(xmin,ymin) and (xmax,ymax) are included in the sub-rectangle. This option
exists primarily for mged(1) to allow sweeping out a rectangular
portion of the view for ray-tracing.
-k xdir,ydir,zdir,dist
enables the use of a cutting plane. The xdir,
ydir, zdir, and dist define a plane (equivalent to a halfspace primitive with
the same parameters). The vector (xdir, ydir, zdir) is normal to the plane and
points away from the space to be subtracted. The dist parameter specifies the
distance from the origin to the plane in the normal direction. The resulting
image approximates subtracting the halfspace from the objects being raytraced.
Note that this is not exactly the same as actually subtracting the halfspace,
but it is faster. If explicit lights are used, objects that are cut away by
the cutting plane will still cast shadows.
-l #
selects lighting model. Default is 0. Model 0 is a full
lighting model with the ability to implement Phong shading, transparent and
reflective objects, shadow penumbras, texture maps, etc. In addition to
ambient light, a small amount of light is supplied from eye position. All
objects in the active model space with a material property string of
"light" represent additional light sources (up to 16 are presently
permitted), and shadow computations will be initiated automatically. (This
mechanism is subject to further change.) Model 1 is a diffuse-lighting model
only, and is intended for debugging. Model 2 displays the surface normals as
colors, and is useful for examining curvature and surface orientation. Model 3
is a three-light diffuse-lighting model, and is intended for debugging. Model
4 is a curvature debugging display, showing the inverse radius of curvature.
Model 5 is a curvature debugging display, showing the principal direction
vector. Model 6 is for debugging the UV parameterization used for surface
texturing. It is exactly the same as applying the texture 'testmap' to every
region. The U parameter is displayed in the red channel and the V parameter is
displayed in the blue channel. Model 7 is for using photon mapping to simulate
global illumination and caustics in a given scene. Options to photon mapping
are passed through the -l parameter in the following format:
-l7,Num_Photons,Caustics_Percent,Irradiance_Rays,Angular_Tolerance,
Random_Seed,Importance_Mapping_Toggle,Irradiance_Hypersampling_Toggle,
Visual_Irradiance_Toggle,Scale_Lumens,Load_Save_File
Example: -l7,16384,0,10,60.0,0,0,0,0,1.0,scene.pm
Note: If just -l7 is used, then the default values above will be
applied. Light sources must also be explicitly defined with lumens defined
for each source, i.e., default light sources will not work.
-n #
defines the height of the image as a number of
scanlines.
-o output
specifies the name of a file to store your output data
file. For example, if you specify your output as image.pix, it will write out
an image file in the pix(5) file format. If you specify an image.png
file, it will write out an image file in the PNG file format. The
pix-fb(1) and png-fb(1) utilities can be used to display
".pix" and ".png" files respectively.
-p #
sets the perspective, in degrees, with 0 < = # <
180
-r
requests that overlapping regions be reported (on by
default); opposite of -R .
-s #
specifies the number of rays to fire in the X and Y
directions on a square grid. The default size is 512 (i.e., 512 x 512).
-t
causes reversal of the order of grid traversal (default
is not to do that)
-u units
specifies units, with "model" being used for
the units of the local model
-v [#]
sets the output verbosity level for rt. You can
use -v 0 for no/minimal output or add -v repeatedly up through four levels
(e.g., -vvvv) to see all available output. Default is all available output.
The -v option will also take a specific hexadecimal value to turn on specific
message categories (e.g., -v 0xFF010030) of output.
-w #
defines the width of each scanline in pixels.
-x #
sets the librt(3) debug flags to the given
hexadecimal bit vector. See raytrace.h for the bit definitions. (Notice that
-! # sets the libbu(3) debug flags to the given hexadecimal bit
vector. See bu.h for the bit definitions.)
-z
Enables OpenCL accelerated raytracing (OpenCL must be
enabled at compilation time for this option to be present.)
-A #
sets the ambient light intensity, as a fraction of the
total light in the scene in the range of 0.0 to 1.0 .
-B
turns on the "benchmark" flag. This causes all
intentional random effects such as ray dither, color dither, etc., to be
turned off to allow benchmark timing comparison and benchmark result
comparison.
-C #/#/#
sets the background color to the RGB value #/#/#, where
each # is in the range of 0 to 255 or 0.0 to 1.0. All non-background colors
will be dithered away from this value.
-D #
This is the "desired frame" flag, specifying
the frame number to start with. Used with animation scripts; specify the
desired ending (kill-after) frame with -K # .
-E #
sets the distance from the eye point to the center of the
model RPP; default is the square root of 2. Only useful with auto-sizing, and
conflicts with -M .
-F framebuffer
indicates that the output should be sent to the indicated
framebuffer. See libfb(3) for more details on the specification of a
framebuffer.
-G #
sets the grid cell height, in millimeters. If the grid
cell height is specified and the grid cell width (which would be set using
-g) is not specified, the grid cell width defaults to be the
same as the height.
-H #
This is the "hypersample" flag, specifying
number of extra rays to fire for each pixel to obtain more accurate results
without needing to store the extra pixels. Automatically invokes -J 1.
The final colors of all rays are averaged together. Better results can be
obtained by simply increasing the resolution, and decimating the results with
a filter such as pixhalve(1).
-J #
This is the "jitter" flag, which is a bit
vector. If one (-J 1), it randomizes the point from which each ray is
fired by +/- one half of the pixel size. Useful if doing your own
post-filtering for antialiasing, or to eliminate systematic errors. This has
been useful in obtaining more accurate results in a volume-calculating
raytrace as well. If two (-J 2), it shifts the origin of the output
frame once for each frame. The shift is along a circular path in the plane of
the frame, with a period of ten seconds, and a radius of +/- 1/4 pixel width.
If three (-J 3), it performs both operations.
-K #
sets the final (kill-after) frame number. Used with
animation scripts in conjunction with -D # .
-M
causes reading of animation (model2view) matrix or
animation script from standard input. Conflicts with -a and -e
options.
-N #
sets the NMG_debug flags to the given hexadecimalbit
vector. See h/nmg.h for the bit definitions.
-O output.dpix
specifies the name of a file to store the
double-precision floating-point version of the image. dpix-pix(1) can
be used to later convert the file to pix(5) format output. (Deferred
implementation)
-P #
specifies the maximum number of processors (in a
multi-processor system) to be used for this execution. The default is system
dependent. On "dedicated" multi-processors, such as workstations and
super-minis, the default is usually set for the maximum number of processors,
while on shared multi-processors, such as SuperComputers, usually just one
processor is used by default.
-Q x,y
selects pixel ray for query with debugging. The option is
used to specify a single pixel for which the debug flags should be turned on.
The computation of all other pixels will be performed without debugging. This
is similar to the -b option, except that it does not limit rendering to the
single ray. The entire image is computed. This option is useful in debugging
problems which arise from specific computation sequences (such as the order of
random numbers previously drawn).
-R
requests that overlapping regions not be reported;
opposite of -r .
-S
turns on stereo viewing. The left-eye image is drawn in
red, and the right-eye image is drawn in blue.
-T # or -T #,# or -T #/#
sets the calculation tolerances used by librt(3).
If only one number is given, it specifies the distance tolerance. Any two
entities closer than this distance are considered to be the same. The default
distance tolerance is 0.005mm. If the second number is given, it specifies the
value of the dot product below which two lines are to be considered
perpendicular. This number should be near zero, but in any case should be less
than 1. The default perpendicular tolerance is 1e-6. If both calculation
tolerances are provided, they shall be separated by either a slash
("/") or a comma (","), with no white space between them.
For example, the default tolerances would be specified as -T0.005/1e-6
on the command line.
-U #
sets the Boolean variable use_air to the given
value. The default is 0, which ignores regions that have non-zero aircode
values.
-V #
sets the view aspect. This is the ratio of width over
height and can be specified as either a fraction or a colon-separated ratio.
For example, the NTSC aspect ratio can be specified by either -V1.33 or
-V4:3 .
-W
specifies rendering on a white background. this option
sets the image background color to a nearly pure white RGB of 255/255/254.
This is equivalent to setting -c "set background=255/255/254".
-X #
turns on the rt(1) program debugging flags. See
raytrace.h for the meaning of these bits.
-! #
turns on the libbu(3) library debugging flags. See
bu.h for the meaning of these bits. In particular, specifying -!1 will
cause bu_bomb() to dump core, rather than logging the error and
exiting. This is useful with dbx(1) or gdb(1) for debugging.
(Notice that -x # sets the libbt(3) debug flags to the given
hexadecimal bit vector. See raytrace.h for the bit definitions.)
-+ #
specifies (setting argument to "t") that output
is NOT binary (default is that it is). -+ is otherwise not
implemented.
The rt program is a simple front-end to librt(3)
which can be invoked directly, or via the rt command in
mged(1).
Visit the GSP FreeBSD Man Page Interface.