RTDEPTH(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

💅 RTDEPTH(1) — the rtdepth page, bestie edition ✨

okay so real quick: this is the rtdepth(1) manual page from BRL-CAD, and it's genuinely one of the most useful little gremlins in the whole toolkit. let's get into it 🫶

✨ NAME ✨

rtdepth — ray trace a model and produce a grayscale depth image 🎀

✨ SYNOPSIS ✨

rtdepth [options] model.g [objects...]

✨ DESCRIPTION ✨

so rtdepth uses librt(3) to ray trace the objects you list in the database model.g, from one single view direction, and it spits out a grayscale depth map. iconic behavior honestly.

here's the whole vibe of how each pixel gets its value: for every pixel, it takes the distance from the eye plane to the first object surface it hits, divides that by the viewsize — and bestie, viewsize is the diagonal of the model bounding box, aka the longest possible path — and then it maps that relative distance onto an 8-bit gray value. near surfaces come out bright (toward 255), far surfaces come out dark (toward 1). and the value 0? that's reserved for rays that hit literally nothing 💀 so the background can be keyed out super easily and your object keeps good contrast. chef's kiss.

if you don't list any objects, rtdepth falls back to the same automatic default-object selection described in rt(1). but if no single usable default can be resolved, it aborts before rendering — no guesses, no drama, it just stops. 🙈

you pick the view with the -a (azimuth) and -e (elevation) options — in that case the model gets auto-sized and the grid is centered on the model so the rays span the selected object set. or, alternatively, with -M a model-to-view matrix gets read from standard input (with the grid covering -1.0 <= X,Y <= +1.0 in view space). that form is so convenient when rtdepth 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 (and heads up: a .bw extension gets you an 8-bit grayscale bw(5) file 🖤). and because the output pixels must be emitted in order, rtdepth always runs on a single CPU no matter what -P says. that's just the rules. ⭐

most of the camera, grid, and debugging options that rt(1) accepts are also honored here — go read that manual page for the complete list, bestie.

✨ OPTIONS ✨

  • -a azimuth — sets the view azimuth in degrees and turns on auto-sizing. use it with -e; it conflicts with -M.
  • -e elevation — sets the view elevation in degrees and turns on auto-sizing. use it with -a; it conflicts with -M.
  • -M — reads a model-to-view transformation matrix (plus an optional animation script) from standard input instead of using -a/-e.
  • -s # — sets the square grid size to # rays on a side (default 512, i.e. a 512x512 image).
  • -w # — sets the image width in pixels.
  • -n # — sets the image height in scanlines.
  • -g mm — sets the grid cell width in millimeters. if you set it without -G, the cell height defaults to the same value. 🎀
  • -G mm — sets the grid cell height in millimeters.
  • -p deg — sets the perspective angle in degrees (0 <= deg < 180; 0 is orthographic, and that's the default).
  • -V #[:#] — sets the view aspect ratio width/height (e.g. 1.33 or 4:3).
  • -o file — writes the depth image to file instead of a framebuffer. the format follows the extension (e.g. .pix, .png, or .bw for grayscale).
  • -O file — writes a double-precision .dpix file for full-resolution post-processing. 🔥
  • -F framebuffer — renders to the named framebuffer (peep the FB_FILE environment variable).
  • -i — uses incremental (progressive-style) rendering.
  • -t — renders top-to-bottom (the default is bottom-up).
  • -u units — sets the display units; -u model uses the database's local units.
  • -P # — requested processor count. accepted for compatibility, but rtdepth always renders with a single CPU (said it once, saying it again 💅).
  • -x # — sets librt debug flags as a hexadecimal bit vector (see raytrace.h).
  • -X # — sets rt program/optical debug flags as a hexadecimal bit vector.
  • -? or -h — prints a usage summary and exits.

see rt(1) for the remaining shared options (e.g. -g/-G grid cell sizing, -T tolerances, -c script commands).

🚨 real talk: the -C and -W background options of rt(1) are disabled in rtdepth. don't come for me, it's just how it is.

✨ EXAMPLES ✨

Example 1 — depth image from a three-quarter view 🌈

rtdepth -a 35 -e 25 -s 1024 -o depth.png model.g all

this ray traces the group all in model.g from azimuth 35, elevation 25 degrees on a 1024x1024 grid, and writes a grayscale PNG. nearer surfaces appear brighter and the empty background is pure black (value 0), which makes it trivial to composite the object over a new background. main character energy fr fr 👑

Example 2 — depth pass matching a saved MGED view 🦋

rtdepth -M -o depth.bw model.g component < component.rt

this reuses the camera from an mged(1) saveview script (the matrix is read from standard input via -M) so the depth map of component is rendered from exactly the view you set up interactively — writing an 8-bit bw(5) file that can be fed to bw-fb(1) or pixhist(1). literally so satisfying.

✨ SEE ALSO ✨

brlcad(1), mged(1), rt(1), rthide(1), rtxray(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 📬

and that's the whole page, bestie!! brought to you by BRL-CAD — the rtdepth(1) manual, now with 100% more sparkle ✨🎀💜 go make some gorgeous depth maps, you got this 🫶

📦 where this page comes from