# Zpup
> Zpup takes a small 3D scene described as a plain JSON tree and returns a flat SVG picture of it from any angle, as a string. The look is round strokes and flat colors, in the style of Zdog. ESM-only TypeScript, no runtime dependencies, no DOM needed.
## Entry points
The npm package is `@zpup/core`.
```ts
import { renderSvg, renderSpinSvg, checkScene, compileScene, ZpupValidationError } from '@zpup/core';
import { group, path, dot, ellipse, rect, polygon, box, cylinder, cone, hemisphere } from '@zpup/core'; // optional typed helpers
renderSvg(scene, { precision: 2 }) // -> "... \n" (pure, deterministic)
checkScene(scene) // -> ValidationIssue[] (empty when valid), never throws
checkSceneWarnings(scene) // -> ValidationIssue[]: valid but suspicious (radians, off-screen, draws nothing, shapes passing through each other)
compileScene(scene) // -> Frame: projected, depth-sorted 2D draw items
renderSpinSvg(scene, options?) // -> "" that turns the scene forever (SMIL, no JavaScript)
```
`renderSvg`, `renderSpinSvg` and `compileScene` throw `ZpupValidationError` on an invalid scene or option. Its `message` lists every problem; `issues` has `{ path, pathSegments, expected, received, hint, detail, message }` for each (`detail` is `message` without the path).
## Conventions
- Axes: x right, y down, z toward the viewer. Origin = center of the image.
- Units: scene units; 1 unit = 1 SVG pixel at `zoom: 1`.
- Angles: degrees, never radians. Rotation applies z first, then y, then x.
- `rotate.z > 0`: clockwise on screen.
- `rotate.y > 0`: the +x side moves away from the viewer.
- `rotate.x > 0`: the bottom (+y) side moves toward the viewer. `scene.rotate = { x: -15 }` looks down from above.
- Vectors are objects with optional keys: `{ x: 10 }`, `{ y: -5, z: 2 }`, `{}`. Arrays such as `[1, 2, 3]` are rejected.
- Node transform order: scale, then rotate, then translate. Children inherit the parent's transform.
- Projection is orthographic. There is no perspective and no light you can move; `shading: "soft"` on the scene shades round things as if lit from the upper left.
- Unknown options are errors (this catches typos such as `colour`).
- Scene JSON may be written without any whitespace; indentation and line breaks are optional.
## Scene
```ts
{
width: number, // required, pixels, > 0
height: number, // required, pixels, > 0
zoom?: number, // default 1
background?: string, // CSS color; default transparent
title?: string, // accessible title
shading?: "flat" | "soft", // default "flat"; "soft" shades dots, thick lines and round solids, lit from the upper left
rotate?: { x?, y?, z? },// view rotation in degrees
children: Node[], // required (may be [])
}
```
## Nodes
Every node: `type` (required), `id?` (string, shown in errors), `translate?`, `rotate?`, `scale?` (number or `{ x?, y?, z? }`, missing axes = 1), `visible?` (default true), `children?`.
Every shape (all types except `group`): `color?` (hex, `rgb()`, or a CSS color name; default `"#333"`), `stroke?` (width >= 0, default 1, round caps and joins), `fill?` (boolean, default false; fills with `color`).
Flat shapes (`path`, `ellipse`, `rect`, `polygon`) also take `backface?`, as in Zdog: `true` (default) shows both sides; `false` hides the shape while its front (local +z) faces away, edge-on included; a color paints the back in that color. On `cylinder`, `cone` and `hemisphere`, `backface` is a face color instead.
| type | own options | notes |
| --- | --- | --- |
| `group` | none | Draws nothing; moves its children together. No `color`. |
| `dot` | none (takes only `color` and `stroke`; no `fill` or `backface`) | A ball at the node's origin; `stroke` is its diameter. |
| `path` | `path` (required, array of points), `closed?` (default false) | 2 points = line/tube, 3+ = polyline or polygon. 1 point is the same as a `dot`. |
| `ellipse` | `diameter`, or `width` and `height` | Circle or ellipse in the local x/y plane. |
| `rect` | `width`, `height` (required) | Centered on the origin, in the local x/y plane. |
| `polygon` | `sides` (integer >= 3), `radius` (required) | Regular polygon, one corner pointing up. |
| `box` | `width`, `height`, `depth` (required); `frontFace`, `rearFace`, `leftFace`, `rightFace`, `topFace`, `bottomFace` | Centered. Faces: front +z, top -y. |
| `cylinder` | `diameter`, `length` (required); `frontFace` (+z end), `backface` (-z end) | Along local z, centered. |
| `cone` | `diameter`, `length` (required); `backface` (base) | Base at z = 0, tip at z = length. |
| `hemisphere` | `diameter` (required); `backface` (flat side) | Flat side at z = 0, dome toward +z. |
Solids (`box`, `cylinder`, `cone`, `hemisphere`) are always filled and take `color`, `stroke` (default 1, rounds the edges) and `shade?` (default true). Each face gets a fixed lighter or darker version of `color` by the direction it points in the scene (up lighter, down darker, left and right different), so one color reads as 3D. Face options set one face's exact color. `shade: false` paints every face in `color`. Like Zdog, round solids point along z: `rotate: { x: 90 }` stands them up (the +z end, `frontFace`, goes on top).
Path entries are points `{ x?, y?, z? }` or cubic curves `{ "bezier": [control1, control2, end] }`. The first entry must be a point.
Helpers: `group(o)`, `dot(o)`, `ellipse(o)`, `box(o)` and the rest return `{ type, ...o }`.
## How to get volume
- Sphere: `{ "type": "dot", "stroke": 40 }`, or `dot({ stroke: 40 })` (diameter = stroke).
- Tube or limb: a 2-point `path` with a thick `stroke`.
- Disc or plate: `ellipse({ diameter, fill: true })`, optionally with a stroke for a rounded rim.
- Ring: `ellipse({ diameter, stroke })` without fill. Rotate it with `rotate: { x: 90 }` to lay it flat.
- Lay a flat shape on the ground with `rotate: { x: 90 }`.
- Mug: `{ "type": "cylinder", "diameter": 80, "length": 90, "rotate": { "x": 90 }, "color": "#4a7bd0", "frontFace": "#5b3a29" }` (coffee on top), plus a thick `path` for the handle.
- Roof or rocket nose: a `cone` with `rotate: { x: 90 }`, placed on the top of a cylinder.
- Dome or rock: `hemisphere` with `rotate: { x: 90 }`; `scale: { z: 0.5 }` flattens it.
- Crate, building, robot parts: `box`. Stack solids so they touch on flat faces.
## Depth sorting
Shapes are painted back to front. Overlapping shapes are compared where they overlap on screen, not by their centers, so a dot standing on a large floor sorts correctly. Unfilled outlines are sorted segment by segment, so a ring can pass behind and in front of a sphere. Shapes that truly intersect each other, or filled shapes that weave through each other, cannot be drawn correctly; split them into smaller shapes. Do not sink one solid into another: rest it on a flat face (a tower on a base's top, not inside a dome). Coplanar shapes keep tree order (later children paint on top).
Place details slightly in front of the surface they sit on: an eye on a sphere of stroke 40 goes at `z` around 18 to 20.
## Models that turn without popping
Zpup paints whole shapes back to front, so a shape that crosses into another changes order all at once.
- Shapes of different colors should only touch, never cut into each other.
- Shapes that do cut into each other (a snout sunk into a head) should have the same color.
- Color changes on a surface (eyes, cheeks, a belly patch) are flat, filled shapes with `stroke: 0` and `backface: false`, rotated to face out from the surface and placed on the plane that touches it, just outside: `group({ rotate: { x: 15, y: -25 }, children: [ellipse({ translate: { z: 40.5 }, width: 8, height: 11, fill: true, stroke: 0, color: "#222", backface: false })] })` on a head of `stroke: 80`. Such a shape vanishes exactly when it turns edge-on. A stroke stays visible edge-on, so keep it 0 or thin, and add half the stroke to the distance.
## Turning animation
`renderSpinSvg(scene, options)` returns one SVG document that turns the view a full circle, forever, with SMIL animation and no JavaScript. It plays inside ` ` and GitHub READMEs. Without SMIL support the first frame shows, identical to `renderSvg(scene)`.
```ts
{
axis?: 'x' | 'y' | 'z', // default 'y': adds the turning angle to scene.rotate.y (a turntable)
duration?: number, // seconds per turn, >= 0.1, default 8
keyframes?: number, // integer 4..720, default 36; more = smoother and larger
direction?: 'positive' | 'negative', // default 'positive': the angle grows
precision?: number, // integer 0..10, default 1
}
```
Only a constant turn about one axis is possible; nothing else in the scene moves. Keep scenes small (tens of shapes): file size grows with the number of pieces and of overlapping pairs. Use opaque colors; translucent outlines show seams.
## Examples
Sphere with a ring:
```json
{
"width": 120,
"height": 120,
"rotate": { "x": -20, "y": 30 },
"children": [
{ "type": "dot", "stroke": 40, "color": "#e62" },
{ "type": "ellipse", "diameter": 70, "stroke": 5, "color": "#636", "rotate": { "x": 90 } }
]
}
```
Face with grouped features:
```ts
import { dot, group, path, renderSvg } from '@zpup/core';
const svg = renderSvg({
width: 160,
height: 160,
rotate: { y: -25 },
children: [
group({
id: 'head',
children: [
dot({ stroke: 90, color: '#f4c95d' }),
dot({ translate: { x: -16, y: -8, z: 40 }, stroke: 10, color: '#222' }),
dot({ translate: { x: 16, y: -8, z: 40 }, stroke: 10, color: '#222' }),
path({
id: 'smile',
translate: { y: 12, z: 42 },
path: [{ x: -14 }, { bezier: [{ x: -7, y: 10 }, { x: 7, y: 10 }, { x: 14 }] }],
stroke: 5,
color: '#222',
}),
],
}),
],
});
```
A longer example lives in `examples/pup.ts`.
## Common mistakes
- Radians (`1.57`, `Math.PI / 4`) -> angles are degrees (`90`, `45`).
- Origin at the top-left as in SVG -> (0, 0) is the center; x and y run from -width/2 to width/2. Negative `y` is up.
- `fill: "#fff"` -> `fill` is true or false; the color goes in `color`: `"color": "#fff", "fill": true`.
- `stroke: "#000"` or `"12px"` -> `stroke` is a width in scene units (`2`); its color is `color`.
- `type: "circle"` -> `"ellipse"` with `diameter`. `"line"` -> `"path"` with two points. `"sphere"` -> `"dot"` with a thick `stroke`. `"cube"` -> `"box"`.
- `radius` on an ellipse or round solid -> `diameter`. `height` on a cylinder or cone -> `length`.
- `color` on a `group` -> set it on the shapes inside.
## Not available yet
Canvas rendering, animation other than `renderSpinSvg`'s constant turn, perspective, React or other framework bindings.