RTSURF(1)

📦 version 7.44.0, in nixpkgs unstable

🦋 NAME 🦋

rtsurf — the tool that estimates the exterior surface area of geometry via Monte Carlo ray sampling, and yes bestie it is exactly as cool as it sounds 💅

(This page lives in the BRL-CAD manual, section 1, iykyk.)

✨ SYNOPSIS ✨

    rtsurf [-g] [-r] [-n _samples_] [-t _threshold_] [-m _density.txt_] [-o] _model.g_ [_objects..._]

🌸 DESCRIPTION 🌸

Okay so here's the vibe: rtsurf estimates the exterior surface area of BRL-CAD geometry using a Monte Carlo ray sampling method. Literally throwing rays at the problem until it gives us an answer. 🎲

Random points get generated on the geometry's bounding sphere, and then rays are fired between pairs of those points. The ratio of rays that actually hit the geometry to rays fired gets fed through the Cauchy-Crofton formula, and out pops an estimate of exterior surface area — reported in square millimeters. Math ate, no crumbs. 🔥

By default rtsurf does a single sampling iteration. But if you hand it a convergence threshold with -t, it switches to sampling iteratively instead, refining the estimate over successive batches of rays until the change between iterations falls below that threshold. Glow-up behavior honestly. An explicit fixed sample count can also be requested with -n.

When no objects are named, the same automatic default-object selection described in rt(1) is used. And heads up: if that selection is disabled, ambiguous, names an unusable geometry object, or has no deterministic match, rtsurf exits — because there'd be no geometry loaded. 💀 No geometry, no vibes, no output.

The geometry gets loaded from a model.g database created with mged(1) or other BRL-CAD tools. Per-region, per-combination, and per-material breakdowns of the area estimate can all be requested, and — this is the fun part — the sample points, ray directions, and hit points can be emitted as an mged(1) command script for visualization. Like, you can literally watch the sampling happen. Obsessed. 🫶

🎀 OPTIONS 🎀

  • -n samples — Use samples rays per iteration. Without -t you get a single iteration; when combined with -t, batches of this size are run until the threshold is met. The default is 1000 rays in the first iteration.
  • -t threshold — Iterate until the percentage change of the estimate falls below threshold (a percentage) over the trailing iterations. The default threshold is 0, which performs a single iteration.
  • -r — Print the area estimate broken down per region. 🌈
  • -g — Print the area estimate broken down per combination (group).
  • -m density.txt — Print the area estimate broken down per material, using the named density/material file — same format consumed by gqa(1) — to label materials by name. 🍓
  • -o — Emit an mged(1) command script to standard output describing the sample points, ray directions, and hit points as geometry, so the sampling can be visualized. Main character energy fr.
  • -h — Print a usage message and exit.

💖 EXAMPLES 💖

Example 1. Estimate exterior surface area with a single sampling pass

        rtsurf havoc.g havoc

Runs a single sampling iteration on the havoc object in havoc.g and prints the estimated exterior surface area in square millimeters.

Example 2. Iterate to convergence

        rtsurf -t 0.1 havoc.g havoc

Samples the havoc object iteratively, refining the estimate over successive batches of rays until it converges to within 0.1%.

Example 3. Per-region and per-material breakdown with a fixed sample count

        rtsurf -r -m density.txt -n 1000000 havoc.g havoc 2> rtsurf.log

Fires one million rays and reports the total exterior surface area along with per-region and per-material subtotals (labeled using density.txt). The estimate output is on stderr, so it's redirected to a log file. 🧚

Example 4. Visualize the sampling in MGED

        rtsurf -o -n 1000 havoc.g havoc > rays.mged
        mged -c havoc.g source rays.mged

Runs a small thousand-ray pass and writes an mged(1) command script of the bounding sphere, sample points, ray directions, and hit points to rays.mged, which is then sourced into mged(1) to display the sampling. Literally watching the rays do their thing. ✨

⭐ SEE ALSO ⭐

brlcad(1), mged(1), rt(1), gqa(1)

Like, go read them, they're all part of the family. 👑

👑 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

Found a bug? Don't be shy, don't gatekeep it, send it in. Besties help besties ship better software. 💌

okay that's the whole page!! 🎀 it's the BRL-CAD RTSURF(1) page, and the footer situation is literally just BRL-CAD + RTSURF(1) — no separate date field, so the closest thing we've got to a timestamp is that 1989-2026 copyright stretch. periodt. 💅

📦 where this page comes from