9.3
122 3D: Spatial inspection and exact picking
3D reference map · First 3D picture
Spatial inspection exposes the hierarchy that an already sampled view3d submits to its renderer. Inspection is immutable query data; it never adds a wireframe, selection flag, acceleration structure, or other hidden state to an authored Scene. The preview uses the same query data after a viewport click and paints its AABB, exact triangle, normal, local frame, and ray-pixel marker only after the cached bitmap has been drawn.
struct
(struct spatial-inspection ( path kind local-transform world-transform local-bounds world-bounds material triangle-count vertex-count camera-position view-position projected-position view-depth metadata) #:transparent) path : (listof symbol?) kind : symbol? local-transform : transform3? world-transform : affine3? local-bounds : aabb3? world-bounds : aabb3? material : any/c triangle-count : exact-nonnegative-integer? vertex-count : exact-nonnegative-integer? camera-position : vec3? view-position : (or/c #f vec3?) projected-position : (or/c #f vec2?) view-depth : (or/c #f nonnegative-real?) metadata : immutable-hash?
One deterministic pre-order description of a spatial group, mesh, curve, or
surface. path begins with the enclosing view3d identity;
local-transform is the authored decomposition while
world-transform includes all spatial ancestors. Empty geometry has
false projection/depth fields rather than an invented point.
struct
(struct spatial-pick ( inspection path triangle-index point distance barycentric normal ray metadata) #:transparent) inspection : spatial-inspection? path : (listof symbol?) triangle-index : (or/c #f exact-nonnegative-integer?) point : vec3? distance : nonnegative-real? barycentric : vec3? normal : vec3? ray : ray3? metadata : immutable-hash?
The nearest spatial pick. spatial-pick-kind returns
'mesh-triangle, 'stroke-segment, 'point-marker, or
'arrow-marker. Mesh hits are exact ray/triangle intersections; screen
marks use the same prepared projected footprint and depth predicate as the
renderer. Stroke metadata includes source segment index/progress, world point,
view depth, pixel distance, and style. Ties are resolved by depth, drawing
index, then authored triangle or source segment index.
For a mesh triangle, metadata also carries immutable semantic and topological
inspection data: 'semantic-vertex-ids, 'semantic-edge-ids,
'render-triangle-id, 'connected-component,
'boundary-components, and 'topology. The latter records the
Euler characteristic, boundary count, manifold/closed/orientable predicates,
component invariants, genus report, and diagnostics. The explicitly named
'semantic-polygonal-face-id currently equals the render-triangle ID,
with 'polygonal-face-policy set to 'render-triangle: a plain
mesh3d does not yet retain a separate polygonal-face-complex mapping.
'nearest-semantic-vertex-id and 'nearest-semantic-edge-id
classify the nearest lower-dimensional primitive from barycentric coordinates;
they do not claim an exact lower-dimensional ray intersection. The latter’s
'nearest-edge-incident-face-ids reports every incident triangle face.
Inspection only reads immutable topology; it does not alter the Scene.
struct
(struct topology-inspection3d ( path semantic-vertex-ids semantic-edge-ids nearest-vertex-id nearest-edge-id nearest-edge-incident-face-ids render-triangle-id polygonal-face-id polygonal-face-policy connected-component boundary-components topology) #:transparent) path : (listof symbol?) semantic-vertex-ids : vector? semantic-edge-ids : vector? nearest-vertex-id : any/c nearest-edge-id : any/c nearest-edge-incident-face-ids : vector? render-triangle-id : any/c polygonal-face-id : any/c polygonal-face-policy : any/c connected-component : any/c boundary-components : vector? topology : hash?
One immutable, presentation-neutral explanation of a mesh pick’s semantic
parts and topological report. The preview’s 3D topology section uses this
record; a headless authoring tool can use precisely the same data.
procedure
→ (or/c #f topology-inspection3d?) pick : spatial-pick?
Returns a topology-inspection3d for an exact mesh-triangle pick, and
#f for a stroke or marker pick. It only repackages already retained
immutable pick data; it does not traverse or mutate the scene.
struct
(struct spatial-topology-overlay3d ( vertex edge face component-faces boundary-segments halfedges) #:transparent) vertex : vec3? edge : vector? face : vector? component-faces : vector? boundary-segments : vector? halfedges : vector?
Preview-only world-space geometry derived from one exact mesh pick. The
vertex and edge designate the nearest semantic primitive
under the triangle hit; face is the selected render triangle;
component-faces contains its edge-connected component;
boundary-segments contains that component’s boundary edges; and
halfedges preserves the selected triangle’s directed source edges.
Each segment is an immutable two-vec3 vector and each face is an
immutable three-vec3 vector. This is diagnostic geometry only: it is
not a mesh3d and cannot affect rendering, matching, or scene state.
procedure
(spatial-pick-topology-overlay3d view pick)
→ (or/c #f spatial-topology-overlay3d?) view : view3d? pick : spatial-pick?
Returns the immutable topology overlay for an exact mesh-triangle pick in
view, or #f for screen-space marks or a pick that does not
have a matching mesh command in that view. The function performs its component
traversal only on demand after a selection; it does not mutate or augment the
view. The preview paints at most the first 256 component-face outlines and
512 boundary segments to preserve UI responsiveness; the returned value and
the topology inspection report always retain the complete component.
struct
(struct surface-pick3d ( spatial-pick surface-kind parameter trim-boundary source-cell interpolated-normal) #:transparent) spatial-pick : spatial-pick? surface-kind : symbol? parameter : (or/c #f vector?) trim-boundary : any/c source-cell : any/c interpolated-normal : (or/c #f vec3?)
A refinement of an exact mesh spatial-pick for a surface3d.
The source cell is immutable triangle provenance, not an implementation cache.
procedure
(spatial-pick-kind pick)
→ (or/c 'mesh-triangle 'stroke-segment 'point-marker 'arrow-marker) pick : spatial-pick?
Returns the selected primitive kind.
procedure
(view3d-spatial-inspections view)
→ (listof spatial-inspection?) view : view3d?
Returns deterministic pre-order records, including containers.
procedure
→ (listof spatial-inspection?) view : view3d?
An explicit spelling for the same
pre-order hierarchy, convenient for a tree UI.
procedure
(view3d-spatial-inspection-at view path)
→ (or/c #f spatial-inspection?) view : view3d? path : (listof symbol?)
Returns the matching record, or
#f when path does not occur in this view.
procedure
(view3d-pick view ray) → (or/c #f spatial-pick?)
view : view3d? ray : ray3?
Picks a spatial object with world ray ray. It first culls world AABBs,
transforms the candidate ray to mesh-local coordinates, traverses a local BVH,
and finishes with exact triangle and barycentric testing.
procedure
(view3d-surface-pick view ray) → (or/c #f surface-pick3d?)
view : view3d? ray : ray3?
Uses the same CPU path as view3d-pick, returning #f unless
the nearest hit is a surface. Parametric parameters are interpolated from
retained vertex provenance; an implicit result retains its source grid/tetrahedron
record instead.
procedure
(view3d-pixel-pick view pixel-x pixel-y #:width width #:height height) → (or/c #f spatial-pick?) view : view3d? pixel-x : finite-real? pixel-y : finite-real? width : exact-positive-integer? height : exact-positive-integer?
Builds the camera ray through a top-left-origin viewport pixel. It performs
exact mesh picking and supplements it with prepared screen-stroke and marker
footprints; it does not sample a rendered bitmap or require a GUI.
procedure
(mesh3d-bvh mesh) → mesh3d-bvh?
mesh : mesh3d?
Returns the immutable local
acceleration tree used for picking. It splits on the longest centroid axis,
uses a stable median, and breaks ties by triangle index. The cache is an
implementation resource, not semantic scene state.
procedure
(mesh3d-bvh? value) → boolean?
value : any/c
Recognizes an inspection BVH.
procedure
(bvh3d-node? value) → boolean?
value : any/c
Recognizes an internal BVH node.
procedure
(bvh3d-leaf? value) → boolean?
value : any/c
Recognizes a BVH leaf.
procedure
(bvh3d-bounds tree) → aabb3?
tree : mesh3d-bvh?
Returns local bounds for a
node or leaf.
procedure
(bvh3d-triangle-indices tree)
→ (listof exact-nonnegative-integer?) tree : mesh3d-bvh?
Returns the complete stable set
of contained triangle indices.
procedure
(bvh3d-ray-candidates tree ray)
→ (listof exact-nonnegative-integer?) tree : mesh3d-bvh? ray : ray3?
Returns deterministic local
triangle candidates. Exact triangle testing remains separate.
The canonical preview probe is "examples/3d/spatial-inspector-picking.rkt". Open it with animate/preview, click a visible facet, then use the 3D topology inspector section to see semantic part IDs and invariants; the post-render overlay marks its face, component, boundaries, half-edges, and normal. Animate → 3D selection can copy the spatial path, hit point, or normal; its scratch action also supplies a clipping plane. Focusing the inspection camera changes only the preview override, never the authored camera or timeline. The raw mesh uses render triangles as polygonal faces, so the probe does not claim an unretained higher-level polygonal-face mapping.