NEAR(nged)

✨ NEAR (nged) ✨

okay bestie, welcome to the nged manual for near — one of the BRL-CAD user commands, and honestly? kind of a baddie. it's the tool that goes "who's standing near this thing" and actually tells you. let's get into it 🫶

---

🌸 SYNOPSIS 🌸

near [options] {object | x y z} [distance]

you can also call it with a Tcl list of paths for -scope, like this:

near -scope {path1 path2 ...} [options] {object | x y z} [distance]

---

💖 DESCRIPTION 💖

so near searches the model for regions that are geometrically close to a specified "target". and the target can be either:

• an object or path that resolves to one or more regions, or
• an explicit 3D point, given as three distance tokens (x y z).

when the target is an object, near looks at every region in the search scope (default is the model root /, obviously), computes bounding boxes for the target regions and the candidate regions, and then does a sampling-based ray analysis to find region pairs that either overlap/interpenetrate or have a little baby separating gap. when the target is a point, near checks each candidate region and reports the ones that contain or lie near that point. iykyk 💅

distance tokens accept an explicit unit suffix (like 5mm or 0.25in) or just a number in the current local units. unit conversion goes through the BRL-CAD units framework and the units command for formatting output. slay.

🦋 the algorithm (three stages, main character energy)

1. Screen all regions in the search scope by bounding-box distance from the target. Regions farther than the requested maximum distance are discarded.
2. For remaining candidates, sample rays through the combined bbox to detect overlap or measure the minimum separation along world axes.
3. Report nearby regions with a classification of "overlap" (intersect) or "gap" (separating distance), the measured ray-based distance, the bbox gap, axis of best approach, and an approximate contact point.

the sampling density of rays is controlled by the -ray_spacing parameter — that's either a distance or the special value "auto". when it's set to auto, the implementation computes a spacing based on the diagonal of the combined bounding box, and reports the spacing range used. and the maximum number of samples on each axis is governed by -max_samples, so we don't cook the CPU. 🔥

the command prints a human-readable summary when it's not in quiet mode (-quiet 1). when quiet mode is on, it returns a Tcl list of results instead — perfect for programmatic processing, no cap.

---

🎀 OPTIONS 🎀

• -scope path — restrict the search to regions under the given path. the path can be a single object path (for example /world/room) or a Tcl list of paths. if you skip it, the default scope is the model root /. paths that don't start with / get normalized by prepending /. considerate king behavior 👑
• -ray_spacing distance|"auto" — spacing between sample rays, in the current local units or with an explicit unit suffix. smaller spacing = denser ray sampling = maybe more accuracy but more cost, the classic tradeoff, we love her. the special value auto lets the command pick a spacing based on the geometry: it uses the diagonal of the combined bounding box of the pair being sampled divided by 100. and the command reports the spacing values actually used when presenting results. transparent icon 💖
• -max_samples n — maximum number of sample points along any sampled axis. the command computes a sampling grid and clamps the number of samples to this value so it doesn't do excessive work. must be a positive integer. default is 100.
• -quiet 0|1 — when 0 (the default), the command prints a human-readable report. when 1, the command returns a Tcl list of result records and prints nothing. use quiet mode for scripting and further post-processing, it's giving automation ✨

---

🧚 ARGUMENTS 🧚

• object : a single object path or name that resolves to one or more regions. if the object expands to multiple regions, each region is treated as a target and the search reports candidate regions near any of the target regions. multitasking queen.
• x y z : explicit 3D coordinates expressed as distance tokens — numbers in the current local units, or with explicit unit suffixes. when you specify a point, the optional trailing distance argument sets the maximum search radius around that point. if you omit it, near uses 10% of the diagonal of the combined bounding boxes of all candidate regions as the default search radius. cute little default, honestly.
• distance : maximum distance (search radius). accepts a unit suffix or local units. distances get converted to model base units internally.

---

💜 OUTPUT 💜

when you run it in the default non-quiet mode, near prints a compact summary that includes:

• the target label (object path or point),
• the distance searched (formatted with units),
• the ray spacing used (or the computed auto range),
• the number of regions checked, and
• a list of nearby regions — and for each candidate, it tells you:
  • whether the relation is overlap or gap,
  • the measured ray-based distance (in local units),
  • the bounding-box gap (coarse filter),
  • the testing axis (X, Y or Z) that produced the best result, and
  • an approximate contact point expressed as a comma-separated triple.

when you use -quiet 1, the command returns a Tcl list where each element is a property list describing a result — fields include target, candidate, relation, distance, bbox_gap, point, axis. this format is intended for programmatic consumption. scripts are shaking rn 📜

---

🌈 EXAMPLES 🌈

Example 1. Find regions near an object with default parameters

mged> near wheel.r

Target: wheel.r Distance: 0.254 m Ray spacing: 2.54 mm (auto)
Regions checked -> bbox candidates -> near: 123 -> 45 -> 3

Nearby regions:   /car/axle <-> wheel.s : gap 0.00508 m (bbox
0.00512 m, axis X, point {0.1, 0.0, 0.0})   /car/body :
overlap/inside 0.00000 m (bbox 0.00000 m, axis Y, point {0.0, 0.0,
0.0})   /tools/wrench : gap 0.01270 m (bbox 0.01300 m, axis Z, point
{0.0, 0.0, 0.05})

Example 2. Find regions within 2.5 centimeters of an explicit point, with denser sampling

mged> near -ray_spacing 1mm -max_samples 200 0.05m 1.2m 0.0m 2.5cm

Target: point {0.05, 1.2, 0} Distance: 2.5 cm Ray spacing: 1.000000
mm Regions checked -> bbox candidates -> near: 100 -> 30 -> 2

Nearby regions:   /pipe/flange : gap 0.010 m (bbox 0.012 m, axis X,
point {0.06, 1.2, 0.01})   /ground : overlap/inside 0.000 m (bbox
0.000 m, axis Z, point {0.05, 1.2, 0.0})

Example 3. Limit the scope to a subtree and run programmatically (quiet mode)

# return value is a Tcl list of results (suitable for scripts) mged> near -scope {/building/floor1 /building/floor2} -quiet 1 desk.s 10cm

the command returns a Tcl value like:

{candidate /furniture/leg relation gap distance 0.03 bbox_gap 0.032 point {1.2,0.5,0.75} axis X}

this programmatic output can be parsed by Tcl scripts to make automated decisions — for example, to flag geometry that encroaches on clearance corridors. lowkey genius 🧠✨

---

👑 AUTHOR 👑

BRL-CAD Team. legends, periodt.

---

💀 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 🙈

fr fr though — if something's cursed, send it in. they can't fix what they don't know about 💖

---

and that's the whole page, bestie! 💅 this was NEAR(nged) from the BRL-CAD user commands, and it shipped under BRL-CAD, dated as the original footer says — go find something near something, you got this 🦋🎀