Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RT(1)			     BRL-CAD User Commands			 RT(1)

       rt - raytrace an	mged model, giving a shaded picture

       rt [options...] model.g objects...

       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 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 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 used to supply 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.

	   turns on the	reporting of pixel distances, so that each pixel is
	   represented by 3 bytes of color information followed	by 8 bytes for
	   a double (in	IEEE format) giving the	distance to the	ray's first
	   hit.	If the ray doesn't hit,	a zero distance	is reported by default
	   which causes	rt (1) to write	only the color information. See	pix(5)
	   and pixd(5).

	   selects auto-sizing,	and gives the view elevation in	degrees. Used
	   with	-a and conflicts with -M

	   sets	the expected playback rate in frames-per-second. The default
	   is 30fps. Several time-evolving shaders such	as fire	and grass need
	   to know the time at which each frame	and pixel occur	to drive their

	   is used to set 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 is not specified,	the grid cell
	   height defaults to be the same as the width.

       -h 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^(-dist	* 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: -h '2.5e-8,.75,.95,.99'

	   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.

	   xmin,ymin,xmax,ymax enables just this sub-rectangle processing.
	   Specifies the screen	coordinates of the lower left and upper	right
	   corner of a rectangle within	the rectangle (0,0)
	   (width-1,height-1). 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.

	   Select 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:


	   Example: -l7,16384,0,10,60.0,0,0,0,0,1.0,

	   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.

	   defines the height of the image as a	number of scanlines.

	   output.pix Specify the name of a file to store the pix(5) format
	   output. The pix-fb(1) utility can be	used later to display ".pix"

	   Sets	the perspective, in degrees, ranging 0 < = # < 180.

	   requests that overlapping regions be	reported. (conflicts with -R)

	   specifies the number	of rays	to fire	in the X and Y directions on a
	   square grid.	The default size is 512	pixels.

	   sets	the verbosity bit vector flags for rt. Use -v 0	for no output
	   or -v fff for all available output. See include/brlcad/rtprivate.h
	   for various bit definitions.

	   defines the width of	each scanline in pixels.

	   sets	the librt(3) debug flags to the	given hexadecimal bit vector.
	   See raytrace.h for the bit definitions.  -!#	sets the libbu(3)
	   debug flags to the given hexadecimal	bit vector. See	h/bu.h for the
	   bit definitions.

	   sets	the ambient light intensity, as	a fraction of the total	light
	   in the scene	in the range of	0.0 to 1.0.

	   The "benchmark" flag. When specified, all intentional random
	   effects such	as ray dither, color dither, etc., are turned off to
	   allow benchmark timing comparison and benchmark result comparison.

	   sets	the background color to	the RGB	value #/#/#, where each	# is
	   in the range	of 0 to	255. All non-background	colors will be
	   dithered away from this value.

	   The "desired	frame" flag, specifies frame number to start with.
	   Specify the desired ending (kill-after) frame with -K#

	   sets	the distance from the eye point	to the center of the model
	   RPP.	Only useful with auto-sizing, 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.

	   sets	the grid cell height, in millimeters.

	   The "hypersample" flag specifies number of extra rays to fire for
	   each	pixel to obtain	more accurate results without needing to store
	   the extra pixels. Causes -J1	to be set. 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).

	   Turns on interactive	mode. If this flag is off and your image is
	   "large" (> =	256 x 256), it will lower the priority of the rt

	   The "jitter"	flag is	a bit vector. If one (-J1), 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 (-J2), 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 (-J3), it performs both operations.

	   sets	the final (kill-after) frame number. Used with animation
	   scripts in conjunction with -D#

	   Reads animation matrix or animation script from standard input.
	   Conflicts with -a and -e

	   Sets	the NMG_debug flags to the given hexadecimalbit	vector.	See
	   h/nmg.h for the bit definitions.

	   output.dpix Specify 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).

	   Specify 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
	   Query pixel ray 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).

	   requests that overlapping regions not be reported. (conflicts with

	   Turns on stereo viewing. The	left-eye image is drawn	in red,	and
	   the right-eye image is drawn	in blue.

	   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.

	   Sets	the "use_air" value. The default is 0, which ignores regions
	   that	have non-zero aircode values.

	   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

	   Sets	the background image color to white.

	   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.

       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

       For information on the animation	script language	accepted by rt,	please
       refer to	the manual pages for tabinterp(1), tabsub(1), and
       anim_script(1). Also please consult the HTML documentation for a
       complete	animation tutorial.

       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.

       brlcad(1), mged(1), lgt(1), pix-fb(1), rtray(1),	rtpp(1), librt(3),
       ray(5V),	pix(5).

       Numerous	error conditions are possible. Descriptive messages are
       printed on stderr.

       BRL-CAD Team

       This software is	Copyright (c) 1984-2013	United States Government as
       represented by the U.S. Army Research Laboratory. All rights reserved.

       Most deficiencies observed while	using the rt program are a consequence
       of problems in librt(3).

       Reports of bugs or problems should be submitted via electronic mail to
       <>, or via the "" script.

BRL-CAD				  07/08/2017				 RT(1)


Want to link to this manual page? Use this URL:

home | help