GQA(1)

📦

version 7.44.0 · 2 versions

7.44.0 · nixpkgs unstable (latest)
7.42.2 · nixos 26.05

🌸 NAME 🌸

okay so this is gqa(1) from BRL-CAD, and it's literally the quantitative geometry analysis tool. bestie, it just crunches geometry and tells you what's up 💅.

✨ SYNOPSIS ✨

gqa [options] model.g object [object ...]

🦋 DESCRIPTION 🦋

The gqa program computes and reports a variety of characteristics of the objects specified from the given model.g geometric description. The characteristics which can be computed include weight, volume, overlaps, exposed air, gaps/voids, and adjacent air. Only the objects from the database specified on the command line are analyzed. periodt.

It works by shooting grids of rays from the three axis-aligned directions (sometimes called views). That's the whole main character energy of this tool, no cap.

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. it's giving "we commit to the bit" energy fr fr.

💖 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. 😭 so please do not trust those numbers if the geometry is messy.

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.

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.

🎀 bestie, please take the index 1 warning seriously. it's lowkey the "one tiny region forgot its material" jumpscare.

🧚 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. so it's not just "y'all overlap" — it gives you the receipts.

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

💅 OPTIONS 💅

okay so the flags are giving very much "pick your analysis" energy. here's the whole menu:

-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
- c — Weight + Centroids
- e — Exposed air
- g — Gaps/voids
- m — Weight + Centroids + Moments of Inertia
- o — Overlaps
- p — Overlaps + write an overlaps plot file
- v — Volume
- w — Weight

Only those reports requested will be provided. The default is -A A, 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.

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.

-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

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 .

-d — Enables debugging (off by default).
-f filename — tells gqa to pull the density values from an outside file instead of from the _DENSITIES object sitting in the database. Lowkey the move when you're still building out your density table in a text editor and want to fiddle with it before importing it into the geometric database. ✨
-g [initial_grid_spacing-]grid_spacing_limit or -g [initial_grid_spacing,]grid_spacing_limit — sets how far the grid is allowed to refine, and optionally how far apart the rays start out. The first value (if you give one) is the initial spacing between grid rays. The one you can't skip is grid_spacing_limit, the lower bound on how fine the grid spacing can get before computation just stops. 💅

Generally your initial_grid_spacing should be an integer power of the grid_spacing_limit. So if grid_spacing_limit is 1, then whatever initial_grid_spacing you pick should come from the sequence 2, 4, 8, 16, 32… so the grid refines down to precisely that lower limit. Grid spacing can take units too — like 5 mm or 10 in. No units? Then millimeters are presumed. 🎀

The defaults are 50.0 mm and 0.5 mm, which is the same as writing -g 50.0mm-0.5mm or -g 50.0mm, 0.5mm on the command line. And this is a hard limit — if other analysis constraints aren't met, the grid will never refine smaller than the minimum grid size just to satisfy another constraint. The initial grid spacing gets halved at every refinement step. So if you actually want your lower limit to get tested, your initial grid size has to be a power of 2 bigger. Example: -g10mm, 1mm gives you grid spacings of 10, 5, 2.5, 1.25. If your goal was to land exactly on a 1mm grid, you should've picked something like 8 or 16 for the initial value — that gets you 16, 8, 4, 2, 1. 😭

-G — Not Implemented 🫠 supposedly this one tells the program to create new assembly combinations in the geometry database representing the overlap pairs. Worthless if overlap reporting isn't switched on with the -A option, bestie. If regions rod.r and disk.r overlap, this option would create an assembly called _OVERLAP_rod.r_disk.r, containing:
1. rod.r
2. disk.r
3. _OVERLAP_lines_rod.r_disk.r

That last item is an object representing the overlapping area, so you can actually see it. Default behavior is that no groups get created.

-n num_hits — says "keep refining the grid until every single region has at least num_hits ray intersections." Only applies when weight or volume calculations are happening. And bestie, this limit is per-analysis, not per-view — so yeah, it's totally accepted that a thin object might not get hit at all from one view but gets hit when shot from other views. 🦋

Default is 1, meaning each region has to be intersected by a ray at least once during the analysis.

-N num_views — only the first num_views get computed. This is mainly a debugging option, iykyk. 🧚
-p plot_prefix — makes gqa spit out plot files for each analysis it runs. Depending on which analysis type(s) you asked for, the plot files get named with your prefix prepended to one of volume.plot3, gaps.plot3, overlaps.plot3, adj_air.plot3, and/or exp_air.plot3. You can visualize the plot data in mged with the overlay command. Each analysis type writes to its own separate plot file and uses different colors for drawing. 🌈
-P ncpu — use ncpu CPUs for the calculation. By default all local CPUs get used. This option mainly exists so you can reduce the number of computation threads below the machine maximum. Note that asking for more CPUs than the machine actually has does not increase the number of computation threads. 💀
-q — quiets (suppresses) the "was not hit" reporting. Silencio. 🙈
-r — gqa prints per-region statistics for weight and volume, plus the values for the objects you named on the command line. 🌸
-S samples_per_model_axis — the grid spacing gets initially refined so that at least samples_per_axis_min rays are shot along each axis of the model's bounding box. For example, if the objects you specified have a bounding box of 0 0 0 -> 4 3 2 and the grid spacing is 1.0, then -S 4 adjusts the initial grid spacing to 0.5 so 4 samples get shot across the Z dimension of the bounding box. Default is to ensure 1 ray per model grid axis. ⭐
-t overlap_tolerance — sets the tolerance for computing overlaps. It must be a positive number equal to or greater than 0.0. Any overlap smaller than what you specify gets ignored. Default is 0.0, which means any overlap gets reported/processed. You can slap a unit specifier on it, like -t 1.0mm or -t 0.25in. 💅
-U use_air — sets the Boolean value (0 or 1) for use_air, which says whether regions marked as "air" should be retained and included in the raytrace. Unlike other BRL-CAD raytracing applications, the default here is to retain air during raytracing. -U 0 makes air regions get discarded before raytracing. If you turn off use_air and then request any analysis that needs it (check -A above), the program exits with an error message. 🫶
-u distance_units, volume_units, weight_units — sets the units used when reporting values. Gotta be comma delimited, in the order distance_units, volume_units, weight_units. For example: -u "cm, cu ft, kg" or -u ,, kg (that second one sets only the weight units). Note that unit values with spaces in their names, like cu ft, must be wrapped in quotes so the shell keeps them together. 🎀

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

-v — turns on verbose reporting of computation progress. Genuinely useful for learning how the computation is progressing and which tolerances are forcing more computation to happen. 👑
-V volume_tolerance[units] — sets a volumetric tolerance the three view computations have to fall within for computation to complete. If volume calculation is selected and you don't set this, the tolerance becomes 1/1,000 of the volume of the model bounding box. For big complex objects (think entire vehicles), you might need to crank this higher to get reasonable runtimes — or to finish at all. 😭 And given the approximate sampling nature of the algorithm, those three separate view computations usually won't produce identical results. That's just how it is.
-W weight_tolerance[units] — same energy as the volume tolerance -V, but applied to the weight computation results instead of volume. 🔥

The weight computation tolerance is probably the more appropriate one when you're doing whole-vehicle analysis. If weight computation is selected, it gets set to a value equal to the weight of an object 1/100 the size of the model, 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 from the geometry database model.g, reports the weight and volume, and checks for overlaps. Simple, iconic, no notes. 💖

gqa model.g wheel.r

Example 2. Specifying Grid and Target Objects

This one checks objects hull, turret, and suspension for overlaps and reports exposed air. The grid starts at 1 cm and refines to 1 mm — unless overlaps or exposed air get detected before the grid even reaches 1 mm. 🦋

gqa -g 1cm-1mm -A oe model.g hull turret suspension

Example 3. Specifying Using Non-Default Units

Computes volume and weight of hull, turret, and suspension. Results come out in cubic centimeters (cc) and ounces (oz). Grid spacing starts at 5 in. and will not refine below 0.3 mm spacing. 🌸

gqa -g5in-0.3mm -Avw -u ft, cc, oz test.g hull turret suspension

Example 4. Different Analysis Types

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

gqa -u m, m^3, kg -Ao geometry.g 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)

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

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

gqa -u m, m^3, kg -Av geometry.g 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

gqa -u m, m^3, kg -Aw geometry.g 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

👀 SEE ALSO 👀

brlcad(1), mged(1), rtweight(1), mater(n), rt(1)

🫶 AUTHOR 🫶

BRL-CAD Team

🐛 BUG REPORTS 🐛

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

okay that's the whole page bestie, you're officially a gqa girlie now 💅✨ this one's from BRL-CAD, filed under GQA(1) — go forth and ray-trace responsibly, mwah 🎀💖

📦 where this page comes from

nixpkgs unstable: brlcad 7.44.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms