nz-solar-potential

Architecture

Data flow and module responsibilities for developers. For command delegation, machine boundaries and build-engine differences, use tooling and execution. For validation tools and review rules, use the reviewer’s guide.

What it is

A Python geospatial pipeline and a static MapLibre map. The pipeline turns LINZ building outlines, LiDAR, elevation models and aerial imagery into per-building roof faces, panel layouts and yields. The map (preview.html) reads the published tiles and does the money maths in the browser.

Data flow

This is a conceptual producer/consumer view, not a launcher call graph or an exact stage schedule. Vision is optional in the local pipeline and a separate preparation step for district builds.

flowchart TB
  LINZ[(LINZ source datasets)] --> Fetch[[fetch_data / fetch_regions]]
  Fetch --> Inputs[(data/regions/name)]
  Inputs --> Vision[[predict_faces: SAM / line detector / LiDAR candidates + scorer]]
  Vision --> Selected[(data/selected_faces/id.json)]
  Selected --> Segment
  Inputs --> OutlineFit[[outline_fit: district pre-plan]]
  OutlineFit --> Fitted[(outline_fit.json)]
  Fitted --> Segment
  Inputs --> Repeat[[repeat_roofs: district pre-plan]]
  Selected --> Repeat
  Repeat --> Repeated[(data/repeat_faces/id.json)]
  Repeated --> Segment
  Labels[(data/roof_labels.json - hand-drawn markup)] --> Segment
  Inputs --> Segment[[roof segmentation: markup > repeat/selected faces > LiDAR partition/skeleton]]
  Segment --> Detect[[obstruction detection]]
  Detect --> Fit[[panel fitting and gates]]
  Fit --> Layouts[(per-region panel_layouts.geojson)]
  Layouts --> Demolished[[demolished: district photo screen and optional API referee]]
  Demolished --> Derive[[derive_solar_potential]]
  Layouts --> Derive
  Derive --> Horizon[[confidence and building horizons]]
  Horizon --> Heat[[build_heatmap_raster]]
  Heat --> Emit[[emit_region: per-region tiles, cells, detail, summary]]
  Derive --> Emit
  Emit --> Combine[[combine_regions]]
  Combine --> Outputs[(served set: PMTiles, cells, detail, heat-map tiles)]
  Outputs --> Map([preview.html])

Cylinders are data, subroutine boxes are scripts or stages, the rounded node is the map. Per-region intermediates stay separate from the combined served set; no root-level merged solar-potential GeoJSON is required by the map. Outline-fit/repeated-roof precomputation and demolition screening are district-path additions; local and worker orchestration do not run them. Those builds can still read existing outline-fit/repeated-roof sidecars. The direct layout-to-derive edge represents paths without demolition screening.

Module boundaries

Local publication is separate from build execution. tools/regional_staging.py copies a built region’s emitted output into an independently verified, frozen staged copy; tools/local_releases.py assembles an isolated site using the frozen-input combine mode, records comparisons/approvals and atomically switches local state. The authenticated web panel exposes the same operations. Complete-region replacements carry forward unrelated active regions. Staging and release stores do not mutate working outputs or cloud deployments. tools/cloud_staging.py separately submits verified local staging copies to a private, immutable cloud prefix. It does not assemble, approve or activate a cloud release; the submission manifest is written only after remote object verification. See Build data for generation checks, retention, capability limits and recovery.

Principles