70 Projects and Final Rendering

9.3

Racket

70 Projects and Final Rendering🔗ℹ

An animate-project? is the one immutable declaration shared by final rendering and project preview. It separates a pure configuration plan from effectful preparation and execution.

procedure
(animate-project #:id id
#:source source
[ #:render render
#:preview preview
#:output output
#:encoder encoder
#:cache cache
#:assets assets
#:metadata metadata]) → animate-project?
  id : symbol?
   source :
(or/c module-binding-source? scene-source?
       timeline-source? scene-program-source?
       module-builder-source?)
  render : render-spec? = (render-spec)
  preview : preview-spec? = (preview-spec)
  output : output-spec? = (output-spec)
  encoder : encoder-spec? = (encoder-spec)
  cache : cache-spec? = (cache-spec)
  assets : (listof project-asset?) = '()
  metadata : hash? = #hasheq()

Creates one immutable project declaration. The constructor snapshots lists and hashes, so later caller mutation cannot change the project.

procedure
(animate-project? value) → boolean?
value : any/c

Recognizes an immutable project declaration.

procedure
(animate-project-render project) → render-spec?
project : animate-project?

Returns the immutable final-render specification stored in the project.

procedure
(module-binding-source module-path binding)
→ module-binding-source?
module-path : path-string?
binding : symbol?

Declares a reloadable source suited to project workers and persistent caches.

procedure
(module-binding-source? value) → boolean?
value : any/c

Recognizes a reloadable module binding source.

procedure
(module-builder-source module-path
binding
[ #:options options
#:prepare prepare
#:seed seed])
→ module-builder-source?
  module-path : path-string?
  binding : symbol?
  options : hash? = #hasheq()
  prepare : (or/c symbol? #f) = #f
  seed : source-build-seed? = 0

Declares a restartable source that a fresh process can rebuild by loading one module export. The binding export accepts exactly a build context, a copied immutable options map, and either #f or the completed preparation payload. #:prepare, when supplied, names an export that accepts the context and options and returns source-preparation?. Planning normalizes this declaration but does not load either export.

procedure
(module-builder-source? value) → boolean?
value : any/c

Recognizes a module-builder source.

procedure
(module-builder-source-module-path source) → path-string?
source : module-builder-source?

Returns the declared module path.

procedure
(module-builder-source-binding source) → symbol?
source : module-builder-source?

Returns the fixed builder export name.

procedure
(module-builder-source-options source) → immutable?
source : module-builder-source?

Returns the copied immutable builder options map.

procedure
(module-builder-source-prepare source) → (or/c symbol? #f)
source : module-builder-source?

Returns the optional preparer export name.

procedure
(module-builder-source-seed source) → source-build-seed?
source : module-builder-source?

Returns the deterministic builder seed.

procedure
(source-build-seed? value) → boolean?
value : any/c

Recognizes an exact nonnegative seed accepted by the selected Racket CS random-seed API. The current accepted range is 0 through 2147483647; invalid seeds are rejected rather than truncated.

procedure
(source-transfer-data? value) → boolean?
value : any/c

Recognizes the bounded acyclic data representation for builder options and preparation values. It accepts finite reals, booleans, symbols, keywords, characters, strings, bytes, pairs, vectors, and hashes, copying containers and mutable leaves into immutable values. Procedures, ports, bitmap/native values, cycles, and oversized or deeply nested values are rejected.

procedure
(source-preparation [ #:payload payload
#:artifacts artifacts
#:dependencies dependencies
#:frame-reuse frame-reuse
#:diagnostics diagnostics])
→ source-preparation?
  payload : source-transfer-data? = #f
  artifacts : list? = '()
  dependencies : list? = '()
  frame-reuse : (or/c source-transfer-data? #f) = #f
  diagnostics : hash? = #hasheq()

Creates immutable data returned by a module preparer. Payloads should be versioned adapter data rather than a scene or callback. Large assets belong in completed artifact files identified by the small artifact manifest.

procedure
(source-preparation? value) → boolean?
value : any/c

Recognizes completed shared source preparation.

procedure
(source-preparation-payload value) → source-transfer-data?
value : source-preparation?

Returns the builder payload.

procedure
(source-preparation-artifacts value) → list?
value : source-preparation?

Returns completed artifact descriptions.

procedure
(source-preparation-dependencies value) → list?
value : source-preparation?

Returns additional declared source/input identities.

procedure
(source-preparation-frame-reuse value)
→ (or/c source-transfer-data? #f)
value : source-preparation?

Returns optional domain-owned frame-reuse data.

procedure
(source-preparation-diagnostics value) → hash?
value : source-preparation?

Returns immutable preparation evidence.

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

Recognizes the immutable construction context supplied to module preparers and builders. It contains only construction-relevant configuration; worker count, PID, batch assignment, retry identity, and staging paths are intentionally absent.

procedure
(source-build-context-module-path context) → string?
context : source-build-context?

Returns the normalized source location.

procedure
(source-build-context-binding context) → symbol?
context : source-build-context?

Returns the selected builder binding.

procedure
(source-build-context-options context) → immutable?
context : source-build-context?

Returns copied builder options.

procedure
(source-build-context-asset-base context) → string?
context : source-build-context?

Returns the stable source-relative asset base.

procedure
(source-build-context-assets context) → list?
context : source-build-context?

Returns normalized declared asset descriptors.

procedure
(source-build-context-width context) → exact-positive-integer?
context : source-build-context?

Returns target raster width.

procedure
(source-build-context-height context) → exact-positive-integer?
context : source-build-context?

Returns target raster height.

procedure
(source-build-context-camera-policy context)
→ source-transfer-data?
context : source-build-context?

Returns the explicit or scene-camera construction policy.

procedure
(source-build-context-theme context) → color-theme?
context : source-build-context?

Returns the complete selected colour theme snapshot.

procedure
(source-build-context-typography context) → typography-theme?
context : source-build-context?

Returns the complete selected typography snapshot.

procedure
(source-build-context-fps context) → exact-positive-integer?
context : source-build-context?

Returns the semantic frame rate.

procedure
(source-build-context-quality context) → symbol?
context : source-build-context?

Returns the declared semantic quality setting.

procedure
(source-build-context-seed context) → source-build-seed?
context : source-build-context?

Returns the scoped random seed.

procedure
(source-build-context-base-fingerprint context) → string?
context : source-build-context?

Returns the pre-preparation construction identity. Worker count and worker mode do not affect it.

procedure
(source-build-context-preparation context)
→ (or/c source-preparation? #f)
context : source-build-context?

Returns completed preparation for a builder, or #f while a preparer runs.

procedure
(scene-source scene) → scene-source?
scene : scene?

Declares an in-memory Scene source for local planning and preview.

procedure
(scene-source? value) → boolean?
value : any/c

Recognizes a direct Scene source.

procedure
(timeline-source timeline) → timeline-source?
timeline : authored-timeline?

Declares an in-memory authored timeline source.

procedure
(timeline-source? value) → boolean?
value : any/c

Recognizes a direct timeline source.

procedure
(scene-program-source program) → scene-program-source?
program : scene-program?

Declares an in-memory source-program source.

procedure
(scene-program-source? value) → boolean?
value : any/c

Recognizes a direct source-program source.

procedure
(render-spec [ #:fps fps
#:width width
#:height height
#:renderer3d renderer3d
#:supersample supersample
#:workers workers
#:worker-mode worker-mode
#:theme theme
#:typography typography]) → render-spec?
  fps : exact-positive-integer? = 30
  width : exact-positive-integer? = 1280
  height : exact-positive-integer? = 720
  renderer3d : any/c = 'software
  supersample : exact-positive-integer? = 1
  workers : exact-positive-integer? = 1
  worker-mode : (or/c 'auto 'in-process 'subprocess) = 'auto
  theme : color-theme? = animate-light-theme
  typography : typography-theme? = animate-typography-theme

Describes final raster quality. Renderer and camera fields have defaults too; see render-spec in the contract reference for the complete set. #:renderer3d is 'software by default. Passing an explicit opengl-renderer3d-spec selects the optional Racket/OpenGL backend for final project rendering; it requires Racket 9.3 gracket and #:workers 1. OpenGL is not loaded merely by constructing this immutable project declaration. }

procedure
(render-spec? value) → boolean?
value : any/c

Recognizes a final-render configuration.

procedure
(render-spec-workers specification) → exact-positive-integer?
specification : render-spec?

Returns the requested worker capacity for final frame rendering. This is a capacity request, not a prediction of speedup or a guarantee that every worker will start.

procedure
(render-spec-worker-mode specification)
→ (or/c 'auto 'in-process 'subprocess)
specification : render-spec?

Returns the requested final-worker mode. In 'auto, a restartable module source uses local execution for one worker and selects future subprocess execution for more than one; direct in-memory sources with more than one worker are rejected unless they explicitly choose 'in-process. PR-A resolves this policy but does not yet start final-render worker processes.

procedure
(resolve-render-worker-policy source
render) → render-worker-policy?
   source :
(or/c module-binding-source? module-builder-source?
      scene-source? timeline-source? scene-program-source?)
  render : render-spec?

Purely resolves a source/render declaration into an execution policy. It rejects unsupported subprocess combinations before a project loads a source or mutates an output path. The initial subprocess policy accepts only software rendering, the default renderer set, and bounded renderer options.

procedure
(render-worker-policy? value) → boolean?
value : any/c

Recognizes a pure worker-policy decision.

procedure
(render-worker-policy-requested-mode policy)
→ (or/c 'auto 'in-process 'subprocess)
policy : render-worker-policy?

Returns author intent.

procedure
(render-worker-policy-resolved-mode policy)
→ (or/c 'in-process 'subprocess)
policy : render-worker-policy?

Returns the selected executor kind.

procedure
(render-worker-policy-restartable? policy) → boolean?
policy : render-worker-policy?

Reports whether the source can be reconstructed from a declaration.

procedure
(render-worker-policy-reason policy) → symbol?
policy : render-worker-policy?

Returns the deterministic resolution reason.

procedure
(render-spec-theme specification) → color-theme?
specification : render-spec?

Returns the complete immutable theme snapshot selected for final rendering. The project plan records its canonical datum, appearance fingerprint, resolver version, and provenance, so replay does not depend on a locally named palette.

procedure
(render-spec-typography specification) → typography-theme?
specification : render-spec?

Returns the immutable semantic text snapshot selected for final rendering. Its canonical datum, appearance fingerprint, and resolver version participate in project and section-cache identity because typography can change text geometry.

procedure
(render-spec-with-theme specification
theme) → render-spec?
specification : render-spec?
theme : color-theme?

Returns a copy with only the selected theme changed. This is useful for an explicit command-line or build-system appearance override; raster dimensions, renderers, worker policy, and quality remain unchanged.

procedure
(render-spec-with-typography specification
typography) → render-spec?
specification : render-spec?
typography : typography-theme?

Returns a copy with only the typography snapshot changed. This is explicit render configuration; raw text constructors remain unaffected.

procedure
(preview-spec [ #:fps fps
#:pixel-scale pixel-scale
#:cache-megabytes cache-megabytes
#:prefetch prefetch
#:audio? audio?])
→ preview-spec?
  fps : exact-positive-integer? = 30
  pixel-scale : positive? = 1
  cache-megabytes : exact-positive-integer? = 512
  prefetch : exact-nonnegative-integer? = 3
  audio? : boolean? = #f

Describes preview quality, a 512 MiB default bitmap-cache budget, and optional audio monitoring.

procedure
(preview-spec? value) → boolean?
value : any/c

Recognizes a preview configuration.

The raco animate command accepts the global prefix options –theme animate-light, –theme animate-dark, or –theme-file PATH before plan, render, or preview. The two options are mutually exclusive. A theme file contains the versioned datum accepted by datum->theme; it is read as data rather than evaluated. Its digest and decoded snapshot become part of the prepared render identity, so workers never reread the file midway through a render.

procedure
(output-spec [ #:root root
#:name name
#:format format
#:overwrite-policy overwrite-policy])
→ output-spec?
  root : path-string? = "media"
  name : string? = "animation"
  format : (or/c 'mp4 'png-sequence) = 'mp4
  overwrite-policy : (or/c 'error 'replace) = 'error

Declares final artifact naming. Planning determines exact artifact paths without creating their parent directories.

procedure
(output-spec? value) → boolean?
value : any/c

Recognizes an output declaration.

procedure
(encoder-spec [ #:codec codec
#:pixel-format pixel-format
#:options options
#:audio-codec audio-codec
#:audio-options audio-options
#:fast-start? fast-start?]) → encoder-spec?
  codec : symbol? = 'h264
  pixel-format : symbol? = 'yuv420p
  options : hash? = #hasheq()
  audio-codec : symbol? = 'aac
  audio-options : hash? = #hasheq()
  fast-start? : boolean? = #t

Declares video and audio encoder settings independently of frame rendering.

procedure
(encoder-spec? value) → boolean?
value : any/c

Recognizes a video/audio encoder declaration.

procedure
(cache-spec [ #:root root
#:policy policy
#:max-bytes max-bytes
#:domains domains]) → cache-spec?
  root : path-string? = ".animate-cache"
  policy : symbol? = 'read-write
  max-bytes : exact-nonnegative-integer? = (* 1024 1024 1024)
   domains : (listof symbol?)
= '(formula frames segments audio waveform source-program)

Declares domain-specific cache policy. Encoder settings affect segment caches, not frame caches; audio changes do not invalidate visual frames.

procedure
(cache-spec? value) → boolean?
value : any/c

Recognizes a cache declaration.

procedure
(project-asset path
[ #:role role
#:metadata metadata]) → project-asset?
  path : path-string?
  role : symbol? = 'visual
  metadata : hash? = #hasheq()

Declares a visual, audio, formula, or author-defined asset.

procedure
(project-asset? value) → boolean?
value : any/c

Recognizes a declared project asset.

procedure
(project-target-section name) → project-target?
name : symbol?

Selects one authored section.

value
project-target-all : project-target?

Selects the complete declared source.

procedure
(project-target? value) → boolean?
value : any/c

Recognizes a project target.

procedure
(plan-project project
[ #:target target
#:directory directory]) → project-plan?
  project : animate-project?
  target : project-target? = (project-target-all)
  directory : path-string? = (current-directory)

Normalizes the declaration and produces exact output/cache paths without reading source files, locating tools, creating directories, or rendering.

procedure
(project-plan? value) → boolean?
value : any/c

Recognizes an immutable pure project plan.

procedure
(prepare-project! plan) → prepared-project?
plan : project-plan?

Loads the declared source, validates its type and selected target, fingerprints inputs/tools, and determines frame indices. Preparation may read files and tools but does not render frames or create final artifacts. For a module-builder-source with #:prepare, the preparer runs once in this parent-side operation. Its bounded payload and completed artifact manifest are then verified when a fresh worker reconstructs the builder; a worker does not invoke the preparer again.

procedure
(prepare-project-label-layout3d
project
#:view view-id
[ #:frames frames
#:target target
#:switch-penalty switch-penalty
#:movement-penalty movement-penalty])
→ prepared-label-layout3d?
  project : animate-project?
  view-id : symbol?
  frames : (or/c #f (listof exact-nonnegative-integer?)) = #f
  target : project-target? = (project-target-all)
  switch-penalty : nonnegative-real? = 0
  movement-penalty : nonnegative-real? = 0

Prepares one view3d’s projected-label trajectory using the project target’s source-frame grid, output camera, raster dimensions, renderer list, and supersampling policy. With #:frames #f, it uses the selected target’s frames. The immutable result is safe to share read-only with render workers. Pass it to a project render operation as #:prepared-label-layout; its selected placement boxes become part of the frame-cache identity.

This is an explicit preparation operation: ordinary project rendering keeps direct per-frame layout unless the author supplies a table. Preparation measures 2D templates without constructing an optional live OpenGL renderer.

procedure
(prepared-project? value) → boolean?
value : any/c

Recognizes an effectfully prepared but unrendered project.

procedure
(prepared-project-source-build-context prepared)
→ (or/c source-build-context? #f)
prepared : prepared-project?

Returns the context actually supplied to a module builder, or #f for a direct or module-value source.

procedure
(prepared-project-source-preparation prepared)
→ (or/c source-preparation? #f)
prepared : prepared-project?

Returns completed shared preparation retained for a module builder, if one was declared.

procedure
(prepared-project-input-manifest prepared) → immutable?
prepared : prepared-project?

Returns the bounded local-input snapshot for a restartable module source. The executor checks the represented module/dependency and declared asset contents before child startup, after child readiness, and before publication. It is an inspection value; callers should not treat it as an editable cache API.

procedure
(prepared-project-preparation-manifest prepared)
→ (or/c immutable? #f)
prepared : prepared-project?

Returns the parent-to-worker preparation handoff for a prepared module builder, or #f when no preparer was declared. Path-bearing artifacts are content-identified files under the source asset root; invalid or changed artifacts cause execution to fail before a worker accepts final frames.

procedure
(prepared-project-preparation-elapsed-milliseconds prepared)
→ nonnegative-real?
prepared : prepared-project?

Returns the parent-observed elapsed time spent loading and preparing the restartable source. It is reported separately from worker startup and frame rasterization.

procedure
(prepared-project-worker-policy prepared)
→ render-worker-policy?
prepared : prepared-project?

Returns the policy resolved before source loading.

procedure
(check-project! plan) → project-check-report?
plan : project-plan?

Prepares a project only far enough to validate its declared source, assets, tools, target, and renderer capabilities. It writes no frames or output artifacts. The immutable report separates required failures from optional warnings, so it is suitable for a command-line or preview diagnosis.

procedure
(project-check-report? value) → boolean?
value : any/c

Recognizes an immutable project-validation report.

procedure
(project-plan->datum plan) → immutable-hash?
plan : project-plan?

Returns a serializable inspection representation of a pure plan.

Use execute-prepared-project! from animate/render to run a prepared plan. It produces an immutable execution report after frame rendering, encoding, and optional media assembly, and installs final artifacts atomically.

Limitation: direct Scene, timeline, and program sources may contain arbitrary procedures. They are valid for an in-memory session but cannot have an honest persistent fingerprint unless the author supplies an explicit key.

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