math-primitives

---
name: math-primitives
description: Build maths and physics animations for packages in Blender with a small proven primitive library - mathtext equations and matrices as meshes, live numbers, live vector fields, particle trails, parametric curves, vectors, pops, rays and veils, bloom, lit 3D sets and CC0 asset import - plus the Blender 5.x traps that each cost a debugging round. Use when starting or extending a package builder.
---

# Maths animation primitives

A package builder is a Python script run by `blender -b --python build_<id>.py` that constructs the whole scene
headless, keys every motion to the beat cues, and saves the `.blend`, a manifest and a build-revision fingerprint.
Put the shared primitives in the project's `common.py` (2D/stylised layer) and a 3D extension module; read an
existing builder close to your idea before writing a new one. This plugin does not ship that library: the API table
below is the contract to implement (or adapt from your own code) the first time, then reuse for every package.

## Setup pattern

```python
import sys; from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import common as E            # primitives below; E.C = base helpers (pop, visible, key, line, mesh, text…)
C, K = E.C, E.K               # K = config: FPS, palette (V1 orange, V2 cyan, V3 magenta, GOLD, WHITE, FIELD_RAMP), SAFE_UNITS
FILM = K.film('<id>', **cues) # cues from beats.timeline.json: beat starts, events
S = E.setup(FILM, bloom=.5)   # dark scene, 16-unit-tall camera (120 px/unit), compositor bloom
...
C.finish()                    # sets Bezier + constant-visibility interpolation; re-linearise baked channels after it
E.save(FILM, [__file__], notes)   # .blend + manifest + build-revision fingerprint (the render cache key)
```

3D sets: a module with `setup(FILM)` (perspective camera), `key_camera(t, loc, target)`, `starfield()`,
`glossy(name, color, …)` (dithered for self-occlusion), `import_gltf(path, name, scale=…)`, CC0 asset helpers
(Kenney packs, Poly Haven downloads cached once, with a per-package provenance file), `bounds(objs)`.

Coordinates (2D layer): origin at frame centre, x right, y up; safe area x -3.75…3.0, y -4.83…5.5 units.

## API

| Primitive | Call | Notes |
|---|---|---|
| Equation | `E.eq(tex, x, y, size, color, parent, align, …)` | STIX mathtext → triangulated mesh (holes kept); `size` = em height; `ob['width']`. Glyphs cached by hash, prepared with matplotlib + shapely via `uv run` |
| Coloured row | `E.eq_row([(tex, color), …], x, y, size)` | pieces on one baseline, to colour-code terms |
| Matrix | `rig, cells = E.matrix(entries, x, y, size, colors=…, col_gap=…)` | `cells[(i,j)]`, `rig['width']` for placing neighbours |
| Live number | `ob, g = E.live_number(name, x, y, size, color, decimals=2)`; `g.key('value', t, v)` | Geometry Nodes String to Curves in STIXGeneral (matches mathtext), true minus sign |
| Vector field | `ob, g = E.arrow_field(name, field, origin=…, speed_ref=…, highlight=…)` | `field(g, u, v)` returns (wx, wy) sockets; keyed values (matrix entries, zoom) update the field live; built-in keys `dots`, `arrows`, `phase` |
| Particles | `E.particles(name, poses, colors, key_times, …)` | poses (keys, P, T, 3), z = alpha; RK4 via `E.rk4`; tapered tubes + heads |
| Live curve | `ob, g = E.curve_from_gn(name, build, width, color)` | `build(g, s)` maps s in [-1,1] to (x, y); keys `draw` (grows from centre), `width scale` |
| Vector | `v = E.Vec(name, color, x, y)`; `v.set(t, dx, dy)` | constant-size head; `v.linear()` for baked keys |
| Show/fade | `E.show(ob, start, end, fade_in, fade_out, peak)` | alpha via Object Info → `object.color[3]` keys |
| Pop | `C.pop(rig, t, dur, shift=, angle=)` + `E.rays(name, x, y, w, h, t)` | restrained intro: overshoot, lift, tilt, brief rays |
| Typography backing | `E.veil(name, x, y, w, h)` | feathered dark backing behind text over busy visuals |
| Materials | `E.emission(name, color, strength)` | emission + Object-Info alpha (fadeable) |
| Nodes | `g = E.G(name)`; `g.m(op,a,b)`, `g.v(op,a,b)`, `g.value(name, v)`, `g.key(name, t, v)` | tiny Geometry Nodes builder |

## Traps (each cost a debugging round)

- **Particles: one shape key per frame.** Absolute keys every 2 frames interpolate a respawned particle halfway
  across the screen on the in-between frame, giving one-frame ghost streaks.
- **Pre-roll simulations** (simulate from t = -PRE and keep the history) so frame 1 is fully alive; it also lets the
  ending replay the pre-roll to loop.
- Trails must only span the current life: clamp trail history to the particle's birth frame.
- Blender 5.x Geometry Nodes: String to Curves font and alignment are **input sockets** (`inputs['Font']`, menu values
  `'Center'`, `'Bottom Baseline'`), not node properties; digits come out 0.461 em tall against mathtext's 0.688, so
  scale Size by 1.49.
- Compositor: `scene.compositing_node_group = <CompositorNodeTree>` with a Group Output; the Glare type is an input
  socket (`'Bloom'`).
- Use STIXGeneral for live text so it matches matplotlib's `stix` mathtext.
- `bpy.context.window` exists in `blender -b`, so scene creation works headless; no GUI needed to build.
- Some asset APIs reject Python's default User-Agent; send one.
- `C.finish()` resets interpolation to Bezier; re-apply linear interpolation to per-frame baked channels.
- Blender curve `bevel_depth` is a **radius**: the full thickness is twice it. Map Range nodes clamp and use
  smoothstep by default.
- Keep text in the safe area, but let fields, panels, tints and floors bleed to the frame edge (no dead bottom band).
- Log every motion onset in the manifest's `cues.events` (camera moves as kind `move`) so pacing can be checked
  before rendering.
- Verify with `visual-qa`; build and render only through the lock (`blender-agent-renders`).