<!-- Converted by db4-upgrade version 1.0 -->

<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  <info><title>Interactive Raytracing: The <command>nirt</command> Command</title>
    
    <author><personname><firstname>Clifford</firstname><surname>Yapp</surname></personname></author>
  </info>

  


  <section><info><title>About <application>NIRT</application></title></info>
    
    <para>
      The <application>NIRT</application> (Natalie's Interactive Ray-Tracer) command line tool provides a user-level interface to the low-level routines
      defining the ray tracing logic, allowing a user to specify and cast an individual ray
      and tailor the information reported.  It was originally written by Natalie L. Eberius and Paul J. Tanenbaum
      in the early 1990s, with additional updates by others over the years. Significant work was done by 
      Bob Parker in the late 1990s to integrate <application>NIRT</application> with <application>MGED</application>, 
      resulting in wireframe visualization of ray paths and the Query Ray Control Panel.
    </para>

  </section>

  <section><info><title><application>NIRT</application>:  Basic Syntax and Operations</title></info>
    
    
    <para>
      There are two environments within which <application>NIRT</application> can be used - inside the
      <application>MGED</application> interactive geometry editor and within its own command line
      interactive environment.  Consequently, there are three command line environments where behavior
      needs to be described in this document; operating system command prompt, <application>NIRT</application>
      command prompt, and <application>MGED</application> command prompt.  The convention used here will be:

      	<informaltable>
	  <tgroup cols="2" align="center">
	    <colspec colwidth="1*"/>
	    <colspec colwidth="1*"/>
	    <tbody>
	      <row>
		<entry><emphasis role="bold">Command Line Environment</emphasis></entry>
		<entry><emphasis role="bold">Command Type</emphasis></entry>
	      </row>
	      <row>
		<entry>Operating System Command Line Prompt</entry>
		<entry>command</entry>
	      </row>
	      <row>
		<entry><application>NIRT</application> Command Prompt</entry>
		<entry>interactive command</entry>
	      </row>
	      <row>
		<entry><application>MGED</application> Command Prompt</entry>
		<entry><application>MGED</application> command</entry>
	      </row>
	  </tbody>
	</tgroup>
      </informaltable>
    </para>


    <section><info><title>Command Line Help</title></info>
      
      <para>
	<application>NIRT</application> provides an <emphasis>h</emphasis> option
	which prints out a list of available options and command syntax:

	<literallayout class="monospaced">
user@machine ~ $ nirt --h
Usage: 'nirt [options] model.g objects...'
Options:
 -b        back out of geometry before first shot
 -B n      set rt_bot_minpieces=n
 -e script run script before interacting
 -f sfile  run script sfile before interacting
 -L        list output formatting options
 -M        read matrix, cmds on stdin
 -O action handle overlap claims via action
 -s        run in silent (non-verbose) mode
 -u n      set use_air=n (default 0)
 -v        run in verbose mode
 -x v      set librt(3) diagnostic flag=v
 -X v      set nirt diagnostic flag=v

	</literallayout>
      </para>
    </section>

    <section><info><title>Loading a Model</title></info>
      

      <para>
	There will be a number of models used to illustrate various <application>NIRT</application>
	behaviors, all of which will be centered around regions created with various combinations of 2mm arb8 cubes.  
	The left cube is centered at (-2, 0, 0), the center cube at (0, 0, 0) and the right
	cube at (2, 0, 0).  One additional arb8 will be defined to overlap the center cube with side lengths in the
	z direction of 4mm.  The various models based off of these primitives will be read from a
	database called <filename>nirt_example.g</filename>.
      </para>
      <para>
	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig01.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Wireframe view of the three arb8 cubes which will be used to build example models for illustrating
		<application>NIRT</application> behavior.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>
      </para>
      

      <para> 
	Although there are many <command>nirt</command>	options available,
	only the database name and objects are essential to get started:
	
	<cmdsynopsis sepchar=" ">
	  <command>nirt</command>
	  <arg choice="req" rep="norepeat"><replaceable>model.g</replaceable></arg>
	  <arg choice="req" rep="norepeat"><replaceable>objects</replaceable></arg>
	</cmdsynopsis>
	
	where <emphasis>objects</emphasis> is a list of objects in the database 
	separated by spaces.   To begin, select the object <emphasis>center_cube.r</emphasis>
	object with interactive command line <application>NIRT</application>.  The form of the command
	is:
	<footnote>
	  <para>
	    To quickly find out what objects are in a database, 
	    use the commands <command>mged -c nirt_example.g tops</command> 
	    to see all top level objects and <command>mged -c nirt_example.g ls</command>	
	    to see all objects in the model.
	  </para>
	</footnote>:
	
	<literallayout class="monospaced">
nirt nirt_example.g center_cube.r
	</literallayout>
      </para>
      
      <para>
	This starts up the <application>NIRT</application> command line interactive environment:
      
	<literallayout class="monospaced">
BRL-CAD Release 7.13.0  Natalie's Interactive Ray Tracer
    Tue, 26 Aug 2008 23:21:32 -0400, Compilation 2
    user@localhost:/usr/brlcad
Database file:  'nirt_example.g'
Building the directory...
Get trees...
Prepping the geometry...
Object 'center_cube.r' processed
Database title: 'Example BRL-CAD Database'
Database units: 'mm'
model_min = (-1, -1, -1)    model_max = (1, 1, 1)
nirt&gt;
	</literallayout>
	
	The first three lines identify the release number, tool
	being used, date of compilation or date release was made, and user.  The fourth line identifies the database
	file. The next three lines are informational
	messages relating to model setup.  The database title and units are then
	printed. The last pieces of information, <literal>model_min</literal> and 
	<literal>model_max</literal>, are the outer bounds of the objects
	specified. 
      </para>
    </section>
    
    <section><info><title>Shooting a Ray</title></info>
      
      <para>
	With the example loaded into <application>NIRT</application>, the <command>s</command>
	interactive command is used to shoot a ray:

	<literallayout class="monospaced">
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000 
	</literallayout>

	What happened and what do these results mean?  The following table breaks down
	the structure of the report:

	<informaltable>
	  <tgroup cols="2" align="center">
	    <colspec colwidth="1*"/>
	    <colspec colwidth="3*"/>
	    <tbody>
	      <row>
		<entry><emphasis role="bold">Report Element</emphasis></entry>
		<entry><emphasis role="bold">Meaning</emphasis></entry>
	      </row>
	      <row>
		<entry>Origin</entry>
		<entry>Origination point of the ray (NOT the model origin)</entry>
	      </row>
	      <row>
		<entry>x y z</entry>
		<entry>Coordinates in the reference frame of the model</entry>
	      </row>
	      <row>
		<entry>h v d</entry>
		<entry>Coordinates in the reference frame of the view</entry>
	      </row>
	      <row>
		<entry>Direction</entry>
		<entry>Direction in which the ray is traced; reported as a unit vector in model coordinates
		and as an azimuth/elevation angle pair</entry>
	      </row>
	      <row>
		<entry>Region Name</entry>
		<entry>Name of region as recorded in database file</entry>
	      </row>
	      <row>
		<entry>Entry (x y z)</entry>
		<entry>Point at which ray first enters the region</entry>
	      </row>
	      <row>
		<entry>LOS</entry>
		<entry>Line of Sight thickness. In this basic instance, it is equivalent to the thickness of the object along the ray vector.</entry>
	      </row>
	      <row>
		<entry>Obliq_in</entry>
		<entry>Obliquity of the ray at the point of entry into the region (0 in this case, because the ray happened to be perpendicular to the surface in question)</entry>
	      </row>
	      <row>
		<entry>Attrib</entry>
		<entry>Additional attributes the region in question has assigned and the user requested (in this case, none were requested)</entry>
	      </row>
	  </tbody>
	</tgroup>
      </informaltable>

      Because the ray only hit <emphasis>center_cube.r</emphasis>, only <emphasis>center_cube.r</emphasis> appears in the report. (Remember 
      <application>NIRT</application> was only supplied with <emphasis>center_cube.r</emphasis> for a target object to begin with.)  
      Many examples of real world <application>NIRT</application> usage will have much more complex geometries and hence longer reports.
      </para>
    </section>
    <section><info><title>Moving the Origination Point</title></info>
      
      <para>
	If we move the origin to some point other than the
	sphere center, a different ray is cast and the reported intersections change.  The 
	<command>xyz</command> interactive command will print the current origin if given no arguments, and
	accepts a list of points to change the origin:
	
	<literallayout class="monospaced">
nirt&gt;  xyz
(x, y, z) = (0.00, 0.00, 0.00)
nirt&gt;  xyz 0 0 .5 
nirt&gt;  xyz
(x, y, z) = (0.00, 0.00, 0.50)
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.50000000)  (h v d) = (0.0000 0.5000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.5000)   2.0000   0.0000 
	</literallayout>

      </para>
    </section>
    <section><info><title>Backing Out of a Model</title></info>
      
      <para>
	Although in both previous cases the ray's origin was inside the cube, 
	<application>NIRT</application>	backed up to the point of first intersection along the
	indicated vector to report both LOS thickness and entry.  This behavior is specific to 
	the case of an origination point <emphasis>inside</emphasis> 
	a region.  In the case where the origination point of the ray is between two objects belonging
	to the same region, <application>NIRT</application> will report only those portions of the region along
	its path forward. To ensure that a ray always starts outside the <emphasis>entire</emphasis> 
	geometry, the <command>backout</command> interactive command is used.<footnote>
	  <para>
	    To perform this operation automatically when the model is loaded, supply 
	    the <emphasis>b</emphasis> flag to <command>nirt</command> at startup: <command>nirt -b</command>.
	  </para>
	</footnote>
	The backout command moves the starting point outside the bounding box of the model.  This ensures that all segments
	along a given ray path will be reported.
	As an illustration, reload <filename>nirt_example.g</filename> and this time specify <emphasis>left_and_right_cubes.r</emphasis> 
	(defined as the combination of <emphasis>left_cube.s</emphasis> and <emphasis>right_cube.s</emphasis>).  Cast rays before 
	and after backout:

	<literallayout class="monospaced">
nirt&gt;  q
Quitting...

user@machine ~ $ nirt nirt_example.g left_and_right_cubes.r
BRL-CAD Release 7.13.0  Natalie's Interactive Ray Tracer
    Tue, 26 Aug 2008 23:21:32 -0400, Compilation 2
    user@localhost:/usr/brlcad
Database file:  'nirt_example.g'
Building the directory...
Get trees...
Prepping the geometry...
Object 'left_and_right_cubes.r' processed
Database title: 'Example BRL-CAD Database'
Database units: 'mm'
model_min = (-3, -1, -1)    model_max = (3, 1, 1)
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 
nirt&gt;  backout 1
nirt&gt;  s
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 

	</literallayout>

	Note that in the first raytrace,  <emphasis>left_and_right_cubes.r</emphasis> did not
	backtrack to generate its LOS thickness value, and when the backout option was applied,
	<emphasis>left_and_right_cubes.r</emphasis> gained an extra entry.  The double report for 
	<emphasis>left_and_right_cubes.r</emphasis> is not a 
	mistake; the ray did indeed enter and exit the region twice once the <command>backout</command>
	interactive command changed the origination point.  
      </para>
      
      <para>
	It is important to understand that the <command>backout</command> interactive command does
	not permanently change the origination point of the ray; it requests an 
	automatic adjustment of the origination point based on the model 
	<emphasis>for the casting of the ray</emphasis>, and then restores the original 
	specified origination point. If the user no longer wishes to have 
	<application>NIRT</application> back the origination point out of the model, 
	deactivating the backout flag (supplying 0 to the <command>backout</command> interactive command)
	will restore the non-backout point.  If the 
	<command>xyz</command> interactive command is used to change the origination point while backout is
	activated, the backout routine will back out from the new point.  For
	example:
	
	<literallayout class="monospaced">
nirt&gt;  backout 0
nirt&gt;  xyz
(x, y, z) = (0.00, 0.00, 0.00)
nirt&gt;  xyz 0 0 .5
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.50000000)  (h v d) = (0.0000 0.5000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (  -1.0000    0.0000    0.5000)   2.0000   0.0000 
nirt&gt;  backout 1
nirt&gt;  xyz
(x, y, z) = (0.00, 0.00, 0.50)
nirt&gt;  backout 0
nirt&gt;  xyz
(x, y, z) = (0.00, 0.00, 0.50)
nirt&gt;  backout 1
nirt&gt;  xyz 0 0 .8
nirt&gt;  s
Origin (x y z) = (6.63324958 0.00000000 0.80000000)  (h v d) = (0.0000 0.8000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.8000)   2.0000   0.0000 
left_and_right_cubes.r (  -1.0000    0.0000    0.8000)   2.0000   0.0000 
nirt&gt;  backout 0
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.80000000)  (h v d) = (0.0000 0.8000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (  -1.0000    0.0000    0.8000)   2.0000   0.0000 
nirt&gt;
	</literallayout>
      </para>
    </section>

    <section><info><title>Changing the Direction of the Ray</title></info>
      
      <para>
	The other fundamental operation needed to make <application>NIRT</application> usable
	is changing the direction of the ray.  This is achieved with the 
	<command>dir</command> interactive command, which either prints out the current direction 
	unit vector (if no arguments are supplied) or takes x, y, and z components of a vector
	separated by spaces and changes the direction.  To make interpreting 
	the results easier for this example, the origination point of the ray is first returned
	to the origin:
	
	<literallayout class="monospaced">
nirt&gt;  xyz 0 0 0
nirt&gt;  dir
(x, y, z) = (-1.00, 0.00, 0.00)
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (-0.00000000 -0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 
nirt&gt;  dir -1 -.5 0
nirt&gt;  dir
(x, y, z) = (-0.89, -0.45, 0.00)
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-0.89442719 -0.44721360 0.00000000)  (az el) = (26.56505118 -0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (  -1.0000   -0.5000    0.0000)   1.1180  26.5651 
nirt&gt;  dir 0 0 1
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (0.00000000 0.00000000 1.00000000)  (az el) = (0.00000000 -90.00000000)
You missed the target
nirt&gt;
	</literallayout>

	The first shot, in the default -x direction, intersects one of the sections.  
	The second shot changes the aim slightly off the -x axis, with different results - 
	the <literal>LOS</literal> thickness is now longer.  <literal>Obliq_in</literal> changed as well, 
	because the ray is no longer perpendicular to the tangent at the point of intersection.  Notice that the 
	direction was not specified using a unit vector, but was reported as one; the 
	conversion to a unit vector is handled automatically by <application>NIRT</application>.
	The third shot is a more drastic change of direction, from the -x to positive z.  As there are no portions of the
	region present along that path, a miss is reported.
      </para>
    </section>

    <section><info><title>Reporting of Overlaps</title></info>
      
      <para>
	In many cases, a geometry will have overlaps:  errors where a model is
	assigning two physical regions to one volume.  To demonstrate
	this behavior, <application>NIRT</application> is reloaded with <emphasis>overlap_example</emphasis>:

	<literallayout class="monospaced">
nirt&gt;  q
Quitting...

user@machine ~ $ nirt nirt_example.g overlap_example
BRL-CAD Release 7.13.0  Natalie's Interactive Ray Tracer
    Tue, 26 Aug 2008 23:21:32 -0400, Compilation 2
    user@localhost:/usr/brlcad
Database file:  'nirt_example.g'
Building the directory...
Get trees...
Prepping the geometry...
Object 'overlap_example' processed
Database title: 'Example BRL-CAD Database'
Database units: 'mm'
model_min = (-3, -1, -2)    model_max = (3, 1, 2)
nirt&gt;  backout 1
nirt&gt;  s
Origin (x y z) = (7.48331477 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
all_cubes.r          (   3.0000    0.0000    0.0000)   6.0000   0.0000 
OVERLAP: 'center_overlap.r' and 'all_cubes.r' xyz_in=(1 0 0) los=2
nirt&gt;
	</literallayout>

	The last line in the preceding report is reporting that the regions
	<emphasis>all_cubes.r</emphasis> and <emphasis>center_overlap.r</emphasis>
	are both claiming the same volume, starting at (1, 0, 0) and continuing to do so
	for 2 mm per the LOS thickness.  If the direction and origin are changed to
	shoot along the z axis:

	<literallayout class="monospaced">
nirt&gt;  dir 0 0 -1
nirt&gt;  s
Origin (x y z) = (0.00000000 0.00000000 7.48331477)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (0.00000000 0.00000000 -1.00000000)  (az el) = (0.00000000 90.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_overlap.r     (   0.0000    0.0000    2.0000)   1.0000   0.0000 
OVERLAP: 'center_overlap.r' and 'all_cubes.r' xyz_in=(0 0 1) los=2
all_cubes.r          (   0.0000    0.0000    1.0000)   2.0000   0.0000 
center_overlap.r     (   0.0000    0.0000   -1.0000)   1.0000   0.0000 
nirt&gt;  
	</literallayout>

	Along that vector, <emphasis>center_overlap.r</emphasis> is encountered first, then <emphasis>all_cubes.r</emphasis> intersecting
	with <emphasis>center_overlap.r</emphasis>. 
	<footnote>
	  <para>
	    The last two lines that appear in the output when the direction vector is 
	    changed are a result of how the raytracing library keeps track of regions 
	    internally.  Even when in an overlap, the ray is considered to be in only 
	    <emphasis>one</emphasis> region at a time. In this particular overlap 
	    situation, it might be either region, so librt selects the region with the 
	    lowest bit number (for more information, see rt_defoverlap in librt/bool.c).
	    If the ray happens to exit the lowest bit number region when it exits the overlap
	    the active region changes again and another line is generated.  Ultimately the 
	    difference is inconsequential and can be disregarded.  Both reports contain 
	    the key information: the overlap to be removed.
	   </para>
	  </footnote>
       </para>
       <para>
	 It should be pointed out that overlaps are usually regarded as modeling errors and 
	 need to be corrected, unless they are below some previously established threshold for precision
	 in the model.  One of the potential uses of <application>NIRT</application> is
	 to provide detailed information on which regions are overlapping and where, 
	 although tools such as <command>rtcheck</command> typically provide more 
	 comprehensive summaries of overlap problems.
       </para>
     </section>
   </section>
   
   <section><info><title>Graphical Visualization: <application>NIRT</application> in <application>MGED</application></title></info>
     
     <para> 
       The command line interaction provided by <application>NIRT</application> has few options
       for graphic visualization, but <application>MGED</application> allows the use and visualization of 
       <application>NIRT</application> rays.  <application>MGED</application> provides a <command>nirt</command>
        command, but rather than starting an interactive environment, each invocation of 
       the <command>nirt</command> <application>MGED</application> command casts one ray and returns a report, together with 
       information allowing <application>MGED</application> to graphically plot the ray on its wireframe view.
     </para>
     
     <section><info><title>Basic Usage</title></info>
       
       <para>
	 The most important thing to remember when starting to use 
	 <application>NIRT</application> in <application>MGED</application> is that the ray direction is always 
	 perpendicular to the viewing plane.  In other words, the user is looking in the
	 direction in which the ray will be cast.  There is no option to choose a 
	 different direction from the <application>MGED</application> command line, and as a consequence it may 
	 initially look like nothing has happened in the <application>MGED</application> wireframe.  The report on 
	 the command line will print out, but the user will have to change the direction
	 from which the model is being viewed in MGED before the graphical results will 
	 be visible. 
       </para>
       <para>
	 Another important point to remember about using <application>NIRT</application> in <application>MGED</application>
	 is that the user does not specify objects as arguments to the <command>nirt</command> <application>MGED</application>
	 command.  Even if supplied with objects it will not use them - the objects used are those active in 
	 <application>MGED</application>'s wireframe view.
       </para>
       <para>
	 For example, load <filename>nirt_example.g</filename> in <application>MGED</application>, 
	 <command>draw center_cube.r</command>, 
	 set the view direction to a front view looking down the negative x axis, and run the 
	 <command>nirt</command> <application>MGED</application> command:
	
	<literallayout class="monospaced">
mged&gt; draw center_cube.r
mged&gt; ae 0 0
mged&gt; nirt

Firing from view center...
Origin (x y z) = (0.00 0.00 0.00)  (h v d) = (0.00 0.00 0.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
center_cube.r        (    1.000     0.000     0.000)     2.00    0.000

mged&gt;  
	</literallayout>

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig02.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		View of wireframe immediately after running <application>NIRT</application> within <application>MGED</application>.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>
 
	Select the <application>MGED</application> view window and press "3" to view the path of the ray:

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig03.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		View of wireframe after changing view direction, showing path of <application>NIRT</application> ray.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	Because the ray encountered only a single region,
	the only visible path drawn is the intersection path of the ray and the region (the light blue 
	line).  The region intersection was backed out to the first intersection with that region, 
	despite the origination point of the ray being at the center of the sphere.

	<note>
	  <para>
	    When a miss is reported by <application>NIRT</application>, no line is drawn in 
	    the wireframe view.
	  </para>
	</note>
       </para>
     </section>

     <section><info><title>Backing Out with <application>NIRT</application> in <application>MGED</application></title></info>
       
       <para>
	  Because <application>NIRT</application>'s interactive mode cannot be used while in <application>MGED</application>,
	  the <emphasis>b</emphasis> flag must be provided to the invocation of the <command>nirt</command> <application>MGED</application>
	  command to back out the origination point while using <application>NIRT</application> within <application>MGED</application>.  
	  For comparison purposes, it is more instructive to 
	  examine <emphasis>left_and_right_cubes.r</emphasis> than <emphasis>center_cube.r</emphasis>.  To generate a "no backout" 
	  control view, the display is cleared, <emphasis>left_and_right_cubes.r</emphasis> is drawn, the view direction is set, 
	  <application>NIRT</application> (no <emphasis>b</emphasis> flag) is run, and the view is switched to view 
	  the ray path:

	 <literallayout class="monospaced">
mged&gt; B left_and_right_cubes.r
mged&gt; ae 0 0
mged&gt; nirt

Firing from view center...
Origin (x y z) = (0.00 0.00 0.00)  (h v d) = (0.00 0.00 0.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
region1.r            ( -300.000     0.000     0.000)   100.00    0.000

mged&gt; ae 90 0
mged&gt;  	 
	 </literallayout>

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig04.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		View of <application>NIRT</application> ray intersecting <emphasis>left_and_right_cubes.r</emphasis> with ray origin at the global origin.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	 The ray did indeed intersect a solid area as indicated in the report, but only in one of the two
	 cubes making up the region. Repeating the steps using the <emphasis>b</emphasis> flag to back the origination point 
	 out produces somewhat different results:

	 <literallayout class="monospaced">
mged&gt; ae 0 0
mged&gt; nirt -b

Firing from view center...
Origin (x y z) = (6.63 0.00 0.00)  (h v d) = (0.00 0.00 0.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
left_and_right_cubes.r (    3.000     0.000     0.000)     2.00    0.000
left_and_right_cubes.r (   -1.000     0.000     0.000)     2.00    0.000

mged&gt; ae 90 0
	</literallayout>

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig05.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		View of <application>NIRT</application> ray intersecting <emphasis>left_and_right_cubes.r</emphasis> with ray origin backed out of the region.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	Notice that the ray path is now drawn over a much larger area, and multiple 
	colors are used.  The colors have significance; the purple segment in the <application>NIRT</application> ray path 
	corresponds to the empty area or "gap" between the two solid areas.
      </para>
     </section>
     
     <section><info><title>Ray Segment Coloring with <application>NIRT</application> and <application>MGED</application></title></info>
       
       <para>
	 <application>NIRT</application> uses colors to visually represent the information seen
	 in text form in its report.  The conventions are:
	 
	 <informaltable frame="all">
	   <tgroup cols="2" align="center">
	     <tbody>
	       <row><entry><emphasis role="bold">Property</emphasis></entry><entry><emphasis role="bold">Color</emphasis></entry></row>
	       <row><entry>Solid</entry><entry>Alternates between Blue and Yellow</entry></row>
	       <row><entry>Gap</entry><entry>Purple</entry></row>
	       <row><entry>Overlap</entry><entry>White</entry></row>
	     </tbody>
	   </tgroup>
	 </informaltable>
	 
	 To illustrate these outputs, a series of cube configurations will be examined.
	 First, all three are drawn at once, the viewing direction is set to the -x
	 direction, <command>nirt -b</command> is run, and the view is changed to see 
	 the results:

	<literallayout class="monospaced">
mged&gt; B left_cube.r center_cube.r right_cube.r
mged&gt; ae 0 0
mged&gt; nirt -b

Firing from view center...
Origin (x y z) = (6.63 0.00 0.00)  (h v d) = (0.00 0.00 0.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
right_cube.r         (    3.000     0.000     0.000)     2.00    0.000
center_cube.r        (    1.000     0.000     0.000)     2.00    0.000
left_cube.r          (   -1.000     0.000     0.000)     2.00    0.000

mged&gt; ae 90 0
	</literallayout>

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig06.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Side view of aligned individual arb8 cubes with a single <application>NIRT</application> ray passing through all three cubes.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>


	There are three regions present, according to the text report.
	The first region encountered is that associated with <emphasis>right_cube.r</emphasis>, and the
	portion of the ray intersection in that region is light blue.  The second
	region, <emphasis>center_cube.r</emphasis>, has its intersection with the yellow ray.
	Note the color of the intersection in <emphasis>left_cube.r</emphasis> is the same as that 
	shown for <emphasis>right_cube.r</emphasis>.  <emphasis role="bold">It is important to realize that the
	same intersection color in two different areas does NOT imply that they
	are the same region, material, etc.  Nor do different colors guarantee
	that noncontiguous geometric areas are in different regions.</emphasis>  
	The color swap is simply an aid when viewing two different contiguous 
	solid regions that would otherwise be indistinguishable visually.  For example, 
	if all three cubes were unioned into a single region, the wireframe would look 
	identical but the region report would be very different.  In that case, there would be only 
	one region, and only one line color would be needed.  To illustrate:

	<literallayout class="monospaced">
mged&gt; B all_cubes.r
mged&gt; ae 0 0
mged&gt; nirt -b

Firing from view center...
Origin (x y z) = (6.63 0.00 0.00)  (h v d) = (0.00 0.00 0.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
all_cubes.r          (    3.000     0.000     0.000)     6.00    0.000

mged&gt; ae 90 0
	</literallayout>

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig07.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		View of wireframe of three arb8 cubes combined into a single region with a <application>NIRT</application> ray passing through the region on the same path as that used for the individual arb8 cubes. 
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>


	Without the color-changing mechanism, the two previous situations would
	have been visually identical despite having very different properties.

      </para>
      
      <para>
	The other two situations that result in a color change are gaps and overlaps.  
	A gap in <application>NIRT</application> is any area along the ray path 
	<emphasis role="bold">after a solid portion of a region is encountered</emphasis> and 
	<emphasis role="bold">before the last solid portion of a region is encountered</emphasis>
	that does not intersect a region.  As an illustration, casting the same
	ray through just <emphasis>left_cube.r</emphasis> and <emphasis>right_cube.r</emphasis> results in a gap where
	<emphasis>center_cube.r</emphasis> was in the first example in this section:
	
	<literallayout class="monospaced">
mged&gt; B left_cube.r right_cube.r
mged&gt; ae 0 0
mged&gt; nirt -b

Firing from view center...
Origin (x y z) = (6.63 0.00 0.00)  (h v d) = (0.00 0.00 0.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
right_cube.r         (    3.000     0.000     0.000)     2.00    0.000
left_cube.r          (   -1.000     0.000     0.000)     2.00    0.000

mged&gt; ae 90 0
	</literallayout>

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig08.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		View of ray cast through only <emphasis>left_cube.r</emphasis> and <emphasis>right_cube.r</emphasis>.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	
	To illustrate overlaps, both <emphasis>center_cube.r</emphasis> and <emphasis>all_cubes.r</emphasis> are drawn at the same
	time:

	<literallayout class="monospaced">
mged&gt; B all_cubes.r center_cube.r
mged&gt; ae 0 0
mged&gt; nirt -b

Firing from view center...
Origin (x y z) = (6.63 0.00 0.00)  (h v d) = (0.00 0.00 0.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
all_cubes.r          (    3.000     0.000     0.000)     6.00    0.000
OVERLAP: 'center_cube.r' and 'all_cubes.r' xyz_in=(1 0 0) los=2

mged&gt; ae 90 0
	</literallayout>

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig09.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Example of an overlap region in a <application>NIRT</application> ray.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>
	
      </para>
    </section>
    
    <section><info><title>Mouse-Based <application>NIRT</application> Usage</title></info>
      
      <para>
	In addition to providing a <command>nirt</command> command on the <application>MGED</application>
	command	line, there is a mouse-based trigger that can be used.  In the <application>MGED</application> 
	menu, selecting	Settings-&gt;Mouse Behavior-&gt;Query Ray will change the behavior of 
	the mouse. Selecting the view window, placing the mouse at some 
	point over the model, and preforming a click will cast a 
	ray in the view direction, centered at the point under the mouse pointer rather 
	than the view center. 
      </para>
      <para>
	For this example, bring up <emphasis>left_cube.r</emphasis>, <emphasis>center_cube.r</emphasis>, and 
	<emphasis>right_cube.r</emphasis>:
	<literallayout class="monospaced">
mged&gt; B left_cube.r center_cube.r right_cube.r
mged&gt; 
	</literallayout>

	To aid with aiming, the grid overlay is enabled from the menu: 
	Settings-&gt;Grid-&gt;Draw Grid. Grid spacing is adjusted with
	Settings-&gt;Grid Spacing-&gt;Autosize:

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig10.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Grid overlay on <application>MGED</application> wireframe.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	
	With the mouse behavior set to Query Ray, the following results are from casting rays
	at (approximately) the (-2 mm, 0 mm), (0 mm, 0 mm), and (2 mm, 0 mm) grid 
	points:

	<literallayout class="monospaced">
Firing from (-1.992832, -4.000000, -0.028674)...
Origin (x y z) = (-1.99 -10.63 -0.03)  (h v d) = (-1.99 -0.03 4.00)
Direction (x y z) = (-0.0000 1.0000 0.0000)  (az el) = (-90.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
left_cube.r          (   -1.993    -1.000    -0.029)     2.00    0.000

Firing from (0.014337, -4.000000, -0.000000)...
Origin (x y z) = (0.01 -10.63 -0.00)  (h v d) = (0.01 0.00 4.00)
Direction (x y z) = (-0.0000 1.0000 0.0000)  (az el) = (-90.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
center_cube.r        (    0.014    -1.000     0.000)     2.00    0.000

Firing from (2.021505, -4.000000, -0.028674)...
Origin (x y z) = (2.02 -10.63 -0.03)  (h v d) = (2.02 -0.03 4.00)
Direction (x y z) = (-0.0000 1.0000 0.0000)  (az el) = (-90.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
right_cube.r         (    2.022    -1.000    -0.029)     2.00    0.000
	</literallayout>

	Notice the entry points are off from the target values by small but significant amounts.
	A more precise way to do this analysis is to use the "snap to grid" feature.  This feature
	is enabled by selecting	Modes-&gt;Snap To Grid.  Repeating the above ray casts:

	<literallayout class="monospaced">
Firing from (-2.000000, -4.000000, -0.000000)...
Origin (x y z) = (-2.00 -10.63 -0.00)  (h v d) = (-2.00 0.00 4.00)
Direction (x y z) = (-0.0000 1.0000 0.0000)  (az el) = (-90.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
left_cube.r          (   -2.000    -1.000     0.000)     2.00    0.000

Firing from (0.000000, -4.000000, -0.000000)...
Origin (x y z) = (0.00 -10.63 -0.00)  (h v d) = (-0.00 0.00 4.00)
Direction (x y z) = (-0.0000 1.0000 0.0000)  (az el) = (-90.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
center_cube.r        (    0.000    -1.000     0.000)     2.00    0.000

Firing from (2.000000, -4.000000, -0.000000)...
Origin (x y z) = (2.00 -10.63 -0.00)  (h v d) = (2.00 0.00 4.00)
Direction (x y z) = (-0.0000 1.0000 0.0000)  (az el) = (-90.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
right_cube.r         (    2.000    -1.000     0.000)     2.00    0.000
	</literallayout>

	These values are exact thanks to the corrections provided by the snap to grid mode.

      </para>
    </section>

    <section><info><title>Configuring <application>NIRT</application> with the Query Ray Control Panel</title></info>
      

      <para>
	When using <application>NIRT</application> within <application>MGED</application>, some of its settings can be 
	changed	through a graphical dialog found in the menu: 
	<application>MGED</application>'s Tools-&gt;Query Ray Control Panel. This section will describe the basic 
	options.  More advanced settings will be covered later.
      </para>

      <section><info><title>Enabling and Disabling Mouse-Based <application>nirt</application> Ray Casting</title></info>
	
	<para>
	  Earlier, mouse-based <application>NIRT</application> ray casting was enabled via a menu option.  The
	  Query Ray Control Panel offers a more convenient option for toggling the
	  same behavior via the <emphasis role="bold">Mouse Active</emphasis> check box in the lower
	  left corner of the dialog box.  Selecting this check box and clicking 
	  <emphasis role="bold">Apply</emphasis> will activate the mouse as a trigger 
	  for a ray cast. Clearing the <emphasis role="bold">Mouse Active</emphasis> check box and 
	  clicking <emphasis role="bold">Apply</emphasis> will restore the default behavior.

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig11.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel with the <emphasis role="bold">Mouse Active</emphasis> check box circled.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>
	</para>
      </section>

      <section><info><title>Customizing <application>NIRT</application> Coloring in <application>MGED</application></title></info>
	
     
	<para>
	  Although the default colors normally work well, it is possible to adjust the
	  colors used for regions, overlaps, and gaps:

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig12.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel with the <emphasis role="bold">Query Ray Colors</emphasis> circled.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>


	  The <emphasis role="bold">odd</emphasis> and <emphasis role="bold">even</emphasis> colors 
	  correspond to solid areas of regions, <emphasis role="bold">void</emphasis> is a gap 
	  between regions, and <emphasis role="bold">overlap</emphasis> is the color for overlapping regions.  Select a color 
	  by typing in an RGB color designation directly 
	  or using the drop-down menu visible on the right end of each color entry:

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig13.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel with an example color list selected.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	</para>

	<para>
	  If the default color listings are insufficient, the <emphasis role="bold">Color Tool</emphasis> can be used 
	  for more fine-tuned selection:

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig14.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Color Tool
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	</para>
      </section>

      <section><info><title>Customizing the Pseudo-Primitive Base Name</title></info>
	
	<para>
	  <application>MGED</application> and <application>NIRT</application> use "pseudo" primitives to describe the
	  actual graphical lines.  They will not behave like "normal" primitives, but 
	  they do need a name.  By default, these names are the string "query_ray" and the color used for the 
	  string.  For example, the pseudo-primitive list after running <application>NIRT</application> on the cube 
	  example with a gap is given below:

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig08.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Wireframe view of a <application>NIRT</application> ray using multiple colors.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>


	  <literallayout class="monospaced">
mged&gt; who p
query_rayffff00 query_rayffff query_rayff00ff 
	  </literallayout>

	  This naming convention is used almost completely as an internal mechanism
	  by <application>MGED</application> and <application>NIRT</application>.  For example, an <command>l</command>
	  command on <emphasis>query_rayffff</emphasis> does not work:

	  <literallayout class="monospaced">
mged&gt; l query_rayffff
rt_db_get_internal(query_rayffff) failure
	  </literallayout>

	  However, it <emphasis>is</emphasis> possible to use these names to erase the <application>NIRT</application>
	  line segments from the drawing.  For example, to remove the purple line segments from the wireframe, 
	  the command:

	  <literallayout class="monospaced">
mged&gt; erase query_rayff00ff
	  </literallayout>

	  will remove <emphasis>only</emphasis> the purple line segment and leave the others:


	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig15.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Wireframe view of the <application>NIRT</application> ray <emphasis>after</emphasis> erasing <emphasis> query_rayff00ff</emphasis>.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	</para>

	<para>
	  The Query Ray Control Panel also offers a way to customize the base name used
	  for these pseudo-primitives.  Changing the <emphasis role="bold">Base Name</emphasis> from 
	  query_ray to line_segment
	  and rerunning <application>NIRT</application> results in pseudo-primitives named:

       <literallayout class="monospaced">
mged&gt; who p
     line_segmentffff00 line_segmentffff line_segmentff00ff 
	 </literallayout>

 

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig16.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel showing a new  <emphasis role="bold">Base Name</emphasis>.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>
	</para>
      </section>

      <section><info><title>Echoing the Internal <command>nirt</command> Command</title></info>
	
	<para>
	  The <emphasis role="bold">Echo Cmd</emphasis> check box in the <emphasis role="bold">Effects</emphasis>
	  row allows the user to enable/disable
	  the printing of the internal <command>nirt</command> command being run
	  by <application>MGED</application>.  

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig17.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel with the <emphasis role="bold">Echo Cmd</emphasis> check box circled.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>


	  For example, with <emphasis role="bold">Echo Cmd</emphasis> selected, casting a ray into the last example
	  in the previous section results in:

	  <literallayout class="monospaced">
nirt -e fmt r ""; fmt h ""; fmt p ""; fmt m ""; fmt o ""; fmt f ""; fmt g "" -e fmt p
 "%e %e %e %e\n" x_in y_in z_in los -e xyz 4.000000 0.022222 0.011111;dir -1.000000 
-0.000000 0.000000; s -e fmt r "\n" ; fmt p ""; fmt o "%e %e %e %e\n" ov_x_in ov_y_in 
ov_z_in ov_los -e xyz 4.000000 0.022222 0.011111;dir -1.000000 -0.000000 0.000000; s 
-e  fmt r "\nOrigin (x y z) = (%.2f %.2f %.2f)  (h v d) = (%.2f %.2f %.2f)\nDirection 
(x y z) = (%.4f %.4f %.4f)  (az el) = (%.2f %.2f)\n"  x_orig y_orig z_orig h v d_orig 
x_dir y_dir z_dir a e -e fmt h "    Region Name               Entry (x y z)          
    LOS  Obliq_in\n"; fmt p "%-20s (%9.3f %9.3f %9.3f) %8.2f %8.3f\n" reg_name x_in 
y_in z_in los obliq_in; fmt f ""; fmt m "You missed the target\n"; fmt o "OVERLAP: 
'%s' and '%s' xyz_in=(%g %g %g) los=%g\n" ov_reg1_name ov_reg2_name ov_x_in ov_y_in 
ov_z_in ov_los; fmt g "" -e xyz 4.000000 0.022222 0.011111;dir -1.000000 -0.000000 
0.000000; s -b nirt_example.g right_cube.r center_cube.r left_cube.r 

Firing from (4.000000, 0.022222, 0.011111)...
Origin (x y z) = (10.63 0.02 0.01)  (h v d) = (0.02 0.01 4.00)
Direction (x y z) = (-1.0000 -0.0000 0.0000)  (az el) = (0.00 -0.00)
    Region Name               Entry (x y z)              LOS  Obliq_in
right_cube.r         (    3.000     0.022     0.011)     2.00    0.000
center_cube.r        (    1.000     0.022     0.011)     2.00    0.000
left_cube.r          (   -1.000     0.022     0.011)     2.00    0.000
	  </literallayout>

	  This feature is primarily useful for debugging or scripting outside of <application>MGED</application>.

	</para>
      </section>

      <section><info><title>Selecting Graphical and Textual Output</title></info>
	
	<para>
	  By default, <application>NIRT</application> in <application>MGED</application> outputs both graphical
	  and text-based output.  This is reflected in the drop-down menu
	  on the right side of the <emphasis role="bold">Effects</emphasis> row in the Query Ray Control Panel,
	  which is set to <emphasis role="bold">Both</emphasis>.  The other options in the drop-down menu allow
	  the user to specify only <emphasis role="bold">Graphics</emphasis> (no text report is printed)
	  or only <emphasis role="bold">Text</emphasis> (no ray path is drawn in the wireframe.)

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig18.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel with the <emphasis role="bold">Effects</emphasis> drop-down menu shown.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	</para>
      </section>
    </section>
  </section>
  
  <section><info><title>Reporting Options</title></info>
    
    <para> 
      Up until this point, only the default output configuration of 
      <application>NIRT</application> has been used.  Much of the power of 
      <application>NIRT</application> comes from taking that output and changing the format and
      information to supply precisely what is needed for any given purpose.
    </para>

    <section><info><title>How to Change the Reporting Format</title></info>
      
      <para>
	The <emphasis>f</emphasis> option allows <application>NIRT</application> to load 
	customized formatting files that change its reporting style.  In addition 
	to the default style used thus far in this report, <application>NIRT</application> has several 
	built-in options for convenient formatting.  Running <command>nirt -L</command> prints out a list of
	available built-in formats, with a description of each:

	<literallayout class="monospaced">
user@machine ~ $ nirt -L
csv-gap   - Comma Separated Value Output Formatting with Gap Reporting
entryexit - Variation on Standard format that prints Entry and Exit points rather than LOS.
csv       - Comma Separated Value Output Formatting
gap2      - Reporting with Gap input point, output point and LOS
gap1      - Reporting with Gap Input Point and LOS
default   - Standard NIRT Reporting Format
	</literallayout>

        To use a particular format, the name on the left (csv, gap1, etc.) is supplied as an argument to 
	the <emphasis>f</emphasis> flag.
      </para>
      <para>
	For example, cases where data needs to be imported into a 
	spreadsheet can benefit from using comma-separated-variable (csv) output formatting.
	The individual cube regions are loaded and a ray cast:

	<literallayout class="monospaced">
user@machine ~ $ nirt -b -f csv nirt_example.g left_cube.r center_cube.r right_cube.r
BRL-CAD Release 7.13.0  Natalie's Interactive Ray Tracer
    Tue, 26 Aug 2008 23:21:32 -0400, Compilation 2
    user@localhost:/usr/brlcad
Database file:  'nirt_example.g'
Building the directory...
Get trees...
Prepping the geometry...
Objects 'left_cube.r' 'center_cube.r' 'right_cube.r' processed
Database title: 'Example BRL-CAD Database'
Database units: 'mm'
model_min = (-3, -1, -1)    model_max = (3, 1, 1)
nirt&gt;  s
Ray:
x_orig,y_orig,z_orig,d_orig,h,v,x_dir,y_dir,z_dir,az,el
6.63324958,0.00000000,0.00000000,0.00000000,0.00000000,0.00000000,-1.00000000,0.000000... 

Results:
reg_name,path_name,reg_id,x_in,y_in,z_in,d_in,x_out,y_out,z_out,d_out,los,scaled_los,o...
"right_cube.r","/right_cube.r",1002,3.000000,0.000000,0.000000,3.000000,1.000000,0.000...
"center_cube.r","/center_cube.r",1000,1.000000,0.000000,0.000000,1.000000,-1.000000,0....
"left_cube.r","/left_cube.r",1001,-1.000000,0.000000,0.000000,-1.000000,-3.000000,0.00...

	</literallayout>

	The output of the shot command is then copied to a file (for example,
	test.csv) and imported into a spreadsheet:

	<screenshot>
	  <mediaobject><imageobject><imagedata align="center" fileref="../../articles/en/images/nirt_fig19.png"/></imageobject></mediaobject>
	</screenshot>

      </para>

      <para>
	Since copying to a file is impractical in many cases, <application>NIRT</application>
	provides an interactive command called <command>dest</command> which can specify an output
	file.  In the previous case, the test.csv file is created easily:

	<literallayout class="monospaced">
nirt&gt;  dest test.csv
nirt&gt;  s
	</literallayout>

	The file contents match the previous output:

	<literallayout class="monospaced">
Ray:
x_orig,y_orig,z_orig,d_orig,h,v,x_dir,y_dir,z_dir,az,el
6.63324958,0.00000000,0.00000000,0.00000000,0.00000000,0.00000000,-1.00000000,0.000000... 

Results:
reg_name,path_name,reg_id,x_in,y_in,z_in,d_in,x_out,y_out,z_out,d_out,los,scaled_los,o...
"right_cube.r","/right_cube.r",1002,3.000000,0.000000,0.000000,3.000000,1.000000,0.000...
"center_cube.r","/center_cube.r",1000,1.000000,0.000000,0.000000,1.000000,-1.000000,0....
"left_cube.r","/left_cube.r",1001,-1.000000,0.000000,0.000000,-1.000000,-3.000000,0.00...

	</literallayout>

	To restore output to the command line, use <command>dest default</command> to redirect to standard output:

	<literallayout class="monospaced">
nirt&gt;  dest default
	</literallayout>

      </para>
      
      <para>
	  When dealing with spaces between models, it is sometimes advantageous to report
	  gaps in <application>NIRT</application>'s output.  <application>MGED</application>'s 
	  visualization  routines show gaps between regions as purple lines, but
	  the default text report does not include information about gaps.  Sometimes
	  it is desirable to get exact information on gaps, particularly when they
	  represent errors in a model.  The <emphasis>gap1</emphasis> and 
	  <emphasis>gap2</emphasis> formats will include information about gaps.
	  Running <application>NIRT</application> on the <emphasis>left_and_right_cubes.r</emphasis>
	  object with backout enabled provides an example:

	  <literallayout class="monospaced">
user@machine ~ $ nirt -b -f gap2 nirt_example.g left_and_right_cubes.r
BRL-CAD Release 7.13.0  Natalie's Interactive Ray Tracer
    Tue, 26 Aug 2008 23:21:32 -0400, Compilation 2
    user@localhost:/usr/brlcad
Database file:  'nirt_example.g'
Building the directory...
Get trees...
Prepping the geometry...
Object 'left_and_right_cubes.r' processed
Database title: 'Example BRL-CAD Database'
Database units: 'mm'
model_min = (-3, -1, -1)    model_max = (3, 1, 1)
nirt&gt;  s
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
GAP: xyz_in=(1 0 0) xyz_out=(-1 0 0) los=2
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 
	  </literallayout>

	</para>
    </section>
    
    <section><info><title>Handling Attribute Reporting</title></info>
      
      <para>
	The default command line reporting format lists an <emphasis role="bold">Attrib</emphasis> column 
	where attributes may be printed, but does not print any as default output.  Including attributes in a
	<application>NIRT</application> report requires adding attributes in question to the attributes
	table using the <command>attr</command> command.  For example, if the user wants the report to identify
	the <emphasis role="bold">rgb</emphasis> color being used for each region:

	<literallayout class="monospaced">
user@machine ~ $ nirt -b nirt_example.g left_cube_color.r center_cube_color.r right_cube_color.r
nirt&gt;  attr rgb
nirt&gt;  attr -p
"rgb"
nirt&gt;  s

Get trees...
Prepping the geometry...
Objects 'left_cube_color.r' 'center_cube_color.r' 'right_cube_color.r' processed
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
right_cube_color.r   (   3.0000    0.0000    0.0000)   2.0000   0.0000 rgb=255/0/0 
center_cube_color.r  (   1.0000    0.0000    0.0000)   2.0000   0.0000 rgb=0/255/0 
left_cube_color.r    (  -1.0000    0.0000    0.0000)   2.0000   0.0000 rgb=0/0/255 
	</literallayout>

	Notice how the report now includes the <emphasis role="bold">rgb</emphasis> attribute for each region.  The 
	<emphasis>p</emphasis> flag prints the current list of attributes to include.  In the previous case it's 
	simply the "rgb" attribute.  An <emphasis>f</emphasis> option can be supplied to flush all entries and
	clear the table.

	<literallayout class="monospaced">
nirt&gt;  attr -f
nirt&gt;  attr -p
	</literallayout>

	Multiple attributes can also be specified:

	<literallayout class="monospaced">
nirt&gt;  attr rgb region
nirt&gt;  attr -p
"rgb"
"region"
nirt&gt;  s

Get trees...
Prepping the geometry...
Objects 'left_cube_color.r' 'center_cube_color.r' 'right_cube_color.r' processed
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
right_cube_color.r   (   3.0000    0.0000    0.0000)   2.0000   0.0000 rgb=255/0/0 region=R 
center_cube_color.r  (   1.0000    0.0000    0.0000)   2.0000   0.0000 rgb=0/255/0 region=R 
left_cube_color.r    (  -1.0000    0.0000    0.0000)   2.0000   0.0000 rgb=0/0/255 region=R  
	</literallayout>

	If the user wishes to add yet another attribute, it could be appended to the current
	list with another <command>attr</command> command.
      </para>
      <para>
	To provide attributes to the list on startup, the <emphasis>A</emphasis>
	option will add its arguments to the list:

	<literallayout class="monospaced">
user@machine ~ $ nirt -b -A rgb nirt_example.g left_cube_color.r center_cube_color.r right_cube_color.r 
BRL-CAD Release 7.13.0  Natalie's Interactive Ray Tracer
    Mon, 25 Aug 2008 15:14:03 -0400, Compilation 1
    user@localhost:/usr/brlcad
Database file:  'nirt_example.g'
Building the directory...
Get trees...
Prepping the geometry...
Objects 'left_cube_color.r' 'center_cube_color.r' 'right_cube_color.r' processed
Database title: 'Example BRL-CAD Database'
Database units: 'mm'
model_min = (-3, -1, -1)    model_max = (3, 1, 1)
nirt&gt;  s
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000...
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
right_cube_color.r   (   3.0000    0.0000    0.0000)   2.0000   0.0000 rgb=255/0/0 
center_cube_color.r  (   1.0000    0.0000    0.0000)   2.0000   0.0000 rgb=0/255/0 
left_cube_color.r    (  -1.0000    0.0000    0.0000)   2.0000   0.0000 rgb=0/0/255 
	</literallayout>

      </para>
      <note>
	<para>Reporting attributes when running <application>NIRT</application> from within <application>MGED</application> is more involved.  This will be covered later.</para>
      </note>
    </section>

    <section><info><title>Changing Units</title></info>
      
      <para>
	By default <application>NIRT</application>'s interactive command line mode reads and writes all 
	dimensions in millimeters, regardless of the units set in the geometry file.  This is configurable 
	via the <command>units</command> command, which will accept mm, cm, m, in, and ft as arguments or 
	print the current unit with no arguments.  Using <emphasis>center_cube.r</emphasis> as an example:

	<literallayout class="monospaced">
nirt&gt;  units   
units = 'mm'
nirt&gt;  s
Origin (x y z) = (3.46410162 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000 
nirt&gt;  units m
nirt&gt;  s
Origin (x y z) = (0.00346410 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   0.0010    0.0000    0.0000)   0.0020   0.0000 
nirt&gt;  units in
nirt&gt;  s
Origin (x y z) = (0.13638195 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   0.0394    0.0000    0.0000)   0.0787   0.0000 
nirt&gt;  units ft
nirt&gt;  s
Origin (x y z) = (0.01136516 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   0.0033    0.0000    0.0000)   0.0066   0.0000 
	</literallayout>

	When run from within <application>MGED</application> <application>NIRT</application> uses the 
	current units set within the <application>MGED</application> environment.

      </para>
    </section>

  </section>

  <section><info><title>Other Options</title></info>
    
    <para> 
    </para>
    <section><info><title>Silent and Verbose Modes</title></info>
      
      <para>
	<application>NIRT</application> supports two behaviors associated with output verbosity.  
	The interactive command line environment uses the verbose mode 
	by default.  Verbose mode prints out the headers containing information about 
	the BRL-CAD version number, database name, database title, etc. and also 
	provides the "<emphasis role="bold">nirt&gt;</emphasis>" command prompt label.  Silent mode, used by 
	default inside the MGED command window, does not print any headers or prompt label.
      </para>
      <para>
	When generating large numbers of results, it is sometimes desirable to switch to
	silent mode on the command line. This is accomplished by supplying the 
	<emphasis>s</emphasis> option to <command>nirt</command>.  Similarly, in the <application>MGED</application>
	window, supplying the <emphasis>v</emphasis> option will produce the full text 
	output of <application>NIRT</application>'s interactive mode in the <application>MGED</application> window.
      </para>
    </section>
    <section><info><title>Using Air Regions</title></info>
      
      <para>
	Air regions have a special status in BRL-CAD, and by default 
	<application>NIRT</application> does not report them. If the user <emphasis>does</emphasis> wish to
	have air regions reported, the <emphasis>u</emphasis> option is supplied with an
	argument of 1 to activate air region reporting.  This is illustrated with a 
	<emphasis>center_cube_air.r</emphasis> object:

	<literallayout class="monospaced">
user@machine $ nirt -s -b <emphasis role="bold">-u 0</emphasis> -f gap2 nirt_example.g left_and_right_cubes.r center_cube_air.r
s
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
GAP: xyz_in=(1 0 0) xyz_out=(-1 0 0) los=2
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000  


user@machine $ nirt -s -b <emphasis role="bold">-u 1</emphasis> -f gap2 nirt_example.g left_and_right_cubes.r center_cube_air.r
s
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
center_cube_air.r    (   1.0000    0.0000    0.0000)   2.0000   0.0000 
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000

	</literallayout>

	In the first case, area in between the cubes of <emphasis>left_and_right_cubes.r</emphasis> is reported as a 
	gap when gap reporting is enabled. In the second case, <emphasis>center_cube_air.r</emphasis> is treated as a 
	region and a new region report line is generated instead of a gap report.
      </para>

      <para>
	The Query Ray Control Panel also offers a way to select the Use Air option:
<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig20.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel showing the <emphasis role="bold">Use Air</emphasis> check box.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>


	</para>
    </section>
    <section><info><title>Reading an Orientation Matrix and Commands</title></info>
      
      <para>
	This option is seldom used manually from the command line. Its primary purpose is to allow <application>MGED</application>'s <command>saveview</command> command to generate scripts 
	that allow commands run on <application>MGED</application> views to be repeated on the command line.  By default
	the <command>saveview</command> <application>MGED</application> command generates scripts to run 
	<command>rt</command>, so it is necessary to specify <command>nirt</command> with 
	<command>saveview</command>'s <emphasis>e</emphasis> option; for example <command>saveview -e nirt tsv.script</command>.
	Typically the <command>saveview</command> <application>MGED</application> command generates scripts with a few 
	other options included, but the important parts are the orientation matrix and eyepoint:

	<literallayout class="monospaced">
#!/bin/sh
nirt -M  nirt_example.g 'right_cube.r' 'center_cube.r' 'left_cube.r'  &lt;&lt;EOF
orientation 2.480973490458727e-01 4.765905732660485e-01 7.480973490458729e-01 \
            3.894348305183902e-01;
eye_pt 6.000000000000000e+00 4.201245229258262e+00 3.415539237722919e+00;
 	</literallayout>

	When the above script is run, a <application>NIRT</application> report is generated 
	for a ray cast in the same direction as that which would have been cast in 
	the original <application>MGED</application> view where the <command>saveview</command> command was run:

	<literallayout class="monospaced">
machine:~ user$ sh tsv.script
Origin (x y z) = (6.00000000 4.20124523 3.41553924)  (h v d) = (0.0000 0.0000 8.0819)
Direction (x y z) = (-0.74240388 -0.51983679 -0.42261826)  (az el) = (35.00000000 25.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
right_cube.r         (   1.4281    1.0000    0.8130)   0.5767  58.6787 
center_cube.r        (   1.0000    0.7002    0.5693)   2.6940  42.0634 
left_cube.r          (  -1.0000   -0.7002   -0.5693)   0.5767  42.0634 
  	</literallayout>

	Notice the <literal>az</literal> and <literal>el</literal> reported are 35 and 25, which correspond to the 
	settings for those values in <application>MGED</application> when <command>saveview</command> was run.
      </para>
    </section>
  </section>
  
  <section><info><title>Scripting <application>NIRT</application></title></info>
    
    <para> 
      As mentioned in the output formatting section, hand-copying <application>NIRT</application>
      output can be an inconvenient way to store results, particularly in cases where 
      large numbers of rays will be cast.  In such cases, it is possible to automate 
      <application>NIRT</application> usage with scripting.
    </para>
    
    <section><info><title>Command Line Scripts:  The <emphasis>e</emphasis> Option</title></info>
      
      <para>
	The most straightforward approach to supplying <application>NIRT</application> with a 
	series of commands is to do so in a string from the command line using the 
	<emphasis>e</emphasis> option.  The format of such a string is 
	<command>nirt -e "command1; command2; ... commandn" model.g object</command>.
	For example, to cast a ray in the negative z direction and avoid interactive
	mode, the following would work:

	<literallayout class="monospaced">
user@machine ~ $ nirt -b -s -e "dir 0 0 -1; s; q" nirt_example.g all_cubes.r
Origin (x y z) = (0.00000000 0.00000000 6.63324958)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (0.00000000 0.00000000 -1.00000000)  (az el) = (0.00000000 90.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
all_cubes.r          (   0.0000    0.0000    1.0000)   2.0000   0.0000
	</literallayout>
      </para>

      <para>
	It's important to be aware that the order of <emphasis>e</emphasis> and 
	<emphasis>f</emphasis> options matters.  They are read in from left to right 
	and each option is aware of the effects of the previous options. 
	Using the gap format with the <emphasis>left_and_right_cubes.r</emphasis> object, both orders of the 
	<emphasis>e</emphasis> and <emphasis>f</emphasis> options produce different 
	results:

	<literallayout class="monospaced">
user@machine ~ $ nirt -b -s -f gap2 -e "s; q" nirt_example.g left_and_right_cubes.r
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
GAP: xyz_in=(1 0 0) xyz_out=(-1 0 0) los=2
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000

user@machine ~ $ nirt -b -s -e "s; q" -f gap2 nirt_example.g left_and_right_cubes.r
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 

	</literallayout>

	In the second case, the arguments to <emphasis>e</emphasis> were executed before
	the formatting change was reached.  A final illustration of this behavior
	uses multiple instances of the <emphasis>e</emphasis> and <emphasis>f</emphasis>
	options:

	<literallayout class="monospaced">
user@machine ~ $ nirt -b -s -e "s" -f gap2 -e "s; q" nirt_example.g left_and_right_cubes.r
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
GAP: xyz_in=(1 0 0) xyz_out=(-1 0 0) los=2
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 
	</literallayout>

	Notice how the commands in the first <emphasis>e</emphasis> option are run without
	the gap formatting, but the command in the second is run <emphasis>with</emphasis> gap formatting.  
      </para>
    </section>
    
    <section><info><title>Script Files: Other Uses of the <emphasis>f</emphasis> Option</title></info>
      
      <para>
	Earlier, the <emphasis>f</emphasis> option was used to change the output formatting
	of <application>NIRT</application>.  This is only
	one instance of using scripted commands in files to control 
	<application>NIRT</application>. The same principles apply for any command normally 
	available during an interactive <application>NIRT</application> session.
      </para>

      <para>
	Instead of hand-copying the output to a file as was done in the previous example using 
	<filename>tire.g</filename>, a more ambitious goal is to output the results of several 
	different ray casts to a single file without manual copying.
	A script file is defined thus:

	<literallayout class="monospaced">
# testscript: A Scripted NIRT Example
backout 1
dir -1 0 0
s
dir 1 0 0
s
q
	</literallayout>

	Because the intent is to have <emphasis>only</emphasis> the output in the file, the 
	<emphasis>s</emphasis> option is supplied to the <command>nirt</command> command.  The output is
	redirected to a file called <filename>output.txt</filename><footnote><para>These examples use a standard
	POSIX-style output redirect to create the file.  If this doesn't work, the above script can
	be edited to use the <command>dest</command> command instead.</para></footnote>

	<literallayout class="monospaced">
nirt -s -f testscript nirt_example.g left_and_right_cubes.r &gt; output.txt
	</literallayout>

	The contents of that file are the text reports of the two rays cast into the 
	model:

	<literallayout class="monospaced">
Origin (x y z) = (6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (-0.00000000 -0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (   3.0000    0.0000    0.0000)   2.0000   0.0000 
left_and_right_cubes.r (  -1.0000    0.0000    0.0000)   2.0000   0.0000 
Origin (x y z) = (-6.63324958 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (1.00000000 0.00000000 0.00000000)  (az el) = (-180.00000000 -0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
left_and_right_cubes.r (  -3.0000    0.0000    0.0000)   2.0000   0.0000 
left_and_right_cubes.r (   1.0000    0.0000    0.0000)   2.0000   0.0000  
	</literallayout>

	This is useful, but more interesting would be the above output in csv format.
	Fortunately, the <emphasis>f</emphasis> option can be used multiple times in a 
	single <command>nirt</command> run:

	<literallayout class="monospaced">
nirt -s -f csv -f testscript nirt_example.g left_and_right_cubes.r &gt; output.csv
	</literallayout>

	As mentioned in the earlier section when combinations of  
	<emphasis>e</emphasis> and <emphasis>f</emphasis> options were used, using
	multiple instances of the <emphasis>f</emphasis> option in this fashion requires
	paying attention to the left-to-right order.  The csv script in the above case is
	executed before testscript.  The result is the csv equivalent of the preceding file:

	<literallayout class="monospaced">
Ray:
x_orig,y_orig,z_orig,d_orig,h,v,x_dir,y_dir,z_dir,az,el
6.63324958,0.00000000,0.00000000,0.00000000,0.00000000,0.00000000,-1.00000000,0.00000...

Results:
reg_name,path_name,reg_id,x_in,y_in,z_in,d_in,x_out,y_out,z_out,d_out,los,scaled_los,...
"left_and_right_cubes.r","/left_and_right_cubes.r",1004,3.000000,0.000000,0.000000,3....
"left_and_right_cubes.r","/left_and_right_cubes.r",1004,-1.000000,0.000000,0.000000,-...

Ray:
x_orig,y_orig,z_orig,d_orig,h,v,x_dir,y_dir,z_dir,az,el
-6.63324958,0.00000000,0.00000000,0.00000000,0.00000000,0.00000000,1.00000000,0.00000...

Results:
reg_name,path_name,reg_id,x_in,y_in,z_in,d_in,x_out,y_out,z_out,d_out,los,scaled_los,...
"left_and_right_cubes.r","/left_and_right_cubes.r",1004,-3.000000,0.000000,0.000000,3...
"left_and_right_cubes.r","/left_and_right_cubes.r",1004,1.000000,0.000000,0.000000,-1...
	</literallayout>

	As before, this format is trivially imported into a spreadsheet:

	<screenshot>
	  <mediaobject><imageobject><imagedata align="center" fileref="../../articles/en/images/nirt_fig21.png"/></imageobject></mediaobject>
	</screenshot>

      </para>
    </section>
 
    <section><info><title>Defining a Custom Reporting Format</title></info>
      
      <para>
	A final example of the use of the scripting mechanism is constructing a custom-tailored report
	format and specifying it using the <emphasis>f</emphasis> option.  In the case of a
	custom file stored in a user directory, the full file name needs to be supplied
	just like any other script, e.g.,
	<command>nirt -f my_report_format.nrt model.g item</command>.
      </para>
      <para>
	Generally, it is simplest to use one of the predefined files as a
	starting point.  For example, if the user prefers to have commas between
	xyz coordinates, but otherwise wishes to use the default format, the 
	<filename>default.nrt</filename> file from the installed BRL-CAD system is copied to the local 
	directory and renamed <filename>default-commas.nrt</filename>:

	<literallayout class="monospaced">
machine:~ user$ cp /usr/brlcad/share/brlcad/7.12.5/nirt/default.nrt default-commas.nrt

machine:~ user$ more default-commas.nrt   
# default.nrt
# Description: default   - Standard NIRT Reporting Format
fmt r "Origin (x y z) = (%.8f %.8f %.8f)  (h v d) = (%.4f %.4f %.4f)\nDirection (x y z)...
fmt h "    Region Name               Entry (x y z)              LOS  Obliq_in Attrib\n"
fmt p "%-20s (%9.4f %9.4f %9.4f) %8.4f %8.4f %s\n" reg_name x_in y_in z_in los obliq_in...
fmt m "You missed the target\n"
fmt o "OVERLAP: '%s' and '%s' xyz_in=(%g %g %g) los=%g\n" ov_reg1_name ov_reg2_name ov_...

	</literallayout>

	Next, the file is edited to replace all of the spaces in the point strings with
	commas:

	<literallayout class="monospaced">
machine:~ user$ more default-commas.nrt   
fmt r "Origin (x,y,z) = (%.8f,%.8f,%.8f)  (h,v,d) = (%.4f,%.4f,%.4f)\nDirection (x,y,z...
fmt h "    Region Name               Entry (x,y,z)              LOS  Obliq_in Attrib\n"
fmt p "%-20s (%9.4f,%9.4f,%9.4f) %8.4f %8.4f %s\n" reg_name x_in y_in z_in los obliq_i...
fmt f ""
fmt m "You missed the target\n"
fmt o "OVERLAP: '%s' and '%s' xyz_in=(%g,%g,%g) los=%g\n" ov_reg1_name ov_reg2_name ov...
fmt g ""
	</literallayout>

	Running the <emphasis>center_cube.r</emphasis> object:
	
	<literallayout class="monospaced">
machine:~ user$ nirt -s -b -f default-commas.nrt nirt_example.g center_cube.r
s
Origin (x,y,z) = (3.46410162,0.00000000,0.00000000)  (h,v,d) = (0.0000,0.0000,0.0000)
Direction (x,y,z) = (-1.00000000,0.00000000,0.00000000)  (az,el) = (0.00000000,0.00000000)
    Region Name               Entry (x,y,z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000,   0.0000,   0.0000)   2.0000   0.0000 
	</literallayout>

	Notice the commas now present between points.  This file can be saved and 
	reused on any <application>NIRT</application> task.
      </para>

      <note>
	<para>
	  If a user wishes to save the current session configuration of an interactive
	  command line <application>NIRT</application> session at any time,
	  they can always use the <command>dump</command> interactive command to print out a script
	  file that contains all the relevant commands required to restore a
	  specific configuration.  By default this file is called <filename>nirt_state</filename>. 
	  The <command>statefile</command> interactive command is used to change that name if
	  desired.  If a user has used in-session commands to alter formatting, but
	  wants to preserve them for later use or as a starting point for a new
	  report format, the output of <command>dump</command> is an excellent starting
	  point.
	</para>
      </note>

    </section>

    <section><info><title>Customizing Report Output in <application>MGED</application></title></info>
      
      <para>
	The Query Ray Control Panel discussed earlier also provides access to
	the reporting logic used by <application>MGED</application> when calling <application>NIRT</application>, but
	it does not provide any graphical aid when it comes to laying out the
	formatting.  All layout logic must be defined with the same syntax already seen
	for the script files.  Customizations of this logic in <application>MGED</application> are done
	using the <emphasis role="bold">Advanced</emphasis> option in the lower right corner of the Query Ray Control Panel, which
	brings up the following window:

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig22.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		<application>MGED</application>'s Query Ray Control Panel Advanced Settings dialog box.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

	Note also the last line of this dialog box, which provides a place for script
	commands to be executed before the internal <command>s</command> command is run.  It functions
	just like the <emphasis>-e</emphasis> option on the normal command line, including the syntax of
	separating all commands except the last one with semicolons.  This is
	useful for setup not possible in normal command line operation, as illustrated
	in the next section.

      </para>
    </section>

    <section><info><title>Reporting Attributes in <application>MGED</application>:  Advanced Formatting and Scripting</title></info>
      
      <para>
	As mentioned earlier,
	reporting attributes with <application>NIRT</application> inside of <application>MGED</application> is more 
	involved than the strictly command line interface allows.
	In default <application>NIRT</application> reporting inside <application>MGED</application>, the attributes column
	is not even listed.  Attributes <emphasis>can</emphasis> be reported with <application>NIRT</application> in
	<application>MGED</application>, but it requires custom formatting and scripting.
      </para>
      
      <para>
	The first step is to open the Query Ray Advanced Settings dialog box shown in the previous section.
	Examining the default <application>NIRT</application> formatting file used on the command line reveals
	that the partition formatting string needs a <emphasis role="bold">%s</emphasis> variable added and the 
	<emphasis role="bold">attributes</emphasis>
	variable in position to be supplied to the <emphasis role="bold">%s</emphasis>.  Also the 
	<emphasis role="bold">Attrib</emphasis> column header is added to <emphasis role="bold">Head</emphasis>.

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig23.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Query Ray Advanced Settings dialog box showing changes to values (white highlight).
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>
 	
      </para>

      <para>
	The second step is to use the <emphasis role="bold">Script</emphasis> line in this dialog box to add <emphasis role="bold">rgb</emphasis> to the
	attributes list.  Because the script line is run before <application>MGED</application> sends the <command>s</command>
	command, the attributes list will be updated by the time the ray is cast and the subsequent
	report is generated.

	<informalfigure>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="../../articles/en/images/nirt_fig24.png" format="PNG"/>
	    </imageobject>
	    <caption>
	      <para>
		Adding commands to the <emphasis role="bold">Script</emphasis> line in the Advanced Settings dialog.
	      </para>
	    </caption>
	  </mediaobject>
	</informalfigure>

     </para>

      <para>
	Unless graphical visualization is needed, it is probably simpler to work from the <application>NIRT</application>
	interactive command
	line in cases where a lot of adjustment of attribute reporting is needed.  If <application>MGED</application>
	is needed, however, this technique will allow custom reports inside of <application>MGED</application> that include
	attributes.
      </para>

    </section>

    <section><info><title>Available Information for Inclusion in Reports</title></info>
      
      <para>
	There are many cases where the user may want to change <emphasis>what</emphasis>
	<application>NIRT</application>	is reporting, instead of or in addition to the 
	<emphasis>formatting</emphasis> of the reports. <application>NIRT</application> 
	internally defines values that it supports as output options, most of which are
	not reported in the default format for the sake of brevity and clarity.  It also
	defines "events" corresponding to various model geometric states encountered by 
	the ray, which are used to trigger print events:
	
	<informaltable frame="all">
	  <tgroup cols="2" align="center">
	    <colspec colwidth="1in"/>
	    <colspec colwidth="4in"/>
	    <tbody>
	      <row>
		<entry><emphasis role="bold">Event</emphasis></entry>
		<entry><emphasis role="bold">Description</emphasis></entry>
	      </row>
	      <row>
		<entry><emphasis role="bold">r</emphasis></entry>
		<entry><emphasis role="bold">Ray</emphasis>.  A ray is cast.  The formatting associated with r will 
		print regardless of whether a region is encountered.</entry>
	      </row>
	      <row>
		<entry><emphasis role="bold">h</emphasis></entry>
		<entry><emphasis role="bold">Header</emphasis>. First output after a ray hits anything.  Formatting at 
		<emphasis role="bold">h</emphasis> is output once per ray.</entry>
	      </row>
	      <row>
		<entry><emphasis role="bold">p</emphasis></entry>
		<entry><emphasis role="bold">Partition</emphasis>.   Output for each region encountered by the ray.  
		Typically this will be where most of the information about a model is 
		reported.</entry>
	      </row>
	      <row>
		<entry><emphasis role="bold">f</emphasis></entry>
		<entry><emphasis role="bold">Footnote</emphasis>.  Last output statement after a ray hits anything; a 
		"footnote" line after the ray has completed its evaluations;  once per ray.</entry>
	      </row>
	      <row>
		<entry><emphasis role="bold">g</emphasis></entry>
		<entry><emphasis role="bold">Gap</emphasis>.  Output written once for each gap the ray may encounter.
		</entry>
	      </row>
	      <row>
		<entry><emphasis role="bold">m</emphasis></entry>
		<entry><emphasis role="bold">Miss</emphasis>.  If triggered, prints a message that nothing was hit;  
		maximum once per ray.</entry>
	      </row>
	      <row>
		<entry><emphasis role="bold">o</emphasis></entry>
		<entry><emphasis role="bold">Overlap</emphasis>.  Output written once for each overlap along the 
		ray.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	The available variables pertain to the ray, partitions, overlaps, and gaps.  
	Other event options typically use only labeling strings.  The variables are 
	listed in Appendix A and can be used to change reported information.
	The csv output format is one example of such use.
      </para>
    </section>
  </section>

  <section><info><title>Summary</title></info>
    
    <para> 

      <itemizedlist mark="bullet">
        <listitem>
          <para>
	    <application>NIRT</application> is the standard, interactive ray trace query tool used
	    for obtaining precise, detailed information about specific areas of a
	    model via individual ray queries.
          </para>
        </listitem>
        <listitem>
          <para>
	    <application>NIRT</application> offers a wide variety of formatting options for 
	    various analysis needs as well as support for custom formats.
          </para>
        </listitem>
        <listitem>
          <para>
	    Running <application>NIRT</application> within <application>MGED</application> offers additional
	    graphical feedback not available when run outside of <application>MGED</application>.
          </para>
        </listitem>
        <listitem>
          <para>
	    <application>NIRT</application> provides both command-line and file-based scripting
	    to allow for powerful, automated, custom analyses.
          </para>
        </listitem>
      </itemizedlist>
     </para>
  </section>

  <acknowledgements><para>
    The author would like to thank Bob Parker, John Anderson, Janine Gettier, and Christopher
    Sean Morrison for their time and help with explaining some of the more subtle concepts
    encountered by the author during the creation of this report.
  </para></acknowledgements>

  <appendix><info><title>Report Format Variable Listings</title></info>
    
    <para>
    	<informaltable frame="all">
	  <tgroup cols="2" align="center">
	    <colspec colwidth="1in" colname="c1"/>
	    <colspec colwidth="4in" colname="c2"/>
	    <tbody>
	      <row>
		<entry namest="c1" nameend="c2" align="center"><emphasis role="bold">Ray Variables</emphasis></entry>
	      </row>
	      <row>
		<entry>x_orig</entry>
		<entry>x coordinate of ray origination point.</entry>
	      </row>
	      <row>
		<entry>y_orig</entry>
		<entry>y coordinate of ray origination point.</entry>
	      </row>
	      <row>
		<entry>z_orig</entry>
		<entry>z coordinate of ray origination point.</entry>
	      </row>
	      <row>
		<entry>d_orig</entry>
		<entry>d coordinate of ray origination point.</entry>
	      </row>
	      <row>
		<entry>h</entry>
		<entry>h coordinate for the entire ray.</entry>
	      </row>
	      <row>
		<entry>v</entry>
		<entry>v coordinate for the entire ray.</entry>
	      </row>
	      <row>
		<entry>x_dir</entry>
		<entry>x component of direction vector.</entry>
	      </row>
	      <row>
		<entry>y_dir</entry>
		<entry>y component of direction vector.</entry>
	      </row>
	      <row>
		<entry>z_dir</entry>
		<entry>z component of direction vector.</entry>
	      </row>
	      <row>
		<entry>a</entry>
		<entry>azimuth of view (i.e., of ray direction).</entry>
	      </row>
	      <row>
		<entry>e</entry>
		<entry>elevation of view (i.e., of ray direction).</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
	
	<informaltable frame="all">
	  <tgroup cols="2" align="center">
	    <colspec colwidth="1in" colname="c1"/>
	    <colspec colwidth="4in" colname="c2"/>
	    <tbody>
	      <row>
		<entry namest="c1" nameend="c2" align="center"><emphasis role="bold">Partition Variables</emphasis></entry>
	      </row>
	      <row>
		<entry>attributes</entry>
		<entry>A string variable consisting of the names and values of
                       the  attributes requested by the <command>attr</command> interactive command or the -A
                       command line option.</entry>
	      </row>
	      <row>
		<entry>x_in</entry>
		<entry>x coordinate of entry into current region.</entry>
	      </row>
	      <row>
		<entry>y_in</entry>
		<entry>y coordinate of entry into current region.</entry>
	      </row>
	      <row>
		<entry>z_in</entry>
		<entry>z coordinate of entry into current region.</entry>
	      </row>
	      <row>
		<entry>d_in</entry>
		<entry>d coordinate of entry into current region.</entry>
	      </row>
	      <row>
		<entry>x_out</entry>
		<entry>x coordinate of exit from current region.</entry>
	      </row>
	      <row>
		<entry>y_out</entry>
		<entry>y coordinate of exit from current region.</entry>
	      </row>
	      <row>
		<entry>z_out</entry>
		<entry>z coordinate of exit from current region.</entry>
	      </row>
	      <row>
		<entry>d_out</entry>
		<entry>d coordinate of exit from current region.</entry>
	      </row>
	      <row>
		<entry>los</entry>
		<entry>line-of-sight distance through current region.</entry>
	      </row>
	      <row>
		<entry>scaled_los</entry>
		<entry>scaled  line  of  sight:   product   of   line-of-sight
                       distance  through  current  region  and region solidity<footnote><para>
		       Region solidity refers to a thickness equivalence factor often used to simulate
		       material properties like density.</para></footnote>
		       (sometimes called ``percent LOS'').</entry>
	      </row>
	      <row>
		<entry>path_name</entry>
		<entry>full path name of current region.</entry>
	      </row>
	      <row>
		<entry>reg_name</entry>
		<entry>name of current region</entry>
	      </row>
	      <row>
		<entry>reg_id</entry>
		<entry>region ID of current region.</entry>
	      </row>
	      <row>
		<entry>claimant_count</entry>
		<entry>number of regions claiming  this  partition  (that  is,
                       participating in a retained overlap).</entry>
	      </row>
	      <row>
		<entry>claimant_list</entry>
		<entry>space-separated list of names of regions claiming  this
                       partition   (that   is,  participating  in  a  retained
                       overlap).</entry>
	      </row>
	      <row>
		<entry>claimant_listn</entry>
		<entry>Same as claimant_list,  except  that  it  is  newline-,
                       rather than space-separated.</entry>
	      </row>
	      <row>
		<entry>obliq_in</entry>
		<entry>entry obliquity for current region.</entry>
	      </row>
	      <row>
		<entry>obliq_out</entry>
		<entry>exit obliquity for current region.</entry>
	      </row>
	      <row>
		<entry>nm_x_in</entry>
		<entry>x component of entry normal vector</entry>
	      </row>
	      <row>
		<entry>nm_y_in</entry>
		<entry>y component of entry normal vector</entry>
	      </row>
	      <row>
		<entry>nm_z_in</entry>
		<entry>z component of entry normal vector</entry>
	      </row>
	      <row>
		<entry>nm_h_in</entry>
		<entry>h component of entry normal vector</entry>
	      </row>
	      <row>
		<entry>nm_v_in</entry>
		<entry>v component of entry normal vector</entry>
	      </row>
	      <row>
		<entry>nm_d_in</entry>
		<entry>d component of entry normal vector</entry>
	      </row>
	      <row>
		<entry>nm_x_out</entry>
		<entry>x component of exit normal vector</entry>
	      </row>
	      <row>
		<entry>nm_y_out</entry>
		<entry>y component of exit normal vector</entry>
	      </row>
	      <row>
		<entry>nm_z_out</entry>
		<entry>z component of exit normal vector</entry>
	      </row>
	      <row>
		<entry>nm_h_out</entry>
		<entry>h component of exit normal vector</entry>
	      </row>
	      <row>
		<entry>nm_v_out</entry>
		<entry>v component of exit normal vector</entry>
	      </row>
	      <row>
		<entry>nm_d_out</entry>
		<entry>d component of exit normal vector</entry>
	      </row>
	      <row>
		<entry>surf_num_in</entry>
		<entry>entry-surface ID of entry solid.</entry>
	      </row>
	      <row>
		<entry>surf_num_out</entry>
		<entry>exit-surface ID of exit solid.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<informaltable frame="all">
	  <tgroup cols="2" align="center">
	    <colspec colwidth="1in" colname="c1"/>
	    <colspec colwidth="4in" colname="c2"/>
	    <tbody>
	      <row>
		<entry namest="c1" nameend="c2" align="center"><emphasis role="bold">Overlap Variables</emphasis></entry>
	      </row>
	      <row>
		<entry>ov_reg1_name</entry>
		<entry>name of one of the overlapping regions.</entry>
	      </row>
	      <row>
		<entry>ov_reg2_name</entry>
		<entry>name of the other overlapping region.</entry>
	      </row>
	      <row>
		<entry>ov_reg1_id</entry>
		<entry>region ID of one of the overlapping regions.</entry>
	      </row>
	      <row>
		<entry>ov_reg2_id</entry>
		<entry>region ID of the other overlapping region.</entry>
	      </row>
	      <row>
		<entry>ov_sol_in</entry>
		<entry>name of one of the overlapping solids.</entry>
	      </row>
	      <row>
		<entry>ov_sol_out</entry>
		<entry>name of the other overlapping solid.</entry>
	      </row>
	      <row>
		<entry>ov_los</entry>
		<entry>line-of-sight distance through the overlap.</entry>
	      </row>
	      <row>
		<entry>ov_x_in</entry>
		<entry>x coordinate of entry into overlap.</entry>
	      </row>
	      <row>
		<entry>ov_y_in</entry>
		<entry>y coordinate of entry into overlap.</entry>
	      </row>
	      <row>
		<entry>ov_z_in</entry>
		<entry>z coordinate of entry into overlap.</entry>
	      </row>
	      <row>
		<entry>ov_d_in</entry>
		<entry>d coordinate of entry into overlap.</entry>
	      </row>
	      <row>
		<entry>ov_x_out</entry>
		<entry>x coordinate of exit from overlap.</entry>
	      </row>
	      <row>
		<entry>ov_y_out</entry>
		<entry>y coordinate of exit from overlap.</entry>
	      </row>
	      <row>
		<entry>ov_z_out</entry>
		<entry>z coordinate of exit from overlap.</entry>
	      </row>
	      <row>
		<entry>ov_d_out</entry>
		<entry>d coordinate of exit from overlap.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<informaltable frame="all">
	  <tgroup cols="2" align="center">
	    <colspec colwidth="1in" colname="c1"/>
	    <colspec colwidth="4in" colname="c2"/>
	    <tbody>
	      <row>
		<entry namest="c1" nameend="c2" align="center"><emphasis role="bold">Gap Variables</emphasis></entry>
	      </row>
	      <row>
		<entry>x_gap_in</entry>
		<entry>x coordinate of entry into gap.</entry>
	      </row>
	      <row>
		<entry>y_gap_in</entry>
		<entry>y coordinate of entry into gap.</entry>
	      </row>
	      <row>
		<entry>z_gap_in</entry>
		<entry>z coordinate of entry into gap.</entry>
	      </row>
	      <row>
		<entry>gap_los</entry>
		<entry>line-of-sight distance through gap.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>  
    </para>
  </appendix>

  <appendix><info><title>Debugging Options</title></info>
    
    <para>
      In cases where problems are being encountered, it is possible to use
      debugging options to print additional information related to the raytracing
      process.  <application>NIRT</application> exposes two levels of debugging: 
      the core raytracing library and <application>NIRT</application> itself.
    </para>
    <section><info><title>librt Debugging Information</title></info>
      
      <para>
	In cases where detailed behavior of the core raytracing routines is of interest,
	it is possible to use the <emphasis>x</emphasis> (lower case "x") option to print
	additional diagnostic messages.<footnote><para>librt's diagnostic setting can also be set in 
	the interactive environment with the <command>libdebug</command> command.</para></footnote>
	See the <emphasis role="bold">librt</emphasis> header files for more detail about
	the very extensive debugging options provided.

	<literallayout class="monospaced">
machine:~ user$ nirt -s -b -x 0x002 -e "s; q" nirt_example.g center_cube.r

  **********shootray cpu=0  0,0 lvl=0 a_onehit=0 (NIRT ray)
  Pnt (3.4641016151377543864, 0, 0)
  Dir (-1, 0, 0)
    ------Partition list passed to a_hit() routine
    00604d50: PT center_cube.s (ARB8#0) center_cube.s (ARB8#0) (2.4641,4.4641)
      InHIT dist=2.4641 (surf 5)
     OutHIT dist=4.4641 (surf 4)
      Primitives: center_cube.s, 
      Untrimmed Segments spanning this interval:
        0680d600: SEG center_cube.s (2.4641,4.4641) st_bit=0 xray#=0
      Region: /center_cube.r
  ------
Origin (x y z) = (3.46410162 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000 
----------shootray cpu=0  0,0 lvl=0 (NIRT ray) HIT ret=1

	</literallayout>


      </para>
    </section>
    <section><info><title><application>NIRT</application> Debugging Information</title></info>
      
      <para>
	<application>NIRT</application> itself also provides debugging information. It is accessed using
	the <emphasis>X</emphasis> option.<footnote><para>The <command>nirt</command> level diagnostics can be set in 
	the interactive environment with the <command>debug</command> command.</para></footnote> 
	<application>NIRT</application> provides five different debug flags, as seen in <filename>nirt.h</filename>:

	<literallayout class="monospaced">
/** FLAG VALUES FOR nirt_debug */
#define DEBUG_INTERACT  0x001
#define DEBUG_SCRIPTS   0x002
#define DEBUG_MAT       0x004
#define DEBUG_BACKOUT   0x008
#define DEBUG_HITS      0x010
	</literallayout>

	0x001 and 0x002 pertain to interaction and scripts, respectively:

	<literallayout class="monospaced">
machine:~ user$ nirt -s -b <emphasis role="bold">-X 0x001</emphasis> -e "s; q" nirt_example.g center_cube.r
interact(READING_STRING, 603c10)...
sgetc((null)) '(null)' '(null)'... initializing
sgetc(s; q) '(null)' '(null)'... initializing
returning 's' (o163)
line_buffer[0] = 's' (o163)
sgetc(s; q) 's; q' '; q'... returning ';' (o73)
Line buffer contains 's'
Origin (x y z) = (3.46410162 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000 
sgetc(s; q) 's; q' ' q'... returning ' ' (o40)
Skipping ' '
sgetc(s; q) 's; q' 'q'... returning 'q' (o161)
line_buffer[0] = 'q' (o161)
sgetc(s; q) 's; q' ''... returning EOS
Line buffer contains 'q'



machine:~ user$ nirt -s -b <emphasis role="bold">-X 0x002</emphasis> -e "s; q" nirt_example.g center_cube.r
interact(READING_STRING, 603c10)...
sgetc((null)) '(null)' '(null)'... initializing
sgetc(s; q) '(null)' '(null)'... initializing
returning 's' (o163)
line_buffer[0] = 's' (o163)
sgetc(s; q) 's; q' '; q'... returning ';' (o73)
Line buffer contains 's'
Origin (x y z) = (3.46410162 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000 
sgetc(s; q) 's; q' ' q'... returning ' ' (o40)
Skipping ' '
sgetc(s; q) 's; q' 'q'... returning 'q' (o161)
line_buffer[0] = 'q' (o161)
sgetc(s; q) 's; q' ''... returning EOS
Line buffer contains 'q'
user@localhost $ nirt -s -b -X 0x002 -e "s; q" nirt_example.g center_cube.r
- - - - - - - The command-line scripts - - - - - - -
1. script string 's; q'
- - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - The command-line scripts - - - - - - -
1. script string 's; q'
- - - - - - - - - - - - - - - - - - - - - - - - - -
  Attempting to run literal 's; q'
Origin (x y z) = (3.46410162 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000 
	</literallayout>

	The 0x004 DEBUG_MAT flag pertains to the <emphasis>M</emphasis> option seen earlier
	in the <command>saveview</command> <application>MGED</application> command example
	that supplies a matrix for <application>NIRT</application> to read.  Adding the
	debug option to the script triggers a printout of the matrix:

	<literallayout class="monospaced">
#!/bin/sh
nirt -M <emphasis role="bold">-X 0x004</emphasis> nirt_example.g center_cube.r &lt;&lt;EOF
orientation 5.000000000000000e-01 5.000000000000001e-01 5.000000000000000e-01 4.999999999999999e-01;
eye_pt 0.000000000000000e+00 0.000000000000000e+00 0.000000000000000e+00;
	</literallayout>

	<literallayout class="monospaced">
machine:~ user$ sh tsv.script 
MATRIX view matrix:
     -0.000    1.000    0.000    0.000
      0.000    0.000    1.000    0.000
      1.000    0.000   -0.000    0.000
      0.000    0.000    0.000    1.000
Origin (x y z) = (0.00000000 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 -0.00000000 0.00000000)  (az el) = (0.00000000 -0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000   -0.0000)   2.0000   0.0000
	</literallayout>

	DEBUG_BACKOUT and DEBUG_HITS pertain to the backout option and geometry hits:
	
	<literallayout class="monospaced">

machine:~ user$ nirt -s -b -X 0x008 -e "s; q" nirt_example.g center_cube.r
Backing out 3.4641 units to (3.4641 0 0), shooting dir is (-1 0 0)
Origin (x y z) = (3.46410162 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000

machine:~ user$ nirt -s -b -X 0x010 -e "s; q" nirt_example.g center_cube.r
Origin (x y z) = (3.46410162 0.00000000 0.00000000)  (h v d) = (0.0000 0.0000 0.0000)
Direction (x y z) = (-1.00000000 0.00000000 0.00000000)  (az el) = (0.00000000 0.00000000)
    Region Name               Entry (x y z)              LOS  Obliq_in Attrib
Partition 1 entry: (1, 0, 0) exit: (-1, 0, 0)
center_cube.r        (   1.0000    0.0000    0.0000)   2.0000   0.0000 

	</literallayout>
      </para>
    </section>

  </appendix>
</article>
