NAME

nirt_formatting - DRAFT!!! Document supported output formatting specifications for Natalie's Interactive RayTracer (NIRT)

OVERVIEW

One of the most powerful features of Natalie's Interactive RayTracer (NIRT) is the ability to support user-defined output formatting for its outputs. The fmt command allows on-the-fly alteration of what and how various values generated by shotline intersections, using a subset of the C/C++ printf format specifier syntax for flexibile template specification and a series of pre-defined keys to specify individual elements of generated results. The general form of a fmt command is:

fmt 'char' "format string" [keys...]

where the "char" argument is replaced by a single character identifying the category of output the format string applies. The "format string" is the printf style formatting string, and the keys will line up with format specifiers in the string the same way variables in C/C++ line up with specifiers in a printf format string.

OUTPUT CATEGORIES

NIRT offers seven categories of output reporting:

Category Name	Char	Description
Ray	r	Report of ray information. The formatting associated with r will print once per ray, regardless of whether a region is encountered.
Header	h	First output after a ray hits anything, typically used to identify columns in subsequent output. Printed once per ray.
Partition	p	Output for each region encountered by the ray. Typically this will be where most of the information about a model is reported.
Footnote	f	Last output statement after a ray hits anything; a "footnote" line after the ray has completed its evaluations. Printed once per ray.
Gap	g	Output written once for each gap the ray may encounter.
Miss	m	If triggered, prints a message that nothing was hit; maximum once per ray.
Overlap	o	Output written once for each overlap along the ray.

FORMAT STRINGS

NIRT's format specifications are a subset of those found in printf implementations. Specifically, the d, i, and f types are supported, as well as width and precision specifiers.

REPORTING KEYS - CONNECTING DATA TO FORMAT STRINGS

Unlike the full C/C++ printf, NIRT accepts only pre-defined string keys that identify elements of specific information related to each cateogry of output. Ray information is consistent over an entire shot event, and therefore Ray keys may be used in all categories:

Table 1. Ray Variables

x_orig	x coordinate of ray origination point.
a	azimuth of view (i.e., of ray direction).
e	elevation of view (i.e., of ray direction).
y_orig	y coordinate of ray origination point.
z_orig	z coordinate of ray origination point.
d_orig	d coordinate of ray origination point.
h	h coordinate for the entire ray.
v	v coordinate for the entire ray.
x_dir	x component of direction vector.
y_dir	y component of direction vector.
z_dir	z component of direction vector.

Footnote and Miss categories have no particular keys unique to them, although they (like all categories) can use the Ray keys if desired. Partition, Overlap, and Gap, on the other hand, have keys that are unique to their contexts and valid only within those contexts:

Table 2. Partition Variables

attributes	A string variable consisting of the names and values of the attributes requested by the attr interactive command or the -A command line option.
los	line-of-sight distance through current region.
scaled_los	scaled line of sight: product of line-of-sight distance through current region and region solidity (sometimes called ``percent LOS''). Note that "region solidity" refers to a thickness equivalence factor often used to simulate material properties like density.
path_name	full path name of current region.
reg_name	name of current region
reg_id	region ID of current region.
claimant_count	number of regions claiming this partition (that is, participating in a retained overlap).
claimant_list	space-separated list of names of regions claiming this partition (that is, participating in a retained overlap).
claimant_listn	Same as claimant_list, except that it is newline, rather than space-separated.
obliq_in	entry obliquity for current region.
obliq_out	exit obliquity for current region.
x_in	x coordinate of entry into current region.
nm_x_in	x component of entry normal vector
nm_y_in	y component of entry normal vector
nm_z_in	z component of entry normal vector
nm_h_in	h component of entry normal vector
nm_v_in	v component of entry normal vector
nm_d_in	d component of entry normal vector
nm_x_out	x component of exit normal vector
nm_y_out	y component of exit normal vector
nm_z_out	z component of exit normal vector
nm_h_out	h component of exit normal vector
y_in	y coordinate of entry into current region.
nm_v_out	v component of exit normal vector
nm_d_out	d component of exit normal vector
surf_num_in	entry-surface ID of entry solid.
surf_num_out	exit-surface ID of exit solid.
z_in	z coordinate of entry into current region.
d_in	d coordinate of entry into current region.
x_out	x coordinate of exit from current region.
y_out	y coordinate of exit from current region.
z_out	z coordinate of exit from current region.
d_out	d coordinate of exit from current region.

Table 3. Overlap Variables

ov_reg1_name	name of one of the overlapping regions.
ov_z_in	z coordinate of entry into overlap.
ov_d_in	d coordinate of entry into overlap.
ov_x_out	x coordinate of exit from overlap.
ov_y_out	y coordinate of exit from overlap.
ov_z_out	z coordinate of exit from overlap.
ov_d_out	d coordinate of exit from overlap.
ov_reg2_name	name of the other overlapping region.
ov_reg1_id	region ID of one of the overlapping regions.
ov_reg2_id	region ID of the other overlapping region.
ov_sol_in	name of one of the overlapping solids.
ov_sol_out	name of the other overlapping solid.
ov_los	line-of-sight distance through the overlap.
ov_x_in	x coordinate of entry into overlap.
ov_y_in	y coordinate of entry into overlap.

Table 4. Gap Variables

x_gap_in	x coordinate of entry into gap.
y_gap_in	y coordinate of entry into gap.
z_gap_in	z coordinate of entry into gap.
gap_los	line-of-sight distance through gap.