9.3
58.12 Live Endpoints and Mathematical Annotations
Use live endpoint constructors when geometry must follow sampled values or other Visuals. Use the static annotation constructors for fixed points. An edge or corner supplied with anchor-of requires renderer-measured layout; a center reference is a semantic position. These marks express an author’s diagram, not a geometric proof.
See also Arrows and Coordinate Axes, Relations and Live Layout.
58.12.1 Dynamic Endpoint Geometry
Live endpoint constructors provide deterministic geometry relationships without mutable updaters. Each endpoint accepted by the procedures below may be a literal vec2, a point-valued scene-parameter? handle, a top-level Visual/symbol/nested visual-path?, or a value made with anchor-of. A plain Visual reference selects its semantic reference position. Parameter values must be vec2 at every sampled time.
procedure
target : (or/c visual? symbol? visual-path?)
anchor :
(or/c 'bottom-left 'bottom 'bottom-right 'left 'center 'right 'top-left 'top 'top-right) = 'center offset : vec2? = origin
Creates one endpoint description for target. A centre anchor is the
ordinary semantic point. An edge or corner selects the target’s live
renderer-measured box at render time; offset is a world-space offset
from that selected point. This result is intended as an endpoint argument to
the live endpoint constructors.
procedure
(line-between start end #:id id [ #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → relation-visual? start : any/c end : any/c id : symbol? opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates a finite line segment with independently sampled endpoints.
Even a literal-endpoint connection is represented by a relation.
Example:
> (relation-visual? (line-between origin (vec2 2 0) #:id 'connection)) #t
procedure
(segment-between start end #:id id [ #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → relation-visual? start : any/c end : any/c id : symbol? opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
The mathematical finite-segment spelling of line-between.
procedure
(arrow-between start end #:id id [ #:opacity opacity #:stroke stroke #:stroke-width stroke-width #:tip-length tip-length #:tip-width tip-width #:start-tip? start-tip? #:end-tip? end-tip?]) → relation-visual? start : any/c end : any/c id : symbol? opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2 tip-length : (and/c finite-real? positive?) = 3/10 tip-width : (and/c finite-real? positive?) = 1/4 start-tip? : boolean? = #f end-tip? : boolean? = #t
Creates an arrow with a shaft and optional tips that follow independently
sampled endpoints.
procedure
(ray-from start through #:id id [ #:length length #:opacity opacity #:stroke stroke #:stroke-width stroke-width #:tip-length tip-length #:tip-width tip-width #:start-tip? start-tip? #:end-tip? end-tip?]) → relation-visual? start : any/c through : any/c id : symbol? length : (and/c finite-real? positive?) = 2 opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2 tip-length : (and/c finite-real? positive?) = 3/10 tip-width : (and/c finite-real? positive?) = 1/4 start-tip? : boolean? = #f end-tip? : boolean? = #t
Creates a finite visible ray that begins at start and points through
through. Its rendered length is fixed by length, avoiding an
ill-defined infinite renderer object.
Every endpoint constructor returns a relation-visual?. Literal points, parameters, and centre references create a 'semantic relation; a non-centre anchor-of creates a 'layout relation, measured against the current renderer-visible box after normal scene sampling. The relations retain their identity, support their ordinary outer movement and opacity animation, and can be inspected before rendering. Endpoint geometry must still resolve to distinct points at the sampled time.
58.12.2 Mathematical Annotations
Mathematical annotations are small semantic, path-backed marks for explanatory diagrams. Selected marks support the same live endpoint protocol as line-between: a literal vec2, point-valued scene-parameter, Visual ID/path (its semantic centre), or anchor-of description. Literal points return the immediate path-visual? or group-visual? values. Parameter and centre-reference inputs create semantic relations; an edge/corner anchor creates a layout relation. Both are deterministic from the sampled state. The layout phase is restricted to top-level relations, and it uses complete renderer bounds rather than exact visible outlines.
procedure
(arc #:id id [ #:center center #:radius radius #:start-angle start-angle #:angle angle #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → path-visual? id : symbol? center : vec2? = origin radius : (and/c finite-real? positive?) = 1 start-angle : finite-real? = 0 angle : (and/c finite-real? (not/c zero?)) = (/ pi 2) opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates an open circular arc. Positive sweeps travel counter-clockwise; the
absolute sweep must be no greater than one full turn. The implementation splits
the arc into quarter-turn cubic Bézier pieces, retaining exact cardinal
endpoints rather than using a polyline approximation.
procedure
(dashed-path geometry #:id id [ #:dash-length dash-length #:gap-length gap-length #:center center #:rotation rotation #:scale scale #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → path-visual? geometry : path-geometry? id : symbol? dash-length : (and/c finite-real? positive?) = 1/5 gap-length : stroke-width? = 1/8 center : vec2? = origin rotation : finite-real? = 0 scale : scale-factor? = 1 opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Selects dash intervals by the geometry’s total arc length. Curves remain cubic
path fragments; they are not flattened into renderer-specific segments.
procedure
(dashed-line start end #:id id [ #:dash-length dash-length #:gap-length gap-length #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → path-visual? start : vec2? end : vec2? id : symbol? dash-length : (and/c finite-real? positive?) = 1/5 gap-length : stroke-width? = 1/8 opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates a finite dashed line. start and end must differ.
procedure
(angle-marker first vertex second #:id id [ #:radius radius #:reflex? reflex? #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → path-visual? first : vec2? vertex : vec2? second : vec2? id : symbol? radius : (and/c finite-real? positive?) = 1/3 reflex? : boolean? = #f opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates an arc mark from the ray vertex–first to the ray
vertex–second. By default it selects the signed minor angle;
reflex? selects its complementary reflex sweep. Collinear rays are
rejected instead of producing a deceptive zero-angle mark. Its name avoids
shadowing racket/base’s numeric angle procedure.
procedure
(right-angle first vertex second #:id id [ #:size size #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → path-visual? first : vec2? vertex : vec2? second : vec2? id : symbol? size : (and/c finite-real? positive?) = 1/3 opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates the conventional square-corner mark from two supplied rays. It does not
try to prove that those rays are perpendicular.
procedure
(angle-between first vertex second #:id id [ #:radius radius #:reflex? reflex? #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → visual? first : any/c vertex : any/c second : any/c id : symbol? radius : (and/c finite-real? positive?) = 1/3 reflex? : boolean? = #f opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates angle-marker from three live endpoint descriptions. Literal
vec2 values return the same static path as angle-marker. Otherwise,
all three endpoints are sampled together before the angle arc is built. It
still does not infer a mathematical relationship between the rays.
procedure
(right-angle-between first vertex second #:id id [ #:size size #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → visual? first : any/c vertex : any/c second : any/c id : symbol? size : (and/c finite-real? positive?) = 1/3 opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates right-angle from three live endpoint descriptions. A right
angle remains an author assertion: the implementation follows the two rays but
does not verify they are perpendicular.
procedure
(brace-between start end #:id id [ #:offset offset #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → visual? start : any/c end : any/c id : symbol? offset : (and/c finite-real? (not/c zero?)) = 1/3 opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates a symmetric cubic curly brace. Positive offset places it to
the left of start-to-end travel; negative values place it on the other side.
With literal points it is an ordinary path; otherwise its two live endpoints
are sampled together. brace is a short spelling with the same
arguments.
procedure
(brace start end #:id id [ #:offset offset #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → visual? start : any/c end : any/c id : symbol? offset : (and/c finite-real? (not/c zero?)) = 1/3 opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Short spelling for brace-between. It creates the same symmetric cubic
brace with the same placement and styling rules.
procedure
(brace-label start end label #:id id [ #:offset offset #:gap gap #:font-size font-size #:color color #:opacity opacity #:stroke stroke #:stroke-width stroke-width]) → visual? start : any/c end : any/c label : string? id : symbol? offset : (and/c finite-real? (not/c zero?)) = 1/3 gap : stroke-width? = 1/6 font-size : (and/c finite-real? positive?) = 1/4 color : color-spec? = "black" opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2
Creates a brace and centered plain-text label. The child identities are
deterministically derived as id plus -brace and -label.
With live endpoints the brace and label are rebuilt together from the same two
sampled points.
procedure
(curved-arrow-between start end #:id id [ #:angle angle #:opacity opacity #:stroke stroke #:stroke-width stroke-width #:tip-length tip-length #:tip-width tip-width]) → visual? start : any/c end : any/c id : symbol? angle : finite-real? = (/ pi 2) opacity : opacity? = 1 stroke : any/c = "black" stroke-width : stroke-width? = 2 tip-length : (and/c finite-real? positive?) = 3/10 tip-width : (and/c finite-real? positive?) = 1/4
Creates curved-arrow from two live endpoint descriptions. Each
sample rebuilds both the circular shaft and its final-tangent tip, so the arrow
head follows the changing arc. It does not select routes around obstacles or
support arbitrary Bézier/elliptical routes.
procedure
(surrounding-rectangle target #:id id [ #:padding padding #:opacity opacity #:fill fill #:stroke stroke #:stroke-width stroke-width]) → relation-visual? target : (or/c visual? symbol? visual-path?) id : symbol? padding : stroke-width? = 1/8 opacity : opacity? = 1 fill : any/c = #f stroke : any/c = "yellow" stroke-width : stroke-width? = 3
Creates a layout relation around the sampled rendered bounding box of
target. Padding is in world coordinates. The relation follows motion,
scale, rotation, and nested/derived target layout, retains its ordinary outer
style and opacity animation, and records its target as a semantic selection
dependency. Its current implementation is square-cornered; #f selects
its default transparent fill. Like other layout relations, it must currently
remain top-level and its box includes renderer padding rather than only visible
ink.