RTSHOT(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

🌈 RTSHOT — the manual page for BRL-CAD's single-ray icon 💅

okay so bestie, welcome to rtshot(1) — the BRL-CAD manual page that's literally about shooting one ray and telling you everything it smooched on the way through. no cap, it's the most main-character little tool in the whole suite. let's get into it 🎀

✨ NAME ✨

rtshot — fire a single ray at a BRL-CAD model and report what it hits ⭐

🦋 SYNOPSIS 🦋

rtshot {-p|-d|-a} _x_ _y_ _z_ {-p|-d|-a} _x_ _y_ _z_ [options] model.g [objects...]

💖 DESCRIPTION 💖

so rtshot fires one single ray at the objects you list inside the BRL-CAD database model.g, and then prints a textual summary of every region the ray passes through — the in and out hit points, surface normals, surface curvature, the regions claiming stuff for any overlaps, and optionally whatever region attributes you asked for. it's giving "x-ray vision but make it text" 🔥

if you don't name any objects, rtshot will attempt to use a deterministic database default object. and omitting objects only works when that resolver finds exactly one 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, or exactly one top-level combination whose name begins with all or scene. 🙈

heads up bestie: if default selection is disabled, if you name an unusable geometry object, if it's ambiguous, or if there's just no deterministic match — rtshot prints the resolver's explanation and exits with "no objects specified." 💀

now the ray itself: you define it by supplying exactly two of these three options — a start point (-p), a direction vector (-d), and a point to shoot "at" (-a). when -a is combined with -d, the start point is backed off from the "at" point by half the model diagonal so the ray begins outside the geometry. and the direction vector is always normalized. always always. 🫶

rtshot is a thin front-end to librt(3) intended for inspecting and debugging geometry — it's literally the command-line analog of the ray that a single pixel of rt(1) would cast. iconic behavior honestly 👑

🌸 OPTIONS 🌸

  • -p _x_ _y_ _z_ — set the ray starting point.
  • -d _x_ _y_ _z_ — set the ray direction vector (it gets normalized before use, don't worry).
  • -a _x_ _y_ _z_ — set the point the ray is fired "at".
  • -U _#_ — set reporting of air regions. the default is 1 (air is reported).
  • -o _#_ — set the onehit flag, stopping the ray after the given number of hits (0, which is the default, means no limit).
  • -r _#_ — set the maximum ray length, in millimeters. the default of 0 means unlimited.
  • -O _keyword_ — set overlap-claimant handling. accepts a keyword or its numeric equivalent:
    • resolve (or 0, the default) — resolves all overlaps so none appear in the output
    • rebuild_fastgen (or 1) — mimics FASTGEN4 plate-mode behavior
    • rebuild_all (or 2) — rebuilds and reports every overlap along the ray
    • retain (or 3) — does not resolve overlaps
  • -v "attr1 attr2 ..." — report the listed region attribute names (and their values) for each region hit. the names are given as a single space-separated string. 🍓
  • -A _name_ — report, for each region carrying the named attribute, the hit points and ray direction transformed into that region's local (untransformed) coordinate system via the inverse of its placement matrix.
  • -n _#_ — set the number of rings to use for a ray bundle (the central ray is not counted).
  • -c _#_ — set the number of rays per ring for a ray bundle. the rings spiral outward and are not aligned ring-to-ring; a central ray is always included.
  • -R _#_ — set the ray bundle radius, in millimeters. the outermost ring lies at this radius.
  • -g _#_ — set the grid spacing, in millimeters, for a circular-grid ray bundle (the default is 1mm).
  • -u _#_ — set the libbu(3) debug flags (hexadecimal).
  • -x _#_ — set the librt(3) debug flags (hexadecimal).
  • -X _#_ — set the optical/rt program debug flags (hexadecimal). setting the ray-plot bit writes a plot of the ray and its hits to rtshot.plot3. 🎀
  • -N _#_ — set the NMG debug flags (hexadecimal).

💜 RAY BUNDLES, THE VIBE CHECK 💜

a ray bundle can be cast in two ways, bestie, pick your fighter:

  1. supplying both -n and -c (with an optional -R radius) fires a spiral ring bundle whose results are merged as a single ray.
  2. supplying only -R (with an optional -g grid spacing) fires a circular grid of parallel rays.

the default is to fire a single ray. just one. solo. main character energy ✨

🔥 EXAMPLES 🔥

Example 1. Fire a ray down the X axis at a component

rtshot -p 0 0 0 -d 1 0 0 havoc.g hull

shoots a single ray from the origin in the +X direction at the hull region of havoc.g, printing the in/out points and normals of each region encountered. slay 💅

Example 2. Aim at a known point and list a material attribute

rtshot -a -1000 0 500 -d -1 0 0 -v "material_id" model.g engine

fires a ray toward the point (-1000, 0, 500) heading in the -X direction, with the start point automatically placed outside the geometry, and prints the material_id attribute of every region the ray strikes. this is a quick way to verify which components and materials lie along a line of sight. lowkey the most useful thing ever 👀

Example 3. Use the database default object

rtshot -p 0 0 0 -d 1 0 0 single.g

shoots the ray at single.g's automatically selected default object. this form is valid only when the database default-object rules resolve exactly one usable object. in a database with multiple top-level candidates and no explicit _GLOBAL default_object, name the intended object after model.g. no shortcuts, bestie 😤

🧚 SEE ALSO 🧚

brlcad(1), mged(1), rt(1), rtarea(1), nirt(1), librt(3), plot3(5)

😭 DIAGNOSTICS 😭

numerous error conditions are possible. descriptive messages are printed on standard error. that's it, that's the tea 💀

👑 AUTHOR 👑

BRL-CAD Team 🫶

this software is Copyright (c) 1987-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 — they will read it, fr fr 💌

okay that's the whole page!! this all comes to you straight out of BRL-CAD, and it's the rtshot(1) manual page — go shoot a single ray at something and think of me 💖✨🌈

📦 where this page comes from