Windgram

Why this project exists

Free flight has shaped my aviation career, and this is a landmark project within it. Windgram turns the work of understanding model output into something I can give back: an open pipeline and library that clubs, pilots, and other publishers can inspect, adapt, and run for themselves.

Windgram produces versioned profile documents and renders them. A downstream application decides where, when, and for whom those documents are presented. acrophobia.ca was the first downstream publisher and applies its own access and presentation choices.

The open-pipeline bet

Windgram publishes shareable inputs, makes derivations executable, versions the resulting document, and lets more than one frontend draw it. Readers can check the number behind a mark, compare a profile with its archived run, and build another presentation from the same science.

An acknowledged lineage

This work descends from canadarasp. canadarasp ran this kind of publication for years and kept its operations open enough for this project to learn from; the first derivations here were faithful ports of its constants. That is a debt worth naming. The jobs and architectures now differ: canadarasp draws national maps from a standing server, while Windgram derives site columns, publishes portable documents, and supplies a reusable renderer.

Portable state

Portable documents keep renderer decisions reversible. The prototype stored display units, pre-smoothed height series, a Pacific daylight window, and thresholds that belonged to one chart.

The current contract inverts those defaults: SI values, unsmoothed derived series, every forecast hour, published source fields, slugs as identity, declared field semantics, and a schemaVersion on every document. Presentation choices—timezone, window, palette, smoothing, overlays, and interaction— belong to the renderer or the downstream application.

Authority across the document boundary

Every published quantity has exactly one authority — the pipeline or the package, never both. Authority by quantity in the documentation overview is that split’s home; the figure below shows where each value lives.

Authority across the document boundary

The pipeline publishes authoritative values; the package derives views and projections from the document.

The pipeline derives stored quantities that need provider inputs or cross-run authority. The npm package derives pure functions, typed statements, and a parameterized usable-lift projection from the published document.

Authority across the document boundaryThe pipeline (pipeline/src/windgram/derive.py) derives boundary-layer top, thermal velocity, cloud base, and the default usable-lift top, and writes the published schema-version-1 document once per run. The windgram npm package reads only that document and owns humidity conversions, lapse and stability, thermal index and shear, day windowing with the timezone as a parameter, typed single-profile analysis, a sink-rate projection from the published inputs, the 1-2-1 smoothing option, and the scene-to-SVG renderer.THE PIPELINEpipeline/src/windgram/derive.py · buildersOWNS THE DERIVED COREboundaryLayerTopMdry parcel / environment crossingthermalVelocityMs · w*Deardorff scale: heat flux × depthcloudBaseMBolton LCL · saturated-layer floorusableLiftTopMpublished 1.0 m/s sink crossing · cloud capUses provider context beyond the hour blocks:GRIB fields · cross-run history; terrain is echoed in site.SCHEMAVERSION: 1The published documentdata/<model>/sites/<slug>.jsonsurfaceSI units · fluxes includedlevelsper level · every hourderivedfour core values · unsmoothedrun · sitereferenceTime · coordinatesTHE ONLY INTERFACE BETWEEN HOMESTHE PACKAGEnpm windgram · six subpath exportsPURE FUNCTIONS + TYPED STATEMENTShumidity conversionslapse · shear · sink-rate projectionanalyze — cited findings over one profileday windowing — timezone a parametersmooth121 — a renderer optionscene graph → SVG rendererConsumers run it wherever the JSON reaches,with thresholds, tokens, and windows kept downstream.writesper runreadsTHE RULENeeds inputs beyond the published JSON, or cross-run authority → the pipeline.A pure function of the published document → the package. No quantity lives in both.
Authority declared by pipeline/src/windgram/derive.py and the windgram package exports.Units Conceptual ownership map; no numeric scale

The versioned JSON between the pipeline and package carries model and site identity, times, units, declared provider semantics, source fields, and pipeline-derived values. The model catalogue states what each model can and cannot publish. Missing capability remains an honest absence, not a zero invented by a frontend.

Publishing

The pipeline fetches provider data, derives profiles, and publishes static artifacts. The package validates those artifacts and turns them into a scene or SVG. Club sites, personal publishers, and other downstream applications choose their schedule, hosting, location catalogue, access, retention, alerts, and presentation.

The documentation overview maps these responsibilities. Executable authority lives in pipeline/src/windgram/derive.py for pipeline derivations, toolkit/ for the contract and renderer, and models.json for the model catalogue.