Revision: 78068
http://sourceforge.net/p/brlcad/code/78068
Author: starseeker
Date: 2021-01-12 18:54:40 +0000 (Tue, 12 Jan 2021)
Log Message:
-----------
Start roughing out a man page. Need to clearly articulate what some of these
ideas are supposed to do in order to know what has to be implemented, so might
as well document the meaning while we're at it...
Modified Paths:
--------------
brlcad/trunk/doc/docbook/system/mann/CMakeLists.txt
brlcad/trunk/src/libged/npush/npush.cpp
Added Paths:
-----------
brlcad/trunk/doc/docbook/system/mann/npush.xml
Modified: brlcad/trunk/doc/docbook/system/mann/CMakeLists.txt
===================================================================
--- brlcad/trunk/doc/docbook/system/mann/CMakeLists.txt 2021-01-12 15:33:42 UTC
(rev 78067)
+++ brlcad/trunk/doc/docbook/system/mann/CMakeLists.txt 2021-01-12 18:54:40 UTC
(rev 78068)
@@ -131,6 +131,7 @@
nirt.xml
nmg_collapse.xml
nmg_simplify.xml
+ npush.xml
oed.xml
opendb.xml
orientation.xml
Added: brlcad/trunk/doc/docbook/system/mann/npush.xml
===================================================================
--- brlcad/trunk/doc/docbook/system/mann/npush.xml
(rev 0)
+++ brlcad/trunk/doc/docbook/system/mann/npush.xml 2021-01-12 18:54:40 UTC
(rev 78068)
@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<refentry xmlns="http://docbook.org/ns/docbook"; version="5.0"
xml:id="STATFORMAT" xmlns:xlink="http://www.w3.org/1999/xlink";>
+ <refmeta>
+ <refentrytitle>NPUSH</refentrytitle>
+ <manvolnum>nged</manvolnum>
+ <refmiscinfo class="source">BRL-CAD</refmiscinfo>
+ <refmiscinfo class="manual">BRL-CAD</refmiscinfo>
+ </refmeta>
+
+ <refnamediv xml:id="name">
+ <refname>npush</refname>
+ <refpurpose>
+ push matrices down a tree hierarchy
+ </refpurpose>
+ </refnamediv>
+
+ <!-- body begins here -->
+ <refsynopsisdiv xml:id="synopsis">
+ <cmdsynopsis sepchar=" ">
+ <command>npush</command>
+ <arg choice="opt" rep="norepeat">-h</arg>
+ <arg choice="opt" rep="norepeat">-?</arg>
+ <arg choice="opt" rep="norepeat">-v</arg>
+ <arg choice="opt" rep="norepeat">-f</arg>
+ <arg choice="opt" rep="norepeat">-x</arg>
+ <arg choice="opt" rep="norepeat">-r</arg>
+ <arg choice="opt" rep="norepeat">-s</arg>
+ <arg choice="opt" rep="norepeat">-d
<replaceable>max_depth</replaceable></arg>
+ <arg choice="req">arg1 [arg2]...</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsection xml:id="npush_background"><info><title>Background: Matrices in
BRL-CAD</title></info>
+
+ <para>
+ BRL-CAD uses a global coordinate system in which all objects are placed.
This means each region
+ must uniquely occupy its own portion of that space in order to avoid
overlapping with another
+ region. Naively, this means that all objects defined in a .g file need to
individually
+ describe distinct volumes using unique primitives. While possible, such
an approach is quite
+ wasteful if different regions define the same shape and vary only in the
positioning of that shape.
+ A classic example is as a standard bolt used hundereds of times in
assembling a machine - ideally
+ such a shape should only need to be described once, and then
<emphasis>instances</emphasis> of that
+ shape are positioned to identify individual bolts in the overall model.
+ </para>
+ <para>
+ COMB trees, which describe organized hierarchies of individual shapes (or
other COMB trees) in
+ BRL-CAD, are the standard mechanism used in .g files to reusing otherwise
identical object definitions
+ in <emphasis>different</emphasis> positions and orientations. Matrices
associated with instances of
+ objects listed in COMB trees position those individual parts, and matrices
at different portions of
+ the COMB tree hierarchy can position smaller or large components of the
whole.
+ For example, the tree:
+ </para>
+ <literallayout>
+ sph3/
+ u sph3_1.r/R
+ u sph3.s
+ u sph3_2.r/R
+ u sph3.s
+ </literallayout>
+ <para>
+ appears at first glance to define an overlap, since it includes two
different regions both of which
+ are defined using the same sphere object: sph3.s. However, if we inspect
sph3_1.r and sph3_2.r more
+ closely, we see that their definitions incorporate matrices over the
instances of sph3.s:
+ </para>
+ <literallayout>
+sph3_1.r: REGION id=1002 (air=0, los=100, GIFTmater=1) --
+ u sph3.s [10, 0, 0] scale 1
+sph3_2.r: REGION id=1003 (air=0, los=100, GIFTmater=1) --
+ u sph3.s [20, 0, 0] scale 1
+ </literallayout>
+ <para>
+ The instance of sph3.s in sph3_1.r is offset in the X direction by 10mm,
and the sph3_2.r instance is
+ offset by 20mm. In addition, if we inspect sph3's tree:
+ </para>
+ <literallayout>
+sph3: --
+ u sph3_1.r
+ u sph3_2.r [100, 0, 0] scale 1
+ </literallayout>
+ <para>
+ we see that the instance of sph3_2.r in sph3 also has a matrix offsetting
its position. So the
+ instance of sph.s defined by sph3/sph3_2.r/sph.s is offset in total by
120mm in the positive X direction
+ relative to the global definition of sph.s
+ </para>
+ <para>
+ As useful as these matrices are, users frequently need to consolidate
multiple levels of positioning
+ within a COMB tree, or even eliminate them completely if a client's code
is not able to properly interpret
+ the matrix information of a COMB hierarchy for its own processing. Thus,
specific logic is available in
+ BRL-CAD to accomplish these tasks.
+ </para>
+
+ </refsection>
+
+ <refsection xml:id="npush_overview"><info><title>Overview</title></info>
+
+ <para>
+ The GED command <command>npush</command> defines logic for "moving" matrix
operations within a COMB tree,
+ without changing the position of individual object instances in the tree
definition.
+ </para>
+
+ </refsection>
+
+ <refsection xml:id="search_options"><title>OPTIONS</title>
+
+ <variablelist remap="TP">
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">-h or -?</emphasis></term>
+ <listitem>
+ <para>
+ Print help and exit.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">-v</emphasis></term>
+ <listitem>
+ <para>
+ Verbose processing output (primarily used for debugging).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">-f or -x</emphasis></term>
+ <listitem>
+ <para>
+ Force creation of new objects if necessary to avoid conflicts
while fully push matrices. (A.k.a "xpush" mode).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">-r</emphasis></term>
+ <listitem>
+ <para>
+ Halt push operations at the hierarchy level above regions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">-s</emphasis></term>
+ <listitem>
+ <para>
+ Halt push operations at the hierarchy level above solids.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">-d max_depth</emphasis></term>
+ <listitem>
+ <para>
+ Halt push operations at the hierarchy level specified by
<emphasis>max_depth</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsection>
+
+ <refsection xml:id="examples"><title>EXAMPLES</title>
+
+ <example><title>Default</title>
+ <para>
+ <userinput>push sph1</userinput>
+ </para>
+ <literallayout>
+ </literallayout>
+ </example>
+
+ </refsection>
+
+</refentry>
Property changes on: brlcad/trunk/doc/docbook/system/mann/npush.xml
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:mime-type
## -0,0 +1 ##
+text/xml
\ No newline at end of property
Modified: brlcad/trunk/src/libged/npush/npush.cpp
===================================================================
--- brlcad/trunk/src/libged/npush/npush.cpp 2021-01-12 15:33:42 UTC (rev
78067)
+++ brlcad/trunk/src/libged/npush/npush.cpp 2021-01-12 18:54:40 UTC (rev
78068)
@@ -71,6 +71,7 @@
std::map<struct directory *, int> s_c;
int verbosity = 0;
int max_depth = 0;
+ bool stop_at_regions = false;
const struct bn_tol *tol;
};
@@ -91,6 +92,17 @@
return false;
}
+ /* Solids are always leaves, since there's nothing to walk */
+ if (!(dp->d_flags & RT_DIR_COMB)) {
+ return true;
+ }
+
+ /* Regions may be leaves, depending on user options */
+ if ((dp->d_flags & RT_DIR_REGION) && s->stop_at_regions) {
+ return true;
+ }
+
+ /* Depth halting may be active */
if (s->max_depth && (depth >= s->max_depth))
return true;
@@ -151,10 +163,7 @@
}
bn_mat_mul(*curr_mat, om, nm);
- /* Process branch. Note - in pushes leaf_func is null, since
- * matrix operations are defined in comb trees. If solids need to
- * be updated to push matrices to their parameters, this is handled
- * at the end when we have full knowledge of what must be done. */
+ /* Process branch. */
push_walk(dbip, dp, comb_func, leaf_func, resp, depth, curr_mat,
client_data);
/* Done with branch - put back the old matrix state */
@@ -284,7 +293,8 @@
s->s_i.insert(idp);
}
-void comb_cnt(struct db_i *dbip, struct directory *dp, int depth, mat_t
*curr_mat, void *data)
+static void
+process_comb(struct db_i *dbip, struct directory *dp, int depth, mat_t
*curr_mat, void *data)
{
struct rt_db_internal intern;
if (rt_db_get_internal(&intern, dp, dbip, (fastf_t *)NULL,
&rt_uniresource) < 0) {
@@ -300,7 +310,24 @@
}
}
+static void
+process_solid(struct db_i *dbip, struct directory *dp, int depth, mat_t
*UNUSED(curr_mat), void *data)
+{
+ if (!depth)
+ return;
+ struct rt_db_internal intern;
+ if (rt_db_get_internal(&intern, dp, dbip, (fastf_t *)NULL,
&rt_uniresource) < 0) {
+ return;
+ }
+ rt_db_free_internal(&intern);
+ struct push_state *s = (struct push_state *)data;
+ if (s->verbosity) {
+ bu_log("Processed solid (depth: %d): %s\n", depth, dp->d_namep);
+ }
+}
+
+
static void
npush_usage(struct bu_vls *str, struct bu_opt_desc *d) {
char *option_help = bu_opt_describe(d, NULL);
@@ -377,7 +404,7 @@
for (s_it = s.target_objs.begin(); s_it != s.target_objs.end(); s_it++) {
struct directory *dp = db_lookup(dbip, s_it->c_str(), LOOKUP_NOISY);
if (dp != RT_DIR_NULL)
- push_walk(dbip, dp, comb_cnt, NULL, &rt_uniresource, 0, &m, &s);
+ push_walk(dbip, dp, process_comb, process_solid, &rt_uniresource,
0, &m, &s);
}
/* Sanity - if we didn't end up with m back at the identity matrix,
@@ -399,7 +426,7 @@
for (int i = 0; i < tops_cnt; i++) {
struct directory *dp = all_paths[i];
if (s.target_objs.find(std::string(dp->d_namep)) == s.target_objs.end())
- push_walk(dbip, dp, comb_cnt, NULL, &rt_uniresource, 0, &m, &s);
+ push_walk(dbip, dp, process_comb, process_solid, &rt_uniresource,
0, &m, &s);
}
bu_free(all_paths, "free db_ls output");
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
_______________________________________________
BRL-CAD Source Commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/brlcad-commits
