FACETIZE(nged)

Creates new_object using old_object as a guide, creating an evaluated NMG or BoT planar approximation of the original shape.

📅 published 7.44.0, from nixpkgs unstable

💅 FACETIZE(nged) — BRL-CAD User Commands

✨ NAME ✨

okay so facetize creates new_object using old_object as a guide, making an evaluated NMG or BoT planar approximation of the original shape. 🫶

🦋 SYNOPSIS 🦋

bestie, here’s the exact command shape — every bracket is doing its job:

facetize [-h] [-v] [-q] [-n] [-r] [-s suffix] [-p prefix] [--in-place] [--max-time #] [--max-pnts #] [--resume] [--methods m1,m2,...] [--method-opts METHOD opt1=val opt2=val...] [--no-empty] [--log-file filename] [--nmg-booleval] [--disable-fixup] [--perturb] [--no-perturb] [--perturb-sa-tol #] [--perturb-vol-tol #] [--tolerate-failures] [-B -t threshold] {old_object new_object}

🌸 DESCRIPTION 🌸

okay so the facetize operation in BRL-CAD is, broadly speaking, the whole process of creating an explicit planar approximation of a CSG volume by evaluating the boolean expressions used to combine a set of explicit and implicit solid primitives. it’s literally the core operation you need for creating triangle based meshes from BRL-CAD geometry. 🔥

the facetize command can attempt to produce either triangle-only BoT objects, or N-Manifold Geometry (NMG) objects, but generally speaking BoT generation will have a higher success rate than NMG. BoTs are also more useful when exporting to formats such as STL and OBJ — by default BoT output is what facetize will produce. slay. 💖

in general Boolean evaluation of meshes is a very difficult problem, and there are also some specific considerations when it comes to preparing geometry for solid shotline raytracing that require more effort than producing a visualization mesh. it is recommended to use the lint command, both to verify input objects are well behaved before facetization and to check facetize outputs for any potential issues. often times either the original CSG geometry definitions will need adjustment to avoid coplanar faces, or mesh editing is required to resolve problematic triangle configurations. 😭

by default all specified existing objects will be combined into a single mesh, but that is often undesirable when working within BRL-CAD — information stored on region combs such as color will be lost when converting in this fashion. the -r option will introspect into the specified objects and perform facetization on a per-region basis. (If the specified input has no regions in its tree, a normal facetization to a single object is performed instead.) the output will be a new hierarchy that references the facetized regions but retains the properties of parent regions. users looking to interact visually with a shaded display of a model will likely find the -r output useful for that purpose. 👑

there are a number of different verbosity levels available for the facetize command. one or multiple specifications of the -v flag will increase reporting detail. because full output from facetize can be quite verbose, the user has the option to specify a log file with the --log-file option — this will capture all output from the command and allow for more detailed scrutiny of what took place after a conversion has finished. 🎀

🔥 OUTPUT CHARACTERISTICS AND PROCESSING CONTROLS 🔥

by default, the facetize command attempts to be non-destructive when operating on objects — it will not rename or replace any existing geometry in normal operational modes, and will adjust its naming accordingly when producing new objects. however, if a user wants to replace objects with facetized replacements, this may be accomplished by specifying the --in-place option.

⚠️ note that this is a destructive operation — the original object definitions will be overwritten — so use with care! 💀

users may be a bit startled to see empty (0 face, 0 vertices) BoTs produced by a facetize command, but this is in fact expected behavior when a boolean option legitimately results in an empty mesh. for example, if a sphere in a comb is subtracted from itself, and no other geometry is referenced, the result is a zero (empty) volume. the lint command can be used to identify such BoTs — if they are produced, it is often an indication the original CSG definition has some sort of problem. these empty outputs can be suppressed by specifying the --no-empty option, but the recommended course is to determine what about the original geometry produced them and either correct any issues or (if the shapes truly are not intended to be present) remove the original CSG definitions producing them. 🧚

it may happen that a conversion fails part way through the process. this can happen due to user intervention, resource exhaustion, or simply as a consequence of a bug in the conversion logic. if this happens, the intermediate state of the conversion will be stored by BRL-CAD in its cache directory, and the interrupted process may be resumed by re-running facetize with the --resume option. (If a conversion fails and the command is re-run without specifying --resume, previous work will be cleared and the process will start over from the beginning.) 💅

in normal operation, when converting to BoT output there are post-processing routines that try to identify and automatically fix certain categories of geometric flaws that can crop up during Boolean evaluation. if a user finds that they are getting unexpected output for a particular input, and the log indicates the repair step was run, one option available is to repeat the conversion with these repair steps disabled via the --disable-fixup flag. repair should only be disabled if there is a problem — coplanar subtractions frequently result in thin triangle artifacts lingering after Boolean evaluation due to the limitations of floating point math, and in at least some cases the fixup routines are able to deal with these without requiring manual intervention. (These routines will not always work, so checking of outputs after a conversion with the lint command to identify BoTs with potentially problematic features is still recommended — see the lint man page for more details.) 🌈

by default facetize treats failed primitive tessellations, failed leaf preparation, and failed Boolean subtree evaluations as command failures. this is deliberate: a BoT or NMG produced after silently omitting input components can be hard to distinguish from a complete result. the --tolerate-failures option restores the older partial-output behavior as an explicit user choice. when this option is used, facetize will omit components it cannot successfully evaluate and continue when it can still produce some output. if any failures are tolerated, facetize prints a final warning that the result is partial and not a complete representation of the input, along with a capped list of omitted components; the full list is written to the log file. 😭🫶

by default, the Manifold BoT path can make use of a coplanarity-avoidance perturbation retry for eligible primitives. in per-region mode, facetize first evaluates the unperturbed BoT and validates it against the source CSG with Crofton metrics; perturbed variant tessellation is only attempted if those metrics indicate the initial result is outside tolerance. in non-region BoT mode, perturbation is disabled by default but can be enabled explicitly with --perturb. this helps avoid difficult Boolean edge cases where the same primitive participates in both additive and subtractive roles and coplanar/sliver configurations can lead to problematic near-tolerance triangles. if needed, this behavior can be disabled with --no-perturb. ⭐

when the perturbation step is active, per-region facetize validates the initial Boolean output against the original CSG geometry using a Crofton stochastic raytrace. the default tolerance thresholds that trigger a perturb retry are 10% for both surface area and volume; these can be adjusted with --perturb-sa-tol and --perturb-vol-tol. at the end of a per-region facetization run facetize prints a concise validation summary listing how many regions passed, triggered a perturb retry, or encountered one of the following noteworthy conditions: 🦋

  • Sub-mm / few-hit bypass (accepted with note): when the Crofton sampler finds only a very small number of ray-surface intersections (below an internal threshold of 50 crossings), the sampling noise alone would exceed 14% relative error, making any SA comparison meaningless. geometry in this category is typically sub-millimetre in cross-section (e.g., a TGC with a radius under 0.2 mm) but the stochastic sampler has confirmed that some geometry is present. the BoT conversion is accepted and the region is counted separately in the summary. users should verify that such extreme geometry reflects actual modeling intent rather than an accidental near-degenerate primitive. 🍓
  • Zero-hit replacement: when the Crofton sampler fires rays but records zero intersections with the CSG geometry while the corresponding BoT is non-empty, facetize concludes that the Boolean evaluation most likely produces empty geometry (for example, a subtractor that fully engulfs the base object). in this case the non-empty BoT is discarded and replaced with an empty BoT to match the expected raytrace behavior. if this replacement appears unexpected for a given region, the lint command can be used to inspect the result. 👀
  • Perturb topology shift (accepted with note): after a perturb retry, if the Crofton raytrace of the perturbed CSG returns zero while the perturbed BoT is non-empty, the perturbation itself may have shifted the geometry topology (for example, a subtractor that now fully engulfs the base in parametric space). the BoT output is still accepted; the lint command can be used to inspect the result. 💜
  • Persistent validation mismatch: when both the P1 and P2 Crofton comparisons exceed the tolerances for reasons other than sub-mm geometry (for example, union-coplanar shared faces or curved-surface volume sensitivity), a WARNING is reported. the BoT conversion is still written out and the lint command should be used to assess the output. ⚠️

different tolerance settings will create finer or coarser meshes. see the tol man page for more details. ✨

✨ OPTIONS ✨

  • -h, —help — prints the help and dips, that's it 💅
  • -v[v..], —verbose — spills extra (verbose) info into your results. You can stack the vs. If —quiet shows up too, —quiet wins, sorry bestie.
  • -q, —quiet — shuts down all output. Yeah, it overrides the verbosity flag, no cap.
  • -n, —nmg-output — tells facetize to give you NMG solids instead of BoT solids.
  • -r, —regions — instead of mashing all your specified inputs into one top-level object, it walks the trees you gave it and converts each region individually into a facetized object. This mode is the move when you wanna display models in shaded mode but still keep color and region ID properties intact. If there are no regions present, it just does a normal conversion instead. 🎀
  • -s, —suffix — a user-specified suffix so you dodge naming conflicts (and you do need conflict avoidance when you're creating objects in -r mode).
  • -p, —prefix — same deal but a prefix, user-specified, for dodging naming conflicts (again: conflict avoidance is needed when creating objects in -r mode).
  • —in-place — replaces the object(s) you specified with their facetizations. > ⚠️ WARNING: this one is destructive and will change pre-existing geometry, bestie, like actually.
  • —max-time # — max time to spend per object, in seconds. Default is method specific. Careful though: specifying shorter times may cut off conversions (especially with sampling methods) that would've succeeded if you'd just let them cook longer. You can also adjust the per-method time limits to allow longer runtimes on the slower methods.
  • —max-pnts # — caps the max number of pnts per object when it's applying ray sampling methods.
  • —resume — picks up an incomplete facetization process where it left off (it'll use cached data from the previous run instead of starting from scratch). And ngl, re-running without this option clears any old data and starts from the very beginning. 💀
  • —methods — takes a comma separated list of one or more facetization methods to use. Default behavior is to try all algorithms available as needed, but if you already know you want a specific methodology, call it out here.
  • —method-opts — passes parameter values to specific facetize methods. The argument format is "METHOD opt1=val1 opt2=val2 ...". Peep the —help output to see which methods and parameters facetize actually supports.
  • —no-empty — don't write out empty BoT objects when a Boolean evaluation comes back with an empty mesh.
  • —log-file — specify a log file to store the full verbose output of a facetization process. Highly recommended for big or long-running facetize runs so you can actually understand what steps got taken and what problems popped up. 🫶
  • —nmg-booleval — uses the libnmg boolean evaluation algorithm even when you're producing BoT output. It can be less robust, but it may give you cleaner results for some coplanar cases.
  • —disable-fixup — by default, BoT facetization tries to clear certain categories of undesirable triangles from the outputs. This option skips that repair attempt entirely.
  • —perturb — enables the coplanarity-avoidance perturbation step. In per-region mode this behavior is on by default; in non-region BoT mode you have to ask for it explicitly. Conflicts with —no-perturb. ⚡
  • —no-perturb — disables the coplanarity-avoidance perturbation retry machinery in BoT Manifold Boolean evaluation. Conflicts with —perturb.
  • —perturb-sa-tol # — surface-area percentage threshold (0–100) that triggers the coplanarity-avoidance perturb retry when the per-region Crofton-sampled CSG surface area differs from the initial facetized BoT surface area by more than this amount. Default is 10 (percent).
  • —perturb-vol-tol # — volume percentage threshold (0–100) that triggers the coplanarity-avoidance perturb retry when the per-region Crofton-sampled CSG volume differs from the initial facetized BoT volume by more than this amount. Default is 10 (percent).
  • —tolerate-failures — keeps going after failed primitive or subtree evaluations and generates a partial result when possible. Any omitted components get reported at the end of the run, and you should treat the resulting output as incomplete until you understand those reported failures. Useful for diagnosis, or for extracting a best-effort mesh out of a very large model — but do not use it when you need a complete representation. 🙈
  • -B — experimental non-overlapping facetization to BoT objects for union-only brep comb trees.
  • -t threshold, —threshold threshold — experimental overlap-threshold length used by -B mode.

🧚 FACETIZATION METHODS 🧚

Okay so broadly speaking, a facetization process has two stages. Stage one is generating mesh representations for individual geometric primitives — implicit ELL, ARB8, TOR, etc. solids have to be represented by mesh approximations before they can become part of an evaluated mesh. On top of that, inputs that are already meshes get checked for suitability: all input meshes, whether they were generated from implicit shapes or are pre-existing as BoTs, must be properly manifold before they can be used for facetization. Once all the solids are successfully converted, stage two is evaluating the Boolean tree hierarchy by unioning, subtracting or intersecting the various meshes together to produce the evaluated shapes. ✨

The individual primitive-to-mesh conversion can be... a lot. Routines may take extremely long lengths of time trying to resolve a conversion problem. To avoid the process hanging indefinitely with zero progress, a timeout is established that limits how long each individual conversion process should take. Various methods have defaults defined internally, so this isn't something you normally need to worry your pretty head about — but if you wanna set a limit yourself (either allowing more time or forcing shorter cycles), that's what —max-time is for. 💅

Producing a mesh from a primitive shape can be genuinely hard. Simply waiting longer for results often isn't practical or even the right answer — indeed, infinite looping has been observed in some primitive conversion cases. 😭 To work around these limitations, BRL-CAD provides multiple methods you can use to attempt mesh production in case other methods fail. We deliberately do not document those methods in detail here — they're subject to change as new alternatives get identified that can produce better results. What we do document is how to use the facetize command to see what methods are currently available and control them. The -h option lists, at the end of its output, information about all currently available methods and what controls they offer. The —methods option restricts facetize to a particular subset of the available methodologies, and —method-opts passes specific parameters to a specific method. 🦋

Because many of the facetization methods are sampling based (the raytracer samples the volume), there's a top level control for specifying the maximum number of points to use when generating inputs for such methods. More points generally means a better conversion, at the expense of memory and runtime.

Primitive tessellation also applies internal minimum tolerance floors to avoid pathological "triangle bombing" (very small tolerance requests producing extreme triangle counts with little practical benefit for modeling/raytrace fidelity). Advanced users who explicitly want to bypass those defaults may set environment variables RT_PRIM_MIN_ABS_TOL and/or RT_PRIM_MIN_NORM_TOL to positive floating-point values before running facetize. These overrides are an expert-use escape hatch: lower floors can substantially increase memory/runtime cost and may produce extremely high triangle counts. 🔥

🌈 EXAMPLES 🌈

Example 1. Create a facetized BOT version of an existing object.

The example shows the use of the facetize command to create a facetized BOT version of an existing object (old_object) and renaming that facetized object (new_object).

mged>facetize region1.r region1.bot

Example 2. Facetize all regions in a hierarchy.

This runs the per region conversion on all regions under the "model" assembly and creates a new conversion hierarchy under model_facetized.

mged>facetize -r model model.f

Example 3. Facetize all regions in a hierarchy, attempting only NMG conversion.

This runs the NMG approach per region conversion on all regions, but in the case of failure will not attempt any fallback conversion methods.

mged>facetize -r —methods NMG model model.f

Example 4. Retry failed conversion objects in a previous facetization attempt with new methodology.

This resumes a failed conversion of model.

mged>facetize -r —resume model model.f

Example 5. Generate a partial BoT from a difficult tree.

This attempts to facetize large_model while explicitly allowing failed primitives or subtrees to be omitted. The final result should be inspected carefully: if any failures are tolerated, facetize will report that the output is partial.

mged>facetize —tolerate-failures large_model large_model.partial.bot

Example 6. Increase Decimation in CM Mode

mged>facetize —methods CM —method-opts feature_size=0.06
d_feature_size=2.0 ellipse.r ell.bot

The default settings on this object in CM mode will produce a little over 8000 faces in the final bot, but the addition of the d_feature_size option with a >1.5 value has dramatically reduced the count to 104. 👑

Example 7. Decrease Decimation in CM Mode

mged>facetize —methods CM —method-opts feature_size=0.06
d_feature_size=0.01 ellipse.r ell.bot

If the intent is preserve a more detailed mesh, reducing decimation-feature-size will keep more of the original triangles — in the above example, almost 250 thousand of the original 6.9 million faces were retained. NOTE: use lower values here cautiously, as extremely large meshes can be very difficult for many tools to deal with. 💀

🌸 USEFUL TRICKS 🌸

ok so these are the little side-quest commands that are lowkey obsessed with the facetization process — keep them in your back pocket bestie 💖

Example 8. List invalid BoT objects below a comb

use lint -I to snitch on all the invalid objects hanging out below a comb 🕵️‍♀️

mged>lint -I model.f

Example 9. Pre-extrude Plate Mode BoTs

use search -exec to extrude, like, all the plate mode bots before you even try a facetize operation — do it first, thank yourself later ✨

mged>search model.f -type bot -type plate -exec bot extrude -i "{}"
";"

🧚 IMPLEMENTATION DETAILS 🧚

ok so here's the tea about how this actually works under the hood 👀

the current implementation of facetize launches primitive facetization operations in a subprocess, specifically so there's recovery available if individual primitives crash, infinite loop, or otherwise trigger what would otherwise be catastrophic behavior 😭💀 like, genuinely a whole disaster. this means it is essential that the operating environment allow the parent program to launch those subprocesses — otherwise, conversion will fail. no cap, it just won't work 🙈

unlike previous versions of facetize, this version (in BoT mode) will only facetize each primitive once — if a primitive is instanced repeatedly in multiple combs, it will use the same BoT to represent all of those instances 👑 that's the main character efficiency right there. if for some reason this is not desired behavior, the user should first prepare the geometry by making all instances unique with xpush. periodt ✨

👑 AUTHOR 👑

BRL-CAD Team 🫶

🐛 BUG REPORTS 🐛

reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org — please do, the team wants to know fr fr 💌

k bye bestie, that's the whole page — source/version is BRL-CAD, it's FACETIZE(nged), and it's dated 2024-06-27 (or whatever date your copy says, iykyk) ✨🎀🦋

📦 where this page comes from