Verified facts and rules for AI-assisted work on this repo. Code wins where it disagrees with this file. Update this file in the same change that alters a fact, rule or workflow.
A Python geospatial pipeline (LINZ outlines, LiDAR, imagery → per-building
solar estimates and panel layouts) and a static MapLibre map. Module
boundaries: docs/developers/architecture.md.
Entry points, delegation, machine boundaries and run ownership:
docs/developers/tooling-execution.md.
tools/pipeline.py is not yet a common front door for all operations:
local pipeline, district and worker builds maintain separate stage
sequences. Document current behaviour separately from the consolidation target.
Doc map: docs/index.md.
Write for the persona named there. Keep each procedure or detailed
explanation in one primary guide and link from summaries; repeat safety
warnings where a reader is about to act.
Keep Markdown guides in persona subdirectories matching the index, with
point-in-time notes under docs/ai-agents/archive/. When code is removed,
remove its obsolete documentation and diagram paths in the same change;
consolidate redundant explanations rather than preserving them as history.
Setup: docs/data-maintainers/local-setup.md.
bash src/run_dev_loop.sh pilot: quick pilot-region check.bash src/run_district_build.sh: district build. Incremental by default;
--force rebuilds everything; --yield-only only when each panel’s
stored shading_factor stays valid (a change to the system derate or the
panel constants). A sun-model or calibration change alters the beam share
baked into shading_factor, so it needs a full rebuild.tools/pipeline.py [region] (also run by quickstart.sh): builds one
region, then emits and combines the map data under data/, replacing the
current map data. Logs: data/pipeline_runs/<run-id>/run.log and
report.md. Local by default. --mode cloud builds and gates on the
shared VM, then publishes a public developer preview after the user
approves the cost; defaults in config.CLOUD_SHARED_BUILD, preview owner
from the GitHub SSH identity (GitHub CLI fallback).
--mode cloud --profile <name> uses a per-developer VM; --cloud runs a
VM lifecycle action. See docs/data-maintainers/quickstart-cloud.md.tools/pipeline_serve.py: local preview server with PMTiles byte ranges.tools/pipeline_web.py: local web panel (#12) with a Local / Developer /
Published target toggle: choose LINZ localities, estimate (cloud targets add
an NZD cost, not a spending cap), typed yes, queued builds in a local lane
and a cloud lane (shared VM), live log, cancel. Developer runs
tools/pipeline.py --mode cloud --cloud build (preview under devel/<alias>/);
Published runs tools/remote_build.sh --publish, which publishes only when the
deploy gate passes; the panel never passes --reviewed. Published is blocked
unless the checkout is on a clean, pushed main. Loopback with a per-launch
token; records under data/pipeline_web/. The server process never loads
PROJ (pyproj, rasterio, fiona, GDAL, geopandas): once PROJ has opened
proj.db, every later fork from the threaded server segfaults in the child on
macOS (“Python quit unexpectedly”). Area calculations and local layer-catalogue
generation run in tools/pipeline_webui/geo_worker.py; a test in
tests/test_pipeline_web_data.py checks this.
Package tools/pipeline_webui/; page pipeline.html (titled Build data).
The page is one tick-box tree, council › town › locality (LINZ
territorial_authority, locality major_name, suburb_locality), whose
rows show each area’s state in place for the selected target; status
colours the map. Search, fixed filters and sorts are pure logic in
pipeline_tree.js (tests/test_pipeline_tree.js); a sticky selection bar
offers Build…, Push to local staging, Push to remote staging, Cancel queued
and Clear; Queue and Jobs sit over the map. Catalogue refresh,
local staging and local releases are on the ⚙ Config view. The tree comes
from a prebuilt national catalogue
(python -m tools.pipeline_webui.national_catalog, about 80 s, 3,227
localities with buildings; water types dropped) cached in ignored
data/pipeline_web/cache/; per-area status joins runs, jobs,
staging and selections in tools/pipeline_webui/region_status.py
(/api/catalog*, tests/test_pipeline_web_catalog.py). The former
data-explorer.html URL redirects to this page. See
docs/data-maintainers/web-pipeline.md.data/out/<region>/ straight
into a frozen, checksummed copy in ignored
data/regional_staging/<id>/artifacts/ (tools/regional_staging.py,
tools/pipeline_webui/artifacts.py; --staging-root overrides it). The
atomic current.json points to one current copy per region; pushing a newer
copy adds that region or replaces its current pointer while leaving other
regions in the set. Frozen copies remain available to pinned candidates until
explicit local retention cleanup. There is no separate snapshot step. A
region can be staged when it is built, its
latest local build succeeded and no queued or running local job covers it
or its cells (stage_refusal in tools/pipeline_webui/server.py); other
builds may run, and a region being staged cannot be queued. The copy takes
a per-region lock, not the workspace lock, and fails if the source
inventory changes during the copy. Grid cells are never staged. Older
<id>/snapshot/ copies stay readable; data/regional_snapshots/ is unused.
Local staging itself makes no cloud calls, deploys nothing and runs no
automatic cleanup.tools/cloud_staging.py to the private bucket in
config.CLOUD_SHARED_BUILD["artifact_staging_bucket"], under the immutable
pipeline-staging/submissions/<staging-id>/ prefix. The area list offers
one batch Upload/Cancel confirmation after showing verified total bytes and
the private GCS destination; no per-region cost estimate or typed yes is
required. The confirmation warns that storage and transfer may incur charges.
The server rechecks the selected current local versions and their sizes under
the artifact lifecycle lock, uploads create-only, checks remote
inventory/size/SHA metadata and server-computed MD5, and writes its manifest
last. Retained objects continue to incur storage cost. This operation does not build,
assemble, approve, activate, change a preview pointer or publish to the
served tiles bucket. The panel shows live upload and verification counts and
the latest 50 locally recorded push outcomes; this is not a bucket inventory.
Local retention controls do not apply to cloud objects. No cloud cleanup is implemented.tools/local_releases.py) assemble verified
complete staged regions into ignored data/local_releases/ (--release-root).
Unchanged active regions are carried forward. The frozen-input combine mode
validates the region contract without re-emitting mutable inputs; geometry and
yields are not rerun. Candidates pin copied frontend/data and record source
hashes. Comparison/review binds the manifest and active generation; activation
atomically replaces local state. Automatic approval requires all-pass metrics;
warnings/unknowns require a recorded manual reason. Grid selections, overlapping
building ownership, mixed assumptions and incompatible contracts are blocked.
Terrain and markup overlays are omitted; local 3D is explicitly disabled.
Default retention in tools/local_releases.py is 720 hours for rollback,
candidates and unused staging, 168 hours for incomplete copies and 72 hours
for cleanup grace. Current staging copies are protected. Rollback protects
one previous release for the configured window. Cleanup requires
configured lifetimes, a mark/grace phase and explicit apply; no scheduled purge
or cloud action occurs. Capture/stage/release/cleanup share the process lock
data/.artifact-lifecycle-lock. See the web-pipeline guide for recovery and CLI.tools/pipeline_webui/jobs.py, pipeline_progress.js). Only success
reaches 100%; cloud runs without stage telemetry remain indeterminate.
Queue polling is every five seconds. The Queue section shows active and
waiting work; terminal jobs appear once in the newest-first Jobs history.
Disconnected views retain last-known cards with a warning instead of
displaying stale progress as live.JobManager.start_batch). Cells are materialised separately
while retaining the whole grid for stable building ownership. Cloud estimates
sum per-job allowances. The last job in a multi-area local submission combines
existing emitted outputs once without rebuilding geometry/yields.
Grid selection uses the LINZ locality boundary and needs no additional API
key or downloaded dataset. Selections have nested identities and outputs;
acquisition timings are per-run in data/pipeline_runs/ (outline preparation
is recorded under the selection area). See
web pipeline guide.src/local_queue.py and
tools/pipeline_queue.py: loopback coordinator, JSON state and one worker
process by default (--workers changes the pool size). Tasks in a checkout
serialize; concurrent builds need human-managed independent writable
workspaces. No GCS/cloud credentials are required for queue operation.
GCS fleet tasks are not yet migrated. Recovery and locks:
pipeline reference.bash tests/run_all.sh: all local checks (Python, economics, deprecated
APIs, repo sync, diagram, synthetic region in tests/synthetic). Add
targeted tests under tests/ when changing algorithms or data contracts.src/output_contract.py deliberately whenever what the map reads
changes.data/solar_potential.geojson is a local build file, not tracked and not read by the map.
Change producer and consumer together.config.PV_ASSUMPTIONS is the one source for PV assumptions shown in the
UI. Don’t hardcode them elsewhere.config.py and data contracts are the source of truth: link to
them rather than copying values. Update the matching doc in docs/ (including
docs/researchers/how-a-roof-estimate-is-made.md, which is maintained by
hand) in the same change as a command, output, limit or constant. Mark
experiments and unverified cloud steps. Platform setup lives in
docs/data-maintainers/.Every figure on the map must be traceable and must agree with every other figure for the same thing. Code enforces this:
node.value of a
workings.js node; its breakdown is that node opened. Don’t compute a
displayed figure in view code or describe a sum beside it. Build sums
from Wk.input/product/sum/.... Non-arithmetic steps are Wk.table (with
a rowCheck) or Wk.given with a check.generation.js prices the panels drawn on
the roof from the build’s own inputs (tile sb/ab/sh, and
data/sun/<region>.json captured from src/solar_model.py by
src/workings_data.py). The yellow box, curve chart, bills and savings all
read the page’s GEN. The curve is scaled so its year equals the annual
figure.bill_tool.js prices every roof: the open one’s
card and every roof’s panel colours (btPanelEcon). economicsFor in
economics.js is not used for map figures.emit_region re-derives every panel’s kWh from the
shipped inputs and refuses to emit on a mismatch; (2) predeploy_check
fails a release whose summaries lack that check or disagree; (3) CI runs
tests/test_workings.mjs, test_generation.mjs (JavaScript vs Python on
real panels, tests/fixtures/workings_kinloch.json), test_economics.mjs,
test_bill_tool.mjs and test_low_solar_battery.mjs; (4) the page runs
Wk.verify on every breakdown it opens and marks a mismatch in red.tools/export_workings_fixture.py kinloch) and re-emit every region.yes; Enter, anything else, or a non-interactive run declines.
The one exception is the explicit --yes flag on tools/pipeline.py: it
still prints and logs the estimate, then records that --yes (not a
person at the prompt) approved it. No environment variable approves cost,
and --yes never approves the paid referee, a gcloud install or a
--confirm target.
With no defensible default estimate, require one from the user. Keep
no-cost checks separate. Single-VM profile actions live in
tools/pipeline.py (via quickstart.sh); the shared-VM build and publish
is tools/remote_build.sh. See docs/data-maintainers/quickstart-cloud.md
and docs/data-maintainers/team-access.md.
Exception: data-only uploads to private artifact staging use the explicit
batch Upload confirmation described above, with verified bytes, destination
and a charge warning instead of a separate cost estimate or typed yes.Fixes #N.
Open work is also in BACKLOG.md.ai-generated label and open with “Written by Claude
(AI)”; commits carry a Co-Authored-By: trailer. A person removes the
label after checking.claude-doing-things
(australia-southeast1-b, project solar-potential-map-512020), never on a
laptop. The VM fetches LiDAR and imagery from LINZ. Reach it only through
Identity-Aware Proxy: pass --tunnel-through-iap to gcloud compute ssh /
scp (the tools/ scripts do). It is a spot VM that stops itself 40 hours
after starting (max-run-duration 144000 s); resume a cut-off build with
src/run_district_build.sh --force --regions "<the rest>".~/solar-map is a git checkout: push, then tools/sync_vm.sh (or
--ref <branch>) pulls it; it refuses while the VM is busy.tools/deploy_from_vm.sh pulls the
VM’s served set and runs tools/predeploy_check.py against the live
build. --push publishes a new version folder to
gs://solar-potential-map-tiles/v<N>/, keeps the newest three, never
overwrites or prunes the served version, and commits only the
site-config.js switch. --push-reviewed "<why>" publishes past a gate
whose list has been rendered and judged. Roll back by pointing
site-config.js dataBase/dataVersion at an older folder.tools/predeploy_check.py gate in tools/remote_build.sh prints
GATE WARNING and continues for build-only runs and developer previews,
so unattended runs are not held up by human review; --interactive stops
and asks instead. Production --publish still needs a passing gate or
--reviewed "<why>".config.CLOUD_SHARED_BUILD["preview_bucket"] (with a warning
when the gate flagged items), under immutable
devel/<alias>/runs/ paths, and updates only that alias’s pointer. The
bucket expires devel/ objects after preview_retention_days. Never put
private inputs or production releases there.tools/layout_ab.py <region> --n 200 --sample-file s.json --out on.json
(each change has a SOLAR_* switch), score both with
tools/layout_health.py, and render them side by side on the photo. After
a build, also run tools/face_area_check.py against the previous layouts
(a building should not lose roof-face area) and the deploy gate, and render
every roof either flags.data/roof_set.json (written by tools/make_roof_set.py)
holds 100 development roofs (every roof in data/roof_cases.json, render
review finds, new roofs of each failing kind, drawn roofs round-robin by
region) and 30 held-back roofs drawn at random from the whole map. Fix
rules against the 100, scored blind against the markup
(SOLAR_HIDE_LABELS=1, tools/markup_benchmark.py). Never render or study
the 30 while fixing; score them once, at the end.data/blind_check/). The
agent records its own calls before the owner judges, and its agreement
with the owner is reported with every result. On 2 Nov none of the 64
roofs judged for v69 and the fewer-faces rule had markup: every call was
the agent’s eye on a 0.3 m photo. A change whose movers have no markup
ships only after the owner has judged them blind, or is labelled
unverified in the release. The scored check (2 Nov): the owner backed
the agent on 20 of 31 decided pairs, and on 5 of the 14 where the agent
called the change worse.
Build the page with tools/render_built.py --tiles and
tools/review_page.py: each drawing gets a score out of 10 and fault
tags (outline, roof lines, panels across a ridge, over obstructions, over
empty area, racking direction, empty space unused), so a review says
what is wrong as well as which side is better. A one-drawing review of
a sample of the live map, repeated each release, gives the accuracy
over time.setsid nohup and stop them with pkill -s <session>. Killing a Python
parent by PID leaves its multiprocessing workers (~1.8 GB each) running.
Before a build,
ps -eo pid=,ppid=,args= | awk '$2==1 && /multiprocessing\.spawn/' must
print nothing. Never pkill -f a pattern that is also in your own ssh
command..env, else Google Secret Manager
(src/project_secrets.py; secret linz-api-key). Never commit or print a
key.data/roof_labels.json).
Judge geometry by renders against the photo and by measurement against the
markup, not by panel counts. No per-building special cases."elevation": "synthetic"
builds on a modelled surface (src/synthesize_dsm.py) and every building
carries pitch_guessed.src/build_layout_geojson.py).src/build_plan.py is the single per-region step plan (prepare:
outline_fit, repeat_roofs; stages through run_stage.py; finish:
add_addresses, emit_region). The local executor in tools/pipeline.py,
src/run_district_build.sh and src/build_region.sh all read it, and
tests/test_build_plan.py fails on drift. Input preparation, stage
selection and combine scope still differ per engine
(tooling execution).src/run_district_build.sh plans each region from per-building build keys
(clean / patch / full), runs layout, gating, reranking, derivation,
confidence, horizon and raster stages, then emit_region.py per region and
combine_regions.py once. src/merge_regions.py is retired.src/region_build.py treats pilot as a region under
data/regions/pilot/; pilot source inputs are fetched under data/ and
symlinked into the region tree.data/regions/<area>/. Emitted outputs:
data/out/<area>/. Combined map data: data/.src/run_stage.py wraps each stage: preflight checks, completion markers
under data/build_state/, and skips a stage only when its inputs are older
than its marker.config.CLOUD_SHARED_BUILD["local_region"] (a locality id) is the default
region for tools/pipeline.py, and ["regions"] the shared-cloud default.
Both sit inside the CLOUD_SHARED_BUILD block, which
build_keys._hashed_bytes strips, so moving a default changes no build
key. Any other config.py edit, comments included, changes every stage
hash and marks every published region stale. config.PIPELINE_REGION is
the deprecated fallback; config.REGIONS names still build, with a
warning. The CLI takes any region id.data/regions/ and data/out/
(src/region_ids.py): a LINZ NZ Suburbs and Localities area
<council>/<town>/<suburb> (layer config.LINZ_SUBURBS_LOCALITIES_LAYER,
slugs of the LINZ ASCII names, no-town when LINZ gives none,
-<linz-id> appended on a name collision), or a legacy config.REGIONS
bbox name. src/localities.py prepare writes a locality’s outlines,
selected by the outlines’ suburb_locality/town_city/
territorial_authority attributes, and locality.json (bbox = outlines
region_ids.file_slug (/ -> __).
tools/find_area.py and choosing-an-area.md
are the maintainer entry points.config.SERVED_EXCLUDE keeps the Mt Eden regions and akl_epsom_01 off
the map; their builds stay on disk.report.md, then the numbered step
log. Guide: docs/data-maintainers/troubleshooting.md.src/linz_exports.py downloads them once per
territorial authority through the LINZ Exports API (GeoPackage, EPSG:2193,
cropped by LINZ layer 3036) into
data/sources/linz/layer-101290/<council>/ with a manifest.json
(layer version, export id); the cache is reused until the layer version
changes. Exports are spatial only; the attribute selection runs locally.
Selections from the GeoPackage and from WFS matched exactly (IDs,
properties, geometry) on two Queenstown localities. WFS is the fallback
(SOLAR_OUTLINE_SOURCE=wfs, or any export failure, recorded in
locality.json outline_source).typeName and maxFeatures; 2.0.0
returned empty results.src/surveys.py, not maintained as a registry in config.py.
The local metadata cache is data/sources/linz/survey_layer_catalog.json
(ignored by Git); web estimates pin selected layer IDs through local and
cloud execution. Without a verified raw point-cloud bulk source, builds use
the covering DSM and disable cached point-cloud tiles for that run.src/s3_rasters.py probes LERC decoding with system GDAL and Rasterio;
preflight runs the probe before fetching and falls back from GTiff to
LIBERTIFF. SOLAR_TIFF_READER overrides it. Native GDAL tools are in
Brewfile.data/dem_wide_mosaic.tif (LINZ 8 m DEM, layer 51768, over
config.DEM_WIDE_BBOX with a 30 km buffer; fetched by
src/fetch_dem_wide.py) is required for building horizons and terrain
masks. LINZ calls it cartographic, not precision terrain.data/ is not disposable: it holds tracked labels, benchmark and verdict
files and trained models beside ignored inputs and build outputs.
git clean -fd keeps ignored files; rm -rf data deletes tracked ones.site-config.js (dataBase,
dataVersion).mark_roofs.html (its outline tools; the
label’s outline ring) replaces the surveyed and the fitted outline in
outline_fit.fitted_outlines (roof_line_source.hand_outline).
Selected faces (SOLAR_SELECTED_FACES=1, the default): tools/predict_faces.py
scores four readings per building (SAM vit_b, a U-Net line detector,
normal-grown LiDAR regions, and the simplest roof form that fits) and
writes the winner to
data/selected_faces/<id>.json. A reading scored under 0.60 competes with
the LiDAR path. Fallback: RANSAC plane partition and straight skeleton
(src/roof_skeleton.py). Ridge snap and the plant-deck rule are off by
default (SOLAR_RIDGE_SNAP, SOLAR_PLANT_DECKS), as are a plane per
section on faces that curve in plan (SOLAR_CURVED_SPLIT) and refitting the
tilt of an empty face its returns reject (SOLAR_EMPTY_FACE_REFIT). A
drawn line end within 1 m of another drawn line is joined to it
(SOLAR_DANGLE_JOIN_M, 0 turns it off). The
3D view takes obstruction box tops from the DSM where SITE.obstTopFromDsm
is set (on in this deployment) or with ?SOLAR_OBST_TOP_DSM=1. It reads
every height at the building’s LiDAR position, taking off the photo lean
(img_dx/img_dy) the geometry was moved by; ?SOLAR_LEAN_HEIGHTS=0 or
SITE.leanHeights = false turns that off.src/build_plan.py (every engine), both on by default
(=0 turns either off). SOLAR_OUTLINE_FIT: src/outline_fit.py slides an outline that is
clearly offset from the roof the LiDAR sees onto it (writes
data/regions/<r>/outline_fit.json; layout, derive, horizons and heat map
read it through fitted_outlines). SOLAR_REPEAT_ROOFS:
src/repeat_roofs.py finds sets of identical roofs by their LiDAR surfaces
and gives every member the reading that explains the whole set best
(data/repeat_faces/<id>.json, read before data/selected_faces; an agreed
reading skips the per-building LiDAR competition). Both feed the build keys.demolished stage (src/demolished.py, after gate_panels): a pixel
screen on every outline (survey photo vs map photo), then a Claude vision
referee on the screened few hundred; “gone” or “replaced” at confidence
0.7+ replaces the layout with reason demolished. Answers are cached per
building in data/regions/<r>/demolished.json (key: outline and lean);
the key is the project secret Claude-API, and runs stop at
SOLAR_DEMOLISHED_MAX_USD (default $5 a region). The referee is paid and
runs only when SOLAR_DEMOLISHED_REFEREE=1; every entry point asks a
yes/no question at the start (default no; non-interactive runs and
--yes decline unless --paid-referee or the env is set), via build_plan.confirm_paid.
SOLAR_DEMOLISHED=0 turns the stage off. Drawn
roofs are never withheld. config.DEMOLISHED_BUILDING_IDS still drops
field-reported outlines from the build entirely.src/derive_solar_potential.py builds the building summary by adding up
its layout, so totals and layouts match.src/building_shading.py) and the
building’s 72-direction far horizon from the 8 m DEM seen from eave
height (src/building_horizon.py far_profile), blended by the direct-beam
share (SolarModel.kept_sun). The baked horizon_b64 and
horizon_beam_pct (near field to 300 m) are for display only.methodology.js) is
written from the code by src/methodology.py into methodology.json;
tests/test_methodology.py fails when it is stale, a build stage is not
in it, a cited name is gone, or a LINZ layer config names is not described
in data/source_metadata.json (tools/fetch_source_metadata.py).tests/test_reference_cases.py and .mjs are worked examples checkable
by hand (panel kWh, packing, slope, loan, rounding, an hour of solar).
Browser checks, run on the page before a front-end release:
tools/contrast_check.js, tools/overflow_check.js, tools/econ_check.js,
tools/text_check.js (no “undefined”/”NaN” or “Doesn’t add up” on screen),
tools/money_check.js (a roof’s money pill equals its card’s figure).econ.cpi_pct
(bill_tool.js btEvaluate avgOver). The loan covers what is bought on
day one (solar, battery); the inverter (year 16) and battery (year 15,
battery_replace_cost_pct 70% of today’s price) are added to it when
due, at that year’s prices, and repaid by the end of the term (one past
the term is paid in cash). Paid upfront (btReturns) they are paid in cash
in their year. Return on investment is the paid-upfront rate;
with a loan the card gives the net a year instead. A closed roof is priced by
roofMoney in rooftop-solar.html, the card’s own calculation on the
panels the map shows; a roof without loaded panel tiles gets no pill.
From zoom 13 to 16 there are no pills and the area’s total adds up
roofMoneyEstimate: the same bill model at the roof’s size on the map,
from its baked kWh and panel count with the area’s sunny-side day shape
(sum within 0.4% of the cards’ figures, measured on 397 roofs). Below zoom
13 it prices cells with cellMoneyEstimate: each cell’s mg money groups
(its roofs summed by sun region, size band and, for non-homes, 1 m height
band; money_group in src/emit_region.py) priced as their average roof
(within 2% of the per-roof sum in Queenstown and Wanaka at every cell
size). Cells built before the groups existed have no mg, and the total
says to zoom in.
The map’s battery price is BATTERY_DEFAULTS.cost_per_kwh ($900/kWh).wholesale.html (script wholesale.js) shows historic wholesale prices
at FKN0331 (Frankton), CML0331 (Cromwell) and BEN2201 (Benmore): averages
over sunlight hours (sun above a flat horizon, pvlib), peak (economics.js
peak hours), overnight (11pm-7am) and all hours, each half-hour weighted
equally, real (Stats NZ CPI all groups, latest quarter) or nominal.
tools/fetch_wholesale_prices.py writes wholesale_prices.json (per day:
sum and count per group) from the Electricity Authority’s final energy
prices; trading periods count half-hours from local midnight (46/50 on
clock-change days) and the build refuses a day without every half-hour.
.github/workflows/wholesale-prices.yml refreshes it monthly, fetching
only the newest two months (older days come from the published file;
--full with the raw cache in data/wholesale/raw/ rebuilds all).
tests/test_wholesale.py and .mjs check it. It is a comparison
for readers who want to dig in, never an input to the bill model:
households and businesses pay retail prices, not wholesale.src/solar_model.py header).config.py holds shared non-secret defaults, including
CLOUD_SHARED_BUILD and PV_ASSUMPTIONS. Secrets such as LINZ_API_KEY
go in the ignored root .env. Cloud profiles live in
~/.config/nz-solar-potential/cloud-profiles.json.site-config.js holds per-deployment front-end settings. bill_tool.js
is the pricing model; economics.js holds cost tiers, prices and the
battery simulation it uses.src/live_server.py; static hosting lacks it.BTYPE_GROUPS in rooftop-solar.html, a display merge
of the build’s btype; regrouping needs no rebuild; a type no group lists
counts under the last group). In money mode each box also shows its
group’s net saving a year: the in-view money total split by group, so the
boxes add up to it. Advanced > Export video
(video_export.js) renders an MP4 tour of one group, of all buildings,
or of one building type on its own:
a title screen over the current view, flights to well-covered areas drawn
at random (homes and businesses in turn for all buildings), each area’s
panels added in fill order while that group’s MW counts up top left, and
a closing screen with every group’s total for the starting view. A
video fills every roof (density 100, no household cap) whatever the
slider is on, so its MW figures are higher than the sidebar’s on Auto.
The zoomed-out heat map (the cells-heat-* density surface below the
building zooms) is off everywhere (SHOW_ZOOMED_OUT_HEAT in
rooftop-solar.html); the roof heat map from the building zooms up stays.
It is rendered a frame at a time
(maplibregl.setNow, map.redraw, WebCodecs H.264, mp4-muxer loaded
from unpkg on demand), and every frame waits for its map tiles.focusBox in rooftop-solar.html).map_layers.js and map_layers.css provide the shared Build data legend,
catalogue layer styling and aerial/OpenStreetMap switch. The analysis stack
is panels above solar-analysis building outlines above the heat map. Build
data catalogue layers toggle independently and support feature-attribute
queries. rooftop-solar.html retains the simple map’s analysis modes;
preview.html redirects to it.
The shared facet style encodes aspect as hue and slope as saturation, with a
compass legend in both catalogue-based layers and the rooftop map.Last checked against the code: 2026-10-28.
The national candidate-area snapshot is maintained in
Areas, regenerated by tools/list_areas.py
from LINZ locality attributes using the pipeline’s region-id helpers.
It excludes lakes and inland bays, matching tools/find_area.py defaults;
it does not certify building presence or survey coverage.
data/regions/pilot/
on a fresh checkout?src/live_server.py support region outputs, or stay limited to the
root pilot inputs?