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"
is for specifying commands for rt to run prior to ray
tracing. The "script_command" can be a single command or a
semi-colon separated list of commands. The commands
available are the same commands that may appear in a
-M
command script.
Some common script commands include start, viewsize, eye_pt, lookat_pt, viewrot, orientation, multiview, anim, tree, draw, erase, prep, clean, set, ae, start, and end. Running the saveview in MGED will produce an rt script for the current view.
Some common set variables include
ambSamples, overlay, a_onehit, a_no_booleans. Running
-c "set"
will print values for 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 #
Specify the maximum number of processor cores to be used on multicore systems. The default is the maximum number of cores available for the machine. Negative numbers indicate using all except for the count specified.
-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).
You can obtain progress information from a running rt process by sending it a SIGUSR1 or SIGINFO signal. The raytracer will report progress via details about the ray sample being processed at the time of the signal. The progress is reported to stderr in a form similar to: frame 0, xy=1516,2466 on cpu 0, samp=0
When using rt to create an animation
sequence destined for NTSC video, it is useful to give all these
options at one time: -V4:3
-c
"set
gamma=2.2" -w1440
-n972
-J1
and then post-process the output using
pixhalve(1)
for final display. Performing the gamma correction inside
rt instead of post-processing the
pix(5)
file with
bwmod(1)
avoids Mach-bands in dark regions of the image, and retains the
maximum amount of image detail.
Example 1. Render a very high-quality, high-resolution image, very slowly
rt -H8 -R -A1.3 -c "set ambSamples=512 gamma=2.2" -C234/245/255 -s4096 -o render_4k.png file.g object
This command renders with 8x512=4096 additional rays-per-pixel to average color results and determine whether a given hit point is partially shadowed. Ambient occlusion rendering is a simple brute force global illumination method. Hypersampling smooths out edges.
Lower ambient samples for a more "grainy" surface appearance. Depending on geometry, the -A ambient light value may be increased (e.g., if there are very heavy shadows) or decreased if too bright. The gamma setting also affects overall image brightness (and color).
Note: for optimal results, rendering may be performed at 2X or higher resolution (e.g., -s4096 for 2048x2048 resolution), then reduced and potentially color-corrected in post-processing.
brlcad(1), mged(1), lgt(1), pix-fb(1), png-fb(1), rtray(1), rtpp(1), librt(3), ray(5V), pix(5)
Numerous error conditions are possible, usually due to errors in the geometry database. Descriptive messages are printed on stderr (file descriptor 2).