Source code for orbitalpv.pv_detection
"""Supervised, image-only PV footprint inference on explicit spectral inputs.
This is a trainable random-forest baseline, not a pretrained global detector
or an implementation of Dunnett et al.'s OSM inventory method. Labels must be
provided by the caller. In particular, absence from OSM is not a negative
label unless that assumption is explicitly chosen and recorded by the user.
Reflectance bands are aligned to the red band's grid. This derived feature
stack is separate from the untouched native ``GroundImage`` objects. Model
scores are forest class scores, not calibrated detection probabilities.
"""
from __future__ import annotations
import importlib
import json
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from hashlib import sha256
from pathlib import Path
from typing import Any
import numpy as np
from space_pv_connectors.ground_raster import GroundImage
PV_SPECTRAL_BANDS = ("blue", "green", "red", "nir", "swir16", "swir22")
PV_FEATURE_NAMES = (*PV_SPECTRAL_BANDS, "ndvi", "ndbi", "mndwi")
DEFAULT_EXCLUDED_SCL = (0, 1, 2, 3, 6, 8, 9, 10, 11)
_MODEL_FORMAT = "orbitalpv-pv-forest-v1"
def _optional(module: str) -> Any:
try:
return importlib.import_module(module)
except ImportError as exc:
raise ImportError(
"PV footprint methods require the ground extra; install "
"python -m pip install 'orbital-pv[ground]'."
) from exc
def _integer(value: int, name: str, *, minimum: int = 1, maximum: int | None = None) -> int:
if (
isinstance(value, bool)
or not isinstance(value, int)
or value < minimum
or (maximum is not None and value > maximum)
):
raise ValueError(f"{name} must be an integer from {minimum} to {maximum or 'unbounded'}")
return value
def _nonnegative(value: float, name: str) -> float:
if isinstance(value, bool) or not math.isfinite(value) or value < 0:
raise ValueError(f"{name} must be finite and nonnegative")
return float(value)
def _projected_grid(crs_value: str, transform: Sequence[float]) -> tuple[Any, Any, float]:
rio = _optional("rasterio")
if len(transform) != 6 or not all(math.isfinite(value) for value in transform):
raise ValueError("Image affine must contain six finite coefficients")
affine = _optional("rasterio.transform").Affine(*transform)
if affine.a <= 0 or affine.e >= 0 or affine.b != 0 or affine.d != 0:
raise ValueError("PV detection requires a north-up, unrotated image grid")
crs = rio.crs.CRS.from_user_input(crs_value)
if not crs.is_projected:
raise ValueError("PV detection needs a projected image CRS with linear units")
_, metres_per_unit = crs.linear_units_factor
if not math.isfinite(metres_per_unit) or metres_per_unit <= 0:
raise ValueError("Image CRS must have known positive linear-unit conversion")
return crs, affine, float(metres_per_unit)
def _actual_bounds(affine: Any, shape: Sequence[int]) -> tuple[float, float, float, float]:
height, width = shape
return (affine.c, affine.f + height * affine.e, affine.c + width * affine.a, affine.f)
def _grid(image: GroundImage) -> tuple[Any, Any, float]:
if image.data.ndim != 3 or image.data.shape[0] != 1 or 0 in image.data.shape:
raise ValueError("Each spectral/SCL asset must contain one nonempty image band")
crs, affine, unit = _projected_grid(image.crs, image.transform)
actual = _actual_bounds(affine, image.data.shape[1:])
if len(image.bounds) != 4 or not np.allclose(image.bounds, actual, rtol=0, atol=1e-7):
raise ValueError("GroundImage bounds disagree with its affine transform and shape")
return crs, affine, unit
[docs]
@dataclass(frozen=True, slots=True)
class PVFeatures:
"""Derived spectral predictors and validity on one projected image grid.
``data`` has shape ``(rows, columns, features)``. ``valid_mask=True``
means all predictors and the requested SCL quality filters are usable.
Grid areas are projected areas, not an individual-module measurement.
"""
data: np.ndarray
valid_mask: np.ndarray
feature_names: tuple[str, ...]
crs: str
transform: tuple[float, float, float, float, float, float]
bounds: tuple[float, float, float, float]
bbox_wgs84: tuple[float, float, float, float]
scene_id: str
pixel_area_m2: float
provenance: dict[str, Any]
[docs]
def build_pv_features(
images: Mapping[str, GroundImage],
*,
excluded_scl: Sequence[int] = DEFAULT_EXCLUDED_SCL,
max_pixels: int = 4_000_000,
) -> PVFeatures:
"""Calibrate six bands and align them to the native red grid.
Requires ``blue``, ``green``, ``red``, ``nir``, ``swir16``, ``swir22`` and
``scl`` from the same scene and requested area. Reflectance uses each
source's explicit scale/offset, including negative valid values. Any
different spectral grid is resampled bilinearly; SCL always uses nearest
neighbour. No source array or metadata is modified. Upsampled SWIR still
contains only its original 20 m spatial information.
The default excludes nodata, defective pixels, topographic/cloud shadow,
water, cloud/cirrus and snow. This also excludes floating-PV water pixels;
callers studying such systems must explicitly choose quality classes.
The NDVI/NDBI/MNDWI denominator must have absolute value above 1e-6.
"""
_integer(max_pixels, "max_pixels")
required = (*PV_SPECTRAL_BANDS, "scl")
if missing := set(required).difference(images):
raise ValueError(f"Missing PV feature assets: {', '.join(sorted(missing))}")
if any(
isinstance(code, bool) or not isinstance(code, int) or code not in range(12)
for code in excluded_scl
):
raise ValueError("excluded_scl must contain integer SCL codes from 0 to 11")
reference = images["red"]
crs, affine, unit = _grid(reference)
shape = reference.data.shape[1:]
if math.prod(shape) > max_pixels:
raise ValueError("Feature grid exceeds max_pixels")
warp = _optional("rasterio.warp")
resampling = _optional("rasterio.enums").Resampling
bands: dict[str, np.ndarray] = {}
sources: dict[str, Any] = {}
for name in required:
image = images[name]
src_crs, src_affine, _ = _grid(image)
if image.asset_key != name:
raise ValueError(f"Asset {name!r} does not match its GroundImage asset_key")
if image.scene_id != reference.scene_id or image.bbox_wgs84 != reference.bbox_wgs84:
raise ValueError("All feature assets must describe the same scene and requested area")
if name == "scl":
raw = image.data[0]
valid_values = raw.compressed()
if np.any(~np.isin(valid_values, np.arange(12))):
raise ValueError("SCL must contain integer class codes from 0 to 11")
else:
raw = image.reflectance()[0]
source = np.asarray(raw.astype(np.float32).filled(np.nan), dtype=np.float32)
method = resampling.nearest if name == "scl" else resampling.bilinear
unchanged = src_crs == crs and src_affine == affine and source.shape == shape
if unchanged:
aligned = source.copy()
else:
aligned = np.full(shape, np.nan, dtype=np.float32)
warp.reproject(
source=source,
destination=aligned,
src_transform=src_affine,
src_crs=src_crs,
src_nodata=np.nan,
dst_transform=affine,
dst_crs=crs,
dst_nodata=np.nan,
resampling=method,
)
bands[name] = aligned
sources[name] = {
"url": image.source_url,
"scene_id": image.scene_id,
"native_shape": list(source.shape),
"native_transform": list(image.transform),
"resampling": "none" if unchanged else method.name,
}
derived = []
for positive, negative in (("nir", "red"), ("swir16", "nir"), ("green", "swir16")):
numerator = bands[positive] - bands[negative]
denominator = bands[positive] + bands[negative]
ratio = np.full(shape, np.nan, dtype=np.float32)
np.divide(numerator, denominator, out=ratio, where=np.abs(denominator) > 1e-6)
derived.append(ratio)
data = np.stack([*(bands[key] for key in PV_SPECTRAL_BANDS), *derived], axis=-1)
valid = np.isfinite(data).all(axis=-1) & np.isfinite(bands["scl"])
valid &= ~np.isin(bands["scl"], excluded_scl)
bbox = warp.transform_bounds(crs, "EPSG:4326", *reference.bounds, densify_pts=21)
return PVFeatures(
data=data,
valid_mask=valid,
feature_names=PV_FEATURE_NAMES,
crs=crs.to_string(),
transform=reference.transform,
bounds=reference.bounds,
bbox_wgs84=(float(bbox[0]), float(bbox[1]), float(bbox[2]), float(bbox[3])),
scene_id=reference.scene_id,
pixel_area_m2=abs(affine.a * affine.e) * unit**2,
provenance={
"method": "calibrated six-band spectral predictors with three normalized differences",
"sources": sources,
"reference_asset": "red",
"excluded_scl": list(excluded_scl),
"source_pixels_modified": False,
"upsampling_adds_spatial_information": False,
},
)
def _check_features(features: PVFeatures) -> None:
if (
features.data.ndim != 3
or 0 in features.data.shape
or features.data.shape[:2] != features.valid_mask.shape
or features.valid_mask.dtype != bool
or features.data.shape[2] != len(features.feature_names)
or len(set(features.feature_names)) != len(features.feature_names)
or not features.feature_names
or not np.isfinite(features.data[features.valid_mask]).all()
or not math.isfinite(features.pixel_area_m2)
or features.pixel_area_m2 <= 0
):
raise ValueError("Invalid feature data, feature names, validity mask or pixel area")
west, south, east, north = features.bbox_wgs84
if not (-180 <= west < east <= 180 and -90 <= south < north <= 90):
raise ValueError("Feature bounding box must be finite, ordered WGS84 coordinates")
crs, affine, unit = _projected_grid(features.crs, features.transform)
actual = _actual_bounds(affine, features.valid_mask.shape)
bbox = _optional("rasterio.warp").transform_bounds(crs, "EPSG:4326", *actual, densify_pts=21)
pixel_area = abs(affine.a * affine.e) * unit**2
if (
len(features.bounds) != 4
or not np.allclose(features.bounds, actual, rtol=0, atol=1e-7)
or not np.allclose(features.bbox_wgs84, bbox, rtol=0, atol=1e-8)
or not math.isclose(features.pixel_area_m2, pixel_area, rel_tol=1e-9)
):
raise ValueError(
"Feature bounds, geographic bbox and pixel area must match the actual grid"
)
[docs]
def rasterize_pv_labels(
features: PVFeatures,
positive_geometries: Sequence[Mapping[str, Any]],
*,
negative_geometries: Sequence[Mapping[str, Any]] | None = None,
geometry_crs: str = "EPSG:4326",
background_is_negative: bool = False,
boundary_buffer_m: float = 0.0,
) -> np.ndarray:
"""Rasterize supplied labels as 1=PV, 0=non-PV, -1=unknown.
Inputs are polygon/MultiPolygon GeoJSON geometries or Features. Pixel
centres determine membership. Invalid polygons are rejected, not silently
repaired. Invalid feature pixels are always unknown. The outside buffer
around positive geometries remains unknown; positive interiors are not
eroded. Explicit overlapping positive/negative polygons are rejected.
Outside supplied polygons remains unknown by default. Opting into
``background_is_negative=True`` treats every other valid pixel as non-PV:
this is a weak assumption for incomplete OSM inventories, not ground
truth. Record that choice in ``PVTrainingSample.label_source`` and any
independent evaluation's ``label_source``.
"""
_check_features(features)
buffer_m = _nonnegative(boundary_buffer_m, "boundary_buffer_m")
if not isinstance(background_is_negative, bool):
raise ValueError("background_is_negative must be a bool")
shapely = _optional("shapely")
geometry = _optional("shapely.geometry")
warp = _optional("rasterio.warp")
rio = _optional("rasterio")
raster = _optional("rasterio.features")
affine = _optional("rasterio.transform").Affine(*features.transform)
target_crs = rio.crs.CRS.from_user_input(features.crs)
_, unit = target_crs.linear_units_factor
def projected(items: Sequence[Mapping[str, Any]]) -> list[Any]:
result = []
for item in items:
item_geometry = item.get("geometry") if item.get("type") == "Feature" else item
if not isinstance(item_geometry, Mapping) or item_geometry.get("type") not in {
"Polygon",
"MultiPolygon",
}:
raise ValueError("Training labels must be Polygon or MultiPolygon geometries")
polygon = geometry.shape(
warp.transform_geom(geometry_crs, target_crs, dict(item_geometry))
)
if polygon.is_empty or not polygon.is_valid or not np.isfinite(polygon.bounds).all():
raise ValueError("Training label geometry must be finite, nonempty and valid")
result.append(polygon)
return result
positive = shapely.union_all(projected(positive_geometries))
negative = shapely.union_all(projected(negative_geometries or []))
if not positive.is_empty and not negative.is_empty and positive.intersection(negative).area > 0:
raise ValueError("Positive and negative label geometries overlap")
shape = features.valid_mask.shape
def burn(polygon: Any) -> np.ndarray:
if polygon.is_empty:
return np.zeros(shape, dtype=bool)
return raster.rasterize(
[(geometry.mapping(polygon), 1)],
out_shape=shape,
transform=affine,
all_touched=False,
fill=0,
dtype="uint8",
).astype(bool)
labels = np.full(shape, 0 if background_is_negative else -1, dtype=np.int8)
labels[burn(negative)] = 0
if not positive.is_empty:
if buffer_m:
labels[burn(positive.buffer(buffer_m / unit))] = -1
labels[burn(positive)] = 1
labels[~features.valid_mask] = -1
return labels
def _labels(labels: np.ndarray, shape: tuple[int, ...]) -> np.ndarray:
values = np.ma.asarray(labels)
if (
values.shape != shape
or values.dtype.kind not in "biu"
or not np.isin(values.compressed(), (-1, 0, 1)).all()
):
raise ValueError("Labels must match the grid and contain only -1=unknown, 0=non-PV, 1=PV")
return np.ma.filled(values.astype(np.int8), -1)
[docs]
@dataclass(frozen=True, slots=True)
class PVTrainingSample:
"""One labelled scene, with a stable site ID and explicit label source."""
features: PVFeatures
labels: np.ndarray
site_id: str
label_source: str
[docs]
@dataclass(frozen=True, slots=True)
class PVFootprintPrediction:
"""Image-derived scores, filtered mask and WGS84 footprint polygons.
``probabilities`` are uncalibrated forest scores before area filtering.
``mask`` retains only thresholded connected components meeting the area
limit. Both arrays mask invalid pixels rather than coding them non-PV.
GeoJSON contains grid-derived footprint area, not module surface area.
"""
probabilities: np.ma.MaskedArray
mask: np.ma.MaskedArray
geojson: dict[str, Any]
metadata: dict[str, Any]
@property
def area_m2(self) -> float:
"""Sum of retained projected-grid footprint areas."""
return sum(feature["properties"]["area_m2"] for feature in self.geojson["features"])
def _boxes_overlap(a: Sequence[float], b: Sequence[float]) -> bool:
return max(a[0], b[0]) < min(a[2], b[2]) and max(a[1], b[1]) < min(a[3], b[3])
[docs]
@dataclass(frozen=True, slots=True)
class PVFootprintModel:
"""An explicitly trained spectral random forest with safe JSON persistence.
Fitting uses scikit-learn. Prediction reads only learned numeric decision
trees and the supplied spectral stack; it never queries or consults OSM.
JSON persistence stores numeric arrays instead of executable pickle data.
Training provenance is retained so spatially overlapping evaluation can
be rejected. Held-out-site metrics assess a supplied reference, not
automatic worldwide validity of the model.
"""
feature_names: tuple[str, ...]
trees: tuple[dict[str, list[Any]], ...]
metadata: dict[str, Any]
[docs]
@classmethod
def fit(
cls,
samples: Sequence[PVTrainingSample],
*,
random_state: int = 0,
max_samples_per_class: int = 5_000,
n_estimators: int = 100,
min_samples_leaf: int = 3,
max_depth: int = 20,
) -> PVFootprintModel:
"""Fit a deterministic forest from caller-labelled scenes.
At most ``max_samples_per_class`` valid pixels of each class are
sampled without replacement from each scene. Random seed, counts,
site IDs, bounding boxes, scenes and label sources are recorded.
Class weighting balances the retained training labels. This function
performs no random-pixel train/test split: such a split cannot test
transfer to an unseen farm.
"""
if not samples:
raise ValueError("At least one labelled training sample is required")
_integer(random_state, "random_state", minimum=0, maximum=2**32 - 1)
_integer(max_samples_per_class, "max_samples_per_class")
_integer(n_estimators, "n_estimators", maximum=2_000)
_integer(min_samples_leaf, "min_samples_leaf")
_integer(max_depth, "max_depth", maximum=100)
rng = np.random.default_rng(random_state)
x_parts, y_parts, records = [], [], []
names = samples[0].features.feature_names
for sample in samples:
_check_features(sample.features)
if sample.features.feature_names != names:
raise ValueError("All training samples must use identical ordered features")
if not isinstance(sample.site_id, str) or not sample.site_id.strip():
raise ValueError("Each training sample requires a nonempty site_id")
if not isinstance(sample.label_source, str) or not sample.label_source.strip():
raise ValueError("Each training sample requires a nonempty label_source")
labels = _labels(sample.labels, sample.features.valid_mask.shape)
counts = {}
for value in (0, 1):
candidates = np.flatnonzero(
sample.features.valid_mask.ravel() & (labels.ravel() == value)
)
if len(candidates) > max_samples_per_class:
candidates = rng.choice(candidates, max_samples_per_class, replace=False)
counts[str(value)] = len(candidates)
if len(candidates):
x_parts.append(sample.features.data.reshape(-1, len(names))[candidates])
y_parts.append(np.full(len(candidates), value, dtype=np.uint8))
records.append(
{
"site_id": sample.site_id,
"scene_id": sample.features.scene_id,
"bbox_wgs84": list(sample.features.bbox_wgs84),
"crs": sample.features.crs,
"transform": list(sample.features.transform),
"shape": list(sample.features.valid_mask.shape),
"label_source": sample.label_source,
"selected_pixels": counts,
}
)
if not y_parts or len(np.unique(np.concatenate(y_parts))) != 2:
raise ValueError("Training requires both PV and non-PV labelled valid pixels")
ensemble = _optional("sklearn.ensemble")
classifier = ensemble.RandomForestClassifier(
n_estimators=n_estimators,
min_samples_leaf=min_samples_leaf,
max_depth=max_depth,
random_state=random_state,
class_weight="balanced",
n_jobs=1,
)
classifier.fit(np.concatenate(x_parts), np.concatenate(y_parts))
trees = []
positive_index = list(classifier.classes_).index(1)
for estimator in classifier.estimators_:
tree = estimator.tree_
counts = tree.value[:, 0, :]
probabilities = counts[:, positive_index] / counts.sum(axis=1)
trees.append(
{
"left": tree.children_left.tolist(),
"right": tree.children_right.tolist(),
"feature": tree.feature.tolist(),
"threshold": tree.threshold.tolist(),
"probability": probabilities.tolist(),
}
)
return cls(
feature_names=names,
trees=tuple(trees),
metadata={
"algorithm": "RandomForestClassifier",
"sklearn_version": _optional("sklearn").__version__,
"random_state": random_state,
"n_estimators": n_estimators,
"min_samples_leaf": min_samples_leaf,
"max_depth": max_depth,
"max_samples_per_class_per_scene": max_samples_per_class,
"class_weight": "balanced",
"training": records,
"probabilities_calibrated": False,
"inference_uses_osm": False,
},
)
def _payload(self) -> dict[str, Any]:
return {
"format": _MODEL_FORMAT,
"feature_names": list(self.feature_names),
"trees": list(self.trees),
"metadata": self.metadata,
}
@property
def model_id(self) -> str:
"""SHA-256 of the model's canonical numeric JSON representation."""
encoded = json.dumps(
self._payload(), sort_keys=True, separators=(",", ":"), allow_nan=False
)
return sha256(encoded.encode()).hexdigest()
[docs]
def save(self, path: str | Path, *, overwrite: bool = False) -> Path:
"""Save non-executable JSON, refusing to overwrite by default."""
destination = Path(path)
destination.parent.mkdir(parents=True, exist_ok=True)
with destination.open("w" if overwrite else "x", encoding="utf-8") as stream:
json.dump(
self._payload(), stream, sort_keys=True, separators=(",", ":"), allow_nan=False
)
stream.write("\n")
return destination
[docs]
@classmethod
def load(cls, path: str | Path) -> PVFootprintModel:
"""Read and validate numeric JSON; never execute serialized Python."""
source = Path(path)
if source.stat().st_size > 100_000_000:
raise ValueError("Model JSON exceeds the 100 MB size limit")
try:
payload = json.loads(source.read_text(encoding="utf-8"))
# Python's decoder permits NaN/Infinity, but portable model JSON does not.
json.dumps(payload, allow_nan=False)
if not isinstance(payload, dict) or payload.get("format") != _MODEL_FORMAT:
raise ValueError("Unsupported PV model format")
names, trees, metadata = payload["feature_names"], payload["trees"], payload["metadata"]
if (
not isinstance(names, list)
or not names
or not all(isinstance(name, str) and name for name in names)
or len(set(names)) != len(names)
):
raise ValueError("Invalid model feature names")
if (
not isinstance(trees, list)
or not 1 <= len(trees) <= 2_000
or not isinstance(metadata, dict)
):
raise ValueError("Invalid model trees or metadata")
total_nodes = 0
for tree in trees:
keys = ("left", "right", "feature", "threshold", "probability")
if not isinstance(tree, dict) or any(
not isinstance(tree.get(key), list) for key in keys
):
raise ValueError("Invalid numeric decision tree")
n = len(tree["left"])
total_nodes += n
if not n or total_nodes > 2_000_000 or any(len(tree[key]) != n for key in keys):
raise ValueError("Invalid tree lengths or too many nodes")
indegree = np.zeros(n, dtype=np.int32)
for index, (left, right, feature, threshold, probability) in enumerate(
zip(*(tree[key] for key in keys), strict=True)
):
if any(
isinstance(value, bool) or not isinstance(value, int)
for value in (left, right, feature)
):
raise ValueError("Tree indices must be integers")
if (
not math.isfinite(threshold)
or not math.isfinite(probability)
or not 0 <= probability <= 1
):
raise ValueError("Invalid tree threshold or probability")
if left == right == -1:
continue
if not (
index < left < n
and index < right < n
and left != right
and 0 <= feature < len(names)
):
raise ValueError("Invalid or cyclic tree children")
indegree[left] += 1
indegree[right] += 1
if indegree[0] != 0 or not np.all(indegree[1:] == 1):
raise ValueError("Decision tree must be connected and have one parent per node")
training = metadata.get("training")
if not isinstance(training, list) or not training:
raise ValueError("Model must retain training provenance")
for record in training:
if not isinstance(record, dict) or not all(
isinstance(record.get(key), str) and record[key]
for key in ("site_id", "scene_id", "label_source")
):
raise ValueError("Invalid training provenance")
bbox = record.get("bbox_wgs84")
if (
not isinstance(bbox, list)
or len(bbox) != 4
or not all(math.isfinite(v) for v in bbox)
or not (-180 <= bbox[0] < bbox[2] <= 180 and -90 <= bbox[1] < bbox[3] <= 90)
):
raise ValueError("Invalid training bounding box")
shape = record.get("shape")
if (
not isinstance(shape, list)
or len(shape) != 2
or any(
isinstance(value, bool) or not isinstance(value, int) or value <= 0
for value in shape
)
):
raise ValueError("Invalid training grid shape")
crs, affine, _ = _projected_grid(record["crs"], record["transform"])
bounds = _actual_bounds(affine, shape)
actual_bbox = _optional("rasterio.warp").transform_bounds(
crs, "EPSG:4326", *bounds, densify_pts=21
)
if not np.allclose(bbox, actual_bbox, rtol=0, atol=1e-8):
raise ValueError("Training bbox must match its recorded image grid")
return cls(tuple(names), tuple(trees), metadata)
except (KeyError, TypeError, json.JSONDecodeError, OverflowError) as exc:
raise ValueError("Invalid PV model JSON") from exc
def _scores(self, data: np.ndarray) -> np.ndarray:
# Match scikit-learn's tree inference conversion before comparison.
data = np.asarray(data, dtype=np.float32)
scores = np.zeros(len(data), dtype=np.float64)
for tree in self.trees:
left = np.asarray(tree["left"], dtype=np.int32)
right = np.asarray(tree["right"], dtype=np.int32)
feature = np.asarray(tree["feature"], dtype=np.int32)
threshold = np.asarray(tree["threshold"], dtype=np.float64)
probabilities = np.asarray(tree["probability"], dtype=np.float64)
nodes = np.zeros(len(data), dtype=np.int32)
for _ in range(len(left)):
active = np.flatnonzero(left[nodes] != -1)
if not len(active):
break
branch = nodes[active]
take_left = data[active, feature[branch]] <= threshold[branch]
nodes[active] = np.where(take_left, left[branch], right[branch])
scores += probabilities[nodes]
return (scores / len(self.trees)).astype(np.float32)
[docs]
def predict(
self,
features: PVFeatures,
*,
threshold: float = 0.5,
min_area_m2: float = 1_000.0,
) -> PVFootprintPrediction:
"""Infer PV scores and four-connected footprint polygons from imagery.
No OSM input is accepted. Area filtering removes entire components,
retaining holes and the red grid's pixel edges. GeoJSON is WGS84;
areas are measured on the projected input grid. This is approximate
array footprint area, not panel surface area or installed capacity.
"""
_check_features(features)
if features.feature_names != self.feature_names:
raise ValueError("Prediction feature names/order do not match the trained model")
if isinstance(threshold, bool) or not math.isfinite(threshold) or not 0 < threshold < 1:
raise ValueError("threshold must be finite and strictly between 0 and 1")
minimum = _nonnegative(min_area_m2, "min_area_m2")
valid = features.valid_mask
scores = np.full(valid.shape, np.nan, dtype=np.float32)
flat_valid = np.flatnonzero(valid.ravel())
flat_data = features.data.reshape(-1, len(self.feature_names))
for start in range(0, len(flat_valid), 100_000):
indices = flat_valid[start : start + 100_000]
scores.ravel()[indices] = self._scores(flat_data[indices])
candidate = valid & (scores >= threshold)
raster = _optional("rasterio.features")
affine = _optional("rasterio.transform").Affine(*features.transform)
warp = _optional("rasterio.warp")
geometry = _optional("shapely.geometry")
polygons, native_polygons = [], []
pixel_area_units = abs(affine.a * affine.e)
for index, (polygon, _) in enumerate(
raster.shapes(
candidate.astype(np.uint8), mask=candidate, connectivity=4, transform=affine
)
):
area = geometry.shape(polygon).area / pixel_area_units * features.pixel_area_m2
if area + features.pixel_area_m2 * 1e-9 < minimum:
continue
native_polygons.append((polygon, 1))
polygons.append(
{
"type": "Feature",
"id": index,
"geometry": warp.transform_geom(features.crs, "EPSG:4326", polygon),
"properties": {
"area_m2": float(area),
"pixel_count": round(area / features.pixel_area_m2),
"source": "image-derived supervised PV candidate",
"scene_id": features.scene_id,
"threshold": threshold,
},
}
)
retained = np.zeros(valid.shape, dtype=bool)
if native_polygons:
retained = raster.rasterize(
native_polygons, out_shape=valid.shape, transform=affine, fill=0, dtype="uint8"
).astype(bool)
overlaps = any(
_boxes_overlap(features.bbox_wgs84, record["bbox_wgs84"])
for record in self.metadata["training"]
)
metadata = {
"model_id": self.model_id,
"scene_id": features.scene_id,
"crs": features.crs,
"transform": list(features.transform),
"bounds": list(features.bounds),
"bbox_wgs84": list(features.bbox_wgs84),
"pixel_area_m2": features.pixel_area_m2,
"inference_uses_osm": False,
"scores_calibrated": False,
"threshold": threshold,
"min_area_m2": minimum,
"connectivity": 4,
"valid_pixels": int(valid.sum()),
"total_pixels": int(valid.size),
"candidate_pixels_before_area_filter": int(candidate.sum()),
"retained_pixels": int(retained.sum()),
"overlaps_training_area": overlaps,
"area_semantics": "projected pixel footprint; not module surface area",
"feature_provenance": features.provenance,
}
geojson = {"type": "FeatureCollection", "features": polygons, "properties": metadata}
return PVFootprintPrediction(
np.ma.array(scores, mask=~valid), np.ma.array(retained, mask=~valid), geojson, metadata
)
[docs]
def evaluate(
self,
features: PVFeatures,
labels: np.ndarray,
*,
site_id: str,
label_source: str,
threshold: float = 0.5,
min_area_m2: float = 1_000.0,
) -> dict[str, Any]:
"""Evaluate an unseen site against caller-labelled valid pixels.
Rejects a training site ID or geographic overlap, including a later
image of the same farm under a different ID. Returns raw-threshold
and area-filtered metrics separately. OSM labels yield agreement
with that map snapshot; they do not establish ground-truth accuracy.
"""
if (
not isinstance(site_id, str)
or not site_id.strip()
or not isinstance(label_source, str)
or not label_source.strip()
):
raise ValueError("Evaluation requires nonempty site_id and label_source")
_check_features(features)
for record in self.metadata["training"]:
if record["site_id"] == site_id or _boxes_overlap(
features.bbox_wgs84, record["bbox_wgs84"]
):
raise ValueError(
"Held-out evaluation must use a geographically disjoint, unseen site"
)
prediction = self.predict(features, threshold=threshold, min_area_m2=min_area_m2)
raw = np.ma.array(prediction.probabilities >= threshold, mask=~features.valid_mask)
return {
"site_id": site_id,
"scene_id": features.scene_id,
"label_source": label_source,
"spatially_disjoint_from_training": True,
"model_id": self.model_id,
"threshold": threshold,
"min_area_m2": min_area_m2,
"raw_threshold": evaluate_pv_mask(raw, labels),
"area_filtered": evaluate_pv_mask(prediction.mask, labels),
}
[docs]
def evaluate_pv_mask(
predicted: np.ndarray | np.ma.MaskedArray, labels: np.ndarray
) -> dict[str, Any]:
"""Measure binary agreement on labelled, unmasked pixels only.
Labels are -1 unknown, 0 non-PV and 1 PV. Unknown labels and masked
predictions do not become true negatives. Undefined precision/recall/F1/
IoU are ``None``. Counts and coverage make missing-reference cases clear.
This low-level scorer does not enforce train/test spatial separation;
use ``PVFootprintModel.evaluate`` for a held-out-site guard.
"""
prediction = np.ma.asarray(predicted)
reference = _labels(labels, prediction.shape)
if prediction.ndim != 2 or not np.isin(prediction.compressed(), (0, 1)).all():
raise ValueError("Predictions must be a two-dimensional binary mask")
usable = ~np.ma.getmaskarray(prediction)
known = reference != -1
valid = usable & known
values = np.asarray(prediction.data, dtype=bool)
tp = int(np.count_nonzero(valid & values & (reference == 1)))
fp = int(np.count_nonzero(valid & values & (reference == 0)))
fn = int(np.count_nonzero(valid & ~values & (reference == 1)))
tn = int(np.count_nonzero(valid & ~values & (reference == 0)))
def ratio(numerator: int, denominator: int) -> float | None:
return numerator / denominator if denominator else None
return {
"true_positive": tp,
"false_positive": fp,
"false_negative": fn,
"true_negative": tn,
"precision": ratio(tp, tp + fp),
"recall": ratio(tp, tp + fn),
"f1": ratio(2 * tp, 2 * tp + fp + fn),
"iou": ratio(tp, tp + fp + fn),
"accuracy": ratio(tp + tn, tp + fp + fn + tn),
"evaluated_pixels": int(valid.sum()),
"labelled_pixels": int(known.sum()),
"prediction_valid_pixels": int(usable.sum()),
"total_pixels": int(valid.size),
"labelled_coverage": ratio(int(valid.sum()), int(known.sum())),
"evaluated_fraction": ratio(int(valid.sum()), int(valid.size)),
}