# Dupin Cyclide — `dupin-cyclide@1.0.0`

A smooth iridescent cyclide that breathes from a fat ring to a lopsided loop and back while it turns. Loops perfectly.

A Dupin cyclide: the smooth surface that bends, pinches and swells as its two shape numbers change, the generalisation of the torus. Here the numbers glide round a closed circle of values, so the surface breathes between a fat ring and a lopsided pear-shaped loop while it turns in space and an iridescent finish plays across it. Choose the finish (iridescent, chrome, pearl or gold), whether a net of curves lies on the surface, the mesh fineness, the turns per loop, how far the shape changes, the backdrop colour and whether the camera sways.

- Kind: object; status: published; digest sha256:600a2db12eed39274f4307017c07866cd8eca9bbc13f4a32aa8a629a156425f5
- Role: Object (3D, three.js): a mathematical showpiece with a liquid, iridescent look for science, design and tech content.
- Implementation: three; entry `src/dupin-cyclide.js`
- Files: https://aipixelwizard.com/registry/dupin-cyclide/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/dupin-cyclide.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/dupin-cyclide/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/dupin-cyclide/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer, geometry and shader materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createCyclide({ finish?, lines?, detail?, turns?, morph? }) => { group, setProgress(progress), dispose() }` — The morphing cyclide (about 4.4 across, centred on the origin); needs an environment map.
- `FINISHES: { iridescent, chrome, pearl, gold }` — Surface finishes: colour, metalness, roughness, iridescence and film index.

## Parameters
- `finish` (select one of iridescent | chrome | pearl | gold, default "iridescent") — Finish
- `lines` (boolean, default true) — Surface lines
- `detail` (number 0.6–1.4, default 1) — Mesh detail
- `turns` (integer 0–3, default 1) — Turns per loop
- `morph` (number 0–1.5, default 1) — Shape change
- `background` (color, default "#161a28") — Backdrop
- `orbit` (boolean, default true) — Camera sway

## Composition
- Inputs: Time within the loop; the finish, lines, detail, turns, shape change, backdrop and camera sway.
- Outputs: A full frame rendered in 3D with a studio environment.
- Coordinates: The cyclide is centred on the origin, scaled to a fixed root-mean-square radius of 2, hung 3.3 above the floor.
- Lighting: A warm key light with a shadow map and the studio environment.
- Timing: setProgress(progress) rewrites the mesh from a closed form; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- About 11 000 vertices are rewritten on the CPU each frame and the seam normals are averaged.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — The two shape numbers are sines of the loop, the surface turns a whole number of times per loop and the camera sway is a sine of the loop, so the last frame meets the first.
- Verified 2026-10-05 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer with a studio environment, add createCyclide().group and call cyclide.setProgress(progress) each frame.

Existing project: Copy src/dupin-cyclide.js; add the group to your scene with an environment map.

Reuse ideas:
- Maths title: Iridescent, one turn.
- Product-style loop: Chrome, bare.
- Warm accent: Gold, big morph.

## Limitations
- The surface is scaled to a steady size, so its horns and pinches change apparent proportions.
- The ring cyclide has a singular point at its horn at the extreme of the morph, softened by the limited range.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/geometry-math/dupin-cyclide (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original studio object: the ring cyclide's closed form with its two shape numbers on a closed loop, a size-steady mesh rewritten each frame and an iridescent finish on an exact loop.