Scene Measure
scene_measureMeasure the spatial relationship between two Maya objects via world-space bounding boxes to get distance, clearance, penetration, or overlap before moving or separating them.
Instructions
Measure the spatial relationship between two objects.
Call this in the COMPUTE step of the ICEV workflow, to turn a spatial question into a number before you execute a change: size a clearance before moving something, prove two objects interpenetrate before you separate them, or get the axis detail behind an overlap that scene_validate reported.
Read-only and idempotent: it queries world-space bounding boxes and never modifies the scene, so no undo checkpoint is created. Requires an active Maya session.
Every mode measures world-space AABBs, not the mesh surface and not the object origin. The modes differ in what the number means: center distance between the AABB midpoints. surface distance between the closest facing AABB corners — an axis-aligned approximation, so it over-reports clearance for rotated or concave geometry. clearance SIGNED, and 0 is NOT a "merely touching" signal. Per axis the gap is +separated / 0=touching / -penetrating: > 0 euclidean distance across the STRICTLY SEPARATED axes only. Penetrating axes contribute 0, so they are invisible in this number. = 0 no axis is strictly separated and at least one axis is exactly touching. The other axes may be deeply penetrating, so 0 does NOT mean the boxes just touch. < 0 all three axes penetrate; the value is the SHALLOWEST penetration depth, the minimum translation needed to pull them apart. bbox_overlap is true if and only if all three axes strictly penetrate. A single penetrating axis already makes it read false, so it can never be read as "no penetration". Read details.clearances_xyz for the signed per-axis truth before concluding anything from distance alone. bbox overlap test. On overlap, distance is 0 and overlap_dims holds the per-axis penetration extents; otherwise distance is euclidean and gaps_xyz holds the per-axis gaps.
Distances are in the scene's current linear unit (cm, m or mm), not always centimetres.
Boundary: Disambiguated from scene_inspect (per-object property deep-dive), scene_snapshot (whole-scene spatial overview) and scene_assert (checks the scene against expected values rather than measuring one pair).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | What the returned number means — see the list above. | center |
| obj_a | Yes | First object name. | |
| obj_b | Yes | Second object name. | |
| format | No | Output format - "cos" or "json". | cos |
| session_key | No | Maya session key. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |