'\" t
.\"     Title: FACETIZE
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 08/28/2023
.\"    Manual: BRL-CAD User Commands
.\"    Source: BRL-CAD
.\"  Language: English
.\"
.TH "FACETIZE" "nged" "08/28/2023" "BRL\-CAD" "BRL\-CAD User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
facetize \- Creates \fInew_object\fR using \fIold_object\fR as a guide, creating an evaluated NMG or BoT planar approximation of the original shape\&.
.SH "SYNOPSIS"
.HP \w'\fBfacetize\fR\ 'u
\fBfacetize\fR [\-h] [\-v] [\-q] [\-r] [\-n] [\-T] [\-\-NMG] [\-\-CM] [\-\-SPSR] {\fIold_object\ new_object\fR}
.HP \w'\fBfacetize\ \-\-CM\fR\ 'u
\fBfacetize \-\-CM\fR [\-\-feature\-scale] [\-\-feature\-size] [\-\-decimation\-feature\-size] [\-\-max\-time] [\-\-max\-pnts] {\fIold_object\ new_object\fR}
.HP \w'\fBfacetize\ \-\-SPSR\fR\ 'u
\fBfacetize \-\-SPSR\fR [\-d] [\-w] [\-\-samples\-per\-node] {\fIold_object\ new_object\fR}
.HP \w'\fBfacetize\ \-r\fR\ 'u
\fBfacetize \-r\fR [standard_options] [\-\-resume] [\-\-retry] [\-\-in\-place] {\fIoutput_hierarchy_obj\fR}
.SH "DESCRIPTION"
.PP
Creates
\fInew_object\fR
as planar primitive shape (either an NMG or a BOT) approximating the 3D volume bound by
\fIold_object\fR\&. The
\fI\-r\fR
option will operate per\-region rather than on an entire object and produces a new hierarchy\&.
.PP
There are a number of different verbosity levels available for the facetize command\&. One or mulitple specifications of the
\fI\-v\fR
flag will increase reporting detail about what the facetize command is doing in various steps\&. To silence all output specify the
\fI\-q\fR
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\&.
.SH "PER-REGION FACETIZATION AND PARTIAL CONVERSIONS"
.PP
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
\fI\-r\fR
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\&.
.PP
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
\fBfacetize\fR\&.
.PP
By default the
\fBfacetize\fR
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
\fI\-\-in\-place\fR
option in combination with the
\fI\-r\fR
option\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Create a facetized BOT version of an existing object.\fR
.PP
The example shows the use of the
\fBfacetize\fR
command to create a facetized BOT version of an existing object (\fIold_object\fR) and renaming that facetized object (\fInew_object\fR)\&. It will try first NMG conversion, and if that fails attempts CM conversion\&.
.PP

mged>\fBfacetize region1\&.r region1\&.bot\fR
.PP
\fBExample\ \&2.\ \&Facetize all regions in a hierarchy.\fR
.PP
This runs the per region conversion on all regions under the "model" assembly and creates a new conversion hierarchy under model_facetized\&.
.PP

mged>\fBfacetize \-r model model\&.f\fR
.PP
\fBExample\ \&3.\ \&Facetize all regions in a hierarchy, attempting only NMG conversion.\fR
.PP
This runs the per region conversion on all regions, but in the case of failure will not attempt any fallback conversion methods\&.
.PP

mged>\fBfacetize \-r \-\-NMG model model\&.f\fR
.PP
\fBExample\ \&4.\ \&Retry failed conversion objects in a previous facetization attempt with new methodology.\fR
.PP
This retries the per region conversion on all regions that didn\*(Aqt originally succeed in the initial conversion attempt, attempting only CM reconstruction without first retrying NMG conversion\&.
.PP

mged>\fBfacetize \-r \-\-resume model\&.f\fR
.PP
\fBExample\ \&5.\ \&Increase Decimation in CM Mode\fR
.PP

mged>\fBfacetize \-\-CM \-\-feature\-size 0\&.06 \-\-decimation\-feature\-size 2\&.0 ellipse\&.r ell\&.bot\fR
.sp
.if n \{\
.RS 4
.\}
.nf
CM: completed in 16 seconds with size 0\&.06
CM: completed in 23 seconds with size 0\&.054
CM: timed out after 30 seconds with size 0\&.0486
CM: successfully created 6960500 faces, feature size 0\&.054
CM: decimation succeeded, final BoT has 104 faces
	
.fi
.if n \{\
.RE
.\}
.PP
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
\fBdecimation\-feature\-size\fR
option with a >1\&.5 value has dramatically reduced the count to 104\&.
.PP
\fBExample\ \&6.\ \&Decrease Decimation in CM Mode\fR
.PP

mged>\fBfacetize \-\-CM \-\-feature\-size 0\&.06 \-\-decimation\-feature\-size \&.01 ellipse\&.r ell\&.bot\fR
.sp
.if n \{\
.RS 4
.\}
.nf
CM: completed in 16 seconds with size 0\&.06
CM: completed in 23 seconds with size 0\&.054
CM: timed out after 30 seconds with size 0\&.0486
CM: successfully created 6960500 faces, feature size 0\&.054
CM: decimation succeeded, final BoT has 247642 faces
	
.fi
.if n \{\
.RE
.\}
.PP
If the intent is preserve a more detailed mesh, reducing
\fBdecimation\-feature\-size\fR
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\&.
.SH "METHODOLOGY"
.PP
Ideally users would not need to concern themselves with the details of how
\fBfacetize\fR
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\&.
.PP
By default, conversions will first attempt a standard NMG facetization and boolean evaluation of the existing geometry\&. When it succeeds, NMG\*(Aqs output is generally the best quality output that can be produced by any of BRL\-CAD\*(Aqs available facetization methods\&. If NMG booleans fail, a fall\-back method based on Bloomenthal\*(Aqs continuation method (CM) polygonalizer will be attempted by default\&.Note that if any of the methodology flags (\fI\-\-NMG\fR,\fI\-\-CM\fR, or
\fI\-\-SPSR\fR) are explicitly enabled, the other methodologies will be disabled unless they too are explicitly enabled\&.
.PP
While the
\fBfacetize\fR
command does not itself expose options to adjust the behavior of the NMG boolean methodology, it will respect MGED\*(Aqs settings for absolute (\fIabs\fR), relative (\fIrel\fR), and normal (\fInorm\fR) tolerances which are set with the MGED
\fBtol\fR
command\&. These settings may be changed between repeated runs of the facetize command to attempt different NMG evaluations\&.
.PP
Bloomenthal\*(Aqs 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
\fI\-\-feature\-scale\fR
option\&. Alternately, if the user has some specific knowledge of what feature size they are likely to want, they may use the
\fI\-\-feature\-size\fR
option to directly set this parameter independent of the observed average thickness\&.
.PP
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
\fI\-\-decimation\-feature\-size\fR
option\&. Generally speaking smaller values will lead to more meshes being retained in the final output mesh, but experimentation will likely be needed to zero in on desired results\&. See CM examples above for an illustration using the moss\&.g ellipsoid region\&.
.PP
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
\fIold_object\fR\&. This methodology may not cope well with the type of points sets generated from CAD geometry and is off by default in normal
\fBfacetize\fR
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\&.
.PP
There are three parameters available for the SPSR methodology specifically: maximum reconstruction depth (\fI\-d\fR) will control the level of detail in the output mesh, point weight (\fI\-w\fR) 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
\fBpnts\fR
command which offers more fine grained controls when it comes to generating point sets from BRL\-CAD objects\&.
.SH "USEFUL TRICKS"
.PP
These are some useful tricks for targeted manipulation of the facetization process\&.
.PP
\fBExample\ \&7.\ \&Reset CM state of a subset of objects.\fR
.PP
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\&.
.PP

mged>\fBsearch \-attr facetize:CM \-exec attr rm "{}" facetize:CM ";"\fR
.PP
\fBExample\ \&8.\ \&List invalid BoT objects below a comb\fR
.PP
Use lint \-M to report on invalid objects below a comb\&.
.PP

mged>\fB lint \-M model\&.f\fR
.SH "AUTHOR"
.PP
BRL\-CAD Team
.SH "BUG REPORTS"
.PP
Reports of bugs or problems should be submitted via electronic mail to
devs@brlcad\&.org
