GQA(nged)

okay bestie, welcome to GQA(nged) from the BRL-CAD MGED Commands family — a BRL-CAD quantitative geometry analysis tool, and she is literally here to spill all the tea about your model 💅✨

✨ NAME ✨

gqa — a BRL-CAD quantitative geometry analysis tool 🫶

🦋 SYNOPSIS 🦋

gqa [options] objects

🌸 DESCRIPTION 🌸

okay so gqa computes and reports a whole buffet of characteristics for the objects you specify from the given model.g geometric description. The characteristics she can compute include weight, volume, overlaps, exposed air, gaps/voids, and adjacent air. Only the objects from the database specified on the command line are analyzed — no sneaky extras.

She works by shooting grids of rays from the three axis-aligned directions (sometimes called views). 🎯

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.

For error and interface calculations, the grid is refined until an error is found or the grid refinement limit is reached.

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.

🎀 VOLUME AND WEIGHT CALCULATION 🎀

If volume or weight calculation is selected, a value is calculated and reported for each object specified on the command line.

⚠️ note that if there are overlaps or other errors in the geometry, the values reported will be invalid. like, do not trust those numbers, bestie 😭

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 GIFTmater attribute of each region (typically set with the edcodes or adjust commands in MGED).

The density table consists of three columns:

• An integer index value. This is the value to which the GIFTmater attribute will be set to select this material for the region.
• A floating point density value. This is the density for the material, and is specified in grams/cc.
• A name string. This is a name or description the material.

This information may be stored in the .g file or as a separate density file. 🗂️

To check if the .g file you are using has a density table, use the mater -d get * 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 mater -d set command.)

An example file might look like the following:

#******************************************************************************
#  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

To import an existing density file into the database, use the mater -d import command:

mged> mater -d import filename

If existing density values need to be corrected in the .g file, the mater -d set command may be used to alter them. For more about density information manipulation, see the mater(N) manual page.

Density information is sourced in the following order:

1. Filename explicitly supplied to function
2. Density information stored in the .g database
3. A .density file in the same directory as the .g file
4. A .density file in the user's HOME directory

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. 👑

🔥 GEOMETRY ERROR DETECTION 🔥

All of these calculations run until an error is detected, or until the grid refinement limit is reached.

💀 OVERLAP DETECTION 💀

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.

Other analyses in the error detection category behave in a similar manner.

💅 OPTIONS 💅

• -A analysis_flags — Specifies which computations are to be performed and reported. The analysis_flags parameter is one or more of the following:
  • A — all
  • a — Adjacent different air
  • b — Bounding box dimensions
  • e — Exposed air
  • g — Gaps/voids
  • m — Weight + Centroids + Moments of Inertia
  • o — Overlaps
  • p — Visualize Overlaps
  • v — Volume
  • w — Weight

Only those reports requested will be provided. The default is -AA to produce all reports.

Adjacent different air (a): 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. 🫧

Bounding box dimensions (b): Reports the dimensions of an axis-aligned box which fully encloses the objects.

Exposed air (e): This causes checks to be made to see if the ray encounters air regions before (or after all) solid objects. 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.

Gaps/voids (g): This reports when there is more than overlap_tol_dist (see the -t 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.

Overlaps (o): 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 interference checking. Two objects must overlap by at least overlap_tol_dist (see the -t 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 -g option below for details on setting the grid spacing. Once overlaps have been detected, grid refinement is not done, and processing stops. 💀

Visualize Overlaps (p): In MGED, if overlaps are detected, this option causes the overlaps found to be illustrated in the wireframe view via yellow lines. 💛

Volume (v): Computes the volume of the objects specified on the command line.

Weight (w): Computes the weight of the objects specified on the command line. See above for density information and order of sourcing.

• -a azimuth_deg — Not Implemented. Sets a rotation (in degrees) of the coordinate system by a given amount about the Z axis. The default is 0. See also: -e
• -e elevation_deg — Not Implemented.

Okay so, tail end of that elevation option: it 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 -a.

• -f filename — says “bestie, take density values from an external file instead of from the _DENSITIES object in the database.” This is lowkey useful when you’re developing the density table with a text editor before importing it to the geometric database. 🎀
• -g [initial_grid_spacing-]grid_spacing_limit — sets 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) is the initial spacing between grid rays. The mandatory argument, grid_spacing_limit, is a lower bound on how fine the grid spacing may get before computation is terminated. In general, the initial_grid_spacing value should be an integer power of the grid_spacing_limit. So for example, if grid_spacing_limit has the value 1, then any initial_grid_spacing specified should be in the sequence 2, 4, 8, 16, 32... so the grid will refine to precisely the lower limit. The grid spacing may be specified with units. For example: 5 mm or 10 in. If units are not provided, millimeters are presumed to be the units. 🌸

The default values are 50.0 mm and 0.5 mm, which is equivalent to specifying: -g 50.0mm-0.5mm or -g 50.0mm,0.5mm 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. 🫶

• -G — Not Implemented.

Specifies that the program should create new assembly combinations in the geometry database to represent the overlap pairs. This flag is meaningless if overlap reporting is not turned on with the -A option. If regions rod.r and disk.r overlap, this option will cause the creation of an assembly called _OVERLAP_rod.r_disk.r, which includes the following items:

1. rod.r
2. disk.r
3. _OVERLAP_lines_rod.r_disk.r

The last item is an object to represent the overlapping area so it can be easily seen. The default is that no groups are created. ✨

• -n num_hits — says “refine the grid until each region has at least num_hits 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. 👑

The default is 1. Hence, each region must be intersected by a ray at least once during the analysis.

• -N num_views — specifies that only the first num_views should be computed. This is principally a debugging option. 🐛
• -p — specifies that gqa should produce plot files for each of the analyses it performs. These can be overlaid on the geometry in mged with the overlay 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. 🌈
• -P ncpu — specifies that ncpu 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. 💅
• -q — quiets (suppresses) the “was not hit” reporting. No more spam, bestie. 💀
• -r — indicates that gqa should print per-region statistics for weight and volume as well as the values for the objects specified on the command line. 🍓
• -S samples_per_model_axis — specifies that the grid spacing will be initially refined so that at least samples_per_axis_min 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 -S 4 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. 🎀
• -t overlap_tolerance — sets the tolerance for computing overlaps. The overlap_tolerance 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: -t 1.0mm or -t 0.25in. 🔥
• -U use_air — specifies the Boolean value (0 or 1) for use_air, which indicates whether regions marked as “air” should be retained and included in the raytrace. Unlike other BRL-CAD raytracing applications, the default is to retain air in the raytracing. The -U 0 option causes air regions to be discarded prior to raytracing. If you turn off use_air, and request any analysis that requires it (see -A above), then the program will exit with an error message. 😭
• -u distance,volume,weight — specify the units used when reporting values. Values must be comma delimited and provided in the order distance,volume, weight. For example: -u "cm,cu ft,kg" or -u ,,kg (the latter example sets only the weight units). Note that unit values with spaces in their names such as cu ft must be contained in quotes for the shell to keep the values together. 🦋

The default units are millimeters, cubic millimeters, and grams.

• -v — 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. 🧚
• -V volume_tolerance[units] — 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. ⭐
• -W weight_tolerance[units] — this is like the volume tolerance, -T, but is applied to the weight computation results, not the volume computation results. 💜

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.

---

🧪 EXAMPLES 🧪

💖 Example 1. Default Behavior 💖

This command computes the weight of an object called wheel.r, reports the weight and volume, and checks for overlaps. It assumes a _DENSITIES table object is present in the database. 🫶

mged> gqa wheel.r

🌸 Example 2. Specifying Grid and Target Objects 🌸

This 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. ✨

mged> gqa -g 1cm-1mm -Aoe hull turret suspension

🎀 Example 3. Specifying Using Non-Default Units 🎀

This 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. 💅

mged> gqa -g5in-0.3mm -Avw -u ft,cc,oz hull turret suspension

🌈 Example 4. Different Analysis Types 🌈

For an example of each independent analysis type, consider the following: 👑

mged> gqa -u m,m^3,kg -Ao overlaps
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)

mged> gqa -u m,m^3,kg -Ae exposed_air.g
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)

mged> gqa -u m,m^3,kg -Ag gap.g
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)

mged> gqa -u m,m^3,kg -Av closed_box.r
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

mged> gqa -u m,m^3,kg -Aw closed_box.r
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

---

👑 AUTHOR 👑

BRL-CAD Team — iconic behavior only. 🫶

🐛 BUG REPORTS 🐛

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org. Don’t be shy, bestie — tell them what broke. 😭💖

---

Footer sparkle: source/version BRL-CAD, page GQA(nged), and the date field isn’t shown in this footer copy — so that’s the whole vibe. Bye bestie, go ray-trace something iconic 💅✨