NIRT(1)

NAME

nirt - interactively ray trace a BRL-CAD geometric model

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
COMMANDS
OUTPUT STATEMENTS
EXAMPLES
HINTS
DEFINITIONS
- View Coordinates
- Azimuth and Elevation
FILES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

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

nirt (Natalie’s Interactive Ray-Tracer) traces rays through the specified objects in the database model.g, using librt(3), and produces an ASCII report of what each ray encounters. Commands are read from standard input. By default the user interacts with nirt, repeatedly specifying ray origination points and directions and controlling the format and destination of 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), and direction may be expressed either as a vector in model coordinates or as azimuth and elevation angles.

When standard input is not a terminal (for example, when it is redirected from a file or a pipe), nirt defaults to silent mode, making it convenient for scripted ray queries.

OPTIONS

-h, --help, -?: Print a usage message and exit.
-A name: Add name to the list of object attributes reported by the attributes output item. May be repeated to request multiple attributes. See also the attr command below.
-M: Read an eye point and either an orientation quaternion or a view-rotation matrix from standard input, then fire a single ray. This allows nirt to be driven directly from mged(1) via its nirt and rrt commands.
-b: Back the ray out of the geometry before the first shot. Deprecated; this is now the default behavior and the flag is a no-op.
-c: Shoot the ray from the current center point rather than backing out of the geometry first.
-e script: Run the script string before reading standard input. Multiple commands may be separated with a semicolon. -e and -f scripts run in command-line order.
-f format: Load the predefined format (see -L) or script file named format before reading standard input. -e and -f scripts run in command-line order.
-E: Ignore any -e or -f options given earlier on the command line.
-L: List the available output formats and exit.
-s: Run in silent (non-verbose) mode, suppressing the banner and prompt. Useful in pipelines.
-v: Run in verbose mode. Verbose is the default on a terminal; silent is the default when standard input is redirected.
-H n: Enable (n=1, the default) or disable (n=0) the informational header. The header is always off in silent mode.
-u n: Set the use_air value to n, controlling whether air regions are reported. Default is 0 (air ignored).
-O action: Control how overlapping regions' claims to a ray segment are handled. action may be 0 or "resolve", 1 or "rebuild_fastgen", 2 or "rebuild_all", or 3 or "retain". See the overlap_claims command below. Default is "resolve".
-x v: Set the librt(3) diagnostic (debug) flags to the hexadecimal bit vector v.
-X v: Set nirt's own diagnostic (debug) flags to the hexadecimal bit vector v.
--center x,y,z: Set the ray origination (center) point to the given model-space coordinates.
--xyz x,y,z: Synonym for --center.
--plotfile filename: Write graphical plot output of the ray segments to filename.
--color_odd r/g/b: Color used when plotting odd-numbered segments (default 0/255/255).
--color_even r/g/b: Color used when plotting even-numbered segments (default 255/255/0).
--color_gap r/g/b: Color used when plotting gaps between segments (default 255/0/255).
--color_ovlp r/g/b: Color used when plotting overlap segments (default 255/255/255).
-B: Deprecated and no longer used; accepted but ignored.

nirt also checks for a .nirtrc start-up file, first in the current directory and then in the user’s home directory. If found, it is read before interaction begins and may contain any nirt commands, which is useful for loading predefined states or output formats.

COMMANDS

center [ x y z*]* 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.
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.
clear: Clears text from the terminal screen (interactive mode only).
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.

EXAMPLES

Example 1. Scripted line-of-sight query through a model

printf 'xyz 0 0 0\ndir 1 0 0\ns\n' | nirt -s model.g component

Because standard input is a pipe, nirt runs silently. The script positions the ray origin, aims it down the +X axis, and fires a single shot, printing only the ray report for the component object. This is a convenient way to measure line-of-sight distances or material thickness from a shell script.

Example 2. Reporting custom attributes for each region hit

nirt -A material_id -A los_density model.g all

Each region the ray passes through is reported together with its material_id and los_density attribute values via the attributes output item, which is useful for vulnerability and mass-properties analyses.

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, ~/.nirtrc: run-time configuration file, searched first in the current directory and then in the home directory