RESHOOT(1)

NAME

reshoot - re-shoot a list of rays and compare results to a previous run

On this page

SYNOPSIS
DESCRIPTION
EXAMPLES
BUGS
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

reshoot _geom.g_ [_obj_ ...] < _rayfile_

reshoot re-shoots a set of previously recorded rays against the geometry database geom.g and compares the results to the values recorded for each ray. It is geared towards regression testing of the BRL-CAD ray tracing libraries. If one or more obj arguments are given they select the object trees to prepare. If no obj arguments are given, reshoot uses a deterministic database default object. Object omission succeeds only when that resolver finds a single usable geometry object, such as a valid _GLOBAL default_object attribute, exactly one top-level geometry object, exactly one combination, exactly one combination matching the database filename, or exactly one top-level combination whose name begins with all or scene. If default selection is disabled, names an unusable geometry object, is ambiguous, or has no deterministic match, reshoot prints the resolver’s explanation, a list of available top-level objects, and exits with "no objects specified."

Differences are reported to standard error as they are found, and reshoot exits with a non-zero status if any ray result differs from its recorded value, or 0 if all results match.

The list of rays is read from standard input. Each ray begins with a Pnt line giving its origin and a Dir line giving its direction, followed by one region line for each region the ray was expected to cross. The three coordinate values of Pnt and Dir must be comma-separated with no embedded whitespace, and the Pnt and Dir keywords must start their lines. A new Pnt keyword begins the next ray, so any number of rays may appear in the file.

The recorded ray file is normally produced from a candidate application (for example rt(1)) that is run with the RT_G_DEBUG flag DEBUG_ALLHITS set. That flag causes librt to log every call to the application hit routine, together with the contents of each struct partition, on standard error. The verbose log is then reduced to reshoot input with an awk(1) program. A suitable p.awk is:

/Pnt/ { START=index($0,"(") + 1
        STR=substr($0, START, index($0,")") - START)
        gsub(  ", "  , "," , STR)
        printf "Pnt=%s\n",STR
        }
/Dir/ { START=index($0,"(") + 1
        STR=substr($0, START, index($0,")") - START)
        gsub(  ", "  , "," , STR)
        printf "Dir=%s\n",STR
        }
/PT/  { PIN=$3; POUT=$5 }
/InHIT/ { INHIT=$2 }
/OutHIT/ { OUTHIT=$2 }
/Region/ { printf "\tregion=%s in=%s in%s out=%s out%s\n",
        $2,PIN,INHIT,POUT,OUTHIT
        }

The resulting input file looks like:

Pnt=0,0,1
Dir=0,0,-1
	region=r1.r in=p1.s indist=10016.8 out=p2.s outdist=10017.8
	region=r2.r in=p3.s indist=10018.8 out=p4.s outdist=10019.8
Pnt=0,0,10
Dir=0,0,-1
	region=r1.r in=p1.s indist=10016.8 out=p2.s outdist=10017.8

For each ray that disagrees, reshoot prints the ray’s point and direction followed by one or more mismatch lines describing the inhit distance, outhit distance, region name, or in/out primitive name that did not match.

EXAMPLES

Example 1. Capture rays from rt and verify them with reshoot

rt -x 2 -o /dev/null geom.g all.g 2> log
awk -f p.awk < log > shotlist
reshoot geom.g all.g < shotlist
echo "exit status: $?"

Running rt(1) with the DEBUG_ALLHITS debug bit (-x 2) records every hit to the file log, which p.awk distills into the ray list shotlist. Feeding that list back into reshoot re-traces the same rays and reports any result that changed. A non-zero exit status signals that the geometry or the ray tracer now produces different intersections, making this a convenient regression check after editing a model or modifying librt.

Example 2. Use the database default object when it can be inferred

rt -x 2 -o /dev/null single.g 2> log
awk -f p.awk < log > shotlist
reshoot single.g < shotlist

When single.g has a resolvable default object, the omitted object list in both commands selects that same object. If the database has no usable default, or has several plausible defaults and no explicit _GLOBAL default_object attribute, name the object explicitly; otherwise reshoot fails before reading the ray list because no geometry was prepared.

BUGS

The floating point values logged when the DEBUG_ALLHITS flag is set in RT_G_DEBUG are printed with a %g format, which truncates precision. reshoot compensates by re-formatting its own computed numbers to ascii and re-parsing them, so they suffer the same precision loss as the recorded values. As a side effect, small genuine differences can be overlooked.