facetize — Creates new_object using old_object as a guide, creating an evaluated NMG or BoT planar approximation of the original shape.
facetize [-h] [-v] [-q] [-r] [-n] [-T] [--NMG] [--CM] [--SPSR] {old_object new_object}
facetize --CM [--feature-scale] [--feature-size] [--decimation-feature-size] [--max-time] [--max-pnts] {old_object new_object}
facetize --SPSR [-d] [-w] [--samples-per-node] {old_object new_object}
facetize -r [standard_options] [--resume] [--retry] [--in-place] {output_hierarchy_obj}
Creates new_object as planar primitive shape (either an NMG or a BOT) approximating the 3D volume bound by old_object. The -r option will operate per-region rather than on an entire object and produces a new hiearchy.
There are a number of different verbosity levels available for the facetize command. One or mulitple specifications of the -v flag will increase reporting detail about what the facetize command is doing in various steps. To silence all output specify the -q flag - this is generally not recommended as the messages produced by the facetize command often contain important information about conversion failures in addition to reporting incremental progress on large conversion tasks.
Often, it is desirable to perform facetization on each region individually within a geometry hierarchy, rather than trying for a single "all or nothing" shape. This mode, available with the -r flag, has the advantage of allowing for partial conversion of complex models even when individual shapes within the model cannot be converted, as well as preserving all pre-existing region attributes such as color and region ID.
Because multi-region hierarchy conversion is often a long process, the facetize command (when run in region mode) works in a way that allows an incomplete conversion to resume work. For example, if a large model is to be converted it may be advantageous to attempt just the NMG conversion on the hierarchy first to get a sense of the work to be done. After the initial attempt, global facetize parameters can be adjusted and a second NMG run attempted, perhaps this time with SPSR reconstruction also enabled. Note that this works only for a hierarchy generated with the facetize.
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. However, if a user needs to create a new version of an existing hierarchy which replaces geometry below regions with BoT objects but leaves all upper level names intact, this may be accomplished by specifying the --in-place option in combination with the -r option.
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). It will try first NMG conversion, and if that fails attempts CM conversion.
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 per region conversion on all regions, but in the case of failure will not attempt any fallback conversion methods.
mged> facetize -r --NMG model model.f
Example 4. Retry failed conversion objects in a previous facetization attempt with new methodology.
This retries the per region conversion on all regions that didn't originally succeed in the initial conversion attempt, attempting only CM reconstruction without first retrying NMG conversion.
mged> facetize -r --resume model.f
Ideally users would not need to concern themselves with the details of how facetize works, but unfortunately there are a significant number of real world geometries which will cause problems for the current implementation. In those cases, deeper understanding of what is happening can be very important to maximizing the success of a conversion.
By default, conversions will first attempt a standard NMG facetization and boolean evaluation of the existing geometry. When it succeeds, NMG's output is generally the best quality output that can be produced by any of BRL-CAD's available facetization methods. If NMG booleans fail, a fall-back method based on Bloomenthal's continuation method (CM) polygonalizer will be attempted by default.Note that if any of the methodology flags (--NMG,--CM, or --SPSR) are explicitly enabled, the other methodologies will be disabled unless they too are explicitly enabled.
While the facetize command does not itself expose options to adjust the behavior of the NMG boolean methodology, it will respect MGED's settings for absolute (abs), relative (rel), and normal (norm) tolerances which are set with the MGED tol command. These settings may be changed between repeated runs of the facetize command to attempt different NMG evaluations.
Bloomenthal's continuation method tends to be slower and exhibit artifacts around sharp corners - users are advised to inspect the output from this method manually to ensure it will meet their needs. (All objects created with this methodology in a multi-region hierarchical conversion are also included in a top level combination with CONTINUATION in the name to allow users to more easily inspect them.) By default, the BRL-CAD raytracer is used to shoot pseudo-random rays at the object and accumulate an average observed thickness of the model. This thickness is then used as the basis for an initial guess at the appropriate stepping size used by the CM walker (smaller means more triangles, and longer run times, but potentially better preservation of small features.) The initial thickness is multiplied by a scale factor, which defaults to 0.15 but may be overridden by the user with the --feature-scale option. Alternately, if the user has some specific knowledge of what feature size they are likely to want, they may use the --feature-size option to directly set this parameter independent of the observed average thickness.
Because CM tends to generate a very large number of triangles, it is necessary to post process its initial mesh with a decimation routine to remove triangles which are not necessary to actual feature representation. This process is also feature-size based, and by default is set to 1.5x the feature size. However, if the user wishes to preserve more triangles than the default behavior they may manually override this parameter with the --decimation-feature-size option.
Both NMG and CM assume a geometry hierarchy containing only valid solid objects. Both methods will refuse to process any tree containing recognizably non-solid objects, as these tend to cause run-time problems and generate invalid outputs. For non-solid objects, the "--SPSR" methodology may be enabled - it will apply the Kazhdan et. al. Screened Poisson Surface Reconstruction (SPSR) process to a pseudo-randomly sampled point set generated from old_object. This methodology may not cope well with the type of points sets generated from CAD geometry and is off by default in normal facetize processing, but it is also the only currently available methodology in BRL-CAD which has a chance of generating a valid mesh from non-solid inputs.
There are three parameters available for the SPSR methodology specifically: maximum reconstruction depth (-d) will control the level of detail in the output mesh, point weight (-w) which impacts how much the output will attempt to interpolate the original inputs, and samples per node (see the Kazhdan et. al. paper for more information.) For situations where the user wishes to experiment with different point sampling schemes, they are referred to the pnts command which offers more fine grained controls when it comes to generating point sets from BRL-CAD objects.
These are some useful tricks for targeted manipulation of the facetization process.
Example 5. Reset CM state of a subset of objects.
Use search -exec to reset just the continuation method flag (will result in resume retrying CM on all missing objects, without triggering the full retry of all methods entailed by the --retry option.) More targeted searches can do this reset for more narrow subsets of the .g database.
mged> search -attr facetize:CM -exec attr rm "{}" facetize:CM ";"
Example 6. List invalid BoT objects below a comb
Use lint -M to report on invalid objects below a comb.
mged> lint -M model.f
Reports of bugs or problems should be submitted via electronic
mail to <devs@brlcad.org>