CHECK(nged)

Check is a geometry analysis tool.

📅 published 7.44.0, from nixpkgs unstable

✨ NAME ✨

okay bestie, welcome to CHECK(nged) from the BRL-CAD MGED Commands crew — this is the manual page for check, and check is literally a geometry analysis tool. no cap. 💅

🎀 SYNOPSIS 🎀

check sub-command [options] [objects]...

💖 DESCRIPTION 💖

okay so here's the vibe: the check program computes and reports a whole stack of characteristics for the objects you specify from the opened database. the characteristics it can compute include mass, centroid, moments of inertia, volume, overlaps, surface area, exposed air, gaps/voids, unconfined air, and adjacent air. only the objects from the database that you name on the command line get analyzed, periodt.

it works by shooting grids of rays from the three axis-aligned directions (sometimes called views) — or a single view when azimuth/elevation angles are mentioned. 🦋

for volume/mass/surface area 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. it's giving "keep zooming in until everyone agrees" energy.

for mass/centroid/moments of inertia calculations, it is suggested for better accuracy to opt for three axis-aligned grid by not mentioning azimuth/elevation angles. 🔥

for surface area calculations, the rays are fired from three grids at random azimuth/elevation angles and then taken mean of the values reported by the three grids at the end. math bestie behavior, honestly.

🦋 SUBCOMMANDS 🦋

adj_air

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

centroid

computes the centroid of the objects specified. iconic little center-of-mass moment.

exp_air

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

gap

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. iykyk — context matters, bestie.

mass

computes the mass of the objects specified. heavy subject, literally.

moments

computes the moments and products of inertia of the objects specified. rotational main character energy.

overlaps

this reports overlaps, when two regions 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. no cap, tiny overlaps don't count unless they pass the tolerance vibe check.

surf_area

computes the surface area of the objects specified. ✨

unconf_air

this reports when a partition with nonzero air code follows or precedes another partition and the space between them is more than overlap_tol_dist (see the -t option). the data reported are the names of the two regions (and solids) involved, the length of the gap along the ray, and the model coordinates of the ray's exiting the first partition and entering the second. 💀 very "receipts included" of it.

volume

computes the volume of the objects specified. big "how much space do you take up" question, fr fr.

🌈 MASS CALCULATION 🌈

if mass 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. 🚨

bestie, seriously: overlap/error geometry means the reported values are invalid. do not trust the math if the model is messy. 💅

for mass 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.

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

the table is typically created in an external file using a text editor. lowkey the classic way.

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 mass are computed to have different mass because one or two regions were not set to the correct, non-default 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. 🎀

the user will typically want to run gqa and verify the results using the -f option (see below) before importing the table into the database. for example, if a material index is left out of the table, it is easier to rectify the situation using the external file. once the table has been verified as correct and complete, it is imported to the database as the binary object _DENSITIES. to import the text file into the database, the following command is used:

mged> bo -i u c _DENSITIES filename

🔥 GEOMETRY ERROR DETECTION 🔥

all of these calculations run until the grid refinement limit is reached. no early quitting, bestie.

for each pair of regions that cause an error, the tool reports the two erroneous regions, the maximum line-of-sight thickness of the error, and the in-hit location of the ray that caused that maximum error thickness. receipts, coordinates, and all. 👑

✨ OPTIONS ✨

okay bestie, this is the big one — the flag buffet. every single one is here, nothing skipped, no cap 💅

  • -a azimuth_deg [deg|rad] — spins the coordinate system by a given amount about the Z axis (in degrees). and the moment you mention it, check stops doing the whole multi-view thing and shoots only one grid of rays along the azimuth/elevation angle. default is 35. see also -e. 🌀
  • -e elevation_deg [deg|rad] — same energy but for elevation: rotates the coordinate system (in degrees) by a given elevation from the XY plane (rotation about X axis?). when mentioned, check again shoots only one grid of rays along the azimuth/elevation angle. default is 25. see also -a. 🦋
  • -d — turns debugging on. it's off by default, so this is your "hey what's actually happening" button 🐛
  • -f filename — pulls density values from an external file instead of from the _DENSITIES object in the database. super useful when you're still cooking up the density table in a text editor, before importing it into the geometric database. literally the draft-mode flag ✍️
  • -g [initial_grid_spacing-]grid_spacing_limit or [initial_grid_spacing,]grid_spacing_limit — this one caps how far the grid can be refined, and optionally sets the initial spacing between rays in the grids. (yes, you can use either a dash or a comma as the separator, both slay.)

the first value (if you give one) 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 like, if grid_spacing_limit is 1, then any initial_grid_spacing you specify should be in the sequence 2, 4, 8, 16, 32... so the grid refines to precisely the lower limit. the grid spacing may be specified with units — for example: 5 mm or 10 in. if no units are given, millimeters are presumed. 📏

the defaults 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.

heads up: this is a hard limit. if other analysis constraints aren't met, the grid spacing will never be refined smaller than the minimum grid size to satisfy another constraint. periodt.

the initial grid spacing gets divided in half at each refinement step. so if you actually want a lower limit to be tested, the initial grid size needs to be a power of 2 greater. 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 like 8 or 16 should have been chosen for the initial values — that would result in testing 16, 8, 4, 2, 1 grid spacing values. math is math 💀

  • -G [grid_width,]grid_height — sets the grid size. if you only mention grid width, you get a square grid size. lowkey the easiest one here 🎀
  • -i — grabs 'view information' from the view to set up the eye position of the single grid. used only for overlaps calculations. 👀
  • -M mass_tolerance[units] — this is like the volume tolerance, -V, but it applies to the mass computation results, not the volume computation results.

the mass computation tolerance is probably more appropriate when you're doing whole-vehicle analysis. if mass computation is selected, it's set to a value equal to the mass of an object 1/100 the size of the model, which is made of the most dense material in the table. 🏋️

  • -n num_hits — says "keep refining the grid until each region has at least num_hits ray intersections." it applies only when mass or volume calculations are being performed. and it's not applied per-view — it's per-analysis. so like, it's fully accepted that a thin object might not be hit at all from one view, but might get hit when it's shot from other views. that's fine, that's the vibe.

default is 1, so 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. principally a debugging option, iykyk. 🔍
  • -o — displays the overlaps as overlays. cute and visual 💖
  • -p — makes check produce plot files for each of the analyses it performs. you can overlay these on the geometry in mged with the overlay command to help visualize the analysis results. each of the different analysis types writes to a separate plot file and uses different colors for drawing. rainbow-coded science 🌈
  • -P ncpu — says use ncpu CPUs for 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: specifying more CPUs than are actually present on the machine does not increase the number of computation threads. delulu cores are not the solulu 💀
  • -q — quiets (suppresses) the "was not hit" reporting. peace and quiet bestie 🤫
  • -r — tells check to print per-region statistics for mass, volume and surface area, as well as the values for the objects specified on the command line. receipts, basically 🧾
  • -R — disables the reporting of overlaps. used only for the overlaps sub-command. 🙈
  • -s surf_area_tolerance — sets a surface area tolerance value that the three view computations must be within for computation to complete. if surface area calculation is selected and this option isn't set, the tolerance is set to 1/1,000 of the estimated surface area of the model bounding box. 📐
  • -S samples_per_model_axis — says the grid spacing will initially be refined so that at least samples_per_axis_min will be shot along each axis of the bounding box of the model.

example time: if the objects specified have a bounding box of 0 0 0 -> 4 3 2 and the grid spacing is 1.0, specifying -S 4 causes 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. default is to ensure 1 ray per model grid axis. 🎲

  • -t overlap_tolerance — sets the tolerance for computing overlaps. overlap_tolerance must be a positive number equal to or greater than 0.0. any overlap smaller than the value specified gets ignored. default 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 — sets 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 here is to retain air in the raytracing. -U 0 causes air regions to be discarded prior to raytracing.
lol careful: if you turn off use_air and request any analysis that requires it (see -A above), the program will exit with an error message. so dramatic 💀
  • -u distance_units,volume_units,mass_units — specifies the units used when reporting values. values must be comma delimited and provided in the order distance_units,volume_units,mass_units. for example: -u "cm,cu ft,kg" or -u ,,kg (that second one sets only the mass units, sneaky but valid). note that unit values with spaces in their names, like cu ft, must be wrapped in quotes so the shell keeps the values together.

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 causing further computation to be necessary. it's giving commentary track 🎙️
  • -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 isn't 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 runtime (or even completion 😭). given the approximate sampling nature of the algorithm, the three separate view computations will not usually produce identical results — and that's just how it is, ngl. 🚗

✨ EXAMPLES ✨

Bestie, this is the part where it all clicks. Let me walk you through some real ones 🫶

🌸 Example 1. Specifying Grid and Target Objects

So what this does is check hull, turret, and suspension for overlaps. The grid starts at 1 cm and is refined to 1 mm. Iconic, honestly.

mged> check overlaps -g 1cm-1mm hull turret suspension

💜 Example 2. Specifying Using Non-Default Units

This one computes the volume of hull, turret, and suspension. Results are reported in cubic centimeters (cc). The grid spacing starts at 5 in. and will not be refined below 0.3 mm spacing. No cap, that's a whole range 💅

mged> check volume -g5in-0.3mm -u ft,cc,oz hull turret suspension

🦋 Example 3. Different Analysis Types

For examples of some independent analysis types, consider the following. Strap in bestie, this is the long one 😭

mged> check overlaps -g50,50 -u m,m^3,kg overlaps
Units:
length: m volume: m^3 weight: kg
grid spacing 50mm  199 x 199 x 199
OVERLAP PAIRS
------------------------------------------
/overlaps/overlap_obj.r and /overlaps/closed_box.r
        </overlaps/overlap_obj.r , /overlaps/closed_box.r>: 32039 overlaps detected, maximum depth is 8m
==========================================
SUMMARY
        32039 overlaps detected
        1 unique overlapping pair (1 ordered pair)
        Overlapping objects: /overlaps/overlap_obj.r /overlaps/closed_box.r
        2 unique overlapping objects detected

mged> check exp_air -u m,m^3,kg exposed_air.g
Units:
length: m volume: m^3 weight: kg
grid spacing 50mm  199 x 199 x 199
list Exposed Air:
/exposed_air.g/exposed_air.r count:25921 dist:9m @ (10000 1000 1000)

mged> check unconf_air -u m,m^3,kg unconf_air.g
Units:
length: m volume: m^3 weight: kg
grid spacing 50mm  199 x 199 x 199
list Unconfined Air:
/unconf_air.g/air1.r /unconf_air.g/air2.r count:23921 dist:7m @ (10000 1000 1000)

mged> check gap -u m,m^3,kg gap.g
Units:
length: m volume: m^3 weight: kg
grid spacing 50mm  199 x 199 x 199
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> check volume -u m,m^3,kg 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
    closed_box.r  484.195 m^3
    Average total volume: 488.327 m^3

mged> check surf_area -u m,m^3,kg closed_box.r
Units:  length: m volume: m^3 mass: kg
Using estimated surface area tolerance 640000 mm^2
grid: (50, 50) mm, (278, 278) pixels
grid: (50, 50) mm, (278, 278) pixels
grid: (50, 50) mm, (278, 278) pixels
Surface Area:
        closed_box.r 384.485 m^2

  Average total surface area: 384.485 m^2

mged> check weight -u m,m^3,kg 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
Weight:
    closed_box.r  3.6375e+06 kg
    Average total weight: 3.67541e+06 kg

Look at all that data. It's giving main character energy fr fr 🔥

👑 AUTHOR 👑

BRL-CAD Team — the icons who made all this happen 💖

🐛 BUG REPORTS 🐛

Found something cursed? Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org. Please do tell them, bestie, they genuinely want to know 🙈

And that's the whole page, omg you made it to the end 🎀 This little masterpiece comes to you from the BRL-CAD source, filed under CHECK(nged) — go forth and check all the things, you've got this ✨🦋💜

📦 where this page comes from