'\" t
.\"     Title: GQA
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 04/13/2022
.\"    Manual: BRL-CAD MGED Commands
.\"    Source: BRL-CAD
.\"  Language: English
.\"
.TH "GQA" "nged" "04/13/2022" "BRL\-CAD" "BRL\-CAD MGED 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"
gqa \- a BRL\-CAD quantitative geometry analysis tool
.SH "SYNOPSIS"
.HP \w'\fBgqa\fR\ 'u
\fBgqa\fR [\fIoptions\fR] \fIobjects\fR
.SH "DESCRIPTION"
.PP
The
\fBgqa\fR
program computes and reports a variety of characteristics of the
\fIobjects\fR
specified from the given
\fImodel\&.g\fR
geometric description\&. The characteristics which can be computed include
\fBweight, volume, overlaps, exposed air, gaps/voids,\fR
and
\fBadjacent air\&.\fR
Only the
\fIobjects\fR
from the database specified on the command line are analyzed\&.
.PP
It works by shooting grids of rays from the three axis\-aligned directions (sometimes called
\fIviews\fR)\&.
.PP
For volume/weight calculations the resulting calculations for each view are compared to each other\&. The grid of rays is progressively refined until the results from all three views agree within a user\-specifiable tolerance, or a limit on grid refinement is reached\&.
.PP
For error and interface calculations, the grid is refined until an error is found or the grid refinement limit is reached\&.
.PP
When multiple calculations are performed, the most extensive path is taken\&. For example, if weight and overlap calculations are performed, then the grid will be refined until the refinement limit is reached, or an overlap is detected\&.
.SH "VOLUME AND WEIGHT CALCULATION"
.PP
If volume or weight calculation is selected, a value is calculated and reported for each
\fIobject\fR
specified on the command line\&.
\fBNote that if there are overlaps or other errors in the geometry, the values reported will be invalid\&.\fR
.PP
For weight computation, the density of every region must be specified\&. Densities are specified as an index in a table of density values\&. This index is stored in the
\fIGIFTmater\fR
attribute of each region (typically set with the
\fIedcodes\fR
or
\fIadjust\fR
commands in MGED)\&.
.PP
The density table consists of three columns:
.PP
\fIAn integer index value\&.\fR
.RS 4
This is the value to which the
\fIGIFTmater\fR
attribute will be set to select this material for the region\&.
.RE
.PP
\fIA floating point density value\&.\fR
.RS 4
This is the density for the material, and is specified in
\fBgrams/cc\fR\&.
.RE
.PP
\fIA name string\&.\fR
.RS 4
This is a name or description the material\&.
.RE
.PP
This information may be stored in the \&.g file or as a separate density file\&.
.PP
To check if the \&.g file you are using has a density table, use the
\fBmater \-d get *\fR
command to see if any information is already defined (if no density information is found, an error message will be returned\&.) If no pre\-existing information is available, a density table may be defined in an external file using a text editor\&. (Alternately, it may also be built up within MGED directly using the
\fBmater \-d set\fR
command\&.)
.PP
An example file might look like the following:
.sp
.if n \{\
.RS 4
.\}
.nf
#******************************************************************************
#  sample \&.density file for check, gqa and rtweight
#******************************************************************************
#
#     *** IMPORTANT: This file may change over time and should not be
#     *** relied upon for production analysis work\&.
#
#     All densities are in units of g/cm^3\&.
#
#******************************************************************************
#
# To use the file with rtweight, copy the file to your working directory:
#   cp GQA_SAMPLE_DENSITIES \&.density
#
# To use the file with check/gqa, import the file data as a binary object:
#   mged file\&.g bo \-i u c _DENSITIES GQA_SAMPLE_DENSITIES
#
#******************************************************************************

2    7\&.82      Carbon Tool Steel
3    2\&.7       Aluminum, 6061\-T6
4    2\&.74      Aluminum, 7079\-T6
5    8\&.9       Copper, pure
6    19\&.32     Gold, pure
7    8\&.03      Stainless, 18Cr\-8Ni
8    7\&.47      Stainless 27Cr
9    7\&.715     Steel, tool
10   7\&.84      Carbon Steel
12   3\&.00      Gunner
14   10\&.00     Fuel

   
.fi
.if n \{\
.RE
.\}
.PP
To import an existing density file into the database, use the
\fBmater \-d import\fR
command:
.PP

mged>\fBmater \-d import \fR\fB\fIfilename\fR\fR
.PP
If existing density values need to be corrected in the \&.g file, the
\fBmater \-d set\fR
command may be used to alter them\&. For more about density information manipulation, see the
\fBmater\fR(N)
manual page\&.
.PP
The geometry editor MGED automatically assigns an index value of
1
to a newly created region\&. While this default can be handy when a vast majority of objects are made from the same material, it can lead to surprising errors when objects which are supposed to have a certain weight are computed to have different weight because one or two regions were not set to the correct, nondefault index value\&. As a result, it is advised that the index value
1
never be used\&. If this practice is followed, then an error message will be generated for any regions which have not had their material index set to something other than the default\&.
.SH "GEOMETRY ERROR DETECTION"
.PP
All of these calculations run until an error is detected, or until the grid refinement limit is reached\&.
.SH "OVERLAP DETECTION"
.PP
For each pair of regions that overlap, the tool reports the two regions that overlap, the maximum line\-of\-sight thickness of the overlap, and the in\-hit location of the ray that caused that maximum overlap thickness\&.
.PP
Other analyses in the error detection category behave in a similar manner\&.
.SH "OPTIONS"
.PP
\fB\-A \fR\fIanalysis_flags\fR
.RS 4
Specifies which computations are to be performed and reported\&. The
\fIanalysis_flags\fR
parameter is one or more of the following:
.sp
.TS
allbox tab(:);
lB lB.
T{
value
T}:T{
report generated
T}
.T&
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
A
T}:T{
all
T}
T{
w
T}:T{
Weight
T}
T{
a
T}:T{
Adjacent different air
T}
T{
b
T}:T{
Bounding box dimensions
T}
T{
e
T}:T{
Exposed air
T}
T{
g
T}:T{
Gaps/voids
T}
T{
m
T}:T{
Weight + Centroids + Moments of Inertia
T}
T{
o
T}:T{
Overlaps
T}
T{
p>
T}:T{
Visualize Overlaps
T}
T{
v
T}:T{
Volume
T}
.TE
.sp
Only those reports requested will be provided\&. The default is
\fB\-AA\fR
to produce all reports\&.
.sp

\fBAdjacent different air (a):\fR
Detects air volumes which are next to each other but have different air_code values applied to the region\&. This would typically indicate that the regions are different types of air, such as crew_air (which fills the crew compartment of a vehicle) and engine_air (which surrounds the engine)\&. When these different types of air adjoin each other, it is generally considered a modeling error\&.
.sp

\fBBounding box dimensions (b):\fR
Reports the dimensions of an axis\-aligned box which fully encloses the
\fIobjects\fR\&.
.sp

\fBExposed air (e):\fR
This causes checks to be made to see if the ray encounters air regions before (or after all) solid objects\&. It also checks to see if the ray moves from a void to an air region\&. Typically, only the air inside a building or vehicle is modeled if the purpose of the model is to support analysis of that single structure/vehicle\&. There are exceptions, such as when modeling larger environments for more extended analysis purposes\&.
.sp

\fBGaps/voids (g):\fR
This reports when there is more than
\fIoverlap_tol_dist\fR
(see the
\fB\-t\fR
option below) between objects on the ray path\&. Note that not all gaps are errors\&. For example, gaps between a wheel and a fender are expected (unless external air is modeled)\&. Typically, users should perform gap analysis on contained subsets of a model (such as passenger compartments) rather than on whole vehicles\&.
.sp

\fBOverlaps (o):\fR
are two regions which occupy the same space\&. In the real world, two objects may not occupy the same space\&. This check is sometimes also known as
\fIinterference checking\fR\&. Two objects must overlap by at least
\fIoverlap_tol_dist\fR
(see the
\fB\-t\fR
option below) to be considered to overlap\&. Overlap testing causes the grid spacing to be refined until the limit is reached, or an overlap is detected\&. See the
\fB\-g\fR
option below for details on setting the grid spacing\&. Once overlaps have been detected, grid refinement is not done, and processing stops\&.
.sp

\fBVisualize Overlaps (p):\fR
In MGED, if overlaps are detected, this option causes the overlaps found to be illustrated in the wireframe view via yellow lines\&.
.sp

\fBVolume (v):\fR
Computes the volume of the
\fIobjects\fR
specified on the command line\&.
.sp

\fBWeight (w):\fR
Computes the weight of the
\fIobjects\fR
specified on the command line\&.
.RE
.PP
\fB\-a \fR\fIazimuth_deg\fR
.RS 4
\fBNot Implemented\&.\fR
.sp
Sets a rotation (in degrees) of the coordinate system by a given amount about the Z axis\&. The default is 0\&. See also:
\fB\-e\fR
.RE
.PP
\fB\-e \fR\fIelevation_deg\fR
.RS 4
\fBNot Implemented\&.\fR
.sp
Sets a rotation (in degrees) of the coordinate system by a given elevation from the XY plane (rotation about X axis?)\&. The default is 0\&. See also
\fB\-a\fR
.RE
.PP
\fB\-f \fR\fIfilename\fR
.RS 4
Specifies that density values should be taken from an external file instead of from the
\fB_DENSITIES\fR
object in the database\&. This option can be useful when developing the density table with a text editor, prior to importing it to the geometric database\&.
.RE
.PP
\fB\-g \fR\fI[initial_grid_spacing\-]grid_spacing_limit\fR
.RS 4
Specifies a limit on how far the grid can be refined and optionally the initial spacing between rays in the grids\&. The first value (if present) indicates the initial spacing between grid rays\&. The mandatory argument, "\fIgrid_spacing_limit\fR," indicates a lower bound on how fine the grid spacing may get before computation is terminated\&. In general, the
\fIinitial_grid_spacing\fR
value should be an integer power of the
\fIgrid_spacing_limit\fR\&. So for example, if
\fIgrid_spacing_limit\fR
has the value 1, then any
\fIinitial_grid_spacing\fR
specified should be in the sequence 2, 4, 8, 16, 32\&.\&.\&. so that the grid will refine to precisely the lower limit\&. The grid spacing may be specified with units\&. For example:
\fB5 mm\fR
or
\fB10 in\&.\fR
If units are not provided, millimeters are presumed to be the units\&.
.RE
.PP
The default values are 50\&.0 mm and 0\&.5 mm, which is equivalent to specifying:
\fB\-g 50\&.0mm\-0\&.5mm\fR
or
\fB\-g 50\&.0mm,0\&.5mm\fR
on the command line\&. This is a hard limit\&. If other analysis constraints are not met, the grid spacing will never be refined smaller than the minimum grid size to satisfy another constraint\&. The initial grid spacing is divided in half at each refinement step\&. As a result, if you desire a lower limit to actually be tested, then the initial grid size must be a power of 2 greater\&. For example, specifying \-g10mm,1mm would result in grid spacings of 10, 5, 2\&.5, 1\&.25 being used\&. If the goal was to exactly end at a 1mm grid, then values such as 8 or 16 should have been chosen for the initial values\&. This would result in testing 16, 8, 4, 2, 1 grid spacing values\&.
.PP
\fB\-G\fR
.RS 4
\fBNot Implemented\&.\fR
.sp
Specifies that the program should create new
\fIassembly combinations\fR
in the geometry database to represent the overlap pairs\&. This flag is meaningless if overlap reporting is not turned on with the
\fB\-A\fR
option\&. If regions
\fIrod\&.r\fR
and
\fIdisk\&.r\fR
overlap, this option will cause the creation of an assembly called
_OVERLAP_rod\&.r_disk\&.r, which includes the following items:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
\fIrod\&.r\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
\fIdisk\&.r\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
\fI_OVERLAP_lines_rod\&.r_disk\&.r\fR
.RE
.sp
The last item is an object to represent the overlapping area so that it can be easily seen\&. The default is that no groups are created\&.
.RE
.PP
\fB\-n \fR\fInum_hits\fR
.RS 4
Specifies that the grid be refined until each region has at least
\fInum_hits\fR
ray intersections\&. It applies only when weight or volume calculations are being performed\&. This limit is not applied per\-view, but rather per\-analysis\&. So, for example, it is accepted that a thin object might not be hit at all from one view, but might be hit when it is shot from other views\&.
.RE
.PP
The default is 1\&. Hence, each region must be intersected by a ray at least once during the analysis\&.
.PP
\fB\-N \fR\fInum_views\fR
.RS 4
Specifies that only the first
\fInum_views\fR
should be computed\&. This is principally a debugging option\&.
.RE
.PP
\fB\-p\fR
.RS 4
Specifies that
\fBgqa\fR
should produce plot files for each of the analyses it performs\&. These can be overlaid on the geometry in
\fImged\fR
with the
\fIoverlay\fR
command to help visualize the analysis results\&. Each of the different analysis types write to a separate plot file and use different colors for drawing\&.
.RE
.PP
\fB\-P \fR\fIncpu\fR
.RS 4
Specifies that
\fIncpu\fR
CPUs should be used for performing the calculation\&. By default, all local CPUs are utilized\&. This option exists primarily to reduce the number of computation threads from the machine maximum\&. Note that specifying more CPUs than are present on the machine does not increase the number of computation threads\&.
.RE
.PP
\fB\-q\fR
.RS 4
Quiets (suppresses) the "was not hit" reporting\&.
.RE
.PP
\fB\-r\fR
.RS 4
Indicates that
\fBgqa\fR
should print per\-region statistics for weight and volume as well as the values for the objects specified on the command line\&.
.RE
.PP
\fB\-S \fR\fIsamples_per_model_axis\fR
.RS 4
Specifies that the grid spacing will be initially refined so that at least
\fIsamples_per_axis_min\fR
will be shot along each axis of the bounding box of the model\&. For example, if the objects specified have a bounding box of 0 0 0 \-> 4 3 2 and the grid spacing is 1\&.0, specifying the option
\fB\-S 4\fR
will cause the initial grid spacing to be adjusted to 0\&.5 so that 4 samples will be shot across the Z dimension of the bounding box\&. The default is to ensure 1 ray per model grid axis\&.
.RE
.PP
\fB\-t \fR\fIoverlap_tolerance\fR
.RS 4
Sets the tolerance for computing overlaps\&. The
\fIoverlap_tolerance\fR
must be a positive number equal to or greater than 0\&.0\&. Any overlap smaller than the value specified will be ignored\&. The default value is 0\&.0, which causes any overlap to be reported/processed\&. The value may be specified with a unit specifier such as:
\fB\-t 1\&.0mm\fR
or
\fB\-t 0\&.25in\&.\fR
.RE
.PP
\fB\-U \fR\fIuse_air\fR
.RS 4
Specifies the Boolean value (0 or 1) for
\fIuse_air\fR
which indicates whether regions which are marked as "air" should be retained and included in the raytrace\&.
\fBUnlike other BRL\-CAD raytracing applications, the default is to retain air in the raytracing\&.\fR
The
\fB\-U 0\fR
option causes air regions to be discarded prior to raytracing\&. If you turn off use_air, and request any analysis that requires it (see
\fB\-A\fR
above), then the program will exit with an error message\&.
.RE
.PP
\fB\-u \fR\fIdistance,volume,weight\fR
.RS 4
Specify the units used when reporting values\&. Values must be comma delimited and provided in the order
\fIdistance\fR,\fIvolume\fR,
\fIweight\fR\&. For example:
\fB\-u "cm,cu ft,kg"\fR
or
\fB\-u ,,kg\fR
(The latter example sets only the weight units\&.) Note that unit values with spaces in their names such as
\fIcu ft\fR
must be contained in quotes for the shell to keep the values together\&.
.sp
The default units are millimeters, cubic millimeters, and grams\&.
.RE
.PP
\fB\-v\fR
.RS 4
Turns on verbose reporting of computation progress\&. This is useful for learning how the computation is progressing, and what tolerances are causing further computation to be necessary\&.
.RE
.PP
\fB\-V \fR\fIvolume_tolerance[units]\fR
.RS 4
Specifies a volumetric tolerance value that the three view computations must be within for computation to complete\&. If volume calculation is selected and this option is not set, then the tolerance is set to 1/1,000 of the volume of the model bounding box\&. For large, complex objects (such as entire vehicles), this value might need to be set larger to achieve reasonable runtimes (or even completion)\&. Given the approximate sampling nature of the algorithm, the three separate view computations will not usually produce identical results\&.
.RE
.PP
\fB\-W \fR\fIweight_tolerance[units]\fR
.RS 4
This is like the volume tolerance,
\fB\-T\fR, but is applied to the weight computation results, not the volume computation results\&.
.sp
The weight computation tolerance is probably more appropriate when doing whole\-vehicle analysis\&. If weight computation is selected, it is set to a value equal to the weight of an object 1/100 the size of the model, which is made of the most dense material in the table\&.
.RE
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Default Behavior\fR
.PP
The following command computes the weight of an object called
\fIwheel\&.r\fR
reports the weight and volume, and checks for overlaps\&. Assumes a _DENSITIES table object is present in the database\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\fBgqa wheel\&.r\fR
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&2.\ \&Specifying Grid and Target Objects\fR
.PP
The following will check objects hull, turret, and suspension for overlaps and report exposed air\&. The grid starts at 1 cm and is refined to 1 mm unless overlaps or exposed air are detected before the grid is refined to 1 mm\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\fBgqa \-g 1cm\-1mm \-Aoe hull turret suspension\fR
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&3.\ \&Specifying Using Non-Default Units\fR
.PP
The following computes volume and weight of hull, turret, and suspension\&. Results are reported in cubic centimeters (cc) and ounces (oz)\&. The grid spacing starts at 5 in\&. and will not be refined below 0\&.3 mm spacing\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\fBgqa \-g5in\-0\&.3mm \-Avw \-u ft,cc,oz hull turret suspension\fR
.fi
.if n \{\
.RE
.\}
.sp

.PP
For an example of each independent analysis type, consider the following:
.PP
mged> \fBgqa \-u m,m^3,kg \-Ao overlaps\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
Units:
length: m volume: m^3 weight: kg
grid spacing 50mm  199 x 199 x 199
Summary:
list Overlaps:
/overlaps/overlap_obj\&.r /overlaps/closed_box\&.r count:32039 dist:8m @ (9050 1000 1000)
	  
.fi
.if n \{\
.RE
.\}
.RE
.PP
mged> \fBgqa \-u m,m^3,kg \-Ae exposed_air\&.g\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
Units:
length: m volume: m^3 weight: kg
grid spacing 50mm  199 x 199 x 199
Summary:
list Exposed Air:
/exposed_air\&.g/exposed_air\&.r count:25921 dist:9m @ (10000 1000 1000)
	  
.fi
.if n \{\
.RE
.\}
.RE
.PP
mged> \fBgqa \-u m,m^3,kg \-Ag gap\&.g\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
Units:
length: m volume: m^3 weight: kg
grid spacing 50mm  199 x 199 x 199
Summary:
list Gaps:
/gap\&.g/closed_box\&.r /gap\&.g/closed_box\&.r count:26082 dist:8m @ (9000 1000 1000)
/gap\&.g/adj_air2\&.r /gap\&.g/closed_box\&.r count:25921 dist:4m @ (1000 5000 1000)
	  
.fi
.if n \{\
.RE
.\}
.RE
.PP
mged> \fBgqa \-u m,m^3,kg \-Av closed_box\&.r\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
Units:
length: m volume: m^3 weight: kg
setting volume tolerance to 1 m^3
grid spacing 50mm  199 x 199 x 199
grid spacing 25mm  399 x 399 x 399
grid spacing 12\&.5mm  799 x 799 x 799
Summary:
    closed_box\&.r  484\&.195 m^3
    Average total volume: 488\&.327 m^3
	  
.fi
.if n \{\
.RE
.\}
.RE
.PP
mged> \fBgqa \-u m,m^3,kg \-Aw closed_box\&.r\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
Units:
length: m volume: m^3 weight: kg
setting weight tolerance to 768000 kg
grid spacing 50mm  199 x 199 x 199
Summary:
Weight:
    closed_box\&.r  3\&.6375e+06 kg
    Average total weight: 3\&.67541e+06 kg
	  
.fi
.if n \{\
.RE
.\}
.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
