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

       -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'

	   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

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


	   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.

       -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

	   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).

	   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

       -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

       -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.)

	   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 .

	   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

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

	   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

       -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).

	   requests that overlapping regions not be reported; opposite of -r .

	   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 .

	   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

       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), 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).

       BRL-CAD Team

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

       Reports of bugs or problems should be submitted via electronic mail to

BRL-CAD				  08/27/2021				 RT(1)


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

home | help