# Blue Marble — `blue-marble@1.0.0`

A turning blue planet with continents, swirling clouds, a glowing rim and the lights of night cities. Loops perfectly.

An Earth-like planet seen from space: invented continents and oceans drawn from seeded noise, with forests, deserts, mountains and ice caps coloured by height and latitude; a shell of swirling cloud that slides over the land; a blue haze of atmosphere along the rim; the sun low to one side so there is a day side, a terminator and a night side glittering with the lights of cities; and a field of stars. Choose an earthlike or a desert world, the seed, how much of it is ocean, the clouds, the atmosphere, where the sun is and whether the camera pushes in.

- Kind: object; status: published; digest sha256:a6b1dbf49705db559b33118a639555db090f32f8872c3fc2e3f9aafccf3b6c37
- Role: Object (3D, three.js): a cinematic space backdrop for science, tech, environment and sci-fi content.
- Implementation: three; entry `src/blue-marble.js`
- Files: https://aipixelwizard.com/registry/blue-marble/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/blue-marble.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/blue-marble/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/blue-marble/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.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createBluePlanet({ kind?, seed?, ocean?, clouds?, atmosphere?, sunAngle? }) => { group, sunDirection, setProgress(progress), dispose() }` — The planet, its cloud shell, atmosphere and stars as a group (radius 2); no lights needed: the sun is in the shaders.

## Parameters
- `kind` (select one of earth | arid, default "earth") — World
- `seed` (integer 1–999, default 5) — Seed
- `ocean` (number 0.2–0.8, default 0.5) — Ocean: How much of the surface is sea.
- `clouds` (number 0–1.2, default 1) — Clouds
- `atmosphere` (number 0–1.5, default 1) — Atmosphere
- `sun` (number 10–90, default 40) — Sun angle: Degrees from the camera's side.
- `zoom` (boolean, default true) — Push in

## Composition
- Inputs: Time within the loop; the kind of world, seed, ocean, clouds, atmosphere, sun angle and push-in.
- Outputs: A full frame rendered in 3D with shader-lit spheres.
- Coordinates: The planet (radius 2) is at the origin with the sun in direction (sin a, 0.18, cos a); the camera looks at it from z ≈ 9.5.
- Lighting: Self-lit by shaders: Lambert day side, an ocean sun glint, night-side city lights, a cloud shell lit by the same sun and an additive Fresnel atmosphere that is brighter on the sun side.
- Timing: setProgress(progress) sets the two spins; frames render in any order.
- Works with: kinetic-title, number-reveal
- The colour map (1024 × 512) is drawn once from three octaves of seeded 3D noise sampled on the sphere, so it has no seam or pole pinch; the alpha channel marks where city lights glow; the cloud map is a domain-warped fractal.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — The planet turns once and the cloud shell twice per loop, and the camera push-in is a cosine 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 tone mapping, add createBluePlanet().group to a scene on a dark background and call planet.setProgress(progress) each frame.

Existing project: Copy src/blue-marble.js; add planet.group to your scene (no lights needed).

Reuse ideas:
- Climate or science title: Earthlike, evening terminator.
- Sci-fi opener: Desert world.
- Global network backdrop: Water world.

## Limitations
- The world is invented, not real geography; there is no relief shading or normal map, so mountains read by colour only.
- No moon and no city lights on the day side.

## 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/space-cosmic/blue-marble (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original object: seam-free seeded continents and swirled clouds baked from 3D noise, a day/terminator/night shader with ocean glint and city lights, a Fresnel atmosphere and whole-turn motion for an exact loop.