bot exterior [options] {input_bot} [output_name]BOT_EXTERIOR(nged)
NAME
bot_exterior - Reduce a BoT solid to only its exterior (outward-facing) faces.
On this page
SYNOPSIS
DESCRIPTION
bot exterior analyses a closed solid, non-plate-mode BoT (Bag of Triangles) mesh and removes every face that is not classified as exterior, retaining only those triangles that belong to the exterior shell.
Methods
Two classification methods are available:
- Per-triangle Cauchy-Crofton ray sampling (default)
-
Rays are fired from random points on each triangle in uniformly random directions. A triangle is marked exterior when it appears as the first or last surface hit of any ray.
The same rays also drive a Cauchy-Crofton surface-area estimate normalized by the triangle's bounding-sphere area. If the estimate stabilizes within the configured convergence threshold over two successive ray batches, and no exterior hit has been observed, the face is treated as interior.
Sampling is parallelized across available CPU cores. Rays aimed at one face may opportunistically classify other first/last-hit faces, allowing the work queue to prune itself without a separate global sweep.
- Flood-fill / water-filling (--flood-fill, requires OpenVDB)
-
The model is voxelised and a BFS flood-fill from the bounding-box boundary identifies all voxels reachable from outside. A face is exterior when any adjacent voxel is reachable. If OpenVDB support was not compiled in the command falls back to Cauchy-Crofton ray sampling.
Output
If output_name is not supplied the result is written to a new object named input_bot_exterior. Use -i / --in-place to replace the input BoT directly. If output_name already exists the command returns an error rather than overwriting existing data.
The output mesh is condensed: vertices that are no longer referenced by any remaining face are removed. The result is a BoT containing only exterior faces.
OPTIONS
- -h, --help
-
Print command help and exit.
- -i, --in-place
-
Overwrite the input BoT in-place. Exactly one object name must be given and no output_name should be specified.
- -f, --flood-fill
-
Use the voxel flood-fill (water-filling) classification method instead of Cauchy-Crofton ray sampling. Requires OpenVDB support compiled in; if unavailable the command falls back to ray sampling.
- -v, --verbose
-
Print extra diagnostic metrics:
-
Total elapsed classification time and exterior-face count.
-
Flip-time statistics: the wall-clock time from the start of per-face sampling until each face was first confirmed exterior. Reported as maximum and average over all confirmed-exterior faces.
-
- --voxel-size size
-
Edge length in mm of each voxel for the flood-fill method. When omitted the size is computed automatically from the model’s bounding box.
- --visibility-threshold ratio
-
When set to a value greater than zero, enables visibility-threshold mode. In this mode each face is sampled until the per-face time budget is exhausted and is then included in the output only if the fraction of fired rays that saw the face (as either an entry or exit surface) equals or exceeds ratio.
_ratio_ must be in the range [0, 1]. A value of 0 (the default) disables the feature entirely. A value of 1 requires that every fired ray be able to observe the face, which in practice will exclude almost all geometry because rays can always miss due to random direction sampling. Practical values are typically in the range 0.01–0.5; for example, *--visibility-threshold=0.1* requires that at least one ray in ten fired at a face can observe it from outside before it is retained. Setting the ratio higher produces a more conservative result at the cost of more processing time.
Default: *0* (disabled). This mode is considerably slower than the default because it cannot stop sampling a face the instant a single exterior hit is found; it must always exhaust the per-face budget to collect a representative sample. This option has no effect with *--flood-fill*.
- -c, --convergence-threshold percent
-
In the default ray-sampling method, do not declare a face interior until the per-face Cauchy-Crofton estimate is stable to within percent over two successive ray batches.
Default: *1.0*. Lower values make the classifier try harder before deciding a face is interior, usually at the cost of more rays.
- --per-face-budget sec
-
Hard wall-clock time limit for sampling each face in the default ray-sampling method.
Default: *0* (unlimited). When set to zero, the command relies solely on the convergence test to stop sampling interior faces. In visibility-threshold mode, a positive budget is typically needed for the threshold to have practical effect.
EXAMPLES
Example 1. Basic exterior extraction
mged> bot exterior havoc.bot
Extracts the exterior shell of havoc.bot and writes the result to havoc.bot_exterior.
Example 2. In-place extraction
mged> bot exterior -i havoc.bot
Replaces havoc.bot with its exterior shell. The original full mesh is lost.
Example 3. Specify output name
mged> bot exterior havoc.bot havoc_shell
Writes the exterior shell to the new object havoc_shell.
Example 4. Visibility threshold (conservative exterior)
mged> bot exterior --visibility-threshold=0.1 --per-face-budget=0.5 havoc.bot havoc_vis
Samples each face for up to half a second and retains it only if at least 10 % of fired rays see it as an exterior surface. Lightly visible faces (e.g. thin slivers in deep cavities) are excluded. Slower than the default.
Example 5. Custom convergence threshold
mged> bot exterior -c 0.25 havoc.bot havoc_precise
Requires the surface-area estimate to stabilize within 0.25 % before a face is declared interior, which generally increases sampling work relative to the default 1 % threshold.
Example 6. Flood-fill method
mged> bot exterior --flood-fill havoc.bot havoc_flood
Uses the voxel water-filling method (requires OpenVDB). Falls back to Cauchy-Crofton ray sampling if OpenVDB is unavailable.
AUTHOR
BRL-CAD Team
BUG REPORTS
Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org