# Brass Armillary Sphere — `armillary-sphere@1.0.0`

An engraved brass armillary sphere, the astronomers' model of the sky, slowly turning on its stand. Loops perfectly.

A polished armillary sphere: nested rings for the celestial equator, tropics, polar circles and colures, a wide ecliptic band engraved with its degrees, a small enamel Earth at the centre and a gold Sun bead travelling the ecliptic, all held in an engraved meridian ring and horizon ring on a turned stand. The sky turns about its tilted axis while the camera drifts round it, and the rings cast a lattice of shadows on the floor. Choose the metal, the latitude the axis is set to, how many turns per loop, the Earth's finish and the backdrop colour.

- Kind: object; status: published; digest sha256:9c6ad08ee47b52d74783b25436f226e734e64ab5060e02cab7814224af993073
- Role: Hero object (Three.js 3D): a scientific instrument in polished metal for intros and end cards.
- Implementation: three; entry `src/armillary-sphere.js`
- Files: https://aipixelwizard.com/registry/armillary-sphere/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/armillary-sphere.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/armillary-sphere/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/armillary-sphere/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
- `createArmillarySphere({ metal?, latitude?, globe?, anisotropy? }) => { group, setProgress(progress, { turns? }), setAngles({ sky, sun, earth }), bounds, dispose() }` — The instrument as a THREE.Group (1 unit = the sky's radius, the stand down to y = −2). setProgress(0…1) moves it round one seamless loop.
- `METALS: { brass, gold, silver, bronze }` — The finishes: colour and roughness.

## Parameters
- `metal` (select one of brass | gold | silver | bronze, default "brass") — Metal
- `latitude` (number 0–90, default 38.5) — Latitude: Degrees: the polar axis is set this high above the horizon, as for a place on Earth.
- `turns` (integer 1–3, default 1) — Turns per loop
- `globe` (select one of enamel | metal, default "enamel") — Earth
- `background` (color, default "#13233a") — Backdrop
- `orbit` (boolean, default true) — Camera drift

## Composition
- Inputs: Loop progress 0…1 (or the angles of the sky, Sun and Earth directly).
- Outputs: A THREE.Group: the whole instrument with its stand, centred on the sky at the origin.
- Coordinates: 1 unit = the radius of the celestial rings; the horizon ring reaches 1.42 out and the base stands on y = −2. Scale the group to fit your scene.
- Lighting: Physical metal: needs an environment map (scene.environment) to look like metal; a shadow-casting key light shows off the ring shadows.
- Timing: setProgress(progress) is a pure function of progress; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, pocket-watch
- The engravings (hours on the equator, degrees on the ecliptic, meridian and horizon) are drawn once into textures; no image files.
- Latitude 38.5 is about Lisbon; 51.5 London; 40.7 New York; 0 puts the axis flat on the horizon, 90 straight up.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — The sky, the Sun bead and the Earth turn whole turns per loop and the camera drift is a sine of the loop progress, 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: Set scene.environment (createStudioEnvironment from Chrome Material works), add createArmillarySphere().group, and call setProgress(frame / totalFrames) each frame.

Existing project: Copy src/armillary-sphere.js. Add the group to your scene, scale it, and set the progress or the angles every frame.

Reuse ideas:
- Science or history intro: the brass preset with a title over the top third of the frame.
- Luxury backdrop: gold on black, camera drift on, behind a product name.
- In your own scene: add the group, scale it, and drive setAngles from anything (scroll, a clock).

## Limitations
- A decorative model: the rings and the Sun's motion follow the real geometry (obliquity, latitude), but it does not show real dates or star positions.
- Engraved numerals use the system serif font.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.
- three.js 0.185.1: MIT (https://github.com/mrdoob/three.js)

Provenance: Adapted from the owner's threejs-sketches/objects-scenes/astrolabe-align (MIT), rebuilt for AI Pixel Wizard in October 2026 as a true armillary sphere: celestial rings in their real geometry, engraved scales, an enamel Earth and Sun bead, a turned stand, a seamless loop and the frame/time contract.