API Reference

Reads an EDN file and returns the scene map.

Renders a scene or animation. Single scene: (render scene) → BufferedImage (render scene {:output "out.png"}) → writes file, returns path (render scene {:format :svg}) → SVG string Animation (sequence of scenes): (render frames {:output "a.gif" :fps 30}) → animated GIF (render frames {:output "a.svg" :fps 30}) → animated SVG file (render frames {:output "dir/" :fps 30}) → PNG sequence (render frames {:format :svg :fps 30}) → animated SVG string Common opts: :scale, :transparent-background, :quality (JPEG), :dpi (PNG), :loop (GIF, default true), :prefix (frame sequence).

Renders a sequence of scenes to numbered PNG files in a directory. Returns a vector of written file paths. Opts: :scale, :transparent-background, :prefix (default "frame-").

Renders a sequence of export jobs to files. Each job is a map with :scene, :path, and optional :opts. Returns a vector of written paths. With a generator fn and count, calls (f i) for each index.

Reads an EDN scene file and renders it to a BufferedImage.

Renders a sequence of scenes to an animated SVG file. fps: frames per second. Opts: :scale, :transparent-background.

Renders a sequence of scenes to an animated SVG string using SMIL. fps: frames per second. Opts: :scale, :transparent-background.

Renders a scene and writes to file. Format detected from extension. Opts: :format, :quality (JPEG), :scale, :transparent-background, :dpi (PNG).

Renders a sequence of scenes to an animated GIF. fps: frames per second. Opts: :scale, :transparent-background, :loop (default true).

Renders a scene to an SVG XML string. Opts: :scale, :transparent-background.

Validates a scene map against the Eido scene spec. Returns nil if valid, or a vector of error maps with :path, :pred, :message, and :value.

Returns progress for n full cycles within [0, 1]. E.g., (cycle-n 2 0.5) completes one full cycle by midpoint.

Quadratic ease in: slow start, fast end. t in [0, 1].

Back ease in (overshoots then returns). t in [0, 1].

Bounce ease in. t in [0, 1].

Circular ease in. t in [0, 1].

Cubic ease in. t in [0, 1].

Elastic ease in. t in [0, 1].

Exponential ease in. t in [0, 1].

Quadratic ease in-out: slow start and end. t in [0, 1].

Back ease in-out. t in [0, 1].

Bounce ease in-out. t in [0, 1].

Circular ease in-out. t in [0, 1].

Cubic ease in-out. t in [0, 1].

Elastic ease in-out. t in [0, 1].

Exponential ease in-out. t in [0, 1].

Quartic ease in-out. t in [0, 1].

Quartic ease in. t in [0, 1].

Quadratic ease out: fast start, slow end. t in [0, 1].

Back ease out (overshoots then settles). t in [0, 1].

Bounce ease out. t in [0, 1].

Circular ease out. t in [0, 1].

Cubic ease out. t in [0, 1].

Elastic ease out. t in [0, 1].

Exponential ease out. t in [0, 1].

Quartic ease out. t in [0, 1].

Builds a vector of n frames by calling (f t) for each frame, where t is normalized progress [0.0, 1.0].

Linearly interpolates between a and b. t in [0, 1].

Converts linear progress to a value that goes 0 -> 1 -> 0. t in [0, 1], returns [0, 1].

Returns normalized progress [0.0, 1.0] for frame within total frames. Frame 0 returns 0.0, last frame returns 1.0.

Returns per-element progress for staggered animations. i: element index (0-based), n: total elements, t: global progress [0, 1], overlap: how much elements overlap (0 = sequential, 1 = all simultaneous). Returns local progress for element i, clamped to [0, 1].

Decreases lightness by amount (0-1). Accepts color vectors or maps.

Decreases saturation by amount (0-1). Accepts color vectors or maps.

Linearly interpolates between two colors. t in [0, 1]. Accepts color vectors or maps; returns a color vector.

Increases lightness by amount (0-1). Accepts color vectors or maps.

CSS Color Level 4 named colors mapped to [r g b] values.

Resolves a color vector to a map with :r :g :b :a keys.

Converts RGB (0-255 each) to [h s l] where h: 0-360, s: 0-1, l: 0-1.

Shifts hue by degrees (can be negative). Accepts color vectors or maps.

Increases saturation by amount (0-1). Accepts color vectors or maps.

Generates contour paths at iso-thresholds of a scalar field. noise-fn: (fn [x y opts] -> double). Returns a vector of :shape/path nodes. opts: :thresholds ([0.0]), :resolution (5), :noise-scale (0.01), :seed (0).

Places copies of shape at intervals along path-cmds. spacing: distance between placements. rotate?: if true, rotates shapes to follow path tangent. Returns a vector of group nodes with transforms.

Distorts path commands using the specified method. opts keys: :type (:noise, :wave, :roughen, :jitter) For :noise — :amplitude, :frequency, :seed For :wave — :axis (:x or :y), :amplitude, :wavelength For :roughen/:jitter — :amount, :seed

Generates path nodes from a noise-based flow field within bounds. Returns a vector of :shape/path nodes (streamlines). opts: :density (20), :step-length (2.0), :steps (50), :noise-scale (0.005), :seed (0), :min-length (3).

Converts a hatch fill spec to scene path nodes (lines). Each line becomes a path node with the specified stroke. Spec keys: :hatch/angle, :hatch/spacing, :hatch/stroke-width, :hatch/color, :hatch/layers [{:angle :spacing} ...].

Generates hatch line segments [x1 y1 x2 y2] within a bounding box. opts: :angle (degrees), :spacing (pixels between lines).

Rewrites axiom by applying rules for n iterations. Characters not in rules pass through unchanged.

Interprets an L-system string via turtle graphics. Returns scene-format path commands. Symbols: F=draw, G=move, +=turn right, -=turn left, [=push, ]=pop, |=reverse.

Full pipeline: expand axiom with rules, then interpret via turtle. Returns path commands.

Interpolates between two path command sequences at parameter t (0-1). Both must have the same number of commands and matching types.

Resamples both paths to matching point counts, then morphs at t. Works with any two closed or open paths.

Resamples path commands to exactly n evenly-spaced points. Flattens curves to line segments first.

Fractal Brownian motion — layers of noise at increasing frequency. noise-fn must accept (x y) or (x y opts) and return a double. Options: :octaves (4), :lacunarity (2.0), :gain (0.5), :seed.

2D Perlin noise. Returns a double in [-1, 1]. Optionally accepts {:seed n} for a seeded permutation table.

3D Perlin noise. Returns a double in [-1, 1]. Useful for animating noise (use time as z). Optionally accepts {:seed n}.

Ridged multifractal noise — inverts absolute value for sharp ridges. Same options as fbm, plus :offset (1.0).

Turbulence — fbm using absolute values of noise. Returns non-negative values. Same options as fbm.

Returns n colors spread evenly across a 60-degree arc centered on c.

Returns the complementary color (180 degrees opposite).

Interpolates through color stops at parameter t (0-1). stops: [[pos color] ...] sorted ascending by pos. Returns a color vector.

Returns n colors evenly interpolated between start and end.

Returns n colors with the same hue, varying lightness from dark to light.

Named palettes as vectors of color vectors.

Returns the base color plus two colors flanking its complement (±30°).

Returns 4 colors at 90-degree intervals (rectangle/square scheme).

Returns 3 colors evenly spaced at 120-degree intervals.

Confetti burst: colorful rectangles falling with gravity. Note: uses per-particle random colors from :particle/colors palette.

Fire effect: upward flames with orange-to-red color shift.

Fountain: upward spray arcing back down under gravity.

Renders a simulation state to a vector of Eido node maps. Optionally override the projection for this frame (useful for orbiting cameras). state: a simulation state from `states` config: the particle system configuration map opts: optional {:projection proj} to override :particle/projection for this frame

Runs a particle simulation and returns a lazy seq of node-vectors. Each element is a vector of Eido node maps ready for :image/nodes. config: particle system configuration map n: number of frames to produce opts: {:fps 30} — frames per second (determines time step) Returns a lazy seq of n vectors. Use vec to realize for indexed access.

Smoke: slow-rising, expanding, fading gray clouds.

Snowfall: gentle drift downward from a line emitter.

Sparks burst: bright, fast, short-lived points.

Runs a particle simulation and returns a lazy seq of raw simulation states. Each state contains :particles (internal particle maps with :pos, :vel, :age, etc.). Use this when you need per-frame control over rendering, e.g. orbiting cameras for 3D particles. Pair with render-frame to convert states to nodes. config: particle system configuration map n: number of frames to produce opts: {:fps 30} — frames per second (determines time step) Returns a lazy seq of n state maps.

Returns config with the emitter repositioned.

Returns config with a different seed.

Returns path commands for shape A minus shape B.

Returns path commands for the intersection of two shapes.

Returns path commands for the union of two shapes.

Returns path commands for the symmetric difference of two shapes.

Generates n nodes distributed evenly along a line from p1 to p2. f receives (x y t) where t is the normalized parameter [0.0, 1.0]. For n=1, places at the midpoint. For n>1, includes both endpoints.

Generates a vector of nodes by calling f for each cell in a cols x rows grid. f receives (col row) and must return a node map (or nil to skip). Cells are visited row-major: (0,0) (1,0) (2,0) ... (0,1) (1,1) ...

Creates a closed path node from a sequence of [x y] points.

Generates n nodes distributed evenly around a circle. f receives (x y angle) where angle is in radians [0, 2*pi). Angles start from the top (12 o'clock) and proceed clockwise.

Creates a closed regular n-sided polygon path node centered at [cx cy] with the given radius. First vertex is at the top (12 o'clock).

Creates a smooth path through a sequence of [x y] points using Catmull-Rom to cubic bezier conversion. Returns a path node.

Creates a closed star path node with n points centered at [cx cy]. outer-radius is the distance to the tips, inner-radius to the inner vertices.

Creates a text node rendered as vector paths.

Creates a group clipped to text outlines. Children are clipped to the text shape — anything inside the letters shows through.

Creates a per-glyph text node. glyph-overrides is a vector of maps, each with :glyph/index and optional :style/fill, :style/stroke, :node/transform, :node/opacity.

Creates text that follows a path. path-commands uses the same format as :shape/path — [[:move-to [x y]] [:curve-to ...] ...].

Returns text as a path node — the vector outline of the glyphs. Useful as a clip mask, for boolean ops, or as a standalone shape.

Creates layered text (e.g. shadow + outline + fill). layers is a vector of style maps applied to copies of the same text. Earlier layers render behind later ones.

Creates a triangle path node from three [x y] points.

Creates a 3D cone projected into 2D.

Returns a mesh approximating a cone at the origin. Base circle in the XZ plane at y=0, apex at [0 height 0]. radius: base radius. height: cone height. segments: number of sides.

Creates a 3D cube projected into 2D, returned as a :group node. projection: projection map. position: [x y z]. size: number. opts: :style, :light, :cull-back.

Returns a mesh of 6 quad faces for a unit cube at the origin, or a cube at position [x y z] with given size.

Creates a 3D cylinder projected into 2D.

Returns a mesh approximating a cylinder centered at the origin. segments: number of sides for the circular cross-section.

Sorts a mixed collection of nodes by :node/depth for correct 3D occlusion. Accepts any number of node collections — vectors of nodes, individual group nodes (from render-mesh), or single nodes. Groups are flattened into their children before sorting. All nodes are sorted smallest-depth-first (farthest from camera drawn first — painter's algorithm). Nodes without :node/depth are placed at the back. Returns a vector of sorted nodes ready for :image/nodes.

Extrudes a 2D polygon along a 3D vector. path-points: seq of [x y] (treated as [x, 0, y] in 3D space). direction: [dx dy dz] extrusion vector.

Converts a horizontal field-of-view angle (radians) to a perspective :distance value. half-width is half the viewport width in world-space units (typically screen-half-width / scale).

Creates an isometric projection map. opts: :scale (default 1.0), :origin [x y] (default [0 0]).

Returns a projection map oriented so the camera looks from eye toward target. Derives :yaw, :pitch, and :roll from the geometry. Preserves :type, :scale, :origin, and :distance from base-projection. up: world up vector (default [0 1 0]).

Creates a face map from a sequence of 3D vertices. Computes the normal automatically from the first three vertices.

Combines multiple meshes into a single mesh (vector of faces). Each argument is either a bare mesh (vector of faces) or a [mesh style] pair, where style is applied to every face in that mesh.

Returns the axis-aligned bounding box of a mesh as {:min [x y z] :max [x y z]}.

Returns the center point of a mesh's bounding box.

Returns a projection with the camera orbiting target at the given radius. yaw: horizontal orbital angle (radians). pitch: vertical angle (radians). At yaw=0 pitch=0, camera is at +Z relative to target (consistent with the default camera convention).

Creates an orthographic projection map. opts: :scale, :origin, :yaw (radians), :pitch (radians).

Creates a perspective projection map. opts: :scale, :origin, :yaw, :pitch, :distance.

Creates a 3D prism projected into 2D.

Returns a mesh for a prism: a 2D polygon base extruded along the Y axis. base-points: seq of [x y] for the base (in the XZ plane). height: extrusion distance along the Y axis.

Projects a mesh and returns a :group node with faces sorted back-to-front. Each face becomes a :shape/path node. opts: :style - default style {:style/fill [...] :style/stroke {...}} :light - light map for diffuse shading (optional) :cull-back - if true, omit back-facing polygons (default true) :wireframe - if true, render edges only (no fill, no shading)

Rotates all vertices and normals in a mesh around the given axis. axis: :x, :y, or :z. angle: radians.

Scales all vertices in a mesh. factor is a number (uniform) or [sx sy sz].

Creates a 3D sphere projected into 2D.

Returns a mesh approximating a sphere at the origin. segments: longitude slices, rings: latitude bands.

Creates 3D extruded text projected into 2D, returned as a :group node. projection: projection map. content: string. font-spec: font map. depth: extrusion depth. opts: same as render-mesh plus :flatness. The mesh is centered at the origin for natural rotation. Front/back caps use even-odd fill to correctly render letter holes.

Creates side-wall faces for extruded text (no caps). content: string. font-spec: font map. depth: extrusion depth along Y axis. opts: :flatness (curve approximation, default 1.0).

Creates a 3D torus projected into 2D.

Returns a mesh approximating a torus at the origin. R: major radius (center of tube to center of torus). r: minor radius (tube cross-section). ring-segments: divisions around the ring. tube-segments: divisions around the tube.

Translates all vertices in a mesh by offset [dx dy dz].

Generates a regular grid of [x y] positions within bounds.

Generates up to n positions biased by noise density. Points are placed where noise value exceeds a threshold.

Generates well-distributed points via Poisson disk sampling. Delegates to eido.stipple/poisson-disk.

Creates positioned group nodes from a shape and positions. jitter: nil or {:x dx :y dy :seed s} for random displacement.

Generates well-distributed points via Poisson disk sampling. Returns a vector of [x y] within [bx, bx+bw] x [by, by+bh]. min-dist: minimum distance between points. seed: for determinism.

Generates circle nodes for a stipple fill within bounds. spec: :stipple/density (0-1), :stipple/radius, :stipple/seed, :stipple/color.

Generates path commands for a variable-width stroke outline. path-cmds: scene-format path commands ([:move-to [x y]] ...) profile: keyword or [[t width-factor] ...] pairs max-width: the maximum stroke width (profile scales this)

Resolves a profile keyword to a vector of [t width-factor] pairs, or passes through a vector.

Linearly interpolates width from a profile at parameter t (0..1). Profile is a vector of [t width] pairs, sorted by t.

Merges overrides onto a vector of child group nodes. Each override map is merged onto the first child of the group at index i. Wraps via mod when overrides is shorter than children.

Generates n fill overrides interpolated through gradient stops. stops: [[pos color] ...] for palette/gradient-map.

Generates n overrides by calling (f i) for each index 0..n-1. f should return a map of node attribute overrides.

Generates overrides from Perlin noise sampled at each position. Calls (f noise-value) where noise-value is in [-1, 1].

Generates overrides by calling (f x y) for each [x y] position. f should return a map of node attribute overrides.

Generates Delaunay triangulation edges as line nodes. Derived from Voronoi: two seeds are neighbors if their cells share an edge.

Generates Voronoi cell polygons from seed points. Returns a vector of :shape/path nodes (closed polygons), one per point. Uses half-plane intersection: O(n^2) per cell.

Applies a warp transformation to path commands.

Recursively warps a node tree. Converts primitives to paths, then warps.