►V Reference
On this page:
apply-pointwise
apply-pointwise-request?
apply-homotopy
apply-homotopy-request?
apply-wave
apply-wave-request?
pointwise-jacobian
pointwise-jacobian-determinant
pointwise-orientation
inverse-map-mesh
radial-reveal-front
radial-reveal-front?
wipe-in
wipe-out
iris-in
iris-out
ripple
default-confetti-palette
underline-sweep
underline-sweep-request?
strike-through
strike-through-request?
highlight-sweep
highlight-sweep-request?
slide-in
slide-out
spin-in
visual-match
cubic-bezier
spring
change-speed
delay-plan?
index-delay
constant-delay
distance-delay
radial-delay
wave-delay
eager-stagger-map
target-sequence?
concrete-targets
children-of
descendants-of
selection-targets
target-ref?
target-ref-path
target-ref-source-index
target-ref-scheduled-index
procedure-request-template
named-request-template
request-template?
request-template-serializable?
parallel-map
successive-map
crossfade-subsets
animation-order?
forward-order
forward-order?
reverse-order
reverse-order?
permutation-order
permutation-order?
shuffled-order
shuffled-order?
resolve-animation-order
9.3

56.13 Other animation requests🔗ℹ

Additional request constructors and their predicates.

procedure

(apply-pointwise target 
  map-point 
  [#:samples samples 
  #:adaptive? adaptive? 
  #:tolerance tolerance 
  #:max-depth max-depth 
  #:discontinuities discontinuities]) 
 → apply-pointwise-request?
  target : (or/c visual? symbol? visual-path?)
  map-point : (procedure-arity-includes/c 1)
  samples : exact-positive-integer? = 24
  adaptive? : boolean? = #t
  tolerance : (and/c finite-real? positive?) = 1/32
  max-depth : exact-nonnegative-integer? = 8
  discontinuities : (or/c 'split 'error) = 'split
Creates a world-space point-map request. At each positive clip progress, every supported geometric sample p moves to (map-point p) by ordinary linear interpolation. map-point must return a finite vec2? for every retained sample.

Path Visuals, circles, rectangles, axes, and arrows are converted to sampled path geometry. Groups retain their ordinary hierarchy and names. A nested target is resolved into world coordinates and rebased through its invertible enclosing affine map, preserving its siblings and their paths. Text, images, and other affine leaves without an exposed path remain at their original resolved world placement so they stay legible; they are not secretly raster-warped. The request rejects derived Visuals and frame-space overlays. It conflicts with simultaneous same-target spatial, style, opacity, formula, or path changes, because it replaces the complete sampled Visual tree.

#:samples gives the initial positive number of pieces per original line or cubic segment. With the default #:adaptive? #t, intervals whose mapped midpoint differs from their mapped chord by more than #:tolerance are bisected, up to #:max-depth. At 'split discontinuity policy, a raised error or an invalid map result omits that interval and leaves adjacent valid fragments disconnected; 'error propagates it. Point maps should be pure because refinement may call them more than once at a source point.

procedure

(apply-pointwise-request? value) → boolean?

  value : any/c
Returns #t for a request created by apply-pointwise.

procedure

(apply-homotopy target 
  homotopy 
  [#:samples samples 
  #:adaptive? adaptive? 
  #:tolerance tolerance 
  #:max-depth max-depth 
  #:discontinuities discontinuities]) 
 → apply-homotopy-request?
  target : (or/c visual? symbol? visual-path?)
  homotopy : (procedure-arity-includes/c 2)
  samples : exact-positive-integer? = 24
  adaptive? : boolean? = #t
  tolerance : (and/c finite-real? positive?) = 1/32
  max-depth : exact-nonnegative-integer? = 8
  discontinuities : (or/c 'split 'error) = 'split
Creates a time-dependent world-space deformation request. At each positive eased clip phase alpha, every supported geometric source sample p is placed directly at (homotopy p alpha). This is not an endpoint map blended toward its final value: sampling a frame at any time evaluates the same immutable clip-start geometry and phase.

The exact source Visual is retained at clip time zero; authors normally supply (homotopy p 0) equal to p. The map must be pure, may be called repeatedly at a source point by adaptive refinement, and must return a finite vec2? for every retained sample. Nested targets, supported geometric leaves, adaptive sampling, and 'split versus 'error discontinuity semantics are the same as for apply-pointwise. As a sampled approximation, phase-dependent adaptive refinement can choose different path subdivisions at different phases; this API does not infer continuous topology changes over the full time interval.

procedure

(apply-homotopy-request? value) → boolean?

  value : any/c
Returns #t for a request created by apply-homotopy.

procedure

(apply-wave target    
  [#:direction direction    
  #:amplitude amplitude    
  #:wavelength wavelength    
  #:cycles cycles    
  #:phase phase]) → apply-wave-request?
  target : (or/c visual? symbol? visual-path?)
  direction : vec2? = (vec2 0 1)
  amplitude : (and/c finite-real? (>=/c 0)) = 1/5
  wavelength : (and/c finite-real? positive?) = 1
  cycles : (and/c finite-real? (>=/c 0)) = 1
  phase : finite-real? = 0
Creates a target-local sinusoidal path deformation. direction is normalized in the target’s immutable local affine frame; it selects both the wave-coordinate axis and displacement direction. The displacement amplitude is multiplied by a zero-at-both-ends sine-squared envelope, so each interior frame is sampled directly from the captured source geometry and the exact source Visual is restored at completion.

The request uses the adaptive pointwise path mapper. It supports ordinary affine, world-space Visuals with exposed geometry and rejects derived and frame-space Visuals. Because it temporarily replaces the sampled target tree, it conflicts with simultaneous target movement, style, opacity, formula, and path writers.

procedure

(apply-wave-request? value) → boolean?

  value : any/c
Returns #t for a request created by apply-wave.

procedure

(pointwise-jacobian map-point    
  point    
  [#:step step]) → linear2?
  map-point : (procedure-arity-includes/c 1)
  point : vec2?
  step : (and/c finite-real? positive?) = 1/1000
Approximates the local Jacobian by centred finite differences. It is an inspection helper, not symbolic differentiation.

procedure

(pointwise-jacobian-determinant map-point    
  point    
  [#:step step]) → finite-real?
  map-point : (procedure-arity-includes/c 1)
  point : vec2?
  step : (and/c finite-real? positive?) = 1/1000
Returns the determinant of pointwise-jacobian at point.

procedure

(pointwise-orientation map-point 
  point 
  [#:step step 
  #:tolerance tolerance]) 
 → (or/c 'preserving 'reversing 'singular)
  map-point : (procedure-arity-includes/c 1)
  point : vec2?
  step : (and/c finite-real? positive?) = 1/1000
  tolerance : (and/c finite-real? positive?) = 1e-8
Classifies the numerical Jacobian determinant using tolerance.

procedure

(inverse-map-mesh inverse-map    
  #:id id    
  [#:x-min x-min    
  #:x-max x-max    
  #:y-min y-min    
  #:y-max y-max    
  #:x-count x-count    
  #:y-count y-count    
  #:samples samples    
  #:tolerance tolerance    
  #:max-depth max-depth    
  #:stroke stroke    
  #:stroke-width stroke-width]) → group-visual?
  inverse-map : (procedure-arity-includes/c 1)
  id : symbol?
  x-min : finite-real? = -3
  x-max : finite-real? = 3
  y-min : finite-real? = -2
  y-max : finite-real? = 2
  x-count : exact-integer? = 7
  y-count : exact-integer? = 5
  samples : exact-positive-integer? = 12
  tolerance : (and/c finite-real? positive?) = 1/32
  max-depth : exact-nonnegative-integer? = 8
  stroke : any/c = "mediumpurple"
  stroke-width : (and/c finite-real? (>=/c 0)) = 2
Builds a regular target-space grid and adaptively maps it through the explicitly provided inverse. This does not attempt to derive an inverse automatically.

procedure

(radial-reveal-front [#:center center 
  #:start-radius start-radius 
  #:padding padding]) 
 → radial-reveal-front?
  center : (or/c 'automatic vec2?) = 'automatic
  start-radius : (and/c finite-real? (>=/c 0)) = 0
  padding : (and/c finite-real? (>=/c 0)) = 1/20
Constructs a deterministic radial reveal front. Its immutable polygonal disk is chosen conservatively so its endpoint covers every corner of the frozen layout box. #:start-radius can make the initial clip nonempty.

procedure

(radial-reveal-front? value) → boolean?

  value : any/c
Recognizes a radial reveal front.

procedure

(wipe-in visual    
  direction    
  [#:origin origin    
  #:padding padding]) → reveal-in-request?
  visual : (and/c visual? affine-visual? opacity-visual?)
  direction : (or/c vec2? 'left 'right 'up 'down)
  origin : (or/c 'automatic vec2?) = 'automatic
  padding : (and/c finite-real? (>=/c 0)) = 1/20
Returns reveal-in with a linear-reveal-front. Cardinal and nonzero vector directions use the same normalized spelling as slide-in. All timing, frozen-layout, and exact endpoint behavior is the generic reveal lifecycle behavior.

procedure

(wipe-out target    
  direction    
  [#:origin origin    
  #:padding padding]) → reveal-out-request?
  target : (or/c visual? symbol? visual-path?)
  direction : (or/c vec2? 'left 'right 'up 'down)
  origin : (or/c 'automatic vec2?) = 'automatic
  padding : (and/c finite-real? (>=/c 0)) = 1/20

procedure

(iris-in visual    
  [#:center center    
  #:start-radius start-radius    
  #:padding padding]) → reveal-in-request?
  visual : (and/c visual? affine-visual? opacity-visual?)
  center : (or/c 'automatic vec2?) = 'automatic
  start-radius : (and/c finite-real? (>=/c 0)) = 0
  padding : (and/c finite-real? (>=/c 0)) = 1/20

procedure

(iris-out target    
  [#:center center    
  #:start-radius start-radius    
  #:padding padding]) → reveal-out-request?
  target : (or/c visual? symbol? visual-path?)
  center : (or/c 'automatic vec2?) = 'automatic
  start-radius : (and/c finite-real? (>=/c 0)) = 0
  padding : (and/c finite-real? (>=/c 0)) = 1/20

procedure

(ripple target 
  [#:rings rings 
  #:spacing spacing 
  #:padding padding 
  #:color color 
  #:stroke-width stroke-width 
  #:lag-ratio lag-ratio 
  #:id id]) 
 → lagged-start-animation-request?
  target : (or/c visual? symbol? visual-path? visual-selection?)
  rings : exact-positive-integer? = 3
  spacing : (and/c finite-real? (>=/c 0)) = 1/5
  padding : (and/c finite-real? (>=/c 0)) = 1/5
  color : any/c = "gold"
  stroke-width : (and/c finite-real? (>=/c 0)) = 2
  lag-ratio : (and/c finite-real? (>=/c 0)) = 1/4
  id : (or/c #f symbol?) = #f
Eagerly expands to a lagged-start composition of rings temporary, expanding outlines around target. Each ring reads the target’s renderer-measured bounds at its own sampled time, so it follows a concurrently moving, rotating, or scaled target without writing any target component. The outline starts absent, grows by spacing, fades to transparent, and is absent again at the exact local endpoint.

The expansion uses the same source-order and timing semantics as stagger-map. Its generated helpers have deterministic origin-derived IDs, so simultaneous default ripples on one target are distinct. An explicit #:id remains authoritative; reusing it is rejected as a normal component conflict.

The immutable default palette used by confetti.

procedure

(underline-sweep target 
  [#:color color 
  #:stroke-width stroke-width 
  #:id id 
  #:retain? retain?]) 
 → underline-sweep-request?
  target : (or/c text-visual? symbol?)
  color : (or/c #f color-spec?) = #f
  stroke-width : (and/c finite-real? (>=/c 0)) = 2
  id : (or/c #f symbol?) = #f
  retain? : boolean? = #t
Adds an inspectable ordinary path Visual that sweeps from the frozen text layout’s left edge to its right edge. It is retained at completion by default; pass #:retain? #f for a temporary helper. With no #:id, the deterministic helper identity is derived from the target and immutable scheduler expansion origin. Thus simultaneous default underlines of one target remain distinct; an explicit #:id is authoritative and must be unique.

The request accepts unrotated, unscaled text and snapshots the text box at local clip start. Consequently it is intentionally a frozen-layout decoration: simultaneous motion of the target does not move the line. Its default colour is the text Visual’s outer colour.

procedure

(underline-sweep-request? value) → boolean?

  value : any/c
Recognizes a request created by underline-sweep.

procedure

(strike-through target 
  [#:color color 
  #:stroke-width stroke-width 
  #:id id 
  #:retain? retain?]) 
 → strike-through-request?
  target : (or/c text-visual? symbol?)
  color : (or/c #f color-spec?) = #f
  stroke-width : (and/c finite-real? (>=/c 0)) = 2
  id : (or/c #f symbol?) = #f
  retain? : boolean? = #t
Adds a separately inspectable swept line through the middle of a frozen text box. Its target, retained/temporary lifecycle, colour default, deterministic ID rules, and unrotated/unscaled frozen-layout restriction are the same as underline-sweep. Underline and strike-through use different default helper identities and can therefore be deliberately composed.

procedure

(strike-through-request? value) → boolean?

  value : any/c
Recognizes a request created by strike-through.

procedure

(highlight-sweep target    
  [#:color color    
  #:padding padding    
  #:id id    
  #:retain? retain?]) → highlight-sweep-request?
  target : (or/c text-visual? symbol?)
  color : color-spec? = "#fff2a8"
  padding : (and/c finite-real? (>=/c 0)) = 1/20
  id : (or/c #f symbol?) = #f
  retain? : boolean? = #f
Sweeps a filled semantic rectangle behind an unrotated, unscaled text target’s frozen clip-start text box. The highlight is temporary by default; pass #:retain? #t to keep the final rectangle immediately behind the text in scene drawing order. Its default colour is #fff2a8. The target and helper-ID rules are the same as underline-sweep.

procedure

(highlight-sweep-request? value) → boolean?

  value : any/c
Recognizes a request created by highlight-sweep.

procedure

(slide-in visual    
  direction    
  [#:distance distance]) → enter-request?
  visual : (and/c visual? affine-visual? opacity-visual?)
  direction : (or/c vec2? 'left 'right 'up 'down)
  distance : nonnegative-real? = 2
Returns an enter request whose source is distance local world units from the authored endpoint in direction. A cardinal symbol names the side where the Visual begins; a nonzero vec2 is normalized, so distance always has the same units. The slide preserves authored opacity rather than adding a fade.

procedure

(slide-out target    
  direction    
  [#:distance distance]) → leave-request?
  target : (or/c visual? symbol? visual-path?)
  direction : (or/c vec2? 'left 'right 'up 'down)
  distance : nonnegative-real? = 2
Returns a leave request toward the named local side and removes the target at the exact endpoint. It preserves the clip-start opacity while the target slides away.

procedure

(spin-in visual [#:turns turns]) → enter-request?

  visual : (and/c visual? affine-visual? opacity-visual?)
  turns : finite-real? = 1
Returns an enter request that rotates through signed turns complete counter-clockwise turns before restoring the exact authored Visual. Its opacity behavior is the default enter behavior.

struct

(struct visual-match (source-path destination-path)
    #:transparent)
  source-path : (listof symbol?)
  destination-path : (listof symbol?)
An explicit correspondence between two leaf paths relative to the root Visuals passed to transform-matching-visuals. The empty path names an atomic root. Every selected source and destination leaf may occur in at most one explicit match.

procedure

(cubic-bezier [#:x1 x1    
  #:y1 y1    
  #:x2 x2    
  #:y2 y2]) → rate-function?
  x1 : (and/c finite-real? (>=/c 0) (<=/c 1)) = 1/4
  y1 : finite-real? = 1/10
  x2 : (and/c finite-real? (>=/c 0) (<=/c 1)) = 1/4
  y2 : finite-real? = 1
Returns a CSS/Manim-style cubic Bézier timing curve. Its x controls are limited to the unit interval, so the implementation can deterministically invert time with bisection; y controls may overshoot.

procedure

(spring [#:frequency frequency    
  #:damping damping]) → rate-function?
  frequency : positive-real? = 3
  damping : nonnegative-real? = 6
Returns a damped spring timing curve. Direct intermediate evaluation can overshoot; scene playback applies its normal unit-progress clamp. Zero and one remain exact timeline endpoints.

procedure

(change-speed keyframes) → rate-function?

  keyframes : (listof (list/c finite-real? positive-real?))
Builds a rate from a unit-time piecewise-linear speed profile. Each keyframe is (list time speed); times must strictly increase, begin at zero, and end at one. Positive speed is integrated and normalized, so speed two travels twice as much animation distance per wall-clock time as speed one. Use this semantic value as the #:easing of timed or scene-play.

procedure

(delay-plan? value) → boolean?

  value : any/c
Recognizes an immutable delay policy for a deferred mapped composition.

procedure

(index-delay ratio) → delay-plan?

  ratio : (and/c finite-real? (>=/c 0))
Starts each target after ratio times its scheduled index. This is the default policy corresponding to #:lag-ratio.

procedure

(constant-delay value) → delay-plan?

  value : (and/c finite-real? (>=/c 0))
Adds the same explicit lead-in before every mapped child.

procedure

(distance-delay point scale) → delay-plan?

  point : vec2?
  scale : (and/c finite-real? (>=/c 0))
Schedules targets by scaled frozen distance from point, with the nearest resolved target at offset zero.

procedure

(radial-delay center scale) → delay-plan?

  center : vec2?
  scale : (and/c finite-real? (>=/c 0))
The radial spelling of a frozen-position distance delay.

procedure

(wave-delay direction wavelength phase) → delay-plan?

  direction : vec2?
  wavelength : positive-real?
  phase : finite-real?
Schedules targets by their frozen projection onto a nonzero direction. The lowest computed phase is normalized to offset zero.

procedure

(eager-stagger-map targets 
  make-request 
  [#:lag-ratio lag-ratio 
  #:order order]) 
 → lagged-start-animation-request?
  targets : (or/c list? vector?)
  make-request : procedure?
  lag-ratio : (and/c finite-real? (>=/c 0)) = 1/4
  order : (or/c 'forward 'reverse animation-order?) = 'forward
Eagerly maps make-request over a nonempty list or vector of targets, then returns the ordinary lagged-start composition of the requests it produces. make-request must accept either one argument target, or two arguments target and source-index. When both arities are accepted, Animate uses the two-argument form. The source index is the zero-based position in the original collection.

The factory runs exactly once per target, always in original source order. #:order 'reverse reverses only the completed child request list, so it changes stagger scheduling but never factory evaluation order or source indexes. #:order 'forward is the default. The factory must produce a valid ordinary composition child; its child-specific capability and conflict rules are preserved unchanged.

eager-stagger-map adds no scheduler node or timing vocabulary: its #:lag-ratio is passed directly to lagged-start. Therefore it has the same intrinsic-span scaling, exact finalization, conflict checking, and arbitrary-time sampling behavior as an explicitly written lagged-start tree. For example:

(eager-stagger-map targets
             (lambda (target source-index)
               (move-to target (vec2 (+ 2 source-index) 0)))
             #:lag-ratio 1/5
             #:order 'reverse)

procedure

(target-sequence? value) → boolean?

  value : any/c
Recognizes an immutable deferred target query.

procedure

(concrete-targets values) → target-sequence?

  values : (or/c list? vector?)
Creates an immutable target-sequence snapshot from an author-supplied collection. The collection spine is copied at construction; requests are still instantiated only when a semantic mapper resolves the sequence.

procedure

(children-of parent) → target-sequence?

  parent : (or/c visual? symbol? visual-path?)
Describes the direct children of a composite Visual at mapped local start.

procedure

(descendants-of root [#:where selector]) → target-sequence?

  root : (or/c visual? symbol? visual-path?)
  selector : (or/c #f procedure?) = #f
Describes depth-first source-order descendants of a composite Visual. The optional selector filters resolved Visual values without changing their source order.

procedure

(selection-targets selection) → target-sequence?

  selection : visual-selection?
Describes the stable absolute paths held by a semantic visual selection.

procedure

(target-ref? value) → boolean?

  value : any/c
Recognizes a resolved mapped target.

procedure

(target-ref-path reference) → (or/c #f visual-path?)

  reference : target-ref?
Returns the resolved stable target path when one is available.

procedure

(target-ref-source-index reference)

 → exact-nonnegative-integer?
  reference : target-ref?
Returns the query’s immutable source-order index.

procedure

(target-ref-scheduled-index reference)

 → exact-nonnegative-integer?
  reference : target-ref?
Returns the index assigned after the map’s order policy is resolved.

procedure

(procedure-request-template procedure    
  [#:name name]) → request-template?
  procedure : procedure?
  name : symbol? = 'procedure-template
Marks an in-process one-argument target-ref procedure as intentionally nonserializable. request-template-serializable? distinguishes template families; an arbitrary closure is never treated as project-serializable.

procedure

(named-request-template name) → request-template?

  name : symbol?
Creates a transparent serializable template reference. It contains no closure. Project/worker code must supply a trusted registered implementation for its name at compilation; ordinary in-process use should use procedure-request-template instead.

procedure

(request-template? value) → boolean?

  value : any/c
Recognizes a request template.

procedure

(request-template-serializable? value) → boolean?

  value : request-template?
Reports whether the template protocol marks a representation serializable.

procedure

(parallel-map targets    
  template    
  [#:order order]) → any/c
  targets : target-sequence?
  template : (or/c request-template? procedure?)
  order : (or/c 'forward 'reverse animation-order?) = 'forward
Creates a deferred semantic map whose resolved children share one local start.

procedure

(successive-map targets    
  template    
  [#:order order]) → any/c
  targets : target-sequence?
  template : (or/c request-template? procedure?)
  order : (or/c 'forward 'reverse animation-order?) = 'forward
Creates a deferred semantic map whose resolved children compile in succession; each child sees the exact endpoint state of the prior child.

procedure

(crossfade-subsets targets 
  make-entry 
  [#:exit-template make-exit 
  #:entry-duration entry-duration 
  #:hold-duration hold-duration 
  #:overlap overlap 
  #:order order 
  #:remove-final? remove-final?]) 
 → animation-group-animation-request?
  targets : (or/c list? vector?)
  make-entry : procedure?
  make-exit : procedure? = fade-out
  entry-duration : positive-real? = 1
  hold-duration : (and/c finite-real? (>=/c 0)) = 0
  overlap : (and/c finite-real? (>=/c 0)) = 0
  order : (or/c 'forward 'reverse animation-order?) = 'forward
  remove-final? : boolean? = #f
Creates an explicit one-at-a-time handoff. Entry i begins, remains for entry-duration, optionally holds for hold-duration, then its exit starts. Entry i+1 begins overlap before that exit ends. Thus #:overlap 0 is an exact non-overlapping handoff, while positive overlap is a deliberate crossfade. The final entry remains unless #:remove-final? is true. overlap may not exceed entry-duration.

procedure

(animation-order? value) → boolean?

  value : any/c
Recognizes an immutable order policy for collection-expansion helpers.

procedure

(forward-order) → forward-order?

Constructs the source order policy.

procedure

(forward-order? value) → boolean?

  value : any/c
Recognizes a forward order policy.

procedure

(reverse-order) → reverse-order?

Constructs the reverse source order policy.

procedure

(reverse-order? value) → boolean?

  value : any/c
Recognizes a reverse order policy.

procedure

(permutation-order indices) → permutation-order?

  indices : (or/c list? vector?)
Constructs an immutable explicit ordering. Indices must be distinct exact nonnegative integers. resolve-animation-order checks that the policy has exactly one in-range index for every target count before it is used.

procedure

(permutation-order? value) → boolean?

  value : any/c
Recognizes an explicit permutation order policy.

procedure

(shuffled-order [#:seed seed]) → shuffled-order?

  seed : exact-integer? = 0
Constructs a deterministic shuffle policy from an explicit exact-integer seed. It stores no random generator and never reads global random state.

procedure

(shuffled-order? value) → boolean?

  value : any/c
Recognizes a seeded shuffle order policy.

procedure

(resolve-animation-order order count) → vector?

  order : animation-order?
  count : exact-nonnegative-integer?
Resolves order into an immutable vector of source indices for exactly count targets. A policy can safely be reused with several counts when it remains valid for each one; explicit permutations report count/range errors instead of silently dropping or duplicating targets.