API Reference

Controls whether scene validation runs before compilation.
Defaults to true. Bind to false in REPL/watch workflows for faster
re-renders. The show and watch-* dev helpers automatically skip
validation after the first successful render.

Validates a scene and prints human-readable errors to *out*.
Returns the error vector, or nil if valid.

Formats validation errors as a human-readable string.
Takes a vector of error maps as returned by validate.

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
(render scene {:format :dxf}) → DXF R12 string
(render scene {:format :gcode}) → GRBL G-code string
(render scene {:format :hpgl}) → HPGL plotter string
(render scene {:format :polylines}) → {:polylines [...] :bounds [w h]}

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/TIFF),
:tiff/compression (:lzw :deflate :none),
:loop (GIF, default true), :prefix (frame sequence).

Validation: scenes are validated before compilation by default. Bind
*validate* to false for faster REPL iteration, or set :eido/validate
false on the scene map.

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.

Reads a manifest EDN file and re-renders the scene using stored options.
Override keys in opts to change output path, format, etc.

Renders a sequence of scenes to an animated SVG file.
Opts: :fps (required), :scale, :transparent-background.

Renders a sequence of scenes to an animated SVG string using SMIL.
Opts: :fps (required), :scale, :transparent-background.

Renders a scene and writes to file. Format detected from extension.
Supported formats: PNG, JPEG, GIF, BMP, TIFF, SVG, DXF, G-code, HPGL.
Opts: :format, :quality (JPEG), :scale, :transparent-background,
:dpi (PNG/TIFF), :tiff/compression (:lzw :deflate :none),
:emit-manifest? (write EDN sidecar for reproducibility).
DXF/G-code/HPGL also accept :flatness, :segments, :optimize-travel,
and any writer-specific keys (see eido.io.dxf, eido.io.gcode,
eido.io.hpgl).

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

Renders a scene to an SVG XML string.
Opts: :scale, :transparent-background, :stroke-only, :group-by-stroke,
:deduplicate, :optimize-travel.

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.

Chaikin corner-cutting smoothing on path commands.
Produces rounder, more uniform curves than Catmull-Rom.
opts: :iterations (3), :retain-ends (true).

Tests whether a point [px py] is inside a polygon [[x y] ...].
Uses the ray-casting algorithm (count horizontal ray crossings).

Breaks path commands into dashed segments.
opts: :dash [on-length off-length] — required
:offset (0.0) — shift the pattern start
Returns a vector of path-command vectors, one per dash.

Places copies of shape at intervals along path-cmds.
opts: :spacing (required), :rotate? (default false).
Returns a vector of group nodes with transforms.

Returns path commands for shape A minus shape B.

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

Returns stylize steps for ink-stroke aesthetics.
Moderate Chaikin smoothing with organic jitter.

Shrinks a closed polygon inward by distance d.
Returns a vector of [[x y] ...] points.
Works correctly for convex polygons; concave polygons may produce
self-intersecting results.

Blends between two paths at parameter t (0-1).
Both paths must have the same number and type of commands.
Returns blended path commands.

Returns path commands for the intersection of two shapes.

Adds organic jitter to path commands.
Resamples for uniform point density, then applies jitter distortion.
opts: :amount (3.0), :density (1.0) — approximate spacing between points,
:seed (0)

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.

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)

Returns stylize steps for pencil-line aesthetics.
Light smoothing, fine jitter, short dashes for sketch feel.

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

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

Converts a primitive shape node to path commands.

Douglas-Peucker path simplification on [[x y] ...] point vectors.
Removes points that contribute less than epsilon to the shape.

Douglas-Peucker simplification on path commands.
Wraps simplify on the extracted points and rebuilds commands.

Smooths path commands by resampling and fitting Catmull-Rom curves.
opts: :samples (32) — resample count before fitting.

Splits path commands into segments of approximately equal arc-length.
Returns a vector of path-command vectors, one per segment.

Applies path aesthetic transforms described as data.
Wraps smooth-commands, jittered-commands, dash-commands, chaikin-commands.
steps: vector of {:op :smooth/:jitter/:dash/:chaikin, ...opts}.
Example: (stylize cmds [{:op :chaikin :iterations 3} {:op :dash :dash [10 5]}])

Clips path commands to a bounding rectangle.
bounds: [x y w h] clipping region.
Returns a vector of path-command vectors (one per visible segment).
Flattens curves to line segments before clipping.

Returns path commands for the union of two shapes.

Applies a warp transformation to path commands.

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

Returns stylize steps for watercolor-edge aesthetics.
Heavy Chaikin smoothing with pronounced jitter for bleeding edges.

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

Returns path commands for the symmetric difference of two shapes.

Creates a circle node. Shorthand for the {:node/type :shape/circle ...} map.
Example: (circle-node [200 200] 50 [:color/name "red"])

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 line node. Shorthand for the {:node/type :shape/line ...} map.
stroke is a map with :color and :width keys.
Example: (line-node [0 0] [100 100] {:color [:color/name "black"] :width 2})

Returns a base scene map for a named paper size.
Keyword args: :landscape (false), :dpi (300).
The returned map includes :image/size, :image/units, and :image/dpi —
pass through with-units before rendering.

Example:
(paper :a4) ;=> {:image/size [21.0 29.7] :image/units :cm :image/dpi 300}
(paper :letter :landscape true) ;=> {:image/size [11.0 8.5] :image/units :in :image/dpi 300}

Standard paper sizes as [width height unit] triples.
Width and height are in the specified unit.

Converts [x y] points to path commands.
Convenience for (into [[:move-to p0]] (mapv (fn [p] [:line-to p]) rest)).

Converts polar coordinates to [x y].
Wraps the trig: (+ cx (* r (cos a))), (+ cy (* r (sin a))).

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 rect node. Shorthand for the {:node/type :shape/rect ...} map.
Example: (rect-node [10 10] [100 50] [:color/name "blue"])

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).

Places n copies of shape in a circle. Returns a vector of translated nodes.
Convenience for (radial n [cx cy] radius (fn [x y _] shape-with-translate)).

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.

Wraps a scene's nodes in a group clipped to an inset rectangle.
Margin is the distance in pixels from each edge.
Uses existing :group/clip infrastructure — no new rendering machinery.

Converts a scene described in real-world units to pixel coordinates.
Reads :image/units (:cm, :mm, or :in) and :image/dpi from the scene,
walks the scene tree scaling all spatial values by the conversion factor.
Strips :image/units from the result; retains :image/dpi for metadata embedding.
The core rendering pipeline remains pixel-based — this is a preprocessing step.

Example:
(-> (paper :a4)
(assoc :image/background :white
:image/nodes [...])
with-units)

Approximates curves as line segments. flatness controls subdivision.

Splits path commands into separate closed contours.
Returns [[cmd ...] [cmd ...] ...], one vector per contour.

Returns total arc length of path commands.

Returns {:point [x y] :angle rad} at a given distance along path commands.

Resolves a font-spec map to a java.awt.Font. Memoized.

Converts a string + font-spec to per-glyph path data.
Returns [{:commands [...] :position [x y]} ...], one entry per glyph.
Commands are relative to each glyph's own origin (not layout position).
:position gives the glyph's layout position within the string.

Converts a string + font-spec to Eido path commands for the entire text.
Returns at the origin [0 0]; caller positions via :text/origin.

Returns the total advance width of text rendered with the given font-spec.

Expands a :shape/text-glyphs node into a :group with one :shape/path per glyph.

Expands a :shape/text node into a :group with a single :shape/path child.

Expands a :shape/text-on-path node into a :group with glyphs along a path.

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.

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

Converts a primitive shape node to path commands.

Applies a warp transformation to path commands.

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

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.

Places copies of shape at intervals along path-cmds.
opts: :spacing (required), :rotate? (default false).
Returns a vector of group nodes with transforms.

Chaikin corner-cutting smoothing on path commands.
Produces rounder, more uniform curves than Catmull-Rom.
opts: :iterations (3), :retain-ends (true).

Breaks path commands into dashed segments.
opts: :dash [on-length off-length] — required
:offset (0.0) — shift the pattern start
Returns a vector of path-command vectors, one per dash.

Returns stylize steps for ink-stroke aesthetics.
Moderate Chaikin smoothing with organic jitter.

Adds organic jitter to path commands.
Resamples for uniform point density, then applies jitter distortion.
opts: :amount (3.0), :density (1.0) — approximate spacing between points,
:seed (0)

Returns stylize steps for pencil-line aesthetics.
Light smoothing, fine jitter, short dashes for sketch feel.

Smooths path commands by resampling and fitting Catmull-Rom curves.
opts: :samples (32) — resample count before fitting.

Applies path aesthetic transforms described as data.
Wraps smooth-commands, jittered-commands, dash-commands, chaikin-commands.
steps: vector of {:op :smooth/:jitter/:dash/:chaikin, ...opts}.
Example: (stylize cmds [{:op :chaikin :iterations 3} {:op :dash :dash [10 5]}])

Returns stylize steps for watercolor-edge aesthetics.
Heavy Chaikin smoothing with pronounced jitter for bleeding edges.

WCAG 2.0 luminance contrast ratio between two colors.
Returns a double >= 1.0 (1 = identical, 21 = black/white).
Accepts any color form (vectors, keywords, maps).

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

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

Shorthand for [:color/hsl h s l]. Wraps hue with mod 360.

Linearly interpolates between two colors. t in [0, 1].
Accepts color vectors or maps; returns a color vector.
Optional opts map: {:space :oklab} for perceptually uniform interpolation.

Interpolates between two colors in OKLAB space. t in [0, 1].
Wraps (lerp color-a color-b t {:space :oklab}).

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

Mixes two colors subtractively, simulating how real paint pigments blend.
Blue + yellow = green, red + blue = purple, etc.

color-a, color-b: [r g b] in linear RGB [0..1] float space.
t: mix ratio (0.0 = all color-a, 1.0 = all color-b).

Uses a reflectance multiplication model: pigments absorb light,
so mixing pigments multiplies their reflectance spectra. Approximated
by geometric mean: result_ch = a_ch^(1-t) * b_ch^t.

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

Shorthand for [:color/oklab L a b].

Shorthand for [:color/oklch L C h].

OKLAB deltaE — Euclidean distance in OKLAB perceptual color space.
Returns a double >= 0.0 (0 = identical colors).
More perceptually meaningful than RGB distance.
Accepts any color form (vectors, keywords, maps).

Resolves a color value to a map with :r :g :b :a keys.
Accepts tagged vectors ([:color/rgb 255 0 0], [:color/name "red"])
or bare keywords (:red, :cornflowerblue) as shorthand for named colors.

Shorthand for [:color/rgb r g b].

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

Converts sRGB (0-255 each) to OKLAB [L a b].
L: 0-1 (lightness), a: ~-0.4 to 0.4, b: ~-0.4 to 0.4.

Converts sRGB (0-255 each) to OKLCH [L C h].
L: 0-1, C: 0-0.4+, h: 0-360 degrees.

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

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

Applies multiple palette adjustments in one call.
Wraps warmer/cooler/muted/vivid/darker/lighter.
opts keys: :warmer, :cooler, :muted, :vivid, :darker, :lighter.

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

Returns the complementary color (180 degrees opposite).

Rotates all hues toward cool (negative degrees). Typical: 5-15.

Darkens all colors by amount (0-1).

Extracts a palette of k dominant colors from an image using k-means
clustering in OKLAB perceptual color space. Returns a palette vector
sorted from dark to light.
img: BufferedImage or file path string.
opts: :samples (1000), :seed (0), :max-iter (20).

Interpolates through color stops at parameter t (0-1).
stops: [[pos color] ...] sorted ascending by pos.
Optional opts: {:easing fn} applies an easing function to t before lookup.
Returns a color vector.

Returns n colors evenly interpolated between start and end.

Lightens all colors by amount (0-1).

Returns the minimum pairwise WCAG contrast ratio in a palette.
Wraps (color/contrast) over all pairs. Useful for checking readability.

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

Desaturates all colors by amount (0-1).

Named palettes as vectors of color vectors.

Returns a deterministically shuffled palette.

Sorts a palette from dark to light using OKLAB perceptual lightness.
Wraps (sort-by (fn [c] (first (color/rgb->oklab ...))) palette).

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

Returns a BufferedImage showing color bars for a palette.
Useful with show at the REPL for quick visual feedback.
opts: :width (400), :height (60).

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

Returns 3 colors evenly spaced at 120-degree intervals.

Saturates all colors by amount (0-1).

Rotates all hues toward warm (positive degrees). Typical: 5-15.

Creates gradient stops where each color occupies proportional space.
Returns stops [[pos color] ...] suitable for gradient-map.
palette and weights must have the same length.

Picks one color from palette biased by weights.
palette: vector of color vectors.
weights: vector of positive numbers (same length as palette).
seed: long for deterministic selection.

Samples n colors from palette with replacement, biased by weights.

Attaches role names to a palette for readable access.
Wraps (zipmap roles palette).
Example: (with-roles [:bg :primary :accent] pal) => {:bg c1 :primary c2 :accent c3}

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}.

4D Perlin noise. Returns a double in [-1, 1].
Essential for seamlessly looping animated noise.
Looping trick: (perlin4d x y (* r (cos t)) (* r (sin t))).
Optionally accepts {:seed n}.

Renders a noise function as a grayscale BufferedImage.
noise-fn: (fn [x y] -> double), expected range [-1, 1].
Useful with show at the REPL for tuning noise parameters.
opts: :width (256), :height (256), :scale (0.02).

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

2D OpenSimplex2S noise. Returns a double in [-1, 1].
Fewer directional artifacts than Perlin noise.
Optionally accepts {:seed n}.

3D OpenSimplex2S noise. Returns a double in [-1, 1].
Optionally accepts {:seed n}.

4D OpenSimplex2S noise. Returns a double in [-1, 1].
Essential for seamlessly looping animated noise.
Looping trick: (simplex4d x y (* r (cos t)) (* r (sin t))).
Optionally accepts {:seed n}.

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

Generates path nodes from a noise-based flow field within bounds.
bounds: [x y w h] region.
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),
:collision-distance (nil — set to enforce minimum spacing between streamlines).

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

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

Displaces each point by a Gaussian offset scaled by amount.
Returns [[x' y'] ...]. opts: :amount (required), :seed (default 0).
Amount controls displacement magnitude: 0 = no change, higher = more
disorder. Uses Gaussian for natural feel.

Generates up to n positions biased by noise density.
bounds: [x y w h]. opts: :n (required), :seed (default 0).
Points are placed where noise value exceeds a threshold.

Generates well-distributed points via Poisson disk sampling.
bounds: [x y w h]. opts: :min-dist (required), :seed (default 0).
Delegates to eido.gen.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 Delaunay triangulation edges as line nodes.
bounds: [x y w h] clipping region.
Derived from Voronoi: two seeds are neighbors if their cells share an edge.

Generates Voronoi cell polygons from seed points.
bounds: [x y w h] clipping region.
Returns a vector of :shape/path nodes (closed polygons), one per point.
Uses half-plane intersection: O(n^2) per cell.

Bushy plant with symmetric branching.

Dense branching coral structure.

Rewrites axiom by applying rules for n iterations.
Characters not in rules pass through unchanged.
Rules can be strings (classic) or vectors of strings (uses first alternative).

Asymmetric fern with curving fronds.

Interprets an L-system string via turtle graphics.
Returns scene-format path commands.
opts: :angle (degrees), :length, :origin [x y], :heading (degrees).

Jagged branching lightning bolt.

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

opts:
:iterations — number of expansion steps (default 3)
:angle — turn angle in degrees
:length — step length
:origin — [x y] start position (default [0 0])
:heading — initial direction in degrees (default 0)

When rules contain vector alternatives (e.g. {"F" ["FF+F" "F" ""]}):
:bounds [x y w h] — canvas constraint; growth stays within.
Result is scaled to fill the bounds.
:seed (42) — controls which rule choices are made when
the full expansion overflows bounds.

Swaying organic tendrils.

Classic branching tree with taper.

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.

Generates well-distributed points via Poisson disk sampling.
bounds: [x y w h] region. opts: :min-dist (required), :seed (default 0).
Returns a vector of [x y] within the bounds.

Generates circle nodes for a stipple fill within bounds.
bounds: [x y w h] region.
spec: :stipple/density (0-1), :stipple/radius, :stipple/seed,
:stipple/color.

Converts a hatch fill spec to scene path nodes (lines).
bounds: [x y w h]. 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.
bounds: [x y w h]. opts: :angle (45), :spacing (5).

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].
opts: :noise-scale (required), :seed (default 0).

Generates fill overrides by mapping noise to palette colors.
opts: :noise-scale (required), :seed (default 0).
Wraps (by-noise positions f opts).

Generates n fill overrides from a palette with optional weights.
opts: :seed (default 0), :weights (optional weight vector).
Wraps (by-index n (fn [i] {:style/fill ...})).

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

Returns true with probability p (0.0 to 1.0).

Returns a vector of n Gaussian-distributed doubles with given mean and sd.

Returns a point [x y] uniformly distributed inside a disc.
Uses the sqrt trick for uniform area distribution.

Returns a point [x y z] uniformly distributed inside a sphere volume.
Uses the Gaussian method + cbrt trick for uniform volume distribution.

Creates a java.util.Random from a seed.

Samples n values from a mix of source vectors, weighted by mix-weights.
Wraps weighted-choice to select which source to draw from.
Example: (mixture [(uniform 100 1 5 s1) (gaussian 100 20 3 s2)] [3 1] 50 seed)

Returns a point [x y] on the circumference of a circle.
Uniformly distributed angle.

Returns a point [x y z] uniformly distributed on a sphere surface.
Uses the Gaussian method to avoid polar clustering.

Returns a vector of n Pareto-distributed doubles.
Wraps (sample-n {:type :pareto ...}).

Picks one element from coll uniformly at random.
Returns nil if coll is empty.

Picks one element from items using corresponding weights.
Returns nil if items is empty.

Samples a single value from a distribution spec.
Spec is a plain map with :type and type-specific keys:
{:type :uniform :lo 0.0 :hi 1.0}
{:type :gaussian :mean 0.0 :sd 1.0}
{:type :choice :options [:a :b :c]}
{:type :weighted-choice :options [:a :b] :weights [3 1]}
{:type :boolean :probability 0.5}
{:type :pareto :alpha 2.0 :min 1.0} ;; optional :max
{:type :triangular :min 0 :max 1 :mode 0.5}
{:type :eased :easing fn :lo 0 :hi 1}
Same spec format used by eido.gen.series/series-params.

Samples n values from a distribution spec.
Each value gets a deterministic sub-seed derived from the base seed
and its index, ensuring independent samples.

Returns a vector of n points uniformly distributed inside a disc.
Wraps repeated in-circle calls with independent sub-seeds.

Returns a vector of n points on a circle.
Wraps repeated on-circle calls with independent sub-seeds.

Returns a deterministically shuffled vector of coll (Fisher-Yates).

Returns a vector of n triangular-distributed doubles in [min-val, max-val].
Wraps (sample-n {:type :triangular ...}).

Returns a vector of n uniform doubles in [lo, hi).

Returns a single index chosen from weights (vector of positive numbers).

Returns a vector of n indices sampled from weights (with replacement).

Packs circles within a rectangular region.
Returns a vector of {:center [x y] :radius r} maps.
opts:
:min-radius (2.0) — smallest circle
:max-radius (40.0) — largest circle
:padding (1.0) — gap between circles
:attempts (500) — max failed attempts before stopping
:max-circles (1000) — cap on total circles
:seed (42)
:bounds-fn — optional (fn [x y] -> boolean) for non-rectangular containment

Packs circles within an arbitrary closed path.
Uses java.awt.geom.Area for containment testing.

Circle pack to styled nodes with palette colors.
opts: :seed (default 0), :weights (optional), :style (optional base style map).
Wraps (pack->nodes circles) + (palette/weighted-sample palette).

Converts circle-pack output to scene nodes.
opts: :style (base style map applied to each circle)

Recursively subdivides a rectangle into smaller rectangles.
Returns a vector of {:rect [x y w h] :depth n} maps.
opts:
:depth (4) — max recursion depth
:min-size (20.0) — stop splitting below this dimension
:split-range [0.3 0.7] — random split ratio range
:h-bias (0.5) — probability of horizontal split (vs vertical)
:padding (0.0) — gap between sub-rects
:seed (42)

Converts subdivision output to rect scene nodes.
color-fn: (fn [{:rect [x y w h] :depth n}] -> color).

Subdivision rects to styled nodes with palette colors.
opts: :seed (default 0), :style (optional base style map).
Wraps (subdivide->nodes rects (fn [...] (prob/pick palette seed))).

Categorizes continuous parameter values into named labels.
Wraps a simple threshold lookup over a params map.
buckets: {:param [[threshold label] ...]}
Example: (derive-traits {:density 42} {:density [[20 "sparse"] [40 "medium"] [100 "dense"]]})

Derives a deterministic, uncorrelated seed for an edition number
from a master seed. Uses murmur3-style mixing so nearby editions
produce independent seeds.

Renders a complete edition package: images, manifests, and optional contact sheet.
opts: same as render-editions, plus:
:contact-sheet? — generate a grid thumbnail image (default true)
:contact-cols — columns in contact sheet (default 5)
:thumb-size — per-thumbnail size (default [160 160])
Returns {:editions [...] :contact-sheet path-or-nil}.

Reads all seed bookmarks from an EDN log file.
Returns a vector of maps in append order, or [] if the file does not exist.

Renders a parameter sweep as a single BufferedImage for REPL exploration.
Varies one param across rows, optionally another across columns.
Pass the result to show at the REPL.
opts:
:base-params — base parameter map
:row-param — {:key :param-name :values [v1 v2 ...]}
:col-param — {:key :param-name :values [v1 v2 ...]} (optional, default 1 col)
:seed — seed for scene generation
:scene-fn — (fn [params] scene-map) — takes merged params, returns scene
:thumb-size — [width height] per thumbnail (default [160 160])

Renders a batch of editions from a series spec.
opts:
:spec — parameter spec map (as for series-params)
:master-seed — master seed for the series
:start — first edition number (inclusive)
:end — last edition number (exclusive)
:scene-fn — (fn [params edition-number] scene-map)
:output-dir — directory to write files into
:format — :png (default) or :svg
:render-opts — optional map passed to eido.core/render (e.g. {:scale 2})
:traits — optional trait buckets for derive-traits
:emit-manifest? — write per-edition .edn sidecar manifests (default false)
Returns a vector of {:edition n :params params :traits traits :file path}.

Appends a seed bookmark to an EDN log file.
entry should contain at least :seed; :params and :note are optional.
Adds :timestamp automatically. Accumulates one EDN form per line.

Renders a grid of editions as a single BufferedImage for REPL exploration.
Each cell shows a different seed; pass the result to show at the REPL.
opts:
:spec — parameter spec map
:master-seed — master seed for the series
:start — first edition number (inclusive, default 0)
:end — last edition number (exclusive)
:seeds — explicit list of edition numbers (overrides start/end)
:scene-fn — (fn [params edition-number] scene-map)
:cols — number of columns (default 5)
:thumb-size — [width height] per thumbnail (default [160 160])

Generates a parameter map for one edition in a series.
spec: map of {:param-name {:type :uniform/:gaussian/:choice/:weighted-choice/:boolean, ...}}
Each parameter gets a deterministic sub-seed derived from the edition seed
and a hash of the parameter name.

Returns a vector of parameter maps for editions start (inclusive) to end (exclusive).

Computes trait frequencies across n editions of a series.
Returns {:trait-name {"label" count ...} ...} — pure data for REPL inspection.
Useful for verifying that rare traits are actually rare before releasing.

Renders a CA grid as scene nodes. Only alive cells produce nodes.
alive-style: style map for alive cells (e.g., {:style/fill color}).
cell-size: pixel size per cell.

Creates an initial CA grid.
init: :random (seeded), :empty, or :center (single live cell).
Returns {:grid boolean-array :w w :h h}.

Runs CA for n steps. Returns the final grid.

Advances a CA grid by one generation.
rule: :life, :highlife, or {:birth #{...} :survive #{...}}.

Renders an RD state as scene nodes. One rect per cell.
color-fn: (fn [a-val b-val] -> color-vector).

Creates initial reaction-diffusion concentration grids.
init: :center (circle of B in center), :random (scattered seeds).
Returns {:a double-array :b double-array :w w :h h}.

Named parameter sets for Gray-Scott reaction-diffusion.
All produce visible patterns within 500-2000 steps on 100x100+ grids.

Runs reaction-diffusion for n steps. Returns the final grid.

Advances reaction-diffusion by one time step.
params: {:feed f :kill k :da da :db db :dt dt}.

Computes steering force toward average heading of neighbors.

Classic boids — balanced separation/alignment/cohesion.

Computes steering force toward centroid of neighbors.

Computes steering force away from a point within flee-radius.

Renders a flock state as scene nodes.
opts: :shape (:triangle or :circle), :size (6), :style (style map).

Creates initial flock state.
opts: :count (50), :bounds [bx by bw bh], :max-speed (2.0), :seed (42).
Returns {:boids [...] :tick 0}.

Starling murmuration — tight cohesion, wide alignment.

Computes steering force toward a target point.

Computes steering force away from nearby boids.

Returns a vector of n flock states.

Advances flock by one tick. config contains behavior parameters.

Computes adjacency from path-based regions (Voronoi cells, polygons).
Two regions are adjacent if they share 2+ vertices (within epsilon).
Returns a set of [i j] pairs (i < j).

Applies graph coloring to scene nodes.
nodes: vector of scene nodes
adjacency: collection of [i j] pairs
palette: vector of colors
opts:
:seed (0) — shuffles palette assignment for variety
:pin {idx color} — fix specific regions to specific colors;
the solver completes the rest consistently
Returns nodes with :style/fill applied, or nil if no valid coloring exists.

Computes adjacency from subdivision rects.
Two rects are adjacent if they share an edge.
rects: vector of {:rect [x y w h]} maps.
Returns a set of [i j] pairs (i < j).

Returns a group node with n deformed copies of shape at low opacity.
Simulates watercolor, ink wash, and other translucent media.
opts: :layers (required), :opacity (required), :deform-fn (required),
:seed (default 0).
deform-fn: (fn [shape-node layer-index seed] -> shape-node).
Each layer gets a unique sub-seed derived from the base seed.

Convenience: layered rendering with jitter deformation.
Returns a group node simulating watercolor wash.
opts: :layers (30), :opacity (0.04), :amount (3.0), :seed (0).

Derives a pressure curve from path geometry.
points: [[x y] ...] — point sequence.
opts: {:mode :taper (default), :start 0.3, :end 0.2}
Returns [[t pressure] ...] suitable for :paint/pressure.

Returns a brush spec, optionally merging overrides onto a preset.
(brush :chalk)
(brush :chalk {:brush/paint {:paint/opacity 0.2}})
(brush {:brush/type :brush/dab ...})

Generates stroke points around a circle or arc.
center: [cx cy].
opts: {:radius 50, :n 20, :start 0.0, :end (* 2 PI), :pressure 0.8}
Returns [[x y pressure 0 0 0] ...] suitable for :paint/points.

Composites a painted surface to a BufferedImage.

Generates stroke descriptors to fill an elliptical area with paint.
center: [cx cy].
opts: {:rx 50, :ry 30, :brush :oil, :color [...], :radius 8.0,
:density 12, :seed 0}
Returns a vector of stroke descriptors for :paint/strokes.

Generates stroke descriptors to fill a rectangular area with paint.
bounds: [x y w h].
opts: {:brush :chalk, :color [...], :radius 8.0, :density 15, :seed 0}
Returns a vector of stroke descriptors for :paint/strokes.

Generates stroke points along a straight line.
from: [x0 y0].
opts: {:to [x1 y1], :n 15, :pressure 0.8}
Returns [[x y pressure 0 0 0] ...].

Creates a paint surface from a surface config or size vector.
Accepts [w h], {:paint/size [w h]}, or {:size [w h]}.

Creates a group with a shared paint surface.
children: painted path nodes or generators with paint params.
opts: {:substrate {:substrate/tooth 0.4}}

Creates a paint surface node.
strokes: vector of stroke descriptors.
opts: {:size [w h], :substrate {:substrate/tooth 0.4}, :children [nodes]}

Creates a path node with paint parameters.
points: [[x y] ...] — auto-smoothed via Catmull-Rom, or path commands.
opts: {:brush :ink, :color [...], :radius 8.0, :pressure [[t p] ...], :opacity 0.5}

Named brush presets. Each is a brush spec map.

Renders a single stroke onto a surface.
stroke-desc: {:stroke/brush :stroke/color :stroke/points :stroke/seed}
or path-based: {:paint/brush :paint/color :path/commands :paint/pressure}
Returns nil (mutates surface).
substrate-spec: optional substrate from the surface config.

Renders all strokes onto a surface. Returns the surface.

Resolves a brush reference to a full brush spec.
Accepts a keyword (preset name), a spec map, or nil (returns default).

Creates a stroke descriptor for use in :paint/strokes.
points: [[x y pressure speed tilt-x tilt-y] ...]
opts: {:brush :chalk, :color [...], :radius 12.0, :seed 42}

Creates a stroke descriptor from path commands with auto-derived
pressure. Convenience for composing paths with paint.
path-commands: [[:move-to [x y]] [:line-to [x y]] ...]
opts: {:brush :chalk, :color [...], :radius 12.0,
:pressure :taper (or :curvature, or explicit curve), :seed 42}

Generates stroke points along a wavy line.
from: [x0 y0].
opts: {:to [x1 y1], :amplitude 15, :frequency 0.15, :n 20, :pressure 0.7}
Returns [[x y pressure 0 0 0] ...].

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].

Quadratic fade-in. Wraps (* t t) clamped to [0, 1].

Linear fade: 1.0 at t=0, 0.0 at t=1. Wraps (- 1.0 t).

Quadratic fade-out (softer tail). Wraps (* (fade-linear t) (fade-linear t)).

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.

Sine oscillation: returns a value in [0, 1] that pulses over time.
Wraps (/ (+ 1 (sin (* t 2 PI frequency))) 2).

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].

Returns a set of hard edge keys where adjacent faces meet at more than
the given angle. Use with subdivide's :hard-edges option.
opts:
:angle - threshold angle in radians (edges sharper than this are hard)

Extracts the component of a 3D vector along the given axis (:x, :y, or :z).

Returns [min max] of the given axis across all vertices in a mesh.

Insets selected faces then extrudes the inner faces, creating a beveled edge.
Composes inset-faces and extrude-faces in one step.
opts:
:select/* - face selector (defaults to :all)
:bevel/inset - how far to shrink inward (0-1)
:bevel/depth - extrusion distance (positive = outward, negative = inward)

Builds adjacency maps from a mesh.
Returns {:edge-faces {edge-key → [face-index ...]}
:vert-faces {vertex → [face-index ...]}
:face-data [{:vertices [...] :style ... :normal ... :point ...} ...]}

Colors each face based on a descriptor.
When :select/type is present, only selected faces are colored; others pass through.
opts:
:color/type - :field, :axis-gradient, or :normal-map
:color/palette - vector of [:color/rgb r g b] colors
:color/field - field descriptor (for :field type)
:color/axis - :x, :y, or :z (for :axis-gradient type)
:select/* - optional face selector (defaults to all faces)

Computes smooth vertex normals by averaging adjacent face normals.
Returns {vertex → normalized-average-normal}.

Creates a 3D cone projected into 2D.
opts: :radius, :height, :segments, :style, :light, :cull-back.

Returns a mesh approximating a cone at the origin.
Base circle in the XZ plane at y=0, apex at [0 height 0].
Opts: :segments (default 16) — number of sides.

Creates a 3D cube projected into 2D, returned as a :group node.
opts: :size (1), :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.
opts: :radius, :height, :segments, :style, :light, :cull-back.

Returns a mesh approximating a cylinder centered at the origin.
Opts: :segments (default 16) — number of sides for the circular cross-section.

Applies a deformation to a mesh, returning a new mesh.
descriptor: map with :deform/type and type-specific options.
Types: :twist, :taper, :bend, :inflate, :crumple, :displace.

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.

Adds procedural surface detail by insetting then noise-extruding faces.
Creates mechanical/sci-fi panel detail. Composes inset + field-driven extrude.
opts:
:select/* - face selector (defaults to :all)
:detail/field - noise field for per-face extrusion depth
:detail/inset - inset amount (default 0.1)
:detail/depth-range - [min-depth max-depth] range for extrusion

Returns a canonical key for an edge between two 3D points.
Sorts the endpoints so edge [a b] and [b a] produce the same key.

Extrudes selected faces along their normals.
opts:
:select/* - face selector (see make-face-selector)
:extrude/amount - distance to push faces
:extrude/scale - optional scale factor toward centroid (default 1.0)

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 a mesh from a 2D field sampled on a grid.
opts:
:field - field descriptor (noise, constant, distance)
:bounds - [x z width depth] defining the sampling area
:grid - [cols rows] number of sample points
:height - maximum Y displacement

Insets selected faces, creating a smaller inner face and border quads.
opts:
:select/* - face selector
:inset/amount - how far to shrink inward (0-1 fraction of distance to centroid)

Places copies of a mesh at multiple positions.
Bridges 2D scatter distributions to 3D mesh placement.
opts:
:positions - vector of [x y z] positions
:jitter - {:amount n :seed s} random positional jitter
:rotate-y - {:range [min max] :seed s} random Y-axis rotation per instance

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

Linear interpolation between two RGB colors.

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]).

Generates a 3D mesh from an L-system by sweeping a profile along branches.
Composes L-system string expansion + 3D turtle interpretation + sweep-mesh.
opts:
:axiom - starting string
:rules - rewrite rules {"F" "FF[+F][-F]"}
:iterations - number of rewriting iterations
:angle - turn angle in degrees
:length - distance per F step
:profile - 2D cross-section [[x y] ...] for sweep
:segments - sweep segments per branch (default 4)
:taper - profile scale factor per branch depth (default 1.0, < 1 = thinner)

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

Builds a predicate fn from a selector descriptor.
Returns (fn [face centroid normal] -> boolean).

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.

Reflects a mesh across an axis plane through the origin.
opts:
:mirror/axis - :x, :y, or :z (which axis plane to reflect across)
:mirror/merge - if true, return original + reflection combined (default false)

Perturbs vertex normals using a field sampled at UV coordinates.
Creates visible surface detail under lighting without adding geometry.
Requires :face/texture-coords on faces (from uv-project or OBJ import).
opts:
:normal-map/field - field descriptor
:normal-map/strength - perturbation strength (default 1.0)
:select/* - optional face selector

Returns a projection with the camera orbiting target at the given radius.
opts: :radius, :yaw (radians), :pitch (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).

Assigns per-vertex colors by sampling a field at vertex positions.
When :color/source is :uv, samples at vertex UV coordinates instead of
3D positions — this is the bridge from Eido's 2D procedural system to 3D.
opts:
:color/type - :field, :axis-gradient, or :normal-map
:color/source - :position (default) or :uv (requires :face/texture-coords)
:color/palette - vector of [:color/rgb r g b] colors
:color/field - field descriptor (for :field type)
:color/axis - :x, :y, or :z (for :axis-gradient type)
:select/* - optional face selector

Maps a [0,1] value to a color from a palette via linear interpolation.

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

Returns a platonic solid inscribed in a sphere of the given radius.
type: :tetrahedron, :octahedron, :dodecahedron, or :icosahedron.

Creates a 3D prism projected into 2D.
opts: :base-points, :height, :style, :light, :cull-back.

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 - single light map (backward compatible)
:lights - vector of light maps (multi-light)
:cull-back - if true, omit back-facing polygons (default true)
:wireframe - if true, render edges only (no fill, no shading)
:shading - :flat (default) or :smooth (vertex normal averaging)

Creates a mesh by revolving a 2D profile around the Y axis.
opts:
:profile - vector of [radius height] pairs defining the cross-section
:segments - number of rotation steps around the axis

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].

Varies specular intensity per vertex using a field sampled at UV coordinates.
Requires :face/texture-coords on faces. The material's specular value is
overridden per sub-triangle during rendering.
opts:
:specular-map/field - field descriptor
:specular-map/range - [min-spec max-spec] (default [0.0 1.0])
:select/* - optional face selector

Creates a 3D sphere projected into 2D.
opts: :radius, :segments, :rings, :style, :light, :cull-back.

Returns a mesh approximating a sphere at the origin.
Opts: :segments (default 16) — longitude slices,
:rings (default 12) — latitude bands.

Applies Catmull-Clark subdivision to a mesh.
opts:
:iterations - number of subdivision passes (each 4× face count)
:hard-edges - optional set of edge keys to preserve as creases
Returns a new mesh of quad faces.

Creates a mesh by sweeping a 2D profile along a 3D path.
opts:
:profile - vector of [x y] pairs defining the cross-section
:path - vector of [x y z] waypoints defining the sweep path
:segments - number of steps along the path
:closed - if true, connect last ring back to first (default false)

Creates 3D extruded text projected into 2D, returned as a :group node.
projection: projection map. content: string. font-spec: font map.
opts: :depth (extrusion depth), :flatness, :style, :light, :cull-back.
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.
opts: :major-radius, :minor-radius, :ring-segments, :tube-segments,
:style, :light, :cull-back.

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).
Opts: :ring-segments (default 24) — divisions around the ring,
:tube-segments (default 12) — divisions around the tube.

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

Assigns texture coordinates to mesh faces via projection.
opts:
:uv/type - :box, :spherical, :cylindrical, or :planar
:uv/axis - axis for :cylindrical/:planar (default :y)
:uv/scale - UV scale factor (default 1.0)
:uv/offset - [u-offset v-offset] (default [0 0])
:select/* - optional face selector

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]).

Returns a projection with the camera orbiting target at the given radius.
opts: :radius, :yaw (radians), :pitch (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.

Returns a mesh approximating a cone at the origin.
Base circle in the XZ plane at y=0, apex at [0 height 0].
Opts: :segments (default 16) — number of sides.

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.

Returns a mesh approximating a cylinder centered at the origin.
Opts: :segments (default 16) — number of sides for the circular cross-section.

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.

Creates a mesh from a 2D field sampled on a grid.
opts:
:field - field descriptor (noise, constant, distance)
:bounds - [x z width depth] defining the sampling area
:grid - [cols rows] number of sample points
:height - maximum Y displacement

Returns a platonic solid inscribed in a sphere of the given radius.
type: :tetrahedron, :octahedron, :dodecahedron, or :icosahedron.

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.

Creates a mesh by revolving a 2D profile around the Y axis.
opts:
:profile - vector of [radius height] pairs defining the cross-section
:segments - number of rotation steps around the axis

Returns a mesh approximating a sphere at the origin.
Opts: :segments (default 16) — longitude slices,
:rings (default 12) — latitude bands.

Creates a mesh by sweeping a 2D profile along a 3D path.
opts:
:profile - vector of [x y] pairs defining the cross-section
:path - vector of [x y z] waypoints defining the sweep path
:segments - number of steps along the path
:closed - if true, connect last ring back to first (default false)

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).
Opts: :ring-segments (default 24) — divisions around the ring,
:tube-segments (default 12) — divisions around the tube.

Applies a deformation to a mesh, returning a new mesh.
descriptor: map with :deform/type and type-specific options.
Types: :twist, :taper, :bend, :inflate, :crumple, :displace.

Reflects a mesh across an axis plane through the origin.
opts:
:mirror/axis - :x, :y, or :z (which axis plane to reflect across)
:mirror/merge - if true, return original + reflection combined (default false)

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].

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

Returns a set of hard edge keys where adjacent faces meet at more than
the given angle. Use with subdivide's :hard-edges option.
opts:
:angle - threshold angle in radians (edges sharper than this are hard)

Builds adjacency maps from a mesh.
Returns {:edge-faces {edge-key → [face-index ...]}
:vert-faces {vertex → [face-index ...]}
:face-data [{:vertices [...] :style ... :normal ... :point ...} ...]}

Computes smooth vertex normals by averaging adjacent face normals.
Returns {vertex → normalized-average-normal}.

Applies Catmull-Clark subdivision to a mesh.
opts:
:iterations - number of subdivision passes (each 4× face count)
:hard-edges - optional set of edge keys to preserve as creases
Returns a new mesh of quad faces.

Colors each face based on a descriptor.
When :select/type is present, only selected faces are colored; others pass through.
opts:
:color/type - :field, :axis-gradient, or :normal-map
:color/palette - vector of [:color/rgb r g b] colors
:color/field - field descriptor (for :field type)
:color/axis - :x, :y, or :z (for :axis-gradient type)
:select/* - optional face selector (defaults to all faces)

Perturbs vertex normals using a field sampled at UV coordinates.
Creates visible surface detail under lighting without adding geometry.
Requires :face/texture-coords on faces (from uv-project or OBJ import).
opts:
:normal-map/field - field descriptor
:normal-map/strength - perturbation strength (default 1.0)
:select/* - optional face selector

Assigns per-vertex colors by sampling a field at vertex positions.
When :color/source is :uv, samples at vertex UV coordinates instead of
3D positions — this is the bridge from Eido's 2D procedural system to 3D.
opts:
:color/type - :field, :axis-gradient, or :normal-map
:color/source - :position (default) or :uv (requires :face/texture-coords)
:color/palette - vector of [:color/rgb r g b] colors
:color/field - field descriptor (for :field type)
:color/axis - :x, :y, or :z (for :axis-gradient type)
:select/* - optional face selector

Varies specular intensity per vertex using a field sampled at UV coordinates.
Requires :face/texture-coords on faces. The material's specular value is
overridden per sub-triangle during rendering.
opts:
:specular-map/field - field descriptor
:specular-map/range - [min-spec max-spec] (default [0.0 1.0])
:select/* - optional face selector

Assigns texture coordinates to mesh faces via projection.
opts:
:uv/type - :box, :spherical, :cylindrical, or :planar
:uv/axis - axis for :cylindrical/:planar (default :y)
:uv/scale - UV scale factor (default 1.0)
:uv/offset - [u-offset v-offset] (default [0 0])
:select/* - optional face selector

Insets selected faces then extrudes the inner faces, creating a beveled edge.
Composes inset-faces and extrude-faces in one step.
opts:
:select/* - face selector (defaults to :all)
:bevel/inset - how far to shrink inward (0-1)
:bevel/depth - extrusion distance (positive = outward, negative = inward)

Adds procedural surface detail by insetting then noise-extruding faces.
Creates mechanical/sci-fi panel detail. Composes inset + field-driven extrude.
opts:
:select/* - face selector (defaults to :all)
:detail/field - noise field for per-face extrusion depth
:detail/inset - inset amount (default 0.1)
:detail/depth-range - [min-depth max-depth] range for extrusion

Extrudes selected faces along their normals.
opts:
:select/* - face selector (see make-face-selector)
:extrude/amount - distance to push faces
:extrude/scale - optional scale factor toward centroid (default 1.0)

Insets selected faces, creating a smaller inner face and border quads.
opts:
:select/* - face selector
:inset/amount - how far to shrink inward (0-1 fraction of distance to centroid)

Places copies of a mesh at multiple positions.
Bridges 2D scatter distributions to 3D mesh placement.
opts:
:positions - vector of [x y z] positions
:jitter - {:amount n :seed s} random positional jitter
:rotate-y - {:range [min max] :seed s} random Y-axis rotation per instance

Generates a 3D mesh from an L-system by sweeping a profile along branches.
Composes L-system string expansion + 3D turtle interpretation + sweep-mesh.
opts:
:axiom - starting string
:rules - rewrite rules {"F" "FF[+F][-F]"}
:iterations - number of rewriting iterations
:angle - turn angle in degrees
:length - distance per F step
:profile - 2D cross-section [[x y] ...] for sweep
:segments - sweep segments per branch (default 4)
:taper - profile scale factor per branch depth (default 1.0, < 1 = thinner)

Creates a 3D cone projected into 2D.
opts: :radius, :height, :segments, :style, :light, :cull-back.

Creates a 3D cube projected into 2D, returned as a :group node.
opts: :size (1), :style, :light, :cull-back.

Creates a 3D cylinder projected into 2D.
opts: :radius, :height, :segments, :style, :light, :cull-back.

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.

Creates a 3D prism projected into 2D.
opts: :base-points, :height, :style, :light, :cull-back.

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 - single light map (backward compatible)
:lights - vector of light maps (multi-light)
:cull-back - if true, omit back-facing polygons (default true)
:wireframe - if true, render edges only (no fill, no shading)
:shading - :flat (default) or :smooth (vertex normal averaging)

Creates a 3D sphere projected into 2D.
opts: :radius, :segments, :rings, :style, :light, :cull-back.

Creates 3D extruded text projected into 2D, returned as a :group node.
projection: projection map. content: string. font-spec: font map.
opts: :depth (extrusion depth), :flatness, :style, :light, :cull-back.
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.
opts: :major-radius, :minor-radius, :ring-segments, :tube-segments,
:style, :light, :cull-back.

Parses MTL text into a map of material-name to style map.
Returns e.g. {"wood" {:style/fill [:color/rgb 139 90 43] :node/opacity 1.0}}

Supported directives: newmtl, Kd, d. All others are ignored.

Parses OBJ text into a mesh (vector of face maps).

opts:
:materials - map from material name to style (from parse-mtl)
:default-style - style for faces with no material assignment

Supported directives: v, vn, vt, f, usemtl,
g (group name → :face/group), s (smooth group → :face/smooth-group),
o (object name, ignored). All others are silently skipped.

Texture coordinates (vt) are stored as :face/texture-coords when present.

Generates MTL text from a map of material-name to style map.
Inverse of parse-mtl.

Generates OBJ text from a mesh (vector of face maps).
Exports texture coordinates when :face/texture-coords is present.
opts:
:name - object name (default "mesh")
:mtl - if true, includes material references; returns {:obj str :mtl str}
if false (default), returns the OBJ string directly

Extracts polylines from compiled IR, grouped by stroke color.

Returns {:groups [{:stroke
:polylines [[[x y] ...] ...]} ...]
:bounds [w h]}.

Stroke colors are resolved maps like {:r R :g G :b B :a A}, or nil
for ops without a stroke. Groups appear in the order their stroke
color was first seen. Leaf ops inside :buffer containers are
flattened before grouping.

Options:
:flatness — curve subdivision tolerance (default 0.5)
:segments — number of segments for circle/ellipse/arc (default 64)

Extracts all polyline data from compiled IR.
Returns {:polylines [[[x1 y1] [x2 y2] ...] ...] :bounds [w h]
:dropped {:fills N ...} (only when non-empty)}.

The optional :dropped map summarizes visual features (fills,
gradients, patterns, hatch, stipple, effects) that the polyline
pipeline cannot represent — a scene that looks filled on screen
exports as outlines only, and :dropped flags how much got lost.

Options:
:flatness — curve subdivision tolerance (default 0.5)
:segments — number of segments for circle/ellipse/arc approximation (default 64)

Reorders polylines to minimize pen-up travel between them.
Greedy nearest-neighbor starting from [0 0], picking the polyline
whose first point is closest to the current position each step.

Polylines with no first point (empty/nil) are dropped, since they
produce no motion and can't anchor the nearest-neighbor search.

Input and output are both vectors of polylines:
[[[x y] ...] ...].

Serializes polyline data to an EDN string.

Returns a map of silently-dropped visual features for a compiled IR.
Counts what the polyline pipeline can't represent — fills (solid,
gradient, pattern, hatch, stipple) — so callers can warn or log
when an export would lose visible information.

Returns {} when nothing is dropped.

Returns the unit vector pointing from the scene toward the camera.
Used for back-face culling and depth sorting.
Convention: yaw=0 pitch=0 means camera looks along -Z (camera at +Z).

Cross product of two 3D vectors.

Dot product of two 3D vectors.

Returns the centroid (average position) of a set of 3D points.

Computes the normal vector of a face from its first three vertices.
The direction follows the right-hand rule (counter-clockwise winding).

Computes tangent and bitangent vectors for a face given its first three
vertices and their UV coordinates. Returns [tangent bitangent] as
normalized 3D vectors, or nil if the UV triangle is degenerate.

Linear interpolation between two 3D vectors.
t=0 returns a, t=1 returns b.

Length of a 3D vector.

Returns a function that projects 3D points to 2D screen coordinates.
Precomputes trig values and projection parameters once, avoiding
per-vertex map lookups, trig calls, and intermediate vector allocations.

Returns a unit vector in the same direction, or [0 0 0] for zero vector.

Projects a 3D point to 2D screen coordinates using the given projection.

Rotates a point around the given axis (:x, :y, or :z) by angle (radians).

Hermite interpolation between edge0 and edge1.
Returns 0 when x <= edge0, 1 when x >= edge1, smooth curve between.

Multiplies a 3D vector by a scalar.

Adds two 3D vectors.

Subtracts second 3D vector from first.

Transforms a 3D point into view space (rotated by camera angles).
Used for perspective projection depth calculation.

Flattens a scene path command to concrete IR format.
[:move-to [x y]] → [:move-to x y]

Creates a semantic IR container from size, background, and draw items.
Optionally accepts additional resources to merge with the default framebuffer.

Creates a semantic draw item from geometry and optional style properties.

Creates an effect pass that applies a filter to a resource.

Creates a semantic draw item from a generator descriptor map.
The generator-map should have :item/generator with :generator/type.

Returns [x y w h] bounding box for an IR geometry map.

Creates a multi-pass IR container.
passes: vector of pass maps (draw-geometry, effect-pass, program-pass).
Optionally accepts additional resources and outputs.

Creates a program pass that evaluates a program over a resource.

Returns the set of binding keywords available for a domain kind.
Useful for documentation and validation.

Domain over a pixel grid.

Domain over mesh faces.

Domain over a particle collection.

Domain over a path's parameter space [0..1].

Domain over a point set.

Domain over a shape's local UV space.

Domain over animation time.

Domain over 2D world coordinates within bounds.

Declares a field resource.

Declares a geometry resource.

Declares an image resource.

Declares a mask resource.

Merges multiple resource declarations into one map.

Declares a parameter block resource.

Declares a particle state resource.

Declares a point set resource.

Validates that all resources referenced by a pass exist in the
resource map. Returns nil if valid, or a vector of error strings.

Validates all passes in a pipeline reference declared resources.
Returns nil if valid, or a vector of error strings.

Evaluates a procedural fill over a bounding box, producing a BufferedImage.
The program receives :uv as normalized [0..1, 0..1] coordinates.

Lowers a draw item with a hatch fill to concrete ops.
Calls hatch/hatch-fill->nodes directly and converts to concrete ops.

Lowers a draw item with a procedural fill to concrete ops.
Evaluates the program over the item's bounds and creates an image fill.

Lowers a draw item with a stipple fill to concrete ops.
Calls stipple/stipple-fill->nodes directly and converts to concrete ops.

Creates a procedural fill descriptor.
program is a program map with :program/body and optional :program/inputs.
The program is evaluated per-pixel with :uv bound to normalized [0-1] coords.

Returns true if a fill descriptor requires semantic lowering
(as opposed to direct resolution to a color/gradient).

Lowers a draw item with effects to concrete ops.
Builds BufferOp wrappers directly for shadow/glow and filter effects.

Creates a field that returns the same value everywhere.

Creates a field that returns the distance from a point.

Evaluates a field descriptor at position (x, y).
Returns a double.

Evaluates a field descriptor at 3D position (x, y, z).
Noise fields use 3D Perlin noise. Distance fields use x and y only.
Returns a double.

Creates a noise field descriptor.
Options: :noise-type (:perlin), :variant (:raw | :fbm | :turbulence | :ridge),
:scale (1.0), :octaves (4), :lacunarity (2.0), :gain (0.5),
:seed (nil), :offset (1.0, ridge only).

Evaluates an expression in the given environment.
env is a map of keyword → value (e.g. {:uv [0.5 0.5] :time 0.0}).

Evaluates a program map over a single point.
program: {:program/inputs {:uv :vec2 ...}
:program/domain {:domain/kind :image-grid ...} ;; optional
:program/body }
env: {:uv [0.5 0.5] :time 0.0 ...}

If the program has a :program/domain, validates that the env contains
the expected bindings for that domain kind.

Applies a single pre-transform to path commands.

Applies a sequence of pre-transforms to a geometry map.
Returns a modified geometry map (always :path type after transforms).

Creates a distort transform descriptor.
method: :noise | :wave | :roughen | :jitter
opts: method-specific params (see eido.path.distort).

Creates a morph transform descriptor.
target: path commands to morph toward.
t: interpolation parameter (0.0 = source, 1.0 = target).

Creates a warp transform descriptor.
method: :wave | :twist | :fisheye | :bulge | :bend
params: method-specific params (see eido.path.warp).

Creates a contour generator descriptor.
field: a field descriptor (or nil for default Perlin noise).

Creates a decorator generator descriptor.

Creates a Delaunay edge generator descriptor.

Expands a generator descriptor to concrete ops by calling
existing feature module functions and compiling the results.

Creates a flow field generator descriptor.

Creates a particle system generator descriptor.
config: particle system config map (emitter, forces, lifetime, etc.)
frame: which frame to render (0-indexed)
n: total frames to simulate.

Creates a scatter generator descriptor.

Creates a Voronoi generator descriptor.

Creates a vary descriptor that interpolates fill through gradient stops.

Creates a vary descriptor that generates overrides by index.

Creates a vary descriptor that generates overrides from noise.
opts: :noise-scale (required), :seed (default 0).

Creates a vary descriptor that generates overrides by position.

Evaluates a vary descriptor into an override vector.
If the input is already a vector, returns it as-is.

Creates a directional light (parallel rays).

Creates a hemisphere (sky) light with sky and ground colors.

Creates an omni (point) light that radiates in all directions.

Creates a Blinn-Phong material descriptor.

Shades a face style using a material and lights.
Supports single light or lights vector.

Shades a face using multiple lights and a Blinn-Phong material.
Returns [:color/rgb r g b].

Computes Blinn-Phong shading for a face with a single directional light.

Creates a spot light with a cone defined by hotspot and falloff angles.

Lowers a semantic IR container to the concrete format
consumed by eido.engine.render and eido.engine.svg.

Converts a simple scene node (path, circle, rect, etc.) to a concrete op.
Handles scene-level fill/stroke resolution. For use by IR modules that
receive scene nodes from feature modules (hatch, stipple, flow, etc.).

Converts a vector of simple scene nodes to a flat vector of concrete ops.

Resolves a semantic fill descriptor to the format concrete ops expect.