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

Causes nirt 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.

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

-E

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

-L

List output formatting options.

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

-H n

Set flag (n) for enable/disable informational header (n=1 [on] by default, always off in 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 is 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.

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.

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:

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

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

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

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

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

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

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 coordinate for the entire ray.

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.

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

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 × m corresponds to h, and

o = m × 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

AUTHOR

BRL-CAD Team

COPYRIGHT

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org