'\" t
.\"     Title: COMB
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 04/13/2022
.\"    Manual: BRL-CAD User Commands
.\"    Source: BRL-CAD
.\"  Language: English
.\"
.TH "COMB" "nged" "04/13/2022" "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"
comb \- Create and manipulate BRL\-CAD combination with the name \fIcombination_name\fR\&.
.SH "SYNOPSIS"
.HP \w'\fBcomb\fR\ 'u
\fBcomb\fR [[\-c] | [\-r]] [[\-w] | [\-f] | [\-l]] [[\-S]] {\fIcombination_name\fR} [\fI<operator\ object_name>\fR...]
.SH "DESCRIPTION"
.PP
The
\fBcomb\fR
command creates and manipulates
\fIBRL\-CAD\fR
combination objects\&. For combination creation or appending,
\fIoperator/object_name\fR
pairs of boolean operators and object names are parsed into comb tree entries\&. (TODO \- integrate full expression evaluation like that in
\fBc\fR\&.)
.PP
The following options are recognized:
.PP
\fB\-c\fR
.RS 4
Ensures that the combination does not have the region flag set\&. Conflicts with
\fB\-r\fR\&.
.RE
.PP
\fB\-r\fR
.RS 4
Ensures that the combination does have the region flag set\&. Conflicts with
\fB\-c\fR\&.
.RE
.PP
\fB\-w\fR
.RS 4
Moves the contents of a combination to a new combination and makes that combination the sole child of the original combination\&. See the "fixing nested regions" example below for an illustration of how this option is used\&. Conflicts with
\fB\-f\fR
and
\fB\-l\fR\&.
.RE
.PP
\fB\-f\fR
.RS 4
Flattens a combination that contains only unions into a single top level combination with all of the solids unioned into it, and remove all combinations that were below the input combination that are not used elsewhere in the \&.g file\&. (In essence, the latter behavior prevents "orphaned" combinations that are no longer used from showing up as new top level objects in the database\&.) This feature will not work on any combination containing non\-union boolean operations\&. The following
\fBsearch\fR
command can be used to find combs that are candidates for flattening:
.sp
.if n \{\
.RS 4
.\}
.nf
		    
mged> \fBsearch \-type comb ! \-below ( \-bool + \-or \-bool \- )\fR
		    
	    
.fi
.if n \{\
.RE
.\}
.sp
Conflicts with
\fB\-w\fR
and
\fB\-l\fR\&.
.RE
.PP
\fB\-l\fR
.RS 4
"Lift" a region flag to the top comb, and clear all region flags below the comb in the tree\&. Like the
\fBf\fR
option this option will work to respect the integrity of other geometry in the database, but it is more aggressive in the steps it will take and it will operate on trees that contain non\-union booleans\&. The decision logic is as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Check if regions below the current comb are used elsewhere in the \&.g file\&. If they are not, they will simply be converted to combs\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
For regions that are used elsewhere in the \&.g file, determine if their parent comb (if that comb is not the original comb supplied to the command) is also used elsewhere in the \&.g file\&. If not, the
\fBw\fR
wrapping behavior is used to produce a non\-region equivalent comb, and the parent comb is updated to use that new comb instead of the region\&. If one or more parent combs
\fIare\fR
used elsewhere (i\&.e\&. the parent comb cannot be altered without altering other geometry) the command will fail \- manual intervention is required to resolve the situation\&.
.RE
.sp
Conflicts with
\fB\-w\fR
and
\fB\-f\fR\&.
.RE
.PP
\fB\-S\fR
.RS 4
Stop if the combination object already exists\&.
.RE
.SH "EXAMPLES"
.PP
This example shows how to use the
\fBcomb\fR
command to create a combination according to a given formula\&.
.PP
\fBExample\ \&1.\ \&Creating a combination.\fR
.PP
mged> \fBcomb abc u a u b \- a + d\fR
.RS 4
Creates a combination named
\fIabc\fR\&.
.RE
.PP
\fBExample\ \&2.\ \&Fixing a nested region.\fR
.PP
Nested regions (a region containing another region in its tree) are generally viewed as poor modelling practice\&. This example shows how to fix an instance of this nesting with minimal disruption to the model\&.
.RS 4
.sp
Suppose we have a situation where
\fIregion2\&.r\fR
is unioned into
\fIregion1\&.r\fR, and both
\fIregion1\&.r\fR
and
\fIregion2\&.r\fR
have the region flag set, as seen in the tree below\&.
.sp
.if n \{\
.RS 4
.\}
.nf
      
mged> \fBtree region1\&.r\fR
region1\&.r/R
        u region2\&.r/R
                u sph\&.s
        u comb\&.c/
                u arb\&.s
      
      
.fi
.if n \{\
.RE
.\}
.sp
This geometry has an error in that one region is not supposed to be combined into another using boolean operations\&. Further, suppose that one or more assemblies use
\fIregion2\&.r\fR
and expect it to be a region \- i\&.e\&.,
\fIregion2\&.r\fR
needs to remain a region with the same contents\&. To fix this problem without disturbing other geometry using
\fIregion2\&.r\fR, first make a combination below
\fIregion2\&.r\fR
using the
\fBw\fR
flag to
\fBcomb\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
      
mged> \fBcomb \-w region2\&.r\fR
mged> \fBtree region2\&.r\fR
region2\&.r/R
        u region2\&.r\&.c/
                  u sph\&.s
      
      
.fi
.if n \{\
.RE
.\}
.sp
The next step is to adjust the
\fIregion1\&.r\fR
tree definition to reference the non\-region combination instead of
\fIregion2\&.r\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
      
mged> \fBset glob_compat_mode 0\fR
0
mged> \fBget region1\&.r tree\fR
u {l region2\&.r} {l comb\&.c}
mged> \fBadjust region1\&.r tree {u {l region2\&.r\&.c} {l comb\&.c}}\fR
mged> \fBtree region1\&.r\fR
region1\&.r/R
        u region2\&.r\&.c/
                u sph\&.s
        u comb\&.c/
                u arb\&.s
      
      
.fi
.if n \{\
.RE
.\}
.sp
Because the tree is manipulated as a Tcl list, we need glob compatibility mode to be off on the MGED command line\&. Once the tree is re\-defined,
\fIregion1\&.r\fR
no longer has
\fIregion2\&.r\fR
below it, but still defines the same physical volume via
\fIregion2\&.r\&.c\fR\&.
.sp
Optionally, the name
\fIregion2\&.r\&.c\fR
can be changed to the name
\fIregion2\&.c\fR
with the
\fBmvall\fR
command:
.sp
.if n \{\
.RS 4
.\}
.nf
      
mged> \fBmvall region2\&.r\&.c region2\&.c\fR
mged> \fBtree region1\&.r\fR
region1\&.r/R
        u region2\&.c/
                u sph\&.s
        u comb\&.c/
                u arb\&.s
mged> \fBtree region2\&.r\fR
region2\&.r/R
        u region2\&.c/
                u sph\&.s
      
      
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&3.\ \&Flattening a Combination.\fR
.PP
When a combination contains only unioned objects, it can be flattened with the \fBf\fR option\&.
.RS 4
.sp
First, create an appropriate example to properly illustrate the option\*(Aqs behavior:
.sp
.if n \{\
.RS 4
.\}
.nf
			  
mged> \fBmake sph1\&.s sph\fR
mged> \fBmake sph2\&.s sph\fR
mged> \fBcomb sph1\&.c u sph1\&.s\fR
mged> \fBcomb sph2\&.c u sph2\&.s\fR
mged> \fBcomb spheres\&.c u sph1\&.c u sph2\&.c\fR
mged> \fBcomb misc\&.c u sph2\&.c\fR
mged> \fBtree spheres\&.c\fR
spheres\&.c/
         u sph1\&.c/
                 u sph1\&.s
         u sph2\&.c/
                 u sph2\&.s

mged> \fBtree misc\&.c\fR
misc\&.c/
         u sph2\&.c/
                 u sph2\&.s

mged> \fBtops\fR
misc\&.c/               spheres\&.c
      
      
.fi
.if n \{\
.RE
.\}
.sp
Note that
\fIsph2\&.c\fR
is used in both
\fIspheres\&.c\fR
and
\fImisc\&.c\fR, but
\fIsph1\&.c\fR
is only used in
\fIspheres\&.c\fR
In the
\fBtops\fR
command output,
\fImisc\&.c\fR
and
\fIspheres\&.c\fR
are the only top level objects\&. Targeting
\fIspheres\&.c\fR
with the
\fBf\fR
option reworks the tree as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
      
mged> \fBcomb \-f spheres\&.c\fR
mged> \fBtree spheres\&.c\fR
spheres\&.c/
        u sph1\&.s
        u sph2\&.s

mged> \fBtree misc\&.c\fR
misc\&.c/
         u sph2\&.c/
                 u sph2\&.s

mged> \fBtops\fR
misc\&.c/               spheres\&.c
      
      
.fi
.if n \{\
.RE
.\}
.sp
Notice that while
\fIspheres\&.c\fR
has indeed been flattened and no longer has the intermediate combinations over its solids,
\fImisc\&.c\fR
is still intact\&. Notice also that while
\fIsph2\&.c\fR
was preserved, since it is used by
\fImisc\&.c\fR,
\fIsph1\&.c\fR
was removed and does not show up in the
\fBtops\fR
command\*(Aqs output since it was no longer used by any object in the database\&.
.RE
.PP
\fBExample\ \&4.\ \&Example Of Comb Region Lifting.\fR
.PP
The \fBl\fR option is useful in cases where many \fBw\fR type operations are needed\&.
.RS 4
.sp
Suppose a geometry has the following structure:
.sp
.if n \{\
.RS 4
.\}
.nf
			  
mged> \fBmake sph1\&.s sph\fR
mged> \fBmake sph2\&.s sph\fR
mged> \fBr r1 u sph1\&.s\fR
mged> \fBr r2 u sph2\&.s\fR
mged> \fBcomb assembly u r1 u r2\fR
mged> \fBr r3 u r1 \- r2\fR
mged> \fBtops\fR
assembly/           r3/R

mged> \fBtree assembly\fR
assembly/
        u r1/R
                u sph1\&.s
        u r2/R
                u sph2\&.s
mged> \fBtree r3\fR
r3/R
        u r1/R
                u sph1\&.s
        \- r2/R
                u sph2\&.s
      
      
.fi
.if n \{\
.RE
.\}
.sp
There are regions below region
\fIr3\fR, which is not good modeling practice\&. The
\fBl\fR
option applied to
\fIr3\fR
makes
\fIr3\fR
a region that no longer has regions below it, while at the same time preserving the geometric volumes defined by all existing combs and preserving the meaning of the
\fIassembly\fR
region definitions:
.sp
.if n \{\
.RS 4
.\}
.nf
      
mged> \fBcomb \-l r3\fR
mged> \fBtree assembly\fR
assembly/
        u r1/R
                u r1\&.c/
                         u sph1\&.s
        u r2/R
                u r1\&.c/
                         u sph1\&.s
mged> \fBtree r3\fR
r3/R
        u r1\&.c/
                u sph1\&.s
        \- r2\&.c/
                u sph2\&.s

      
      
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&5.\ \&Example Tree Structure That Will Prevent Successful Region Lifting.\fR
.PP
While the \fBl\fR option can handle many tree configurations, there are some situations where manual intervention is required\&. This example illustrates one such case\&.
.RS 4
.sp
Suppose a geometry has the following structure:
.sp
.if n \{\
.RS 4
.\}
.nf
			  
mged> \fBmake sph1\&.s sph\fR
mged> \fBmake sph2\&.s sph\fR
mged> \fBmake sph3\&.s sph\fR
mged> \fBr r1 u sph1\&.s\fR
mged> \fBr r2 u sph2\&.s\fR
mged> \fBcomb subassembly u r1 u r2\fR
mged> \fBr r3 u sph3\&.s \- subassembly\fR
mged> \fBcomb assembly u subassembly\fR
mged> \fBtops\fR
assembly/           r3/R

mged> \fBtree assembly\fR
assembly/
        u subassembly/
                u r1/R
                        u sph1\&.s
                u r2/R
                        u sph2\&.s
mged> \fBtree r3\fR
r3/R
        u sph3\&.s
        \- subassembly/
                u r1/R
                        u sph1\&.s
                u r2/R
                        u sph2\&.s

      
      
.fi
.if n \{\
.RE
.\}
.sp
This geometry has regions below region
\fIr3\fR, which is not ideal\&. However, attempting to use the
\fBl\fR
option on
\fIr3\fR
will produce the following error:
.sp
.if n \{\
.RS 4
.\}
.nf
      
mged> \fBcomb \-l r3\fR
Comb region lift failed \- the following combs in the tree contain
regions and are also used outside the tree of r3:

subassembly, containing region r1
subassembly, containing region r2

The above combs must be reworked before region lifting the tree
of r3 can succeed\&.
      
      
.fi
.if n \{\
.RE
.\}
.sp
While
\fIr3\fR
has problems, the geometry tree under
\fIassembly\fR
is entirely correct\&. For
\fIr3\fR
to become a toplevel region with no regions under it, the definition of
\fIsubassembly\fR
would have to change too\&. Because
\fIsubassembly\fR
is used in the definition of
\fIassembly\fR, as well as the definition of
\fIr3\fR, changing
\fIsubassembly\fR\*(Aqs contents would destroy the meaning of the (valid)
\fIassembly\fR
comb\&. Hence, the command fails and does not change the geometry\&.
.RE
.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
