RTSHOT(1)

NAME

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

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
DIAGNOSTICS
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

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

rtshot fires a single ray at the listed objects in the BRL-CAD database model.g and prints a textual summary of every region the ray passes through: the in and out hit points, surface normals, surface curvature, claiming regions for any overlaps, and optionally selected region attributes. If no objects are named, rtshot will attempt to use 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, rtshot prints the resolver’s explanation and exits with "no objects specified."

The ray is defined by supplying exactly two of the following 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. The direction vector is always normalized.

rtshot is a thin front-end to librt(3) intended for inspecting and debugging geometry; it is the command-line analog of the ray a single pixel of rt(1) would cast.

OPTIONS

-p x y z: Set the ray starting point.
-d x y z: Set the ray direction vector (normalized before use).
-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, 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).

A ray bundle can be cast in two ways. Supplying both -n and -c (with an optional -R radius) fires a spiral ring bundle whose results are merged as a single ray. Supplying only -R (with an optional -g grid spacing) fires a circular grid of parallel rays. The default is to fire a single ray.

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.

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.

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.