feat(roofmodel): derive PV array geometry from Lantmäteriet open geodata

[HuggeK]

Derives PV array tilt, azimuth and kWp from Lantmäteriet open geodata, so a
Swedish site can stop typing panel angles in by hand.

Stacked on #734 (which adds the coverage registry this registers into), which
is itself stacked on #718.

Shape

roofmodel/ is a separate Python package alongside optimizer/, reached at
arm's length: core spawns it, passes coordinates and the operator's own
Geotorget credentials, and reads back one versioned roof_model.json.

That boundary is the point. LiDAR segmentation drags in a compiled point-cloud
stack, runs for minutes, and is onboarding-time work rather than runtime work.
In a time-boxed subprocess it cannot stall the control tick, cannot leak into the
daemon, and can be absent entirely — which is the normal case, since the data
exists only for Sweden.

Method

Follows the SPAN paper
(Yavuzdoğan, Renewable Energy 2023): iterative RANSAC pulls one roof surface at
a time out of the cloud, then DBSCAN splits faces that satisfy the same plane
equation but sit in different places — two wings of a building fit one plane and
are not one roof.

The method only. No code is taken from SPAN's GPL QGIS plugin; dependencies are
numpy, scikit-learn and requests, all BSD, so the module carries no copyleft
obligation.

Two implementation choices worth flagging

Plane fitting is total-least-squares, not z = ax + by + c. An ordinary
regression of height on position minimises vertical error, which
systematically biases steep roofs. The smallest singular vector of the
mean-centred points minimises perpendicular distance instead, and stays
well-conditioned as the surface approaches vertical.

SWEREF 99 TM is implemented directly rather than via pyproj. Lantmäteriet
publishes in EPSG:3006 and FTW stores WGS84, so every request crosses that
boundary — but it is exactly one projection with fixed parameters, and shipping
a full PROJ build for that is disproportionate on a Pi. The Krüger series is
~120 lines and verified two ways: against the projection's exact analytic
properties (easting on the central meridian is exactly 500000 at every
latitude, and the origin maps to (0, 500000)), and by sub-millimetre round trips
from Smygehuk to Treriksröset.

What it produces

input: 1392 LiDAR returns   (synthetic gable + detached garage)

  tilt  azimuth   area m2  points   truth
  35.0    180.0      87.9     576   35 deg south
  35.0      0.0      87.9     576   35 deg north
  18.0    270.4      23.8     181   18 deg west

-- as candidate PV arrays (north face dropped, too little yield) --
   Roof south       12.31 kWp   tilt 35.0  az 180.0  (88 m2)
   Roof west         3.33 kWp   tilt 18.0  az 270.4  (24 m2)

GET /api/roofmodel reports availability and coverage; POST /api/roofmodel/derive runs a derive and returns the proposal. Lantmäteriet also
joins /api/data-sources as a Sweden-only, credential-gated source.

Deliberately not wired: auto-applying to config

The RFC sketched automatic auto-fill of weather.pv_arrays. This PR returns the
proposal instead and leaves applying it as a separate explicit act. Derivation is
a best guess from a point cloud that may be years old, packing factor is an
assumption, and silently rewriting an operator's panel config is a change they
should make knowingly. Happy to wire the auto-apply if you'd rather — it is a
small change on top, but it is a behaviour decision, not an implementation
detail.

Testing

57 Python tests. Every geometry case is a synthetic roof whose tilt, azimuth
and area are known exactly by construction, and the generator is the inverse of
the code under test rather than a copy of it — so the assertions check recovered
geometry against ground truth, not against a previous run. Covered: six
orientations, gable splitting, two buildings sharing a plane, sloped-vs-footprint
area, realistic LiDAR noise, wall rejection, determinism.

11 Go tests. The subprocess contract is exercised end-to-end against a stub
module, so argument passing, stdout parsing, stderr error surfacing, schema
rejection and the timeout are all real rather than mocked.

A limitation the tests pin rather than hide

Sweden is a long diagonal, so no lat/lon rectangle traces its border — any box
containing Sweden also contains parts of Norway. Oslo is the clearest case: west
of Sweden, inside the box.

Rather than tighten the box until it starts excluding real Swedish addresses near
the border, the box stays generous and the STAC search is the authority: no tiles
come back, and the module reports "Sweden only". There are tests for both halves —
that Oslo is admitted by design, and that Strömstad, Haparanda, Karesuando and
Smygehuk are never excluded.

Not covered: the live Lantmäteriet fetch. It needs Geotorget credentials for
Byggnad-vektor and Laserdata-skog, which are the operator's own; the HTTP layer
is tested against a fake session instead, including the documented quirk that
properties.datetime is still being backfilled through 2026 and the laser strip
datum is the fallback. To try it live:

pip install -e roofmodel[geo]
python -m ftw_roofmodel --lat 59.33 --lon 18.07 --username <user> --token <token>

Part of the roadmap in discussion #717.