Document Reference

Document field reference

Scene documents are JSON data. Unknown fields are rejected, including misspelled optional fields. JSON cannot contain comments, functions, undefined, NaN or Infinity.

Root fields

Field	Required	Meaning and constraints
version	Yes	Exactly 1
spaces	Yes	Array of 1–32 space definitions
parameters	No	Map of declared identifiers to numeric initial values
events	No	Array of up to 2,000 top-level events; nested compositions are validated separately
duration	No	Nonnegative seconds; cannot end before the event timeline
theme	No	Document-wide theme defaults

The schema's structural limits do not replace semantic validation. For example, a tuple can pass the general array rule but have the wrong dimension for its space.

Names, references and shared values

Space names, object IDs and parameter names must match [A-Za-z_][A-Za-z_0-9]*: start with a letter or underscore, then use letters, digits or underscores. Space names are unique. Object IDs are unique within their space. Do not use expression-local variables, function names or constants as parameter names.

Object references use exactly space.object. Group children remain qualified object IDs rather than nested JSON object definitions. Point-component expressions add .x, .y or .z; arbitrary property access is not allowed.

• Scalar: a number or mathematical expression string of 1–2,000 characters. Only fields typed as scalar accept expressions.
• Coordinate: 1–3 scalar components, with the exact dimension determined by the space.
• Vec3: exactly three numeric Cartesian components; not expression strings.
• Range: two numeric endpoints. Sampling/camera ranges generally require increasing bounds.
• Color: # followed by six hexadecimal digits, such as #75dda5.

Event displacement/destination coordinates and numeric matrices have additional restrictions; do not assume every event field supports expressions just because object geometry does.

Space fields

Field	Required	Meaning
name	Yes	Unique space identifier
type	Yes	axis1d, plane2d, polar2d or space3d
objects	Yes	Array of up to 2,000 authored objects
axes	No	Boolean or array drawn from x, y, z; choose axes appropriate to the space
ticks	No	Show axis ticks; defaults to true
grid	No	Show the grid; defaults to true
camera	No	Initial camera configuration
theme	No	Overrides document theme values for this space

{
  "name": "solid",
  "type": "space3d",
  "axes": ["x", "y", "z"],
  "ticks": true,
  "grid": true,
  "camera": {
    "center": [0, 0, 0],
    "position": [7, -9, 7],
    "projection": "perspective",
    "scale": 60
  },
  "objects": [{"id": "cube", "type": "Cube", "size": 2}]
}

Initial camera fields

• center: numeric Cartesian Vec3 describing the view center. Canvas uses its x/y components.
• scale: positive number; initial pixels per unit for orthographic views, default 60.
• position: numeric Cartesian Vec3 for a 3D viewpoint; default [7, -9, 7].
• projection: perspective or orthographic; 3D defaults to perspective.

These describe initial/reset camera state. Use camera events for timeline choreography and the player's camera methods for inspection/reset. Mouse navigation maintains runtime camera offsets; it does not rewrite the authored document.

Common object fields

Field	Required	Meaning
id	Yes	Identifier unique within the space
type	Yes	One of the object types in the complete reference
position	No	Native-coordinate translation, separate from intrinsic geometry such as Point.at or Line.from/to
caption	No	Plain-text hover explanation, up to 10,000 characters
style	No	Object appearance fields below

Captions do not render HTML. A group's caption can supply a fallback for a child; an empty child caption suppresses it. Objects without captions have no tooltip. Rotation, scaling, visibility and animation state are controlled by supported events rather than arbitrary extra JSON fields.

Object style fields

Field	Constraint	Default behavior
color	Six-digit hex color	Uses the document/space object palette when not specified
opacity	Number from 0 to 1	Fully opaque before animation effects
fillOpacity	Number from 0 to 1	Closed paths normally use 0.15; specialized objects may choose another default
strokeWidth	Positive number	Normally 2 pixels in Canvas; native Three.js line width is platform-limited
pointSize	Positive number	Normally 5 pixels
fontSize	Positive number	Normally 20 pixels

Mesh visibility uses object opacity. A fill setting does not make an open stroke or stroke-only polygram into a filled shape.

Theme fields

background, foreground, axes and grid each accept a six-digit hex color. objectColors is a palette containing 1–100 hex colors. A space overrides the corresponding document theme fields; an explicit object color takes precedence over palette assignment.

{
  "background": "#10141d",
  "foreground": "#dbe3ee",
  "axes": "#79899f",
  "grid": "#283344",
  "objectColors": ["#58a6ff", "#75dda5", "#f4b66b"]
}

This fragment belongs in theme, not directly at the document root.

Drag binding fields

Field	Required	Meaning
parameter	Yes	Declared parameter to update
coordinate	No	Native Point coordinate index, 0–2; default 0, constrained by the space dimension
min	No	Numeric lower bound
max	No	Numeric upper bound

Only Point and PointOnCurve expose drag. A Point's bound coordinate must directly name the parameter. Other coordinates may depend on it, so dragging follows a constraint:

{
  "version": 1,
  "parameters": {"a": 1},
  "spaces": [{
    "name": "s",
    "type": "plane2d",
    "objects": [{
      "id": "handle",
      "type": "Point",
      "at": ["a", "a*a"],
      "drag": {"parameter": "a", "coordinate": 0, "min": -2, "max": 2}
    }]
  }]
}

A PointOnCurve binds its parameter field directly, typically with min 0 and max 1. Its value denotes normalized sampled arc length. Camera navigation is independent of parameter dragging.

Expression language

Real expressions support +, -, *, /, ^, parentheses, numeric literals, pi, e, declared parameters and global time t. Multiplication must be explicit.

Unary functions: sin, cos, tan, asin, acos, atan, sqrt, abs, exp, log, floor, ceil. Binary functions: min, max, atan2.

Local variables depend on the object:

• FunctionGraph: x.
• PolarGraph: theta.
• ParametricCurve: u.
• Surface: u, v.
• ImplicitFunction and Cartesian fields: coordinate variables such as x, y and, where applicable, z.
• Cartesian deformation mappings: point-coordinate variables and event-specific progress/time variables.

Complex mappings support z, i, pi, e, arithmetic and exp, log, sqrt, sin, cos, conj, abs, re, im. ComplexHomotopy additionally exposes alpha. Principal branches apply to complex logarithms, square roots and powers. Whole-space complex mappings can use live document parameters and t; deformation events have their own snapshot semantics, described in the animation reference.

An expression is not a general programming language: there are no statements, network calls, assignments, arbitrary methods or user-defined callbacks.

Layout and reference behavior

Matrices, charts and graph layouts expand into ordinary groups and child objects at compilation. Their generated IDs are stable, such as m_cell_0_0, g_vertex_a and g_edge_0. Avoid authoring IDs that collide with generated IDs. The compiled document contains expanded layouts and remains serializable.

Matrix rows must be rectangular, with at most 32 rows/columns and 512 cells. Cell dimensions are layout choices, not automatic text measurement. Graph explicit positions must cover its vertices; self loops and automatic force layout are unsupported. Graph edges follow their declared layout, not later independent vertex motion.

Geometry references, groups and curve targets have same-space restrictions. Cross-space point component expressions are the supported way to derive geometry from another space. Boolean operations work on supported closed planar paths; curved inputs are sampled and holes/disconnected components are preserved.

Images and browser resources

Image sources accept HTTP(S) URLs, relative URLs, or base64 PNG/JPEG/WebP/GIF data URLs. SVG and executable URL schemes are unsupported. Relative URLs resolve in the consuming page's context; the engine does not copy an app's images automatically.

The browser player preloads image resources before committing a scene. The loader bounds unique raster sources to 256 and aggregate decoded pixels to 64 million; each source has a loading timeout. ImageSequence accepts at most 128 source entries. A document can pass headless validation while failing browser loading if a referenced image is missing.

Image objects support affine 2D placement. They are not 3D textured meshes. MathTex uses KaTeX and needs the packaged stylesheet/fonts; invalid math resources can reject loading.

Evaluation output

evaluateDocument returns a DocumentFrame. This is evaluated state, not authored scene JSON.

Frame field	Meaning
time, duration	Current clamped time and total timeline length
parameters	Evaluated parameters with overrides applied
spaces	Evaluated SpaceFrames, including hidden spaces
activeSpace	Current active space name
layers	Space IDs and opacities used during view transitions
pictureInPictures	Evaluated inset view information
diagnostics	Recoverable evaluation messages with paths

Each SpaceFrame contains name, type, objects, resolved theme, camera steps and transforms. Camera steps describe authored choreography; use the browser player's camera methods for the user's current interactive view.

An ObjectFrame contains its qualified id, original/evaluated type, geometry, transform matrix, visible, opacity, reveal, color, style, and selected: false. Optional fields include caption, draggable, interactive, fillReveal, strokeRange and arrowScale.

Custom renderers should honor temporary frames with interactive: false without allowing them to intercept picking. Use fillReveal ?? reveal for separate fill progress, strokeRange for a stroke window and arrowScale for growing arrowheads. Release resources when temporary objects disappear after completion or seeking.

Geometry kinds are path, mesh, point, text, group and image. Geometry stores Cartesian points, with optional triangle indices, closed, disconnected-stroke breaks, polygon-ring polygons, dash, arrows, text, math, image source and viewport sampling metadata functionPlot. breaks identifies the starting point index of each separate stroke; never connect those contours with extra segments. Polygon ring groups preserve holes. Not every object creates a directly drawable geometry node; groups organize children.

Errors and limits

Structural schema errors and semantic compiler errors throw SceneValidationError with JSON-path diagnostics. Validation also covers native dimensions, missing references, cyclic dependencies, degenerate geometry and conflicting event writers. Resource preparation can fail separately in the browser.

Check frame diagnostics while evaluating parameter changes and seeking. A non-finite result should not be treated as valid geometry. Sampling and integration are numerical and bounded; increased resolution costs work and does not turn approximate geometry into symbolic mathematics.

---

Wiki home · Quick start