RTXRAY(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

💅 rtxray — the BRL-CAD one, bestie

okay so this is rtxray(1), the BRL-CAD tool that ray traces your model and spits out a pseudo X-ray image. literally radiography but make it code. let's go ✨

🦋 SYNOPSIS

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

🌸 DESCRIPTION

rtxray uses librt(3) to ray trace the objects you list in the database model.g, all from a single view direction, and produces a simulated X-ray image. no cap, that's the whole vibe.

So here's how the math goes, and it's actually kind of iconic: every material is treated as having the same density. For each ray, the total path length through solid material gets accumulated, then divided by the viewsize (that's the diagonal of the model bounding box, i.e. the longest possible path), and then mapped to an 8-bit gray value. thick regions come out dark (toward 1) and thin regions come out bright (toward 255). and the value 0 is reserved for rays that hit no material at all — so the background can be keyed out super easily while the object still keeps good contrast. periodt. 🎀

If you don't list any objects, rtxray uses the same automatic default-object selection described in rt(1). and if no single usable default can be resolved? it aborts before rendering. no half-sends, we don't do that here.

here's the tea though: most models do not fill their bounding volume, so that safe scaling above gives you very low, mostly-white contrast. 😭 so to compensate, a contrast boost of 2.0 is applied before path lengths get mapped to gray. you can adjust it with -A — the value must be 1.0 or greater, and larger values give you more contrast but may clip thick regions to black (1). so like, use it with intention bestie.

The view gets 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). that form is honestly so convenient when rtxray is being driven by a script produced by the mged(1) saveview command. iykyk 💅

By default the image goes to a framebuffer. use -o to write a pix(5) or png(5) image instead (a .bw extension yields an 8-bit grayscale bw(5) file — cute). 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, sorry bestie) 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. yes, even if you ask politely. 🙈

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

✨ 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, which is 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. slay. 👑

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. big main character energy. 💜

🌈 SEE ALSO

brlcad(1), mged(1), rt(1), rtdepth(1), rthide(1), bw-fb(1), bw(5), librt(3)

🫶 AUTHOR

BRL-CAD Team

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, go make some gorgeous X-rays 💖 this was RTXRAY(1) from BRL-CAD, mwah, bye! 🦋✨

📦 where this page comes from