RTXRAY(1)

NAME

rtxray - ray trace a model and produce a pseudo X-ray image

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

rtxray [options] model.g [objects...]

rtxray uses librt(3) to ray trace the listed objects in the database model.g from a single view direction and produces a simulated X-ray image. All materials are treated as having the same density: for each ray the total path length through solid material is accumulated, divided by the viewsize (the diagonal of the model bounding box, i.e. the longest possible path), and mapped to an 8-bit gray value. Thick regions are dark (toward 1) and thin regions are bright (toward 255). The value 0 is reserved for rays that strike no material, so the background can be keyed out easily while the object retains good contrast.

If no objects are listed, rtxray uses the same automatic default-object selection described in rt(1). If no single usable default can be resolved, it aborts before rendering.

Most models do not fill their bounding volume, so the safe scaling above yields very low (mostly white) contrast. To compensate, a contrast boost of 2.0 is applied before path lengths are mapped to gray. Adjust it with -A; the value must be 1.0 or greater, and larger values give more contrast but may clip thick regions to black (1).

The view is selected with the -a (azimuth) and -e (elevation) options, in which case the model is auto-sized and the grid is centered on the model so the rays span the selected object set. Alternatively, with -M a model-to-view matrix is read from standard input (with the grid covering -1.0 ⇐ X,Y ⇐ +1.0 in view space); this form is convenient when rtxray is driven by a script produced by the mged(1) saveview command.

By default the image is written to a framebuffer. Use -o to write a pix(5) or png(5) image (a .bw extension yields an 8-bit grayscale bw(5) file). With the alternate lighting model (-l 1) rtxray writes raw double-precision path lengths instead of gray pixels; this mode requires -o (it cannot drive a framebuffer) and appends a .los extension when the output name looks like an image, producing data suitable for custom post-processing and scaling. Because the output pixels must be emitted in order, rtxray always runs on a single CPU regardless of -P.

Most of the camera, grid, and debugging options accepted by rt(1) are also honored; see that manual page for the complete list.

OPTIONS

-a azimuth: Set the view azimuth in degrees and enable auto-sizing. Use with -e; conflicts with -M.
-e elevation: Set the view elevation in degrees and enable auto-sizing. Use with -a; conflicts with -M.
-M: Read a model-to-view transformation matrix (and optional animation script) from standard input instead of using -a/-e.
-A #: Contrast boost factor applied before the path-length-to-gray mapping (default 2.0, must be >= 1.0). Higher values increase contrast but may clip thick regions to black.
-s #: Set the square grid size to # rays on a side (default 512, i.e. a 512x512 image).
-w #: Set the image width in pixels.
-n #: Set the image height in scanlines.
-g mm: Set the grid cell width in millimeters. If set without -G, cell height defaults to the same value.
-G mm: Set the grid cell height in millimeters.
-p deg: Set the perspective angle in degrees (0 ⇐ deg < 180; 0 is orthographic, the default).
-V [:]: Set the view aspect ratio width/height (e.g. 1.33 or 4:3).
-l #: Select the lighting (output) model: -l 0 (default) writes a line-buffered grayscale image; -l 1 writes raw double-precision solid path lengths (requires -o).
-o file: Write the image to file instead of a framebuffer. The format follows the extension (e.g. .pix, .png, or .bw for grayscale); with -l 1 a .los extension of doubles is produced.
-O file: Write a double-precision .dpix file for full-resolution post-processing.
-F framebuffer: Render to the named framebuffer (see the FB_FILE environment variable).
-i: Use incremental (progressive-style) rendering.
-t: Render top-to-bottom (the default is bottom-up).
-u units: Set the display units; -u model uses the database’s local units.
-P #: Requested processor count. Accepted for compatibility, but rtxray always renders with a single CPU.
-x #: Set librt debug flags as a hexadecimal bit vector (see raytrace.h).
-X #: Set rt program/optical debug flags as a hexadecimal bit vector.
-? or -h: Print a usage summary and exit.

See rt(1) for the remaining shared options (e.g. -T tolerances, -c script commands, -U air handling). The -C and -W background options of rt(1) are disabled in rtxray.

EXAMPLES

Example 1. Pseudo X-ray from a three-quarter view

rtxray -a 35 -e 25 -s 1024 -A 4.0 -o xray.png model.g all

Ray traces the group all in model.g from azimuth 35, elevation 25 degrees on a 1024x1024 grid and writes a grayscale PNG with a contrast boost of 4.0. Thicker portions of the model appear darker, the empty background is pure black (value 0), and the boosted contrast keeps a sparse model from washing out to white.

Example 2. Raw path lengths for post-processing

rtxray -M -l 1 -o paths.los model.g component < component.rt

Reuses the camera from an mged(1) saveview script (the matrix is read from standard input via -M) and, with the alternate lighting model, writes one double-precision solid path length per ray to paths.los instead of gray pixels. The resulting array can be scaled or analyzed externally to apply true material densities.