RESHOOT(1)

🎀 RESHOOT(1) 🎀

ok so bestie, welcome to reshoot — it lives in the BRL-CAD manual set and it is literally the regression-testing bestie of the BRL-CAD ray tracing libraries. let's get into it 💅

✨ NAME ✨

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

✨ SYNOPSIS ✨

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

✨ DESCRIPTION ✨

okay so reshoot re-shoots a whole set of previously recorded rays against the geometry database _geom.g_ and then compares the results to the values that were recorded for each ray. it's geared towards regression testing of the BRL-CAD ray tracing libraries, which is honestly iconic of it 👑

if you pass one or more _obj_ arguments, those select the object trees to prepare. if you pass no _obj_ arguments, reshoot uses a deterministic database default object. and omitting objects only works when that resolver finds a single usable geometry object, like:

• a valid _GLOBAL default_object attribute
• exactly one top-level geometry object
• exactly one combination
• exactly one combination matching the database filename
• exactly one top-level combination whose name begins with all or scene

if default selection is disabled, or it names an unusable geometry object, or it's ambiguous, or there's no deterministic match, then reshoot prints the resolver's explanation plus a list of available top-level objects, and exits with "no objects specified." 😭 rude but fair.

differences get reported to standard error as they're found, and reshoot exits with a non-zero status if any ray result differs from its recorded value, or 0 if all results match. vibe check: zero means slay, non-zero means something changed 💀

---

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. no cap 🫶

the recorded ray file is normally produced from a candidate application (for example rt(1)) that's 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 then gets 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. it's giving detective energy 🔍

🌸 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. obsessed with the workflow honestly 💖

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. so like... be specific, bestie 😌

💀 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 🙈

⚠️ so yeah — precision ghosting is real. tiny real differences might just slip by unnoticed.

🌈 SEE ALSO 🌈

brlcad(1), rt(1), nirt(1) — go read those too, iykyk ✨

👑 AUTHOR 👑

BRL-CAD Team 🫶

🎀 COPYRIGHT 🎀

This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.

🦋 BUG REPORTS 🦋

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org 📧

---

okay that's the whole page, bestie — this was BRL-CAD's RESHOOT(1), brought to you with love, glamour, and zero lost details 💜🧚‍♀️⭐