142 lines
5.2 KiB
Markdown
142 lines
5.2 KiB
Markdown
# cloud_cover
|
||
|
||
Cloud cover forecast maps for astrophotography planning, powered by DWD open data.
|
||
|
||
|
||
|
||
## What is this?
|
||
|
||
The German Weather Service (DWD) publishes free, high-resolution numerical weather
|
||
predictions through its [open-data server](https://opendata.dwd.de/). The
|
||
**ICON-D2** model covers Germany and surrounding areas with ~2 km grid spacing and
|
||
produces forecasts up to 48 hours ahead, updated every 3 hours.
|
||
|
||
This tool downloads the **total cloud cover (CLCT)** field from ICON-D2 and renders
|
||
it as a series of map images — one per forecast hour — overlaid on an OpenStreetMap
|
||
base layer. The result is a quick visual answer to "will the sky be clear tonight?"
|
||
|
||
## Quick start
|
||
|
||
```sh
|
||
cargo build --release
|
||
./target/release/cloud_cover "2026-03-07T09:00:00Z" 24
|
||
```
|
||
|
||
Output appears in `cache/2026-03-07_09UTC/` — one PNG per forecast hour plus an
|
||
animated GIF.
|
||
|
||
## Usage
|
||
|
||
```
|
||
cloud_cover [OPTIONS] <ISO_TIMESTAMP> <HOURS>
|
||
```
|
||
|
||
| Argument | Description |
|
||
|---|---|
|
||
| `ISO_TIMESTAMP` | Model run time in ISO 8601, e.g. `2026-03-07T09:00:00Z` |
|
||
| `HOURS` | Number of forecast steps to render (0–48) |
|
||
|
||
The timestamp must match an ICON-D2 model run: every 3 hours starting at 00 UTC
|
||
(00, 03, 06, 09, 12, 15, 18, 21).
|
||
|
||
### Options
|
||
|
||
| Flag | Default | Description |
|
||
|---|---|---|
|
||
| `--center-lat` | 52.56 | Map centre latitude (°N) |
|
||
| `--center-lon` | 13.08 | Map centre longitude (°E) |
|
||
| `--zoom` | 10 | OSM tile zoom level (higher = more detail, smaller area) |
|
||
| `--no-basemap` | — | Skip OSM tiles; use a plain green background |
|
||
|
||
### Examples
|
||
|
||
```sh
|
||
# Next 12 hours from the 18 UTC run, default viewport (Falkensee / Berlin)
|
||
./target/release/cloud_cover "2026-03-06T18:00:00Z" 12
|
||
|
||
# Wider area centred on central Germany at zoom 8
|
||
./target/release/cloud_cover "2026-03-07T06:00:00Z" 24 \
|
||
--center-lat 51.0 --center-lon 10.5 --zoom 8
|
||
|
||
# Quick run without map tiles
|
||
./target/release/cloud_cover "2026-03-07T09:00:00Z" 6 --no-basemap
|
||
```
|
||
|
||
## Output
|
||
|
||
Each run produces files in `cache/<date>_<hour>UTC/`:
|
||
|
||
- **`clct_000001.png` … `clct_NNNNNN.png`** — one 900 × 600 px map per forecast
|
||
hour, showing cloud cover blended over the OSM base layer with a colour legend
|
||
- **`clct_animation.gif`** — animated loop of all frames (generated when there are
|
||
multiple steps)
|
||
- **`clat.grib2`, `clon.grib2`, `clct_NNN.grib2`** — cached raw forecast data;
|
||
re-running the same timestamp skips the download
|
||
|
||
Image titles show the forecast time converted to CET/CEST (Europe/Berlin). The first
|
||
frame is labelled "Conditions at …", subsequent frames "Prediction at … (+NNh)".
|
||
|
||
Cloud cover is rendered as a continuous blend from the base map (clear sky) toward a
|
||
light blue-white tone (overcast), matching the style familiar from weather apps.
|
||
|
||
## How it works
|
||
|
||
1. **Download** — Fetches bzip2-compressed GRIB2 files from the DWD open-data
|
||
server: two coordinate grids (`clat`, `clon`) describing the ~542,000 points of
|
||
the ICON-D2 icosahedral grid over Germany, plus one `clct` file per forecast step.
|
||
Downloads run in parallel and are cached to disk.
|
||
|
||
2. **Parse** — A built-in minimal GRIB2 decoder extracts the data arrays. Only
|
||
simple packing (data representation template 0) is implemented, which is the
|
||
format DWD uses for these fields. Grid points flagged absent by the GRIB2 bitmap
|
||
are set to NaN.
|
||
|
||
3. **Interpolate** — The irregular grid points are projected into pixel space via an
|
||
orthographic projection, then connected into a Delaunay triangulation. Each output
|
||
pixel is interpolated via barycentric coordinates within its enclosing triangle,
|
||
followed by a NaN-aware Gaussian blur to smooth triangle edges.
|
||
|
||
4. **Render** — The base layer comes from Carto Voyager OSM tiles (fetched and
|
||
cached separately for the basemap and for labels). Cloud cover is blended on top,
|
||
then map labels are composited above the clouds. City markers, a title bar, and a
|
||
colour legend complete the frame.
|
||
|
||
5. **Animate** — All frames are colour-quantised to 256-colour palettes (in parallel)
|
||
and assembled into a looping GIF.
|
||
|
||
## Dependencies
|
||
|
||
All dependencies are pure Rust or vendored C compiled into the binary — no system
|
||
shared libraries are required at runtime beyond libc.
|
||
|
||
| Crate | Role |
|
||
|---|---|
|
||
| `reqwest` (rustls-tls) | HTTP client with pure-Rust TLS |
|
||
| `bzip2` | Bzip2 decompression (vendors libbzip2) |
|
||
| `plotters` + `plotters-bitmap` | PNG rendering |
|
||
| `font8x8` | Built-in 8×8 bitmap font for map labels |
|
||
| `clap` | CLI argument parsing |
|
||
| `chrono` + `chrono-tz` | Date/time handling and timezone conversion |
|
||
| `anyhow` | Error propagation |
|
||
| `spade` | Delaunay triangulation for grid interpolation |
|
||
| `rayon` | Parallel downloads, rendering, and GIF quantisation |
|
||
| `image` | PNG decoding (loading frames for GIF assembly) |
|
||
| `gif` | GIF encoding |
|
||
|
||
## Building
|
||
|
||
```sh
|
||
cargo build --release
|
||
```
|
||
|
||
The binary is at `target/release/cloud_cover`.
|
||
|
||
## Future ideas
|
||
|
||
- Configurable display timezone (currently hardcoded to Europe/Berlin)
|
||
- Configurable city markers / observation sites
|
||
- Configurable data sources
|
||
- Vector map tile support for increased rendering resolution
|
||
- Separation of cache and output files & automatic cache management
|
||
- Automatic newest prediction fetching
|