Global cloud-coverage maps for any planet, generated offline from its physics. You give a body its rotation, radius, gravity and air, and optionally its land and relief. You get an equirectangular cloud-fraction map with weather in it: an equatorial convergence band, clear subtropics, storm tracks with cyclones that turn the right way in each hemisphere, fronts, and mesoscale cells. The map has no seam at the antimeridian and no pinch at the poles. No training, no AI: a Rust engine on the CPU and, when there is one, the GPU (wgpu).
It is meant for a renderer that loads baked maps, such as a game or a planetarium. The generator never runs at render time.
| Input | Effect | Module |
|---|---|---|
| Rotation, radius, gravity, scale height | Hadley edge (Held-Hou), placing every latitude band | rust/cloud-map-generator-core/src/climate.rs |
| Same | Rossby deformation radius: number and size of the cyclones, their handedness | rust/cloud-map-generator-core/src/flow.rs |
| Weather regime | Fine texture: closed cells, open cells, streets | rust/cloud-map-generator-core/src/texture.rs |
| Land and relief (optional) | Marine decks, dry subtropical land, uplift on the windward side and rain shadow, shift of the convergence band | rust/cloud-map-generator-core/src/surface.rs |
| — | Cloud type, high-cloud share, wind | rust/cloud-map-generator-core/src/products.rs |
| — | Tileable cell-field detail tile (heaps, closed cells, open cells, sheet) | rust/cloud-map-generator-core/src/tiles.rs |
| — | Measurements against Earth (spectrum, object sizes, zonal profile, land/sea contrasts) | rust/cloud-map-generator-core/src/metrics.rs |
The zonal profile is anchored on Earth's measured cloud fraction (data/, NASA Blue Marble). Only
water-cloud bodies are generated: Venus, Mars and Titan are refused, because their cloud amount is not
Earth's (climate.is_bakeable).
A Rust toolchain (stable). Nothing else: the page of the web UI is embedded in the binary.
cd rust
cargo build --release # target/release/cloud-map-generator and target/release/cloud-map-generator-mcpWithout a GPU stack: cargo build --release --no-default-features -p cloud-map-generator-cli (CPU only, no wgpu).
The cloud-map-generator binary has four commands and a server. Run it from anywhere inside the repository (the root is
the folder that holds data/ and examples/; CLOUD_MAP_GENERATOR_ROOT or --root overrides it).
cloud-map-generator gen --seed 42 --width 4096 # one map
cloud-map-generator gen --width 32768 --band-rows 256 # a 537-megatexel map, out of core (about 1 GiB of memory; see docs/large-maps.html)
cloud-map-generator measure output/earth_s42/coverage_earth_s42_4096x2048.png --sheet output/sheet.png
cloud-map-generator bake --version v1 --bodies examples/bodies.json # a set of bodies, with a manifest
cloud-map-generator tiles --version v1 # the cell-field detail tile
cloud-map-generator serve --port 8765 # the local web UI (page and JSON API)genwrites tooutput/earth_s42/: a 16-bit master, an 8-bit preview, a raw R8.gzfile with rows south-up, the products, and a sidecar JSON. Flags:--body earth|mars|titan|venus|fast(only water-cloud bodies generate unless--experiment),--texel-km,--match-earth,--isotropic,--surface <key> [--bodies <file>].bakewrites tooutput/bake/v1/withmanifest.json; paths start with--url-prefix(defaultbaked/v1). It also bakes a library of K seeds per climate class for procedural worlds (--only list|library,--k,--list-width,--library-width).serveoffers the compute modes auto, cpu, gpu (hybrid is not built yet); see ui/README.md.cloud-map-generator-mcpis the Model Context Protocol server for AI clients: see rust/cloud-map-generator-mcp/README.md.
Per-command details: rust/cloud-map-generator-cli/README.md. Measured on one dev machine, a 4096x2048 map takes about 25 s on one CPU thread and about 0.3 s on the GPU.
The tile preview shows each channel as a renderer draws it at 30, 50 and 70 % coverage. Judge the tile through that threshold, not as gray.
Run the tests:
cd rust
GOLDEN_ROOT=../golden/data/v1 cargo test --workspaceThe first Python version of the generator (the oracle the golden cases were frozen from) is kept in the git
tag python-reference.
cloud-map-generator serve is driven by a JSON API, described by an OpenAPI 3.1 document
(ui/static/openapi.json) and browsable with Swagger UI:
- locally:
http://127.0.0.1:8765/docs(the document at/openapi.json); - online: the API page of the demo, where "Try it out" is answered in the browser by the WebAssembly engine, with the same JSON as the local server.
The prose reference is ui/README.md.
examples/bodies.json, schema in rust/cloud-map-generator-service/src/bodies.rs. One record per body:
{
"key": "earth",
"rotationPeriodDays": 0.99727,
"radiusKm": 6371,
"gravityMps2": 9.81,
"scaleHeightKm": 8.4,
"cloudRegime": "water",
"measured": false,
"surface": null
}-
A negative rotation period is a retrograde spin.
-
measured: truemakes the bake skip the body (it already has a real map). -
surfacegives a body land and relief:{"width": 1024, "height": 512, "land": "earth_land_1024x512.u8", "elevation": "earth_elevation_1024x512.i16", "source": "..."}landis a raw u8 land fraction, 0 to 255.elevationis a raw little-endian int16, in meters above the sea.- Both grids are equirectangular, north-up, and stored relative to the bodies file.
- No land data ships with this repository: build the grids from a public DEM of your choice.
The sidecar JSON of each map records them:
| File | Encoding |
|---|---|
*_16bit.png |
Cloud fraction, 16-bit gray, north-up (the master) |
*.r8.gz |
Cloud fraction 0..255, rows SOUTH-up, gzip: ready for a GPU upload with the first row at the south pole |
*_high_share_*.png |
Share of the cloud above 440 hPa, 0..254 = 0..1 (255 = none) |
*_type_*.png |
0 stratiform .. 255 convective |
*_wind_*.png |
RGB, R east / G north, m/s = (byte - 128) x 0.5 |
cloud_cell_tiles_*.rgba.gz |
Detail tile, RGBA8; each channel a rank, floor(256 rank / texels) |
Each limit is a deliberate simplification, a model choice; the design log explains why.
- Frozen flow: vortices neither move nor evolve.
- No season.
- One storm track per hemisphere. A fast rotator would have several jets.
- Earth's cell sizes on every body.
- Weak marine decks: they hold on only 2 of 4 seeds.
- No cirrus layer, and fronts do not join one low to the next: the thin high cloud and the long frontal bands of real maps are the next step (docs/HISTORY.md, "Realism tuning").
- The fine texture is still recognizably procedural up close. That covers the fibres inside frontal shields and the irregularity of real cells.
The design log, with the measurements, the tuning rounds and a physics audit, is in docs/HISTORY.md.
- Earth's reference cloud fraction comes from NASA Goddard Space Flight Center / NASA Visible Earth, Blue Marble (2001, Terra MODIS). Details in data/README.md.
- The tool was first written for the Exokosm game.
MIT, see LICENSE. The license requires keeping the copyright notice in every copy or substantial portion of the software: anyone who uses or redistributes Cloud Map Generator must credit Benoit Podwinski.