58.17 Relations and Live Layout

9.3

Racket

58.17 Relations and Live Layout🔗ℹ

A relation records dependencies and recomputes concrete geometry from a sampled scene state. Choose semantic resolution for model coordinates and layout resolution for renderer-measured anchors or boxes. Following helpers are relations too; they do not require a mutable frame updater.

58.17.1 First-Class Relation Visuals

58.17.1.1 Acyclic Live Layout

58.17.1 First-Class Relation Visuals🔗ℹ

A relation is an immutable Visual whose concrete geometry is recomputed from explicit dependencies in each sampled scene state. No relation uses a mutable updater or needs the preceding frame.

procedure
(relation-visual template
[ #:depends-on dependencies
#:phase phase
#:structure structure
#:space space
#:cache-key cache-key]
resolver) → relation-visual?
  template : visual?
  dependencies : (listof relation-dependency?) = '()
  phase : (or/c 'semantic 'layout) = 'semantic
  structure : (or/c 'root-only 'fixed) = 'root-only
  space : (or/c 'world 'local) = 'world
  cache-key : any/c = #f
  resolver : (-> relation-context? visual? visual?)

Creates a relation with the stable identity of template. The resolver receives a read-only relation-context? and a local template, and must return one concrete Visual with the same identity. Every value, Visual, renderer-anchor, or semantic selection read through the context must be named in dependencies; undeclared reads fail descriptively.

The ordinary movement, rotation, scale, opacity, fill, stroke, and stroke-width controls form an outer envelope. They are applied after the resolver has computed the current geometry, so a relation may be animated concurrently with its own changing dependencies. A requested style must be supported by both the template and the concrete result. A 'fixed relation preserves the template’s complete child-ID tree and may expose nested paths; a 'root-only relation deliberately exposes only its root ID.

A 'semantic relation is resolved from model data. A 'layout relation may use relation-context-anchor-ref, relation-context-layout-box, or selection boxes after the active renderer has measured its targets. Layout relations are currently top-level only, and their measurements are complete Pict boxes rather than tight visible outlines.

procedure
(relation-context-layout-box context
visual) → layout-box?
context : relation-context?
visual : visual?

Measures one resolver-local concrete Visual in the active renderer/camera configuration. This operation is available only to layout relations. It is intended for relations such as follow-anchor that must align one anchor of their own content to an anchor of another Visual.

procedure
(relation-visual? value) → boolean?
value : any/c

Recognizes an immutable relation Visual.

procedure
(relation-visual-dependencies relation)
→ (listof relation-dependency?)
relation : relation-visual?

Returns the relation’s explicitly declared dependencies in author order.

procedure
(relation-visual-cacheability relation)
→ (or/c 'serializable 'explicit-key 'disabled)
relation : relation-visual?

Reports whether the resolver can participate in a persistent cache. Built-in transparent specifications are 'serializable; an author procedure with #:cache-key is 'explicit-key; an opaque procedure is 'disabled.

procedure
(relation-dependency? value) → boolean?
value : any/c

Recognizes a declared value, Visual, anchor, or selection dependency.

procedure
(relation-context? value) → boolean?
value : any/c

Recognizes the read-only context supplied to a relation resolver.

procedure
(relation-context-anchor-ref context
target
anchor) → vec2?
  context : relation-context?
  target : (or/c visual? symbol? visual-path?)
  anchor : symbol?

Returns a renderer-measured anchor for a layout relation after recording the corresponding declared anchor-dependency.

procedure
(value-dependency target) → relation-dependency?
target : (or/c symbol? scene-parameter?)

Declares one sampled scalar/value input.

procedure
(visual-dependency target) → relation-dependency?
target : (or/c visual? symbol? visual-path?)

Declares one semantic Visual input.

procedure
(anchor-dependency target anchor) → relation-dependency?
target : (or/c visual? symbol? visual-path?)
anchor : symbol?

Declares one renderer-measured anchor input.

procedure
(selection-dependency selection) → relation-dependency?
selection : visual-selection?

Declares one semantic selection input.

procedure
(scene-validate-relations state) → immutable-hash?
state : scene-state?

Checks declared relation dependencies and reports missing targets or deterministic dependency cycles before rendering.

procedure
(scene-relation-report state [target]) → any/c
state : scene-state?
target : (or/c #f visual? symbol? visual-path?) = #f

Returns deterministic relation-resolution report data without invoking author resolver procedures. It records full path, drawing order, phase, structure, declared dependencies, cacheability, and warnings. Library-owned serializable specifications are cacheable; generic resolver procedures remain opaque unless the author supplies #:cache-key.

procedure
(scene-relation-sample-report state [target]) → any/c
state : scene-state?
target : (or/c #f visual? symbol? visual-path?) = #f

Returns the same report shape, but additionally resolves each selected 'semantic relation once for this sampled state. The report’s 'used-dependencies and 'unused-dependencies fields then distinguish declared inputs that the resolver actually read from declared inputs it did not read at this instant. This is an opt-in diagnostic operation: it can run the author’s resolver procedure, but does not alter the immutable scene state or renderer cache.

For a 'layout relation those fields are #f. Determining its actual reads requires the active renderer’s measured layout boxes, which this headless report intentionally does not invent.

Built-in line-between, arrow-between, ray-from, parameter-display, and follow-anchor use serializable relation specifications. The live angle, brace, and curved-arrow constructors use generic relations because their builder procedure is author-specific; therefore they deliberately do not claim automatic persistent-cache reuse.

procedure
(follow-anchor content
target
[ #:offset offset
#:target-anchor target-anchor
#:self-anchor self-anchor])
→ relation-visual?
  content : visual?
  target : (or/c visual? symbol? visual-path?)
  offset : vec2? = origin
   target-anchor :
(or/c 'bottom-left 'bottom 'bottom-right
      'left 'center 'right
      'top-left 'top 'top-right)
= 'center
   self-anchor :
(or/c 'bottom-left 'bottom 'bottom-right
      'left 'center 'right
      'top-left 'top 'top-right)
= 'center

Creates one world-space relation whose selected content anchor follows the selected sampled anchor of target, plus offset. target may be a top-level Visual, its symbol identity, or a nested path. The default centre-to-centre form is a semantic relation: it follows the target’s sampled reference point without invoking a renderer. Choosing a non-centre target or content anchor creates a layout relation, which measures the relevant Pict box in the active camera and renderer configuration. Both forms follow target motion without frame-mutating callbacks.

The content must be a concrete, non-frame-space Visual, and content and target must have distinct identities. Attachments may be animated through the normal relation envelope. One attachment may target another when the resulting relation graph is acyclic; they neither avoid other labels nor inherit target rotation. Layout attachments are top-level and renderer-dependent; a semantic centre attachment can be queried directly from a sampled scene state.

An attachment is a relation with an inspectable built-in specification.

Examples:

> (define attachment
(follow-anchor (circle #:id 'follower) 'target #:offset (vec2 1 0)))
> (relation-visual? attachment)
#t
> (relation-visual-cacheability attachment)
'serializable

58.17.1.1 Acyclic Live Layout🔗ℹ

The live-layout procedures give renderer-aware attachments concise relationship names. Their relation graph is resolved from a concrete target outward at each render. A direct or indirect cycle raises an exception; no prior frame is consulted.

procedure
(follow-above content target [#:gap gap]) → relation-visual?
  content : visual?
  target : (or/c visual? symbol? visual-path?)
  gap : (and/c finite-real? (>=/c 0)) = 0

Places the content’s bottom anchor at the target’s top anchor plus gap.

procedure
(follow-below content target [#:gap gap]) → relation-visual?
  content : visual?
  target : (or/c visual? symbol? visual-path?)
  gap : (and/c finite-real? (>=/c 0)) = 0

Places the content’s top anchor at the target’s bottom anchor minus gap.

procedure
(follow-left-of content target [#:gap gap]) → relation-visual?
  content : visual?
  target : (or/c visual? symbol? visual-path?)
  gap : (and/c finite-real? (>=/c 0)) = 0

Places the content’s right anchor at the target’s left anchor minus gap.

procedure
(follow-right-of content target [#:gap gap]) → relation-visual?
  content : visual?
  target : (or/c visual? symbol? visual-path?)
  gap : (and/c finite-real? (>=/c 0)) = 0

Places the content’s left anchor at the target’s right anchor plus gap.

I	Concepts
II	Cookbook
III	Guide
IV	Complete Example Programs
V	Reference

52	Find a task or a name
53	Modules to require
54	Scenes and sampling
55	Scene states
56	Animation requests
57	Native model details
58	Visuals
59	Geometry
60	Number Lines and Coordinate Decorations
61	Point Markers, Scatter Plots, and Filled Areas
62	Probability and Statistical Diagrams
63	Calculus lessons
64	Colors
65	Slides
66	Slide command-line tools
67	Source Programs and Authored Timelines
68	Interactive Preview and Inspection
69	Preview controls and diagnostics
70	Projects and Final Rendering
71	Project execution and cache details
72	Pict Renderer Protocol
73	3D reference map
74	3D: Objects, groups, and paths
75	3D: Cameras and projection
76	3D: Views inside a Scene
77	3D: Animating 3D objects
78	3D: Animating the 3D camera
79	3D: Cuts, caps, and section measurements
80	3D: Supplementary surface, section, and annotation bindings
81	3D: Cuts, sections, and numerical volume
82	3D: Vectors
83	3D: Linear maps and rotations
84	3D: Affine transforms
85	3D: Bounds, rays, and planes
86	3D: Spatial maps and homotopies
87	3D: Materials and lights
88	3D: Lighting inspection
89	3D: Shadow descriptors and stable bounds
90	3D: Finite-light animation
91	3D: Software finite-light evaluation
92	3D: Colour space and final output
93	3D: Relations and geometric annotations
94	3D: Projected labels
95	3D: Textured billboards
96	3D: Spatial curves and vector diagrams
97	3D: Spatial anchors and label layout
98	3D: Anchors and projected labels
99	3D: Parametric surfaces and calculus
100	3D: Adaptive, trimmed, and implicit surfaces
101	3D: Constructive solids
102	3D: Surface constructors and queries
103	3D: Meshes
104	3D: Triangle topology
105	3D: Polygonal faces
106	3D: Deterministic convex hulls
107	3D: Polyhedral duals
108	3D: Schlegel diagrams and polyhedral nets
109	3D: Conservative mesh correspondence
110	3D: Topology-safe mesh matching
111	3D: Checking and repairing mesh orientation
112	3D: Clipping, sections, and transparency
113	3D: Prepared spatial ODE trajectories and vector fields
114	3D: Seeds and streamline sets
115	3D: Poincare sections and return maps
116	3D: Equilibria and local linearization
117	3D: Flow maps and volume change
118	3D: Drawing and inspecting trajectories
119	3D: Reading prepared trajectories
120	3D: Drawing vector fields and particles
121	3D: Trajectory display
122	3D: Spatial inspection and exact picking
123	3D: Retained renderer backends
124	3D: Compiled geometry and instances
125	3D: Frame requests and results
126	3D: Software rendering and statistics
127	3D: Optional Racket/ Open GL backend
128	Experimental Derived Visuals
129	Source Package Hygiene

58.1	Visual Protocols and Groups
58.2	Shapes and Path Visuals
58.3	Bitmap and SVG Visuals
58.4	Text Content and Layout
58.5	Semantic Text and Typography Styles
58.6	Numbers and Units
58.7	Matrices, Tables, and Vector Diagrams
58.8	Formula Construction and Layout
58.9	Formula Assemblies and Named Parts
58.10	Formula Source Selection and Matching
58.11	Arrows and Coordinate Axes
58.12	Live Endpoints and Mathematical Annotations
58.13	Complex and Polar Visuals
58.14	Function, Parametric, and Data Plots
58.15	Graph Helpers and Traced Paths
58.16	ODE Trajectories and Streamlines
58.17	Relations and Live Layout