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  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 seperate 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 short (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 short 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. If there is a file called .nirtrc in the current directory, otherwise in the user's home directory, 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 diplayed. See the discussion of the -B option above for more details.

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

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.

! [command]
    Executes the shell pipeline command. If this command is invoked with no arguments, nirt spins off a subshell, executing the program named in the environment variable SHELL.

?   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 statement, 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.

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

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