GIST(1)

NAME

gist - generate a one-page visual and textual summary of a geometry database

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

gist [options] (-F _model/dir_ | _model.g_)

The Geometric Information Summary Tool (gist) produces a high-level, one-page report describing a BRL-CAD database (.g) file. The report is rendered to a PNG image that combines orthographic and perspective views of the geometry with computed properties such as bounding dimensions, surface area, volume, and mass, alongside the database’s top-level structure and report metadata (preparer, owner, classification, and notes).

gist drives rt(1) and rtwizard(1) to produce its renders; the directory holding those executables is located automatically or set with -T. Intermediate renders are cached in a .working directory so that subsequent runs can be re-used with -Z. If neither an output file (-o) nor a folder of inputs (-F) is given, the report is shown in a pop-up window instead of being saved.

A single database is summarized by naming it on the command line (or with -i). Passing -F with a directory processes every .g file in that directory, writing one report per model into an export folder.

OPTIONS

-i filename.g: Input BRL-CAD database file. A bare .g path given as the final argument is treated the same way.
-o filename.png: Output PNG file name. A .png extension is required (and appended if omitted). When absent and not in folder mode, the report is displayed in a pop-up window.
-F folder: Process every BRL-CAD database in the given folder, generating one report per model.
-e dir_name: Name of the export folder used for reports in folder mode (default is a GIST_REPORTS directory inside the input folder).
-g: Display the generated report in a pop-up window.
-f: Force overwrite of an existing output report or export directory.
-Z: Reuse renders found in an existing .working directory, greatly reducing processing time.
-t component: Name of the primary database object to feature in the report.
-m path/to/image: Path to a custom logo image to include in the report.
-p ppi: Output resolution in pixels per inch (default 300).
-n preparer: Name of the person preparing the report.
-r owner: Name of the model’s owner.
-T path/to/rt: Directory containing the BRL-CAD rt(1) and rtwizard(1) executables. Located automatically if not given.
-c classification: Classification text (e.g. UNCLASSIFIED) shown in the top and bottom banners of the report.
-N notes: Additional textual notes to include in the report.
-L: Use a left-handed coordinate system (default is right-handed).
-A: Orient geometry with +Y up (default is +Z up).
-d density_file: Density file to use for material mass calculations, or 0 to skip density and mass calculations.
-l len_units: Length units to use in the report.
-w wt_units: Weight (mass) units to use in the report.
-a path/to/dir: Directory in which to write cached rendering work (defaults to a .working directory derived from the input name).
-P ncpu: Number of CPUs to use. A non-positive value is added to the number of available cores; the default uses all available cores.
-Q, --preview: Generate a fast, low-resolution preview. The report retains the standard page layout, using reduced-quality renderings and marking the omitted surface-area, volume, and mass verification values as unavailable.
-v: Enable verbose output.
-h, --help, -?: Print a usage summary and exit.

EXAMPLES

Example 1. Summarize a single model

gist -i ktank.g -o ktank.png -t tank -n "J. Doe" -c UNCLASSIFIED

Renders a report for the ktank.g database, featuring the tank component, naming the preparer and stamping the report banners as UNCLASSIFIED, and saves it to ktank.png.

Example 2. Re-run quickly after tweaking metadata

gist -Z -i ktank.g -o ktank_v2.png -N "revised mass properties"

Reuses the cached renders left in the .working directory from a previous run (-Z), so only the report layout is regenerated with the added notes rather than re-rendering all of the views.

Example 3. Batch-process a directory of models

gist -F models/ -e reports -p 600 -w lbs -l in

Generates a 600 ppi report for every .g file in models/, writing them into a reports export folder and presenting weights in pounds and lengths in inches.