Skydome CLI

A Node.js CLI that, given a latitude/longitude, fetches one typical meteorological year (TMY) of irradiance from the PVGIS TMY API, builds a HEALPix (nside=4) sky radiance dome using the physics of the archived Python notebooks in archive/, and writes a single JSON file in the shape of test/data/irradiance_50.0_10.0_2018_yearly.json.

Install / run

npm link          # exposes the `skydome` command (or run: node bin/skydome)
skydome 50 10 -o irradiance_50.0_10.0_yearly.json

Or without linking:

node bin/skydome 50 10 -o out.json

CLI contract

skydome <lat> <lon> [--nside 4] [-o out.json]

• --nside sets the HEALPix resolution (default 4 → 192 pixels, 88 above horizon).
• -o/--output sets the output path; default is irradiance_<lat>_<lon>_yearly.json.
• Exits 1 with a clear message on network, parse, or validation errors.

Physics

For each daylight hour (solar zenith < 90°) and each HEALPix pixel:

• Diffuse: isotropic L = DHI/π on every above-horizon pixel.
• Direct: DNI / pixel_solid_angle added to the pixel containing the sun.

Annual averaging reproduces the reference quirks: per-pixel radiance is the mean over daylight hours, then scaled by daylight/total (the "all-hours" average, i.e. the raw sum divided by 8760). Metadata reports daylight-hour means.

Solar position uses a NOAA-compatible algorithm (accurate to ~0.1° vs pvlib's SPA), and the HEALPix grid is an exact port of the canonical RING operators (matching healpy).

Tests

npm test

Runs node --test (offline, using the cached PVGIS fixture):

• geometry of the HEALPix grid matches test/data exactly (88 pixels, ring order)
• solar position vs published values
• hand-computed skydome physics cases
• end-to-end pipeline from the cached fixture + radiance↔GHI physics self-check

Out of scope (for now)

• Monthly outputs (reference is yearly).