OVERLAPS_TOOL(nged)

✨ OVERLAPS_TOOL ✨ (a.k.a. the nged overlaps tool, bestie)

okay so picture this: you've got a BRL-CAD model, you've got regions that are literally inside each other, and you need to see it and fix it. That's this whole tool. It's a MGED GUI whose entire personality is making overlaps between regions easier to visualize and resolve. 🎀

---

🌸 SYNOPSIS 🌸

overlaps_tool [-F] [overlap_file]

Note — you can also launch it the cozy way, through the menu: Tools > Overlaps Tool. iykyk.

---

💅 DESCRIPTION 💅

Running plain overlaps_tool with zero arguments just launches the overlaps menu GUI. That's it. No cap.

You can hand it the path of the .overlaps file as an argument — do that when the database lives in a different directory than the .ck results directory does, or when you renamed the database file after generating the results directory. Giving it the file makes the checker tool get launched directly. (skipping the menu entirely, main character behavior ✨)

The -F option tells the tool it's okay to make assumptions about overlaps when doing subtractions (see [subtraction_assumptions]). 🦋

---

🌈 OVERLAPS MENU GUI 🌈

The overlaps menu has exactly two sections — New File and Exisiting File. yes that's how it's spelled, we don't fix it, we respect it 💜

🍓 New File

• A tree of objects in the database is listed on the left hand side. Pressing the folder icon reveals the regions inside the objects. Double clicking on the items selects/deselects them.
• The selected items are listed on the right hand side. Double clicking on a listed item deselects it.
• There's also an option to manually type in the object's name to select/deselect them, with add/remove buttons. The text entry also supports wildcards like * and ? for batch operations. (batch ops are so slay)
• Clicking the check for overlaps button runs check overlaps at grid-size of 1024 from 16 different views (45 degree steps in az and el directions), and then runs check overlaps -g1mm,1mm, which runs it for three views at 1mm grid spacing.

The tool produces an output directory in the current directory (i.e. not the model directory unless it's the same) named <model.g>.ck.

Warning — running check overlaps can take many hours for non-trivial geometry. like, go touch grass, come back, it's still going 😭

🦋 Exisiting File

These options are to launch the checker tool directly for a previously created overlaps file.

💖 Use Last File

This option is activated when there's already an output directory named <model.g>.ck from a previous run of the overlaps_tool in the current directory. (it remembers, cute)

💖 Browse Overlaps File

Use this when you wanna browse an overlaps file from any location. Heads up though: if the overlaps file was not made from the currently opened database, it may show a warning and not open the overlaps file at all. 🙈

---

👑 USING THE GEOMETRY CHECKER GUI 👑

🌸 Bounding-Box Volume Calculation

When the geometry checker is run, the first thing that happens is the volume of the axis-aligned bounding box for each overlapping object gets calculated. This can take several minutes depending on the size of the overlaps file — so yeah, grab a snack. 🍓

When this finishes, the GUI window will populate. gorgeous. iconic.

💅 The Overlap List

The main element of the GUI is the overlap list, which consists of four columns.

1. The first column on the left is just a reference number for the overlap.
2. The second and third columns are the paths of the overlapping regions. The region with the smaller bounding-box volume is always listed first, as the "Left" side of the overlapping pair.
3. (that's the third one, same deal — paths 💖)
4. The rightmost column is an estimate of the overlapping volume in mm 3.

That volume number is not a separately calculated value — it's an estimate derived from the overlap data. It's not particularly accurate for any given overlap pair, but the relative relationship of the estimates is fairly accurate, so pairs with a higher volume estimate generally have a larger overlap volume than pairs with a lower volume estimate. (vibe-based math, but the vibes are consistent ✨)

By default, the overlap list is sorted by highest volume estimate first, but you can click any of the headers to sort ascending/descending by overlap number, left or right path name, or volume estimate.

🎀 Drawing Overlap Paths

Clicking on an overlap causes the left and right paths to be drawn as wireframes in the display window. The wireframes are colored red and blue respectively (matching the subtraction buttons at the bottom of the window — coordination, we love it 💅).

Below the overlap list there's an option to draw only the first unioned solid in the region instead of the whole region. It's enabled automatically when using the -F option, because it shows just the two objects the -F mode assumes to be responsible for the overlap. However, this display option can be toggled whether you're using -F or not. 🫶

To navigate through overlaps you can:

• Use the up/down keyboard keys to draw each overlap in turn.
• Use the scroll bar on the right side of the overlap list to find a specific overlap.
• Use the Home and End keyboard keys to scroll all the way to the top or bottom of the list.

If you shift-select multiple paths, all those paths are drawn. For large regions, it can take a while for all paths to be drawn. There's a progress bar below the overlap list that shows how many of the selected paths have been drawn. The specific region being drawn appears above the progress bar. ⭐

The "X" button to the right of the progress bar can be pressed at any time during drawing to stop any more regions from being drawn. On a shift-select, there's a short pause (about three seconds) before any drawing begins so you can hit the X button and prevent anything from being drawn at all. (grace period, we stan 🧚)

🦋 Marking Overlaps

You can right-click on selected overlaps and choose "Mark Selected" or "Unmark Selected" to indicate which overlap pairs you've reviewed or attempted a fix on.

Marked overlaps are grayed out and moved to the bottom of the overlap list. The marked and unmarked sections independently maintain the current sorting of the overlap list. (organized chaos, but organized)

These markings are saved to the .ck directory, so they're maintained when you close and reopen MGED. 💖

🔥 Automatic Subtraction

For each pair of overlapping objects, the overlap GUI can automatically rewrite the tree of one side of the pair to subtract the other side, to attempt to resolve the overlap.

Once you select one or more unmarked overlap pairs, the subtract buttons at the bottom of the window will enable and you can choose to subtract all the left-hand regions from the right-hand ones or vice versa.

Each pair that's processed will be automatically marked in the overlap list. ✔️

The progress bar and X button work the same for subtractions as for drawing.

Warning — performing many subtractions at the same time can take a while, and if MGED is killed for some reason (e.g. system restart), the overlap tool isn't guaranteed to handle that situation gracefully. It may corrupt the region it's currently re-writing or fail to mark a processed overlap pair. 💀 like genuinely be careful.

By default, the overlap GUI will refuse to subtract any combination that doesn't reduce to a single solid. That's because subtracting a non-trivial combination complicates the re-written tree, and can lead to cycles (a - b - a). not the cycle arc we want 😭

Providing the -F ("first") option to the overlaps_tool command causes the overlap GUI to assume that the overlap between an overlapping pair only involves the first unioned solid in their respective trees. Subtracting a combination with the -F option enabled results in just the first unioned solid of that combination being subtracted from the first unioned solid in the other object's tree.

For example, if a overlaps b and they look like this:

a/R
  u adapter.s
  u alert.c
    u ac.s
  - ant.s

b/R
  u bottle.c
    u box.c
      u bend.s
  - blend.c
    u balance.s

Then subtracting b from a would rewrite a to:

a/R
  u adapter.s
  - bend.s
  u alert.c
    u ac.s
  - ant.s

---

🌟 EXAMPLES 🌟

Example 1. Launch the overlaps menu.

mged> overlaps_tool

Opens the overlaps menu GUI for the currently open database so a new overlap check can be configured. 🎀

Example 2. Open an existing overlaps file in first-solid mode.

mged> overlaps_tool -F model.g.ck/overlaps

Launches the checker GUI directly on model.g.ck/overlaps and enables first-solid assumptions for automatic subtraction. 🔥

---

💜 AUTHOR 💜

BRL-CAD Team — legends, honestly.

---

📧 BUG REPORTS 📧

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org. don't be shy, they wanna hear it 🫶

---

and that's the whole page, bestie — brought to you by BRL-CAD and the overlaps_tool(nged) manual page. go fix those overlaps 💅✨