nz-solar-potential

Reviewer’s guide

For a reviewer who wants to check the logic, not just read the code. For each part: what it claims, where that is enforced, and how to check it. Module boundaries are in architecture.md.

What the system claims

For buildings in the served regions, the pipeline estimates roof faces with slope and aspect, obstructions, panels that physically fit (ranked sunniest first) and yearly generation. Inputs: LINZ building outlines, aerial imagery, the LiDAR point cloud, DSM and DEM, plus hand-drawn roof markup for some buildings, used as ground truth and training data.

Roof geometry: two paths

Two roof-geometry systems exist side by side.

LiDAR path (the fallback): a recursive RANSAC partition (src/roof_partition.py) and a straight-skeleton model (src/roof_skeleton.py) compete in src/roof_segmentation.py::segment_building_best under confidence gates.

Selected faces (on by default, SOLAR_SELECTED_FACES=1): an offline step (tools/predict_faces.py) builds up to three readings per building and a scorer picks one:

The winner is written to data/selected_faces/<building_id>.json. A district pre-plan can also write an agreed reading for matching LiDAR roof surfaces to data/repeat_faces/<building_id>.json.

Precedence in a build:

  1. Hand-drawn markup (data/roof_labels.json). Always wins; no plane-fit or confidence gates.
  2. The repeated-roof reading, when enabled and present; otherwise the ordinary selected reading. roof_partition.selected_doc resolves this. The reading must score at least SELECTED_MIN_SCORE (0.30), and each face must pass its one-plane gate (normally 0.45 of returns; large complex faces have a stricter gate). An ordinary reading below SELECTED_TRUST (0.60) competes with the whole LiDAR path and loses if that explains the returns clearly better. An agreed repeated-roof reading skips that per-building competition. Uncovered roof is filled from the LiDAR path.
  3. The LiDAR path.

A verdict-panel entry marked “(old path)” means steps 1 and 2 gave nothing.

Off by default: ridge snapping (SOLAR_RIDGE_SNAP=0) and the plant-deck rule (SOLAR_PLANT_DECKS=0).

Files and who writes them

file written by read by
data/regions/<r>/building_outlines_dedup.geojson src/region_build.py everything region-aware
data/selected_faces/<id>.json tools/predict_faces.py roof_partition.facets_from_selected_faces
data/repeat_faces/<id>.json src/repeat_roofs.py roof_partition.selected_doc
data/regions/<r>/outline_fit.json src/outline_fit.py outline_fit.fitted_outlines, build keys
data/regions/<r>/panel_layouts.geojson layout, gate, optional district demolition screen, rerank src/derive_solar_potential.py, src/emit_region.py
data/regions/<r>/solar_potential.geojson src/derive_solar_potential.py (+ src/add_addresses.py) src/emit_region.py
data/out/<r>/ (not in Git) src/emit_region.py src/combine_regions.py
served set under data/ (not in Git) src/combine_regions.py tools/publish_served.py, local preview
data/roof_labels.json mark_roofs.html via tools/ingest_labels.py training, benchmarks, precedence

For exact stage order and differences between engines, use the execution reference; for serving and release steps, use dataset operations.

Rules, where they are enforced, how to check

rule enforced in check
Markup wins: drawn faces and obstructions used as drawn, exempt from confidence and plane-fit gates; where obstructions are drawn, only those count roof_partition (labels branch), build_layout_geojson (drawn exemptions, obstruction authority) tools/verify_markup_rebuild.py; verdict-panel roofs with markup
Sunny side first: lowering density hides the shadiest panels first, whole arrays by mean panel yield panel_fitting._order_by_array and rerank_layouts (both must use the mean) at 50% density, no hidden panel should out-yield a visible one
100% density shows every feasible panel: low-confidence panels move to ranks 81-100, not deleted build_layout_geojson (low_conf_fit), panel_fitting.assign_fill_ranks, rerank_layouts src/refit_one.py <id> against shipped counts
No lines without evidence: weak lines cost score; like-plane fill faces merge face_candidates (line price 0.45 in the net score), roof_partition residual fill drawn-roof benchmark (tools/markup_benchmark.py)
Equipment is not roof face_candidates.lidar_faces (step test), obstruction detection, gate_panels (lumpy, sparse) obstruction block of the dev loop
Faces stay on their footprint roof_segmentation._attach_building_geometry (drawn exempt) dev-loop audit
District builds run on the build VM, not a laptop src/run_district_build.sh on the VM operating rule

Check each stage yourself

Choose the check for the concept you changed; use the full-suite checklist below before publishing. Historical benchmark figures here are regression context, not an independent accuracy estimate.

Checks before publishing

bash tests/run_all.sh --fast   # unit, JavaScript and repository checks
bash tests/run_all.sh          # also synthetic-region and golden-building checks

Golden-building checks require local region data and skip without it. JavaScript checks require Node; without it the runner skips them. CI’s test workflow provides the data-free checks. CI runs the repository cross-reference check and deterministic pipeline-web panel and map-layer catalogue tests. It records Python failures while continuing the selected checks, then runs the JavaScript checks independently. The existing diagram check validates a curated symbol/constants list, not the Markdown Mermaid diagrams; see the execution-reference checklist.

Add targeted tests for deterministic algorithms and data contracts, and update the matching guide when behaviour changes. For a regional build, also complete the operator review and deploy gate; passing unit tests alone does not establish layout quality.

Environment flags

flag meaning
SOLAR_SELECTED_FACES 1 (default) enables selected/repeated readings; 0 bypasses them, but markup still wins
SOLAR_REPEAT_ROOFS 1 (default) prefers an available repeated-roof reading within the selected-faces path
SOLAR_PREDICT_RESUME=1 predict_faces skips buildings already done
SOLAR_VISION_DIR vision-lines directory (roof_line_source)
SOLAR_MIN_SCORE, SOLAR_MIN_LEN_FRAC vision-line acceptance
SOLAR_LINES_LEAD vision lines lead the partition (older experiment)
SOLAR_DEBUG_NET per-family scores in the line-network contest
SOLAR_KEEP_EXPORTS, SOLAR_LAZ_SINGLE fetch and point-cloud behaviour
LINZ_API_KEY data fetching

Layout switches for A/B tests (SOLAR_*) are named in the module that reads them; tools/layout_ab.py runs a sample with a switch off and on.

Known comprehension debt

  1. roof_segmentation.py and roof_partition.py grew one rule per incident and have no table of contents. A split is planned: segmentation into attach/gates, competition and vision-lines; partition into core, selected-faces and top-surface utilities.
  2. A golden building whose face count drops may be the markup rule working: check data/roof_labels.json for that id before blaming the gates.
  3. One repo. The Wellington copy was retired on 24 Sep 2026. site-config.js holds the per-deployment settings.
  4. rooftop-solar.html is the canonical static map; preview.html redirects old links without losing query/fragment state. Documentation is rendered at build/startup by the static-site tooling. tools/preview_sample.py writes roof-sample.html by default, so a geometry diagnostic does not overwrite the compatibility redirect.

Glossary