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

FreeBSD Manual Pages

  
 
  

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

NAME
       nirt - interactively ray	trace a	BRL-CAD	geometric model

SYNOPSIS
       nirt [options] model.g objects...

DESCRIPTION
       Nirt operates on	the specified objects in the database model.g, using
       librt(3)	to trace rays according	to commands read from the standard
       input and producing an ASCII report of the results. By default, the
       user can	interact with NIRT, repeatedly specifying origination points
       and directions for rays and the format and destination for the reports.
       Locations may be	input and output in either model coordinates (x, y, z)
       or view (a.k.a. grid-plane) coordinates (h, v, d). Similarly, direction
       may be input and	output either as vectors expressed in model
       coordinates or as angles	of azimuth and elevation.

   Options
       -A attribute_name...
	   Adds	the names to the list of attributes that will be reported when
	   the "attributes" partition information value	is specified. See also
	   the attr command below.

       -M
	   Causesnirt to read the eye point and	either the orientation
	   quaternion (new format) or the view-rotation	matrix (old format)
	   from	the standard input, and	fire a single ray from the point in
	   the specified direction. This option	allows nirt to be called
	   directly from within	mged using the nirt and	rrt commands.

       -b
	   Causes nirt to perform a backout command before the first shoot
	   command (see	the description	of these two commands below). This is
	   probably only useful	with the -M option.

       -B rt_bot_minpieces
	   Causes nirt to adjust the setting of	rt_bot_minpieces to the
	   indicated value. A value of zero here indicates that	the "pieces"
	   methodology should not be used. A value greater than	zero indicates
	   that	all BOT	primitives containing more than	rt_bot_minpieces
	   triangles should be broken down into	a separate piece for each
	   triangle. This can result in	significant improvement	in raytrace
	   speed at the	cost of	more memory use.

       -e script
	   Causes nirt to run the script string	before reading the standard
	   input. Multiple commands in script may be separated with a
	   semicolon ';'. Scripts specified with either	the -e or -f options
	   are executed	in the order in	which they are specified on the
	   command line.

       -E
	   Causes nirt to ignore any -e	or -f options specified	previously on
	   the command line.

       -f sfile
	   Causes nirt to run the script file sfile before reading the
	   standard input. Scripts specified with either the -e	or -f options
	   are executed	in the order in	which they are specified on the
	   command line.

       -s
	   Causes nirt to run in silent	(that is, non-verbose) mode. In	this
	   mode, which is useful in a pipeline,	nirt does not print its
	   initial lines of output or the prompt.

       -v
	   Causes nirt to run in verbose mode. The default is verbose mode,
	   except if standard input has	been redirected, in which case the
	   default is silent mode.

       -u n
	   Sets	the useair member of the rt_i structure	to n. See the
	   discussion of the useair command below.

       -O n
	   Causes nirt to handle multiple regions' claims to segments of a ray
	   according to	action n. The argument n may be	any of the values 0,
	   1, 2, or 3, or their	corresponding key words	"resolve,"
	   "rebuild_fastgen," "rebuild_all," or	"retain." See the discussion
	   of the overlap_claims command below.

       -x v
	   Sets	the librt(3) debug flags to the	hexadecimal bit	vector v. See
	   the discussion of the libdebug command below.

       -X v
	   Sets	nirt's own debug flags to the hexadecimal bit vector v.	See
	   the discussion of the debug command below.

       Nirt will check in two places for a .nirtrc file	- first	in the current
       directory, and if it not	found there in the user's home directory. If
       found, nirt begins by reading from it. This start-up file may contain
       any nirt	commands and is	useful for loading predefined states or
       initializing actions for	output statements.

   Commands
       xyz [x y	z]
	   Sets	the ray	origination point to (x, y, z).	If this	command	is
	   invoked with	no arguments, nirt prints the current ray origination
	   point in model coordinates. Default is (0, 0, 0). Changing (x, y,
	   z) will change (h, v, d), according to the current direction
	   vector.

       hv [ h v	 [ d ]
	   Sets	the ray	origination point to (h, v, d).	If this	command	is
	   invoked with	only two arguments, nirt interprets them as h and v,
	   and d retains its previous value. If	invoked	with no	argument, the
	   command causes nirt to print	the current ray	origination point in
	   view	coordinates. Default is	(0, 0, 0). Changing (h,	v, d) will
	   change (x, y, z), according to the current direction	vector.

       dir [dx dy dz]
	   Sets	the direction vector to	the unit vector	in direction (dx, dy,
	   dz).	If this	command	is invoked with	no arguments, nirt prints the
	   current direction vector. Default is	(-1, 0,	0). Changing (dx, dy,
	   dz) will change the azimuth and elevation angles.

       ae [az el]
	   Sets	the direction vector to	point from azimuth = az	and elevation
	   = el. If this command is invoked with no arguments, nirt prints the
	   current values of the azimuth and elevation angles. Default is (0,
	   0). Changing	azimuth	and elevation will change the direction
	   vector.

       s
	   Fires a ray from the	current	origination point in the current
	   direction.

       bot_minpieces [n]
	   Sets	"rt_bot_minpieces" to the new value n.	If n is	not provided,
	   the current value of	"rt_bot_minpieces" is displayed. See the
	   discussion of the -B	option above for more details.

       backout [ n ]
	   Command to set the backout flag. With no option, prints the current
	   value. When activated, backs	the ray	origination point out of the
	   geometry: h and v retain their previous values and d	is set to
	   Dmax, the largest value of d	anywhere in the	geometry. Default is 0
	   (deactivated), 1 is active.

       useair [n]
	   Sets	the useair member of the rt_i structure	to the integer n. If n
	   is 0, then nirt ignores any air in the geometry. If this command is
	   invoked with	no arguments, nirt prints the current value of useair.
	   Default is 0.

       overlap_claims [n]
	   Specifies how to handle multiple regions' claims to segments	of a
	   ray.	If n is	0 or "resolve,"	then all overlaps are resolved in
	   favor of a single region and	any other claimants are	ignored. If n
	   is 2	or "rebuild_all," then all overlaps are	rebuilt, so any
	   overlapping regions along the ray create individual (geometrically
	   intersecting) partitions. If	n is 3 or "retain," then all overlaps
	   are retained. In this case, the resulting partitions	are always
	   geometrically disjoint, each	one is owned by	a single region
	   according to	the current overlap resolution strategy, but every
	   claimant is recorded. If n is 1 or "rebuild_fastgen," then nirt
	   takes on FASTGEN behavior, so overlaps of plate-mode	primitives are
	   rebuilt, but	other overlaps are retained. This command is useful
	   with	the claimant_count, claimant_list, and claimant_listn output
	   items. Default is "resolve."

       attr {-f|-p|attr_names...}
	   When	used with one or more names, adds the names to the list	of
	   attributes that will	be printed when	the "attributes" value is
	   requested in	the output format string.

	   The -p option to the	attr command causes it to print	the list of
	   attributes that will	be reported.

	   The -f option clears	the attributes table.

       units [u]
	   Causes nirt to read and write all distances and locations in	units
	   of u. Valid choices for u are "mm"; "cm"; "m"; "in";	and "ft"; If
	   this	command	is invoked with	no arguments, nirt prints the current
	   choice of I/O units.	Default	is the units of	model.g.

       fmt [t format item item ...]
	   Sets	the action for output statements of type t. If this command is
	   invoked with	only one argument, a valid statement type, nirt	prints
	   the current format and items	for the	specified type.	See the
	   discussion of output	statements below.

       dest [d]
	   Sets	the destination	for subsequent output actions to d. If the
	   first character of d	is `|',	then d is interpreted as a pipeline to
	   which to write its output. Otherwise, if d is the string "default,"
	   nirt	sets the destination to	the standard output. Otherwise,	d is
	   interpreted as a file. In any event,	d is not closed	until the user
	   quits nirt or resets	the destination	by another invocation of the
	   dest	command. If this command is invoked with no arguments, nirt
	   prints the current value of d. Default is "default,"	that is, the
	   standard output.

       statefile [f]
	   Sets	the name of the	state file to which to dump and	from which to
	   load	state information. See the discussion of the dump and load
	   commands below. If this command is invoked with no arguments, nirt
	   prints the current name of the state	file. Default is "nirt_state."

       dump
	   Writes state	information to the state file. The ray origination
	   point and direction vector, useair, units, destination, and all the
	   output actions are dumped.

       load
	   Reads state information from	the state file.	The state file loaded
	   may contain any nirt	commands.

       print item
	   Prints the current value of the output item item. See the
	   discussion of output	statements below.

       libdebug	v
	   Sets	the librt(3) debug flags (the debug member of the rt_g
	   structure) to the hexadecimal bit vector v. These flags control the
	   amount and kind of diagnostic print statements librt(3) executes.
	   If v	is 0, then no diagnostics are produced.	If this	command	is
	   invoked with	no arguments, nirt prints the current value of v and
	   the names of	any of its bits	that are set. Default is 0.

       debug v
	   Sets	nirt's internal	debug flags to the hexadecimal bit vector v.
	   These flags control the amount and kind of diagnostic print
	   statements nirt executes. If	v is 0,	then no	diagnostics are
	   produced. If	this command is	invoked	with no	arguments, nirt	prints
	   the current value of	v and the names	of any of its bits that	are
	   set.	Default	is 0.

       ?
	   Prints a help menu to the standard output.

       q
	   Quits nirt.

   Output Statements
       Nirt allows the user a high degree of control, via the fmt command,
       over what information gets printed out for each ray and in what format.
       There are six types of output statements, each of which is executed
       under appropriate circumstances.	The types and their use	are:

       r
	   Ray.	The first output statement executed whenever the s command is
	   invoked.

       h
	   Head. Executed immediately after the	ray statement if the ray hits
	   anything.

       p
	   Partition. Executed once for	each partition along the ray if	the
	   ray hits anything.

       f
	   Foot. The last output statement executed if the ray hits anything.

       m
	   Miss. Executed immediately after the	ray statement if the ray hits
	   nothing.

       o
	   Overlap. Executed once for each overlap along the ray if the	ray
	   hits	anything.

       g
	   Gap.	Executed once for each gap along the ray if the	ray encounters
	   any gaps.

       The action associated with each output statement	type is	essentially a
       printf(3) statement, with a format string and a list of output items.
       The items may be	chosen from a set of values that nirt updates
       according to user commands and location along the ray. These values may
       be categorized as pertaining to the entire ray, partitions along	the
       ray, or overlaps. The values are	explained in the following table.

       Ray Information

       x_orig
	   x coordinate	of ray origination point.

       y_orig
	   y coordinate	of ray origination point.

       z_orig
	   z coordinate	of ray origination point.

       d_orig
	   d coordinate	of ray origination point.

       h
	   h coordinate	for the	entire ray.

       v
	   v coordinate	for the	entire ray.

       x_dir
	   x component of direction vector.

       y_dir
	   y component of direction vector.

       z_dir
	   z component of direction vector.

       a
	   azimuth of view (i.e., of ray direction).

       e
	   elevation of	view (i.e., of ray direction).

       Partition Information

       attributes
	   A string variable consisting	of the names and values	of the
	   attributes requested	by the attr command or the -A command line
	   option.

       x_in
	   x coordinate	of entry into current region.

       y_in
	   y coordinate	of entry into current region.

       z_in
	   z coordinate	of entry into current region.

       d_in
	   d coordinate	of entry into current region.

       x_out
	   x coordinate	of exit	from current region.

       y_out
	   y coordinate	of exit	from current region.

       z_out
	   z coordinate	of exit	from current region.

       d_out
	   d coordinate	of exit	from current region.

       los
	   line-of-sight distance through current region.

       scaled_los
	   scaled line of sight: product of line-of-sight distance through
	   current region and region solidity (sometimes called	"percent
	   LOS").

       path_name
	   full	path name of current region.

       reg_name
	   name	of current region, as might be obtained	by passing path_name
	   to basename(1).

       reg_id
	   region ID of	current	region.

       claimant_count
	   number of regions claiming this partition (that is, participating
	   in a	retained overlap).

       claimant_list
	   space-separated list	of names of regions claiming this partition
	   (that is, participating in a	retained overlap).

       claimant_listn
	   Same	as claimant_list, except that it is newline-, rather than
	   space-separated.

       obliq_in
	   entry obliquity for current region.

       obliq_out
	   exit	obliquity for current region.

       nm_x_in
	   x component of entry	normal vector

       nm_y_in
	   y component of entry	normal vector

       nm_z_in
	   z component of entry	normal vector

       nm_h_in
	   h component of entry	normal vector

       nm_v_in
	   v component of entry	normal vector

       nm_d_in
	   d component of entry	normal vector

       nm_x_out
	   x component of exit normal vector

       nm_y_out
	   y component of exit normal vector

       nm_z_out
	   z component of exit normal vector

       nm_h_out
	   h component of exit normal vector

       nm_v_out
	   v component of exit normal vector

       nm_d_out
	   d component of exit normal vector

       surf_num_in
	   entry-surface ID of entry solid.

       surf_num_out
	   exit-surface	ID of exit solid.

       Gap Information

       x_gap_in
	   x coordinate	of entry into gap.

       y_gap_in
	   y coordinate	of entry into gap.

       z_gap_in
	   z coordinate	of entry into gap.

       gap_los
	   line-of-sight distance through gap.

       Overlap Information

       ov_reg1_name
	   name	of one of the overlapping regions.

       ov_reg2_name
	   name	of the other overlapping region.

       ov_reg1_id
	   region ID of	one of the overlapping regions.

       ov_reg2_id
	   region ID of	the other overlapping region.

       ov_sol_in
	   name	of one of the overlapping solids.

       ov_sol_out
	   name	of the other overlapping solid.

       ov_los
	   line-of-sight distance through the overlap.

       ov_x_in
	   x coordinate	of entry into overlap.

       ov_y_in
	   y coordinate	of entry into overlap.

       ov_z_in
	   z coordinate	of entry into overlap.

       ov_d_in
	   d coordinate	of entry into overlap.

       ov_x_out
	   x coordinate	of exit	from overlap.

       ov_y_out
	   y coordinate	of exit	from overlap.

       ov_z_out
	   z coordinate	of exit	from overlap.

       ov_d_out
	   d coordinate	of exit	from overlap.

HINTS
       Ray origination coordinates specified with the hv command are
       immediately converted for internal use to model coordinates, according
       to the current direction	vector.	If you want to change the ray
       direction and origination point,	and you're using view coordinates, you
       probably	want to	change the ray direction before	you use	the hv
       command.

       The name	"nirt" stands for "Natalie's interactive ray tracer."

DEFINITIONS
       The usage in nirt of the	following terms	corresponds to that found in
       mged(1) and elsewhere throughout	BRL-CAD. We provide the	definitions
       here for	reference.

   View	Coordinates
       We define the view coordinate system (more precisely its	basis vectors
       m, n, and o) in terms of	the basis vectors i, j,	and k of the model
       coordinate system as follows:

       m is the	opposite of the	direction vector and corresponds to d,

       n = k x m corresponds to	h, and

       o = m x n corresponds to	v.

       Thus if the direction vector is (-1, 0, 0), then	(d, h, v) = (x,	y, z).

   Azimuth and Elevation
       Azimuth is the angle measured around k (right-hand rule)	from the xz
       plane to	m. Elevation is	the angle measured toward k from the xy	plane
       to m.

FILES
	~/.nirtrc
	   run-time configuration file

SEE ALSO
       mged(1),	librt(3), printf(3)

BUGS
       The program sometimes complains about "previously unreported overlaps."
       To the best of our knowledge, this complaint may	be safely ignored. We
       hope to fix this	soon.

AUTHORS
       Natalie Eberius

       Paul Tanenbaum

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

NAME | SYNOPSIS | DESCRIPTION | HINTS | DEFINITIONS | FILES | SEE ALSO | BUGS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nirt&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help