Iridescent crystal
A turning, iridescent SDF crystal: a deterministic turntable of N frames matches toleranced goldens, with optional documented stills.
This is an animation spec on Spekkr, published by onyx. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.
- Spec
onyx/iridescent-crystal- Version
- 0.2.1
- Published by
- onyx
- Updated
- 14 Nov 2026
Build this spec
Build the spec at https://spekkr.com/onyx/iridescent-crystal/start.md.
Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.
Published by onyx.
What does the result look like?
What can I customize?
Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.
What do I get?
-
spec.mdRequirements and acceptance checks.Iridescent crystal
What this builds
A short, lush loop: a crystal, defined as an SDF, turns on a turntable, with an optional iridescent shading. The look is original. A deterministic turntable of N frames is compared to goldens with a stated tolerance. Optional stills at documented camera poses are included. The CPU renderer is the CI reference; a shader may be compared with a looser tolerance. No film set and no capture stage are required.
Read
spekkr.inputs.jsonfirst.framesis a full turn.widthandheightsize the picture.iridescenceandenvironmentchange the shade.rendereris the engine. Tests pin a seed if noise is used; the default has no noise, or a seeded one.Out of scope
- A live environment probe, a film set, or a photogrammetry capture.
- A copyrighted gem photograph as the product.
- A network render farm in the checks.
Requirements
Each requirement has an id. Checks name the id they cover.
R1. The turntable
- A full turn of
framesframes, camera as indesign.md, is deterministic: two CPU runs hash the same frames, or match within 1 level if a documented float slack exists. - Frame 0, a quarter turn, and a half turn match goldens within the tolerance in the file (tighter on the CPU reference).
- If
iridescenceis off, a still dielectric term is used, and a fourth golden or a documented skip applies.
Accept when: the two CPU runs agree, and the three (or four) goldens match within tolerance.
R2. Poses, files
- Optional stills at the camera poses in
fixtures/crystal-poses.json(for example a close-up) match goldens. - One command renders the turntable and the stills, compares, and writes the four named shots. No network. CI uses the CPU reference.
- A seed, if any, is pinned. A hook fails if a live HDRI host is contacted.
Accept when: the command passes, the hook stays quiet, and a deliberately wrong SDF (a sphere) fails the crystal goldens.
R3. Inputs
- Inputs are read from
spekkr.inputs.json.fps,holdorframesand the frame size stay inside the ranges indesign.md. - A value outside a range is refused before a render.
Accept when: an illegal input is refused by name, and the default timeline has the frame count in
design.md.R4. Checks and report
- One command runs every acceptance check at the defaults and at the person's inputs, including golden frames where a requirement asks for them.
- Checks do not need a network, a paid API, or physical hardware.
Accept when: the command passes at the defaults, and a deliberately broken fixture or a wrong price fails it.
Verification
A deterministic turntable of N frames matches toleranced goldens on a CPU reference. Optional stills at documented camera poses are checked. Iridescence is a documented shader term, not a lab measurement. No film set, no capture stage, and no network are required.
Definition of done
- Every acceptance check above runs from one command, and all pass at the person's inputs.
- A README says how to render the loop, how the CPU reference is run, and how tolerances are listed.
# Iridescent crystal ## What this builds A short, lush loop: a crystal, defined as an SDF, turns on a turntable, with an optional iridescent shading. The look is original. A deterministic turntable of N frames is compared to goldens with a stated tolerance. Optional stills at documented camera poses are included. The CPU renderer is the CI reference; a shader may be compared with a looser tolerance. No film set and no capture stage are required. Read `spekkr.inputs.json` first. `frames` is a full turn. `width` and `height` size the picture. `iridescence` and `environment` change the shade. `renderer` is the engine. Tests pin a seed if noise is used; the default has no noise, or a seeded one. ## Out of scope - A live environment probe, a film set, or a photogrammetry capture. - A copyrighted gem photograph as the product. - A network render farm in the checks. ## Requirements Each requirement has an id. Checks name the id they cover. ### R1. The turntable - A full turn of `frames` frames, camera as in `design.md`, is deterministic: two CPU runs hash the same frames, or match within 1 level if a documented float slack exists. - Frame 0, a quarter turn, and a half turn match goldens within the tolerance in the file (tighter on the CPU reference). - If `iridescence` is off, a still dielectric term is used, and a fourth golden or a documented skip applies. Accept when: the two CPU runs agree, and the three (or four) goldens match within tolerance. ### R2. Poses, files - Optional stills at the camera poses in `fixtures/crystal-poses.json` (for example a close-up) match goldens. - One command renders the turntable and the stills, compares, and writes the four named shots. No network. CI uses the CPU reference. - A seed, if any, is pinned. A hook fails if a live HDRI host is contacted. Accept when: the command passes, the hook stays quiet, and a deliberately wrong SDF (a sphere) fails the crystal goldens. ### R3. Inputs - Inputs are read from `spekkr.inputs.json`. `fps`, `hold` or `frames` and the frame size stay inside the ranges in `design.md`. - A value outside a range is refused before a render. Accept when: an illegal input is refused by name, and the default timeline has the frame count in `design.md`. ### R4. Checks and report - One command runs every acceptance check at the defaults and at the person's inputs, including golden frames where a requirement asks for them. - Checks do not need a network, a paid API, or physical hardware. Accept when: the command passes at the defaults, and a deliberately broken fixture or a wrong price fails it. ## Verification A deterministic turntable of N frames matches toleranced goldens on a CPU reference. Optional stills at documented camera poses are checked. Iridescence is a documented shader term, not a lab measurement. No film set, no capture stage, and no network are required. ## Definition of done - Every acceptance check above runs from one command, and all pass at the person's inputs. - A README says how to render the loop, how the CPU reference is run, and how tolerances are listed.
-
design.mdTurntable timing, camera poses, iridescence, and golden-frame tolerances.Design
This file fixes the timeline, the camera and the frame counts. The renderer can vary, as long as the numbers here hold.
Camera
A turntable about the vertical axis, radius and height in
fixtures/crystal-camera.json. Frame i is angle360 * i / framesdegrees.Tolerance
CPU reference: 4 levels, 99% of pixels, or an exact hash if the file says so. Shader versus CPU: 12 levels, 96% of pixels, optional in CI.
SDF
An original crystal (a combination of a polyhedron and a few cuts), in
fixtures/crystal-sdf.txtor in code with a comment that points at the file.Inputs
Key Label Default Notes framesTurntable frames 36 From 12 to 72, a full turn. widthFrame width 960 640, 960 or 1280. heightFrame height 540 360, 540 or 720, or equal to width for a square. iridescenceIridescence on A documented wavelength-dependent term. If off, a still dielectric is used. environmentA simple environment on A shipped lighting environment, not a live probe. rendererRenderer shader shader is a GPU or WebGL marcher. cpu is a software marcher used as the CI reference. Acceptance at the defaults
A turntable of an original SDF crystal. Default 36 frames, 960 × 540, iridescence and a simple environment on.
Quantity Value Tolerance Source Frame count 36 0 A full turn, frame i at 360 * i / 36 degrees Frame size 960 × 540 exact width×heightCamera radius, height 3.00, 0.80 0.01 Scene units, in the camera file Look-at (0, 0, 0) exact The crystal's origin Iridescence a thin-film term, 0.4 µm — When iridescenceis onA CPU marcher is the CI reference. Frames 0, 9, 18 and 27 are goldens (4 levels, 99% of pixels against the CPU). A shader path, when chosen, may be looser (12 levels, 96%) and is optional in CI. The SDF is original.
Screenshots
These pictures are frames from the reference renderer in
reference/preview.py, at the default inputs. They are not drawings of a product that has not been built or simulated. The first picture is the one Spekkr shows on the spec's card. A build may ship its own goldens; those goldens are of that build and do not have to match these frames pixel-for-pixel.File What it shows shots/pose-0.pngCrystal frame 0 of 36, 960 × 540, iridescence on shots/pose-9.pngCrystal frame 9 of 36 (90°), 960 × 540 How to verify
- Render the documented frames at the default
fps, size and hold or frame count. - Compare each named golden to the timeline or camera file in this document, within the stated tolerance.
- Confirm the total frame count matches the table.
- A deterministic turntable of N frames matches toleranced goldens on a CPU reference. Optional stills at documented camera poses are checked. Iridescence is a documented shader term, not a lab measurement. No film set, no capture stage, and no network are required.
# Design This file fixes the timeline, the camera and the frame counts. The renderer can vary, as long as the numbers here hold. ## Camera A turntable about the vertical axis, radius and height in `fixtures/crystal-camera.json`. Frame i is angle `360 * i / frames` degrees. ## Tolerance CPU reference: 4 levels, 99% of pixels, or an exact hash if the file says so. Shader versus CPU: 12 levels, 96% of pixels, optional in CI. ## SDF An original crystal (a combination of a polyhedron and a few cuts), in `fixtures/crystal-sdf.txt` or in code with a comment that points at the file. ## Inputs | Key | Label | Default | Notes | | --- | --- | --- | --- | | `frames` | Turntable frames | 36 | From 12 to 72, a full turn. | | `width` | Frame width | 960 | 640, 960 or 1280. | | `height` | Frame height | 540 | 360, 540 or 720, or equal to width for a square. | | `iridescence` | Iridescence | on | A documented wavelength-dependent term. If off, a still dielectric is used. | | `environment` | A simple environment | on | A shipped lighting environment, not a live probe. | | `renderer` | Renderer | shader | shader is a GPU or WebGL marcher. cpu is a software marcher used as the CI reference. | ## Acceptance at the defaults A turntable of an original SDF crystal. Default 36 frames, 960 × 540, iridescence and a simple environment on. | Quantity | Value | Tolerance | Source | | --- | --- | --- | --- | | Frame count | 36 | 0 | A full turn, frame i at 360 * i / 36 degrees | | Frame size | 960 × 540 | exact | `width` × `height` | | Camera radius, height | 3.00, 0.80 | 0.01 | Scene units, in the camera file | | Look-at | (0, 0, 0) | exact | The crystal's origin | | Iridescence | a thin-film term, 0.4 µm | — | When `iridescence` is on | A CPU marcher is the CI reference. Frames 0, 9, 18 and 27 are goldens (4 levels, 99% of pixels against the CPU). A shader path, when chosen, may be looser (12 levels, 96%) and is optional in CI. The SDF is original. ## Screenshots These pictures are frames from the reference renderer in `reference/preview.py`, at the default inputs. They are not drawings of a product that has not been built or simulated. The first picture is the one Spekkr shows on the spec's card. A build may ship its own goldens; those goldens are of that build and do not have to match these frames pixel-for-pixel. | File | What it shows | | --- | --- | | `shots/pose-0.png` | Crystal frame 0 of 36, 960 × 540, iridescence on | | `shots/pose-9.png` | Crystal frame 9 of 36 (90°), 960 × 540 | ## How to verify 1. Render the documented frames at the default `fps`, size and hold or frame count. 2. Compare each named golden to the timeline or camera file in this document, within the stated tolerance. 3. Confirm the total frame count matches the table. 4. A deterministic turntable of N frames matches toleranced goldens on a CPU reference. Optional stills at documented camera poses are checked. Iridescence is a documented shader term, not a lab measurement. No film set, no capture stage, and no network are required.
- Render the documented frames at the default
-
tasks.mdBuild tasks in order, each with a check.Tasks
Work in order. Finish a task's check before starting the next.
- Set up. Set up the renderer in the
rendererinput. Read the inputs and the timeline or camera file into one place. Check: a single blank or title frame renders at the stated size. - The turntable (R1). Build what
R1. The turntableasks for, to the numbers indesign.md. In particular: A full turn offramesframes, camera as indesign.md, is deterministic: two CPU runs hash the same frames, or match within 1 level if a documented float slack exists. Check: theR1. The turntableacceptance checks pass. - Poses, files (R2). Build what
R2. Poses, filesasks for, to the numbers indesign.md. In particular: Optional stills at the camera poses infixtures/crystal-poses.json(for example a close-up) match goldens. Check: theR2. Poses, filesacceptance checks pass. - Inputs (R3). Build what
R3. Inputsasks for, to the numbers indesign.md. In particular: Inputs are read fromspekkr.inputs.json.fps,holdorframesand the frame size stay inside the ranges indesign.md. Check: theR3. Inputsacceptance checks pass. - Checks and report (R4). Build what
R4. Checks and reportasks for, to the numbers indesign.md. In particular: One command runs every acceptance check at the defaults and at the person's inputs, including golden frames where a requirement asks for them. Check: theR4. Checks and reportacceptance checks pass. - Goldens. Capture the frames named in
design.mdat the defaults, with motion frozen where the file says so. Compare them within the stated tolerance. Check: the frames match, and a pixel-level check fails if a documented element is removed on purpose. - Finish. Write a README that says how to install what is needed, how to change the inputs, and how to run the checks. Run the one command from a clean folder. Check: every item under Definition of done in
spec.mdis true.
# Tasks Work in order. Finish a task's check before starting the next. 1. **Set up.** Set up the renderer in the `renderer` input. Read the inputs and the timeline or camera file into one place. Check: a single blank or title frame renders at the stated size. 2. **The turntable (R1).** Build what `R1. The turntable` asks for, to the numbers in `design.md`. In particular: A full turn of `frames` frames, camera as in `design.md`, is deterministic: two CPU runs hash the same frames, or match within 1 level if a documented float slack exists. Check: the `R1. The turntable` acceptance checks pass. 3. **Poses, files (R2).** Build what `R2. Poses, files` asks for, to the numbers in `design.md`. In particular: Optional stills at the camera poses in `fixtures/crystal-poses.json` (for example a close-up) match goldens. Check: the `R2. Poses, files` acceptance checks pass. 4. **Inputs (R3).** Build what `R3. Inputs` asks for, to the numbers in `design.md`. In particular: Inputs are read from `spekkr.inputs.json`. `fps`, `hold` or `frames` and the frame size stay inside the ranges in `design.md`. Check: the `R3. Inputs` acceptance checks pass. 5. **Checks and report (R4).** Build what `R4. Checks and report` asks for, to the numbers in `design.md`. In particular: One command runs every acceptance check at the defaults and at the person's inputs, including golden frames where a requirement asks for them. Check: the `R4. Checks and report` acceptance checks pass. 6. **Goldens.** Capture the frames named in `design.md` at the defaults, with motion frozen where the file says so. Compare them within the stated tolerance. Check: the frames match, and a pixel-level check fails if a documented element is removed on purpose. 7. **Finish.** Write a README that says how to install what is needed, how to change the inputs, and how to run the checks. Run the one command from a clean folder. Check: every item under Definition of done in `spec.md` is true.
- Set up. Set up the renderer in the
-
reference/preview.pyA CPU reference marcher of the default crystal and camera. -
reference/preview.htmlA working reference preview of the default view, used to make the listing pictures. A build does not have to start from this file.
Is it for me?
- Kind
- animation
- Tools
- TypeScript, WebGL, Python
What does it need?
- Agent permissions
- shell
- Commands it runs
install a ray-marching renderer, in a shader or in Pythoninstall a tool that compares frames
What changed?
- 0.2.114 Nov 2026Add animated loop to the listing shots.
- 0.2.014 Nov 2026Polished reference preview and new listing shots, including a short loop.
- 0.1.014 Nov 2026First version.
For agents: start.md says how to build this spec, and spec.json holds everything on this page, with the address of every file.