# Brass Orrery — `orrery@1.0.0`

A brass orrery: a golden Sun lighting six enamel planets on turning arms, a tower of gear wheels at its foot. Loops perfectly.

An eighteenth-century orrery in polished brass: a golden Sun with a ring of rays on a column, and on arms of different heights the planets from Mercury to Saturn (enamelled and banded, Earth with its tilted axis and its Moon, Saturn in brass hoops) circling it, the nearest fastest; at the foot of the column a tower of gear wheels, one to each arm, turns with it; the whole stands on a turned walnut base with a bevelled brass rim, an engraved dial and the orbits scored in it. The Sun is the light: it shades the planets into day and night and throws the arms' shadows across the base. Choose the metal, how many planets, the pace, the Moon, the gears, the Sun's brightness, the backdrop and whether the camera drifts round it.

- Kind: object; status: published; digest sha256:4e4c78e04fc2b4d259bf70ef102bf2c019eedf1911bb111dd40f7fee56c92863
- Role: Object (3D, three.js): a product-style hero object for science, history, time and "how it works" content.
- Implementation: three; entry `src/orrery.js`
- Files: https://aipixelwizard.com/registry/orrery/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/orrery.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/orrery/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/orrery/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 physical materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createOrrery({ metal?, planets?, moon?, gears?, anisotropy? }) => { group, sunPosition, planets, setProgress(progress, { speed? }), dispose() }` — The orrery as a group of meshes (1 unit ≈ a hand's breadth; base radius 3.2, Sun at y = 1.5); add it to a scene with an environment map and a point light at sunPosition.
- `PLANETS: { name, r, size, turns, spin, surface, phase, … }[]` — The six planets: orbit radius, size, turns round the Sun and on their axes per loop.
- `METALS: { brass, gold, silver, bronze }` — Metal finishes: colour (sRGB) and roughness.

## Parameters
- `metal` (select one of brass | gold | silver | bronze, default "brass") — Metal
- `planets` (integer 3–6, default 6) — Planets: How many planets, nearest the Sun first.
- `speed` (integer 1–3, default 1) — Pace: A whole-number factor on every motion; 1 turns Saturn once a loop.
- `moon` (boolean, default true) — Moon
- `gears` (boolean, default true) — Gear wheels
- `sun` (number 0.4–2, default 1) — Sun's light
- `background` (color, default "#14192b") — Backdrop
- `orbit` (boolean, default true) — Camera drift

## Composition
- Inputs: Time within the loop; the metal, the number of planets, the pace, the Moon, the gears, the Sun's light, the backdrop and the camera drift.
- Outputs: A full frame, rendered in 3D with shadows and a studio environment.
- Coordinates: The base is a disc of radius 3.2 on the plane y = 0, the column rises to the Sun at y = 1.5; planets circle at radii 0.72 … 2.68 in the plane y = 1.5; the camera orbits a point at y = 0.95.
- Lighting: The Sun is a warm point light at the centre with a shadow map: it shades the planets into day and night and casts the arms' shadows on the base; a dim key light and a studio environment give the brass its reflections.
- Timing: setProgress(progress) sets every angle as a whole number of turns of the loop; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- Planet surfaces and the engraved dial are drawn once with Canvas 2D from fixed seeds (CPU-backed canvases), so frames are identical from run to run.
- The gear wheels are extruded 2D shapes with teeth and spoke openings; each turns with its arm.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — Every arm turns a whole number of times per loop (Mercury eight, Venus five, Earth four, Mars three, Jupiter two, Saturn one, each times the pace), the planets spin and the Moon circles the Earth in whole turns, and the camera drift is a sine of the loop, so the last frame meets the first.
- Verified 2026-10-06 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 shadows, a studio environment (see chrome-material), createOrrery(), a PointLight at orrery.sunPosition with castShadow; add orrery.group to the scene and call orrery.setProgress(progress) each frame.

Existing project: Copy src/orrery.js; add orrery.group to your scene (with an environment map so the brass reflects something) and a point light at orrery.sunPosition.

Reuse ideas:
- Science or history-of-science explainer: Brass, six planets.
- Fantasy or steampunk title: Antique bronze, warm study.
- Quiet product-style loop: Silver, midnight blue.

## Limitations
- The distances and sizes are not to scale and the periods are whole-number ratios chosen to loop, not the real ones.
- Pluto and the outer planets are not modelled; Saturn's rings are brass hoops, not a disc.
- The Sun is a lit emissive ball with a sprite glow, not a light source in the render's physics beyond the point light.

## 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/mechanical-kinetic/orrery (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original object: a Sun-lit instrument with textured enamel planets, tilted axes, a Moon, extruded gear wheels, an engraved dial, shadows from the Sun and whole-turn motion for an exact loop.