17.1 Scene Parameters🔗ℹ

17.2 Path Geometry🔗ℹ

Path geometry describes outlines and filled regions without using Pict. It supports straight line segments and cubic Bézier segments. Both kinds are semantic model values. They do not contain drawing-context commands or a rendered approximation.

A path may contain several subpaths. Subpath order is significant. Within each subpath, the start point comes first and segments follow in traversal order. Each segment begins where the preceding segment ended. A closed subpath reconnects its final endpoint to its start when it is rendered and measured. That implicit closing edge is straight.

Length, partial extraction, and morphing use local coordinates before a Visual’s scale, rotation, or translation is applied. Compound paths traverse one subpath fully before continuing with the next one. Morphing pairs subpaths and segments by their stored order; it does not reorder them automatically.

The structure is immutable and transparent. Its public bindings include line-path-segment, line-path-segment?, line-path-segment-end, and struct:line-path-segment.

The curve starts in the direction from its start toward control1. It approaches end from the direction of control2. Control points usually do not lie on the visible curve. They may lie outside the curve’s actual bounds.

The structure is immutable and transparent. Its public bindings include cubic-bezier-path-segment, cubic-bezier-path-segment?, the three field accessors, and struct:cubic-bezier-path-segment.

The start field is the first local point. The segments list contains segment values in significant traversal order. Each segment begins where the preceding segment ended. An empty segment list represents one point.

When closed? is true, rendering reconnects the last endpoint to start with an implicit straight edge. The edge is not stored as an extra segment. It participates in bounds, length, partial extraction, and rendering. A closed subpath can be filled. An open subpath is only stroked by the built-in Pict renderer.

The structure is immutable and transparent. Its public bindings include its constructor, predicate, three field accessors, and structure descriptor.

An empty list is valid and represents geometry that draws nothing. The structure is immutable and transparent. Its public bindings include its constructor, predicate, field accessor, and structure descriptor.

This operation transforms local geometry only. It does not change a Visual’s reference position, rotation, or scale.

For an open subpath, the former final endpoint becomes the new start. For a closed subpath, the original stored start is preserved so the loop changes direction without also changing phase. When the original implicit closing line has positive length, that line is materialized as the first explicit reversed segment; the resulting synthetic closing edge is then zero length. This representation detail can change segment count, but it does not change the visible or measured loop.

For a positive finite closed loop, point lookup on the reversed result follows the original loop at fraction (- 1 fraction) (subject to the same deterministic cubic arc-length approximation as path-geometry-point-at). Tangent direction is reversed correspondingly away from corner one-sided boundaries.

The operation is purely semantic and does not apply a containing Visual transform. Empty geometry and zero-length subpaths are valid.

(vec2-lerp start end 1/3)

(vec2-lerp start end 2/3)

The resulting cubic traces the same straight line in the same direction. An existing cubic segment is kept unchanged. Subpath starts, subpath order, segment order, endpoints, and closure values are preserved. Point-only subpaths and empty geometry are valid.

Only stored line segments are converted. The implicit straight closing edge of a closed subpath remains implicit and is not added to the segment list.

When geometry already contains no stored line segments, the procedure returns geometry itself. Otherwise it returns new immutable geometry.

The paths are normalizable when all of the following hold:

• They contain the same number of subpaths.

• Corresponding subpaths have the same closure value.

• Each pair of corresponding subpaths is either point-only on both sides or contains at least one stored segment on both sides.

Stored segment counts and line-versus-cubic kinds may differ. Coordinates and path lengths do not affect this predicate. The predicate does not change either path.

Correspondence is measured in total-arc-length coordinates. The procedure samples source at sample-count evenly spaced fractions, scores candidate destination phases by mean Euclidean point distance, and chooses the lowest score deterministically. Candidate phases include a uniform full-loop grid and every stored positive-edge boundary of the destination. A fixed number of local refinement rounds then improves the best phase. The algorithm does not depend on frame rate, camera scale, rendering, wall-clock time, or randomness.

When reverse traversal is allowed, the same search is performed on (path-geometry-reverse destination). An exact score tie prefers the original forward traversal. Exact phase ties prefer the smaller phase. An already aligned destination therefore remains unchanged rather than being reversed or split gratuitously.

The returned value is ordinary semantic path geometry. Use it before path-geometry-normalize-for-morph when a caller wants explicit access to the chosen correspondence, or use morph-to-aligned to perform both steps during timeline compilation.

This operation deliberately handles one closed loop on each side. It does not pair multiple subpaths, add or remove subpaths, change closure, solve arbitrary global shape correspondence, or guarantee a globally optimal continuous phase for every pathological curve. Increasing sample-count makes the fixed deterministic geometric score finer.

The procedure samples source and destination at sample-count evenly spaced total-arc-length fractions including both endpoints and scores mean Euclidean point distance. When allow-reverse? is true, the same score is computed for (path-geometry-reverse destination). Reverse traversal is selected only when its score is strictly lower; an exact score tie keeps the caller’s stored forward destination. There is no cyclic phase search for an open path.

When forward traversal wins, the exact destination object is returned. When reverse traversal wins, the returned geometry traces the same destination from its former endpoint toward its former start. The operation is pure semantic geometry and does not inspect Visual transforms, renderers, camera state, frame rate, pixels, or output files.

Use the result before path-geometry-normalize-for-morph for explicit preparation, or use morph-to-open-aligned for timeline compilation. This operation deliberately handles one open subpath on each side; it does not select cyclic phases, pair compound subpaths, change closure, or add/remove subpaths.

For every source/destination subpath pair, the procedure uses the SCENE-AE endpoint-direction score from path-geometry-align-open-for-morph: both paths are sampled at sample-count inclusive total-arc-length fractions, and destination reversal is selected only when its score is strictly lower. One source subpath’s samples are cached while every destination candidate for that assignment row is evaluated.

After all pair costs are known, the same deterministic minimum-total-cost assignment policy as SCENE-AD chooses one distinct destination subpath for every source subpath. Pairing is global rather than greedy. Exact assignment ties use the deterministic destination-index policy of path-geometry-align-compound-for-morph, while exact per-pair direction ties preserve the caller’s stored forward traversal.

The returned value is ordinary immutable path-geometry whose subpath order matches source correspondence. A destination subpath whose stored direction wins is reused exactly. When pairing and direction alignment change nothing, the exact destination object is returned.

Use the result with path-geometry-normalize-for-morph for explicit preparation, or use morph-to-open-compound-aligned for timeline compilation. This specialized operation deliberately requires all subpaths to be open and counts to match. Use path-geometry-align-mixed-compound-for-morph when matching-count open and closed topology is combined in one compound. Use path-geometry-prepare-topology-changing-morph or morph-to-topology-changing when topology-class counts differ.

The procedure partitions both paths by path-subpath-closed?. Open candidates are evaluated with the SCENE-AE endpoint-direction rule used by path-geometry-align-open-for-morph. Closed candidates are evaluated with the SCENE-AC phase/direction rule used by path-geometry-align-for-morph. The deterministic global assignment policy is then solved independently inside the open and closed classes. An open subpath is therefore never paired with a closed loop merely because it is spatially nearby.

After both assignments, selected destination subpaths are placed in the exact subpath order of source. Each open pair may reverse only for a strictly lower score; each closed pair may choose cyclic phase and optional reversal under SCENE-AC’s deterministic tie rules. Unchanged destination subpath objects are reused, and when the entire correspondence is already a no-op the exact destination object is returned.

When one topology class is absent, this operation reduces to the corresponding SCENE-AF all-open or SCENE-AD all-closed behavior. Use path-geometry-prepare-topology-changing-morph when either topology-class count differs.

Use the result with path-geometry-normalize-for-morph for explicit preparation, or use morph-to-mixed-compound-aligned for timeline compilation.

Every real subpath on either side must have positive finite arc length. The whole source or destination may nevertheless be empty, allowing pure birth from empty geometry and pure death to empty geometry. Open and closed topology classes are handled independently and are never paired directly with one another.

Within each topology class, real open pairs use the SCENE-AE forward/reverse endpoint score and real closed pairs use the SCENE-AC phase/direction score. With the default 'forced value for both penalty keywords, the rectangular assignment pads only the forced class-count difference with zero-cost dummy slots; matching topology counts therefore reduce exactly to SCENE-AG as before.

SCENE-AJ adds an optional numeric policy. When both birth-penalty and death-penalty are finite nonnegative reals, the procedure solves an augmented global assignment. A real source/destination edge costs its geometric correspondence score, a source-to-dummy edge costs death-penalty, a dummy-to-destination edge costs birth-penalty, and unused dummy pairs cost zero. A poor real pair may therefore be replaced by death plus birth even when topology counts match. Exact primary-cost ties minimize the number of birth/death edges as a secondary objective, so equal-cost replacement does not occur. The two penalty keywords must either both be 'forced or both be finite nonnegative real numbers. SCENE-AL additionally accepts sparse birth-penalty-map and death-penalty-map hashes in numeric mode. Birth-map keys are exact nonnegative original destination subpath indexes; death-map keys are exact nonnegative original source subpath indexes. Map values are finite nonnegative real costs and missing keys fall back to the corresponding shared numeric penalty. Nonempty penalty maps are rejected in 'forced mode. The sparse costs replace dummy-edge costs only. SCENE-AM additionally accepts match-penalty-map in both forced and numeric modes. Each key is (cons source-index destination-index) using original caller subpath indexes, and each finite nonnegative value is added to that real edge’s existing geometric correspondence score. Missing pairs add zero. Pair penalties do not change topology classes or direction/phase alignment; they bias the global assignment after those per-edge geometric choices are scored. In numeric mode a penalized real edge also competes against death plus birth, while AJ’s exact-tie preference for fewer topology changes remains unchanged. Direct preparation rejects out-of-range pair indexes and keys that name impossible open/closed correspondence edges. allow-reverse? and sample-count retain their existing correspondence meanings.

A destination subpath assigned to a dummy source is a birth. By default its prepared source is a one-line-segment degenerate subpath at the exact axis-aligned bounds center of that destination subpath. A source subpath assigned to a dummy destination is a death and receives the analogous prepared destination seed at its own bounds center. Each seed preserves the real subpath’s path-subpath-closed? value. The controlled seeds have zero arc length; pre-existing zero-length real subpaths are rejected before assignment.

SCENE-AI extends this placement with birth-anchor and death-anchor. Each accepts exactly 'bounds-center or a finite vec2. An explicit point is local path geometry and is shared by every unmatched subpath on that side. SCENE-AK additionally accepts sparse birth-anchor-map and death-anchor-map hashes. Birth-map keys are exact nonnegative original destination subpath indexes; death-map keys are exact nonnegative original source subpath indexes. Map values use the same anchor syntax. A missing key falls back to the corresponding shared anchor, while an explicit 'bounds-center map value may override a shared vec2. Direct preparation rejects out-of-range keys. Anchor selection affects seed placement only; real-pair scores, direction/phase correspondence, penalties, and slot ordering are unchanged. In numeric SCENE-AJ penalty mode the selected assignment may contain additional voluntary unmatched slots, and those slots use the same original-index map lookup.

All slots corresponding to real source subpaths remain first in exact source order. Birth-only slots are appended in exact caller destination order. When open and closed class counts already match under the default forced-only policy, the operation reduces exactly to path-geometry-align-mixed-compound-for-morph, returning the original source as the first value. Numeric penalties may intentionally produce additional interior slots even when endpoint counts match.

Use the two results with path-geometry-normalize-for-morph for explicit preparation, or use morph-to-topology-changing for timeline compilation. This stage does not infer semantic holes, pair an open subpath directly with a closed loop, use appearance-aware scores, or accept arbitrary per-pair scoring callbacks beyond SCENE-AM sparse numeric additions.

The procedure computes every source/destination pair cost with the SCENE-AC closed-loop algorithm used by path-geometry-align-for-morph. Thus each candidate pair may choose a cyclic phase and, when allow-reverse? is true, reverse traversal. One source loop’s score samples are cached while all destination candidates for that source are evaluated.

After all pair costs are known, a deterministic minimum-total-cost assignment selects one distinct destination subpath for every source subpath. Pairing is global rather than greedy. Exact assignment ties preserve earlier source-row matches when an equally good free destination exists and then prefer the lower destination index. Per-pair direction and phase ties retain the SCENE-AC rules.

The returned value is ordinary immutable path-geometry whose subpath order matches source correspondence. When pairing and per-loop alignment change nothing, the exact destination object is returned. Otherwise untouched destination subpath objects are reused whenever possible.

Use the result with path-geometry-normalize-for-morph for explicit preparation, or use morph-to-compound-aligned for timeline compilation. This stage does not add/remove subpaths, pair open subpaths, infer semantic hole nesting, or support topology changes.

Normalization works independently on corresponding subpaths:

• Every stored line segment is converted to an equivalent cubic Bézier segment using path-geometry->cubic.

• The target segment count is the larger of the two stored segment counts.

• The side with fewer segments repeatedly splits its longest current cubic at parameter 1/2 until the counts match.

• Segment length is the same deterministic approximate cubic arc length used by path-subpath-length. When lengths tie, the earliest segment in traversal order is split.

De Casteljau subdivision preserves the exact cubic curve. Splitting therefore changes representation and correspondence, not the traced source or destination figure. Both returned paths contain only cubic stored segments, and path-geometry-morph-compatible? returns #t for them. Point-only corresponding subpaths remain point-only.

The implicit closing edge of a closed subpath is not stored, converted, or split. Closure remains represented by path-subpath-closed?. Subpath order and stored starting points are preserved.

This is deliberately limited normalization. It does not add or remove subpaths, change closure, turn a point-only subpath into a drawn path, reverse traversal, rotate the starting point of a closed path, reorder subpaths, or choose a geometric best match. A difference requiring one of those operations raises an exception that identifies the first unsupported subpath difference. Reported indexes start at zero.

Example:

(define triangle

(polygon-path

(list (vec2 -3 -1)

(vec2 3 -1)

(vec2 0 2))))

(define rectangle

(polygon-path

(list (vec2 -3 -2)

(vec2 3 -2)

(vec2 3 2)

(vec2 -3 2))))

(define-values (normalized-triangle normalized-rectangle)

(path-geometry-normalize-for-morph triangle rectangle))

(path-geometry-morph-compatible? normalized-triangle

normalized-rectangle)

Compatibility requires all of the following:

• The paths contain the same number of subpaths.

• Each corresponding subpath has the same closed? value.

• Each corresponding subpath contains the same number of segments.

• Each corresponding segment has the same kind: line with line, or cubic Bézier with cubic Bézier.

Subpaths and segments are paired by their stored order. Only stored segments are counted. A closed subpath’s implicit closing edge is represented by its closed? value, not by another stored line segment. Coordinates, path lengths, and style do not affect compatibility. Empty geometry is compatible with empty geometry. Point-only subpaths are compatible when their closure values correspond.

The procedure remains strict. It does not insert segments, convert lines to cubics, reverse a path, rotate a closed path’s starting point, or reorder subpaths. Use path-geometry-morph-normalizable? and path-geometry-normalize-for-morph for the limited explicit normalization provided by this version.

progress must be a finite real in the closed unit interval. A value of 0 returns from itself. A value of 1 returns to itself. An interior value returns new path geometry.

The interpolation uses local mathematical coordinates. It does not change a Visual’s identity, reference position, rotation, scale, fill, stroke, stroke width, or drawing order. Use morph-to to place this interpolation on a timeline.

When the paths are incompatible, the procedure raises an exception describing the first mismatch in deterministic traversal order. The diagnostic identifies a subpath-count, closure, segment-count, or segment-kind mismatch. Reported subpath and segment indexes start at zero. The procedure remains strict and does not normalize incompatible paths automatically. Normalize explicitly or use morph-to-normalized for the limited supported cases.

Example:

(define rectangle-path

(polygon-path

(list (vec2 -2 -1)

(vec2 2 -1)

(vec2 2 1)

(vec2 -2 1))))

(define diamond-path

(polygon-path

(list (vec2 0 -2)

(vec2 3 0)

(vec2 0 2)

(vec2 -3 0))))

(path-geometry-lerp rectangle-path diamond-path 1/2)

Line bounds come from their endpoints. Cubic bounds include their endpoints and every interior parameter where the x or y derivative is zero. The result therefore follows the curve itself instead of using the usually larger box of its control points. The result is mathematically tight subject to the ordinary numeric behavior of the supplied coordinates.

The implicit straight closing edge of a closed subpath is included. Empty geometry has no bounds and raises an exception.

Cubic length is computed by repeatedly splitting the curve in half. For each piece, the implementation compares the control-polygon length with the chord length. Subdivision stops when their difference is at most the larger of 1e-10 world units and 1e-8 times the original cubic’s control-polygon length, or after 20 subdivisions. The piece estimate is the average of its chord and control-polygon lengths. These constants are part of the current numeric behavior, but they are not a formal error guarantee.

A point-only subpath has length zero. Repeated adjacent points and completely degenerate cubics contribute zero. The affine transform of a containing Visual is not applied. The line distance calculation avoids unnecessary overflow, but a true distance beyond the inexact number range can produce +inf.0.

This is a geometric model operation. A non-uniform scale on a path Visual can change the displayed world-space length, but it does not change the value returned here. The result can be +inf.0 when an inexact distance is too large to represent. create, uncreate, and non-full partial extraction require a finite result.

Traversal uses the same significant edge order and length model as path-geometry-partial. Line portions use exact Euclidean distance. A point inside a cubic uses the same deterministic adaptive arc-length table described for path-subpath-length to approximate the corresponding curve parameter. The returned value is a semantic local point; no containing Visual transform is applied.

Compound path geometry is traversed subpath by subpath in stored order. Zero-length edges consume no positive fraction. The implicit closing edge of a closed subpath is included. Exact 0 returns the start of the first positive-length edge, and exact 1 returns the endpoint of the final positive-length traversal edge. At an exact boundary between positive subpaths, the endpoint of the preceding subpath is selected.

Empty geometry, zero-total-length geometry, or a non-finite computed total length raises an exception. move-along-path adds a stricter continuity rule and accepts only one positive-length subpath as a motion route.

Line tangents are normalized directed edge vectors. Cubic tangents are computed from the cubic derivative at the parameter selected by the same adaptive arc-length table used for point lookup. When that derivative is zero at a stationary endpoint or cusp, deterministic one-sided curve probes recover the forward traversal direction when one exists. The result is semantic local geometry; no containing Visual transform is applied.

Empty geometry, zero-total-length geometry, a non-finite computed total length, or a selected positive-length cubic point with no recoverable traversal direction raises an exception.

For an outside corner, join selects how adjacent shifted edge lines are connected. 'miter extends them to their intersection. The distance from the original vertex to that intersection is divided by the absolute offset distance; when the ratio exceeds miter-limit, the outside corner falls back to bevel. 'bevel connects the shifted edge endpoints with one straight segment. 'round uses one or more cubic Bézier circular-arc approximations centered at the original vertex, with no cubic spanning more than a quarter turn.

Inside corners always use the natural intersection of the two shifted lines, independent of join. This keeps the offset path traversing forward along both adjacent lines; the short centered arc on the inside would have the wrong endpoint tangents. Collinear same-direction edges share their shifted point.

Open subpath endpoints are shifted by their endpoint edge normals. Closed subpaths are joined cyclically, including the stored start vertex. Every edge participating in a nonzero offset must be a positive-length line-path-segment. A zero-length edge, an exact 180-degree reversal, or a cubic source segment raises an exception in this stage. Cubic segments may still appear in the result as round-join pieces.

The construction is geometric rather than renderer-dependent: camera scale, stroke width, and output resolution do not affect the generated path. The result has its own arc length, so move-along-path with linear easing moves uniformly along the joined offset route itself.

Fractions apply to the whole compound path. Traversal completes each subpath before beginning the next. A cut inside a line is inserted by linear interpolation. A cut inside a cubic uses the same deterministic adaptive length table as path-subpath-length to approximate the corresponding curve parameter. The selected cubic interval is then extracted with de Casteljau subdivision. The result remains a cubic segment; it is not replaced by a polyline or a Pict command.

A partially selected closed subpath becomes open. Its implicit closing edge is part of the traversal and may itself be returned as an open line segment. A closed subpath keeps its closure only when its complete traversal is selected. This rule prevents a partial prefix from being filled as if it were complete.

When start and end are equal, the result is empty-path-geometry. The exact interval from 0 through 1 returns geometry unchanged. This preserves segment types, control points, point-only subpaths, and other zero-length structure. For a zero-length path, every other interval returns empty geometry.

Zero-length edges and subpaths do not consume a positive portion of the arc length. They can therefore disappear from a non-full partial result. Any non-full partial extraction requires the computed total path length to be finite. Extremely large inexact coordinates whose distance overflows raise an exception here.

Examples:

(define mixed-path

(path-geometry

(list

(path-subpath

origin

(list (line-path-segment (vec2 2 0))

(cubic-bezier-path-segment (vec2 3 2)

(vec2 4 2)

(vec2 5 0)))

#f))))

(path-geometry-partial mixed-path 0 1/2)

geometry must contain exactly one closed subpath with positive finite length. Exact 0 and 1 return geometry unchanged. For any other fraction, the selected point becomes both fraction zero and fraction one of the returned closed loop.

When the selected point lies inside a line, the line is split by interpolation. When it lies inside a cubic, the arc-length table chooses the deterministic curve parameter and de Casteljau subdivision splits the curve. The tail from the selected point through the original closing edge is followed by the old prefix back to the selected point. The returned subpath remains closed; its final synthetic closing edge has zero length.

The operation deliberately handles one closed subpath rather than assigning one phase to every subpath of compound geometry. Automatic per-subpath phase selection is a separate correspondence problem. The returned value is ordinary path geometry and can be used directly by make-path-visual, move-along-path, orient-along-path, camera following, partial extraction, and normalized morph preparation.

The points are local coordinates. Use make-path-visual to choose the reference position in the Visual’s containing coordinate system. That system is world space at the top level and group-local space for a child.

Point order determines traversal direction and can affect later path operations. The built-in renderer uses the odd-even fill rule, so clockwise and counter-clockwise order produce the same simple fill in this version.

When closed? is true, the subpath also has an implicit straight edge from its final endpoint back to start. A smooth closed cubic shape normally includes a final cubic whose endpoint is start and also sets closed? to true so that the built-in renderer fills it. In that case, the implicit closing edge has length zero.

Example:

(define arch

(cubic-bezier-path

(vec2 -2 0)

(list

(cubic-bezier-path-segment (vec2 -2 2)

(vec2 2 2)

(vec2 2 0)))))

17.3 Affine Transforms🔗ℹ

Affine-transform values are created through make-affine-transform. The raw structure constructor is not part of the public API.

Rotation is interpolated as an ordinary number. The procedure does not choose the shortest path around a circle. For example, interpolation from 0 to (* 2 pi) describes one full turn.