# Compass Rose — `compass-rose@1.0.0`

A brass ship's compass with an engraved rose and a glass dome, its two-colour needle swinging and settling. Loops perfectly.

A ship's compass lying face up in studio light: a polished metal bowl, a card engraved with the thirty-two points of the rose, degrees and N, E, S, W, a glass dome and a red-and-white needle that swings, settles and hunts around the card. Choose the metal (brass, silver or rose gold), how far the needle swings, whether it also spins whole turns, the dome's opacity, the backdrop colour and whether the camera sways.

- Kind: object; status: published; digest sha256:2b172bba6c5cdb7ce2b6cbf53f187764a320269d0a43d736618d9e023e6a2be9
- Role: Object (3D, three.js): a travel, navigation and adventure showpiece with real brass and a believable needle.
- Implementation: three; entry `src/compass-rose.js`
- Files: https://aipixelwizard.com/registry/compass-rose/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/compass-rose.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/compass-rose/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/compass-rose/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
- `createCompass({ metal?, swing?, spins?, glass? }) => { group, setProgress(progress), dispose() }` — The compass (bowl, engraved card, needle, dome) as a group of radius 3 lying face up; needs an environment map.
- `METALS: { brass, silver, rosegold }` — Metal finishes with colour and roughness.

## Parameters
- `metal` (select one of brass | silver | rosegold, default "brass") — Metal
- `swing` (number 0–1.5, default 1) — Needle swing
- `spins` (integer 0–2, default 0) — Needle spins: Whole extra turns of the needle per loop.
- `glass` (number 0–0.6, default 0.3) — Glass opacity
- `background` (color, default "#16213a") — Backdrop
- `orbit` (boolean, default true) — Camera sway

## Composition
- Inputs: Time within the loop; the metal, needle swing, spins, glass, backdrop and camera sway.
- Outputs: A full frame rendered in 3D with a studio environment.
- Coordinates: The compass is centred on the origin with radius 3, lying in the xz plane, card face up (+y), north towards −z.
- Lighting: A warm key light with a shadow map and the studio environment.
- Timing: setProgress(progress) sets the needle heading; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- The card texture is drawn once on a 2048 canvas; the dome is transparent and drawn last.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — The needle's heading is a sum of sines of whole cycles of the loop plus whole turns, and the camera sway 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, give the scene a studio environment, add createCompass().group and call compass.setProgress(progress) each frame.

Existing project: Copy src/compass-rose.js; add the group to your scene with an environment map and a shadow-casting light.

Reuse ideas:
- Travel title: Brass, gentle swing.
- Night-sea mood: Silver, night blue.
- Energetic intro: Wild needle.

## Limitations
- The card's lettering uses the system serif font.
- The needle swings by a formula; it is not a physical simulation.

## 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/objects-scenes/compass-rose (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original studio object: a canvas-engraved 32-point card, a metal bowl, a glass dome and a swinging needle on an exact loop.