93 3D: Relations and geometric annotations🔗ℹ
3D reference map · First 3D picture
Spatial relations provide derived geometry without a mutable per-frame updater.
A spatial-relation is a spatial Visual declaration with a concrete
template, an explicit list of inputs, and a resolver. During a regular
scene sample, Animate first samples ordinary spatial and camera
animation, then resolves spatial relations inside each view3d, then
renders the spatial viewport, and finally resolves projected labels as ordinary
two-dimensional Visuals. This order means a label may use the resolved
position of a relation result, while ordinary 2D layout can still use the
label.
The three dependency declarations make a resolver’s inputs inspectable:
Recognizes a declared
spatial relation dependency.
Declares a relative or view-rooted path to a spatial Visual.
Declares one immutable named Scene value.
Declares the camera of one owning
view3d.
Creates a semantic spatial Visual.
resolver accepts a
spatial-relation-context? and the transform-free local template, and
must return concrete spatial geometry with the template’s ID. Its outer
transform and opacity remain independently animatable.
A 'root-only relation may change all of its internal structure and can
only be addressed at its own root path. A 'fixed relation must return
the template’s exact child-ID tree, so a descendant is addressable. Generic
resolver procedures are intentionally not cross-process-cacheable; supply a
stable #:cache-key to declare an explicit cache identity.
Recognizes a semantic
spatial relation.
Returns the declared inputs.
Returns the declared structural policy.
Reports whether the relation has an
explicit stable cache key.
The resolver context is read-only and accepts only declared inputs.
Recognizes a
spatial relation resolver context.
Resolves a declared relative or rooted target.
Returns a declared target’s sampled world transform.
Returns a declared target’s sampled world origin.
Reads a declared immutable named Scene value.
Reads the declared camera of the owning view.
An undeclared access is an authoring error. Relations resolve lazily with one
cache for the sampled viewport; a cycle reports complete paths rooted at the
owning view, such as '(world links ab).
The following constructors describe common spatial relationships:
Produces a finite semantic segment between the
current world origins of two declared targets.
Produces the displayed portion of the infinite
line through two current origins.
Produces a segment with a small semantic arrow
head at to.
Produces a double-sided triangular plane through
three current origins.
|
| target : spatial-path? |
| normal : vec3? |
| id : symbol? |
| length : positive-real? = 1 |
| color : any/c = "darkmagenta" |
| width : positive-real? = 2 |
| tip-size : positive-real? = 1/4 |
| opacity : real? = 1 |
Produces a directed normal marker from a target’s
current origin.
Produces a semantically named finite distance
segment.
Produces extension segments and a two-ended
dimension line. The offset is an explicit world-space vector, so the mark
retains mathematical meaning under camera motion.
Produces the smaller arc from first
through vertex to second. The three current points must
remain non-collinear.
Produces a three-segment corner following the
two current rays. It is square when the rays are perpendicular; it deliberately
does not silently assert that an animated non-right configuration is right.
Produces a signed smaller arc around the ordered
hinge, using one off-axis point from each incident face. Face points on the
hinge and coincident face directions are rejected when the relation resolves.
|
| target : spatial-path? |
| normal : vec3? |
| id : symbol? |
| length : positive-real? = 1 |
| color : any/c = "darkmagenta" |
| width : positive-real? = 2 |
| tip-size : positive-real? = 1/4 |
| opacity : real? = 1 |
The fixed-child-tree annotation spelling of
normal-at3d. The supplied normal is a world direction.
| (coordinate-tripod3d | | target | | | | | | | | #:id id | | | | | | | [ | #:length length | | | | | | | | #:width width | | | | | | | | #:tip-size tip-size | | | | | | | | #:x-color x-color | | | | | | | | #:y-color y-color | | | | | | | | #:z-color z-color | | | | | | | | #:opacity opacity]) | | → | | spatial-relation? |
|
| target : spatial-path? |
| id : symbol? |
| length : positive-real? = 1 |
| width : positive-real? = 2 |
| tip-size : positive-real? = 1/4 |
| x-color : any/c = "firebrick" |
| y-color : any/c = "forestgreen" |
| z-color : any/c = "royalblue" |
| opacity : real? = 1 |
Produces three current-origin arrows for the
fixed world x, y, and z directions.