Revision: 71653
http://sourceforge.net/p/brlcad/code/71653
Author: starseeker
Date: 2018-09-04 21:33:35 +0000 (Tue, 04 Sep 2018)
Log Message:
-----------
Start updates to facetize man page
Modified Paths:
--------------
brlcad/trunk/doc/docbook/system/mann/facetize.xml
Modified: brlcad/trunk/doc/docbook/system/mann/facetize.xml
===================================================================
--- brlcad/trunk/doc/docbook/system/mann/facetize.xml 2018-09-04 21:12:27 UTC
(rev 71652)
+++ brlcad/trunk/doc/docbook/system/mann/facetize.xml 2018-09-04 21:33:35 UTC
(rev 71653)
@@ -11,7 +11,7 @@
<refname>facetize</refname>
<refpurpose>
Creates <emphasis>new_object</emphasis> using
<emphasis>old_object</emphasis> as a
- starting point and then creating an NMG or BoT approximation of the
original shape.
+ guide, creating an evaluated NMG or BoT planar approximation of the
original shape.
</refpurpose>
</refnamediv>
@@ -19,41 +19,39 @@
<refsynopsisdiv xml:id="synopsis">
<cmdsynopsis sepchar=" ">
<command>facetize</command>
- <group choice="opt">
- <arg choice="opt" rep="norepeat">-h</arg>
- <arg choice="opt" rep="norepeat">-n</arg>
- <arg choice="opt" rep="norepeat">-T</arg>
- <arg choice="opt" rep="norepeat">-m</arg>
- <arg choice="opt" rep="norepeat">--nmgbool</arg>
- </group>
- <group choice="opt">
- <arg choice="opt" rep="norepeat">--poisson</arg>
- <arg choice="opt" rep="norepeat">poisson options</arg>
- </group>
+ <arg choice="opt" rep="norepeat">-h</arg>
+ <arg choice="opt" rep="norepeat">-v</arg>
+ <arg choice="opt" rep="norepeat">-q</arg>
+ <arg choice="opt" rep="norepeat">-r</arg>
+ <arg choice="opt" rep="norepeat">-n</arg>
+ <arg choice="opt" rep="norepeat">-T</arg>
+ <arg choice="opt" rep="norepeat">--nmgbool</arg>
+ <arg choice="opt" rep="norepeat">--continuation</arg>
+ <arg choice="opt" rep="norepeat">--poisson</arg>
<arg choice="req" rep="norepeat"><replaceable>old_object
new_object</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis sepchar=" ">
+ <command>facetize --continuation</command>
+ <arg choice="opt" rep="norepeat">--feature-scale</arg>
+ <arg choice="opt" rep="norepeat">--feature-size</arg>
+ <arg choice="opt" rep="norepeat">--decimation-feature-size</arg>
+ <arg choice="opt" rep="norepeat">--max-time</arg>
+ <arg choice="opt" rep="norepeat">--max-pnts</arg>
+ <arg choice="req" rep="norepeat"><replaceable>old_object
new_object</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis sepchar=" ">
<command>facetize --poisson</command>
- <group choice="opt">
- <arg choice="opt" rep="norepeat">-d</arg>
- <arg choice="opt" rep="norepeat">-w</arg>
- <arg choice="opt" rep="norepeat">--samples-per-node</arg>
- </group>
- <group>
- <arg choice="opt">-t</arg>
- <arg choice="opt" rep="norepeat">--surface</arg>
- <arg choice="opt" rep="norepeat">--grid</arg>
- <arg choice="opt" rep="norepeat">--rand</arg>
- <arg choice="opt" rep="norepeat">--sobol</arg>
- <arg choice="opt" rep="norepeat">--max-pnts</arg>
- <arg choice="opt" rep="norepeat">--max-time</arg>
- </group>
+ <arg choice="opt" rep="norepeat">-d</arg>
+ <arg choice="opt" rep="norepeat">-w</arg>
+ <arg choice="opt" rep="norepeat">--samples-per-node</arg>
<arg choice="req" rep="norepeat"><replaceable>old_object
new_object</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis sepchar=" ">
- <command>facetize -r --resume</command>
- <arg choice="opt" rep="norepeat">--nmgbool</arg>
- <arg choice="opt" rep="norepeat">--poisson</arg>
+ <command>facetize -r</command>
+ <arg choice="opt" rep="norepeat">standard_options</arg>
+ <arg choice="opt" rep="norepeat">--resume</arg>
+ <arg choice="opt" rep="norepeat">--retry</arg>
+ <arg choice="opt" rep="norepeat">--in-place</arg>
<arg choice="req"
rep="norepeat"><replaceable>output_hierarchy_obj</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -62,39 +60,103 @@
<title>DESCRIPTION</title>
<para>
Creates <emphasis>new_object</emphasis> as planar primitive shape
(either an NMG or a BOT)
- approximating the volume bound by <emphasis>old_object</emphasis>.
+ approximating the 3D volume bound by <emphasis>old_object</emphasis>.
The <emphasis>-r</emphasis>
+ option will operate per-region rather than on an entire object and
produces a new hiearchy.
</para>
<para>
+ There are a number of different verbosity levels available for the
facetize command. One or mulitple specifications
+ of the <emphasis>-v</emphasis> flag will increase reporting detail about
what the facetize command is doing in various
+ steps. To silence all output
+ specify the <emphasis>-q</emphasis> 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.
+ </para>
+ </refsection>
+ <refsection xml:id="methodology">
+ <title>METHODOLOGY</title>
+ <para>
By default, conversions will first attempt a standard NMG facetization
and boolean evaluation of
- the existing geometry. If that attempt fails, a fall-back method using
point sampling and mesh
- reconstruction will be tried. The options "--nmgbool" and "--poisson"
may be used to limit the
- attempted conversion methods to either just NMG or just Screened Poisson
Surface Reconstruction
- (SPSR).
+ 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
(<emphasis>--nmgbool</emphasis>,<emphasis>--continuation</emphasis>,
+ or <emphasis>--poisson</emphasis>) are explicitly enabled, the other
methodologies will be disabled unless they
+ too are explicitly enabled.
</para>
<para>
- Often, it is acceptable or desirable to perform facetization on each
region individually within a
+ While the <command>facetize</command> command does not itself expose
options to adjust the behavior of
+ the NMG boolean methodology, it will respect MGED's settings for
absolute (<emphasis>abs</emphasis>),
+ relative (<emphasis>rel</emphasis>), and normal
(<emphasis>norm</emphasis>) tolerances which are set with
+ the MGED <command>tol</command> command. These settings may be changed
between repeated runs of the
+ facetize command to attempt different NMG evaluations.
+ </para>
+ <para>
+ 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
<emphasis>--feature-scale</emphasis> option.
+ Alternately, if the user has some specific knowledge of what feature
size they are likely to want, they
+ may use the <emphasis>--feature-size</emphasis> option to directly set
this parameter independent of the
+ observed average thickness.
+ </para>
+ <para>
+ Because Bloomenthal's method 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
<emphasis>--decimation-feature-size</emphasis> option.
+ </para>
+ <para>
+ Both NMG boolean evaluation and Bloomenthal's method assume a geometry
hierarchy containing only
+ valid solid objects. Both of these 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 "--poisson" 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 <emphasis>old_object</emphasis>. This
+ methodology may not cope well with the type of points sets generated
from CAD geometry and is off
+ by default in normal <command>facetize</command> 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.
+ </para>
+ <para>
+ There are three parameters available for the SPSR methodology
specifically: maximum reconstruction depth
+ (<emphasis>-d</emphasis>) will control the level of detail in the output
mesh, point weight (<emphasis>-w</emphasis>)
+ 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
<command>pnts</command> command which offers
+ more fine grained controls when it comes to generating point sets from
BRL-CAD objects.
+ </para>
+ </refsection>
+
+ <refsection xml:id="regions">
+ <title>PER-REGION FACETIZATION AND PARTIAL CONVERSIONS</title>
+ <para>
+ 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
+ with the <emphasis>-r</emphasis> 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. The drawback is it will
not produce a single
- geometry object containing all output.
+ region attributes such as color and region ID.
</para>
<para>
- The Screened Poisson Surface Reconstruction algorithm, in addition to
it's -d, -w, and --samples-per-node
- parameters, also offers control over the initial raytrace sampling used
to generate the initial
- point set from the input geometry. To learn more about these options,
see the manual page for
- the "pnts gen" subcommand.
- </para>
- <para>
- Because conversion is often a long process, the facetize command (when
run in region mode) works
+ 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 -r
option - arbitrary
- existing hierarchies will not store the information needed to resume a
conversion.
+ Note that this works only for a hierarchy generated with the
<command>facetize</command>.
</para>
+ <para>
+ By default the <command>facetize</command> 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
+ <emphasis>--in-place</emphasis> option in combination with the
<emphasis>-r</emphasis> option.
+ </para>
</refsection>
+
<refsection xml:id="examples">
<title>EXAMPLES</title>
@@ -105,7 +167,7 @@
The example shows the use of the <command>facetize</command> command to
create a facetized
BOT version of an existing object (<emphasis>old_object</emphasis>) and
renaming that facetized
object (<emphasis>new_object</emphasis>). It will try first NMG
conversion, and if that fails
- attempts SPSR conversion.
+ attempts CM conversion.
</para>
<para>
<prompt>mged></prompt> <userinput>facetize region1.r
region1.bot</userinput>
@@ -119,7 +181,7 @@
a new conversion hierarchy under model_facetized.
</para>
<para>
- <prompt>mged></prompt> <userinput>facetize -r model
model_facetized</userinput>
+ <prompt>mged></prompt> <userinput>facetize -r model
model.f</userinput>
</para>
</example>
@@ -130,20 +192,36 @@
any fallback conversion methods.
</para>
<para>
- <prompt>mged></prompt> <userinput>facetize -r --nmgbool model
model_facetized</userinput>
+ <prompt>mged></prompt> <userinput>facetize -r --nmgbool model
model.f</userinput>
</para>
</example>
<example>
- <title>Retry only failed conversion objects in a previous facetization
attempt.</title>
+ <title>Retry failed conversion objects in a previous facetization
attempt with new methodology.</title>
<para>
This retries the per region conversion on all regions that didn't
originally succeed in the initial
- conversion attempt, attempting only SPSR reconstruction without first
retrying NMG conversion.
+ conversion attempt, attempting only CM reconstruction without first
retrying NMG conversion.
</para>
<para>
- <prompt>mged></prompt> <userinput>facetize -r --poisson --resume
model_facetized</userinput>
+ <prompt>mged></prompt> <userinput>facetize -r --resume
model.f</userinput>
</para>
</example>
+
+ <example>
+ <title>Retry only failed conversion objects in a previous facetization
attempt - retry all methodologies.</title>
+ <para>
+ This retries the per region conversion on all regions that didn't
originally succeed in the initial
+ conversion attempt, attempting first NMG, then CM, then SPSR
conversion. This is warranted if
+ settings were changed, geometry was updated, or other changes warrant
re-attempting steps that
+ previously did not succeed. The poisson flag is also added to maximize
conversion successes even
+ if there are non-solid shapes in the model. On a non-trivial model
this is likely to be a very
+ long running command.
+ </para>
+ <para>
+ <prompt>mged></prompt> <userinput>facetize -r --nmgbool
--continuation --poisson --retry --resume model.f</userinput>
+ </para>
+ </example>
+
</refsection>
<refsection xml:id="author">
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
BRL-CAD Source Commits mailing list
brlcad-commits@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/brlcad-commits
