Source code for energy_methods.pv_lattice_counting

"""Orientation-aware counting of optically resolved PV frame lattices.

PCA rectification, autocorrelation and local contrast checks extend the original
horizontal-table counter. This is an experimental image method, not a trained
model, super-resolution procedure or verified engineering inventory.
"""

from __future__ import annotations

from dataclasses import dataclass
from itertools import pairwise
from typing import Any

import numpy as np
import pandas as pd
from numpy.typing import NDArray
from scipy import ndimage, signal

from energy_methods.pv_module_counting import ModuleCandidate

REFERENCE_IDS = ("cardoso_2024_pv_modules", "scipy_find_peaks")
type FloatArray = NDArray[np.float64]


[docs] @dataclass(frozen=True) class LatticeCountingConfig: """Screening thresholds, not calibrated probabilities or known module counts. ``source_pixel_ratio`` is effective source sampling / finest delivered pixel sampling, at least one. It stops oversampled imagery passing the pitch gate. Colour is (B - R) / (R + G + B); contrast uses 0..1 RGB intensity. """ minimum_chroma: float = 0.018 minimum_component_pixels: int = 300 minimum_aspect: float = 3.0 frame_prominence: float = 0.015 minimum_autocorrelation: float = 0.30 minimum_source_pitch: float = 3.0 maximum_pitch_pixels: int = 30 source_pixel_ratio: float = 1.0 spacing_tolerance: float = 0.30 minimum_panel_fraction: float = 0.55 minimum_cell_contrast: float = 0.003 def __post_init__(self) -> None: for name in ( "minimum_chroma", "frame_prominence", "minimum_autocorrelation", "spacing_tolerance", "minimum_panel_fraction", "minimum_cell_contrast", ): value = getattr(self, name) if isinstance(value, bool) or not np.isfinite(value) or not 0 < value < 1: raise ValueError(f"{name} must be finite and between 0 and 1") for name, low, high in ( ("minimum_component_pixels", 25, 4_000_000), ("maximum_pitch_pixels", 4, 100), ): value = getattr(self, name) if type(value) is not int or not low <= value <= high: raise ValueError(f"{name} must be an integer in {low}..{high}") for name, low, high in ( ("minimum_aspect", 1.5, 100), ("minimum_source_pitch", 3, 30), ("source_pixel_ratio", 1, 100), ): value = getattr(self, name) if isinstance(value, bool) or not np.isfinite(value) or not low <= value <= high: raise ValueError(f"{name} must be finite and in {low}..{high}")
[docs] @dataclass(frozen=True) class LatticeTable: """Image evidence for a rectified table, including all observed frame lines.""" id: int bounds_xyxy: tuple[int, int, int, int] centre_xy: tuple[float, float] angle_degrees: float column_pitch_pixels: float row_pitch_pixels: float autocorrelation: float column_lines: tuple[float, ...] row_lines: tuple[float, ...]
[docs] @dataclass(frozen=True) class LatticeCount: """Candidates and explicit rejected cells/tables; None means unresolved.""" image_shape: tuple[int, int] config: LatticeCountingConfig tables: tuple[LatticeTable, ...] cells: tuple[ModuleCandidate, ...] rejected_tables: tuple[dict[str, Any], ...] @property def estimated_modules(self) -> int | None: return sum(c.status != "excluded" for c in self.cells) if self.tables else None
[docs] def to_frame(self) -> pd.DataFrame: """Export accepted and rejected grid cells in original-image coordinates.""" return pd.DataFrame( [ { "id": c.id, "table": c.table, "row": c.row, "column": c.column, "x_pixel": float(np.mean([p[0] for p in c.vertices_xy])), "y_pixel": float(np.mean([p[1] for p in c.vertices_xy])), "status": c.status, "reasons": ";".join(c.reasons), "panel_fraction": c.blue_fraction, } for c in self.cells ], columns=[ "id", "table", "row", "column", "x_pixel", "y_pixel", "status", "reasons", "panel_fraction", ], )
def _observed_lines(profile: FloatArray, prominence: float) -> FloatArray: """Locate actual bright maxima, with quadratic subpixel refinement; never infill.""" smooth = ndimage.gaussian_filter1d(profile, 0.7) peaks, _ = signal.find_peaks(smooth, prominence=prominence, distance=3) denominator = smooth[peaks - 1] - 2 * smooth[peaks] + smooth[peaks + 1] delta = np.divide( 0.5 * (smooth[peaks - 1] - smooth[peaks + 1]), denominator, out=np.zeros(len(peaks)), where=np.abs(denominator) > 1e-12, ) return peaks.astype(float) + np.clip(delta, -0.5, 0.5) def _period(profile: FloatArray, cfg: LatticeCountingConfig) -> tuple[float, float]: """First supported autocorrelation maximum, rather than a multiple/harmonic.""" residual = profile - ndimage.gaussian_filter1d(profile, cfg.maximum_pitch_pixels / 2) corr = signal.correlate(residual, residual, mode="full", method="fft")[len(profile) - 1 :] if corr[0] <= np.finfo(float).eps: raise ValueError("no_periodic_contrast") corr /= corr[0] peaks, _ = signal.find_peaks(corr, height=cfg.minimum_autocorrelation, prominence=0.05) peaks = peaks[(peaks >= 3) & (peaks <= min(cfg.maximum_pitch_pixels, len(profile) // 4))] if not len(peaks): raise ValueError("no_supported_period") peak = peaks[0] d = 0.5 * (corr[peak - 1] - corr[peak + 1]) / (corr[peak - 1] - 2 * corr[peak] + corr[peak + 1]) return float(peak + np.clip(d, -0.5, 0.5)), float(corr[peak])
[docs] def count_lattice_pv_modules( rgb: NDArray[Any], site_mask: NDArray[np.bool_] | None = None, *, config: LatticeCountingConfig | None = None, maximum_pixels: int = 4_000_000, maximum_cells: int = 100_000, ) -> LatticeCount: """Find rotated blue/grey tables and count cells bounded by observed frame lines. The long-axis period is checked independently with autocorrelation. At least three transverse lines (two module rows) must be visible. Missing lines and irregular gaps are excluded; no lattice positions or table edges are invented. Interpolation only rectifies the input: it adds no optical information. Table ends, mounting hardware, glare and faint frames can reduce recall. A lattice can still be a cell pattern or another repeated structure: evaluate against image annotations and independent records before interpreting modules. """ cfg = config or LatticeCountingConfig() for name, value in (("maximum_pixels", maximum_pixels), ("maximum_cells", maximum_cells)): if type(value) is not int or value < 1: raise ValueError(f"{name} must be a positive integer") image = np.asarray(rgb) if image.ndim != 3 or image.shape[2] != 3 or min(image.shape[:2]) < 16: raise ValueError("rgb must have shape H x W x 3 with H,W >= 16") if np.prod(image.shape[:2]) > maximum_pixels: raise ValueError("Image exceeds maximum_pixels") if image.dtype == np.uint8: image = image.astype(float) / 255 elif np.issubdtype(image.dtype, np.floating): image = image.astype(float) else: raise ValueError("rgb must be uint8 or floating point in 0..1") if not np.isfinite(image).all() or image.min() < 0 or image.max() > 1: raise ValueError("rgb must be finite and in 0..1") h, w = image.shape[:2] scope = np.ones((h, w), dtype=bool) if site_mask is None else np.asarray(site_mask) if scope.dtype != np.bool_ or scope.shape != (h, w) or not scope.any(): raise ValueError("site_mask must be nonempty boolean with matching image shape") grey = image.mean(axis=2) chroma = (image[..., 2] - image[..., 0]) / np.maximum(image.sum(axis=2), 1e-8) colour = (chroma > cfg.minimum_chroma) & scope segmented = ndimage.binary_closing(colour, iterations=2) segmented = ndimage.binary_opening(segmented) & scope labels, _ = ndimage.label(segmented) tables: list[LatticeTable] = [] cells: list[ModuleCandidate] = [] rejected: list[dict[str, Any]] = [] for label, slices in enumerate(ndimage.find_objects(labels), 1): if slices is None: continue ys, xs = slices y, x = np.nonzero(labels[slices] == label) if len(x) < cfg.minimum_component_pixels: continue xy = np.column_stack([x + xs.start, y + ys.start]).astype(float) centre = xy.mean(axis=0) bounds = (xs.start, ys.start, xs.stop, ys.stop) try: if min(xs.start, ys.start, w - xs.stop, h - ys.stop) < 6: raise ValueError("clipped_image_edge") _, eigenvectors = np.linalg.eigh(np.cov(xy.T)) along = eigenvectors[:, -1] if along[0] < 0: along = -along basis = np.column_stack([along, [-along[1], along[0]]]) uv = (xy - centre) @ basis low, high = uv.min(axis=0), uv.max(axis=0) if (high[0] - low[0]) / max(high[1] - low[1], 1) < cfg.minimum_aspect: raise ValueError("unsupported_table_shape") a = np.arange(np.floor(low[0]) - 6, np.ceil(high[0]) + 7) b = np.arange(np.floor(low[1]) - 6, np.ceil(high[1]) + 7) uu, vv = np.meshgrid(a, b) source = np.stack([uu, vv], axis=-1) @ basis.T + centre if ( source[..., 0].min() < 0 or source[..., 0].max() >= w - 1 or source[..., 1].min() < 0 or source[..., 1].max() >= h - 1 ): raise ValueError("clipped_rectified_patch") patch = ndimage.map_coordinates(grey, [source[..., 1], source[..., 0]], order=1) longitudinal = patch[8:-8].mean(axis=0) transverse = patch[:, 10:-10].mean(axis=1) px = _observed_lines(longitudinal, cfg.frame_prominence) + a[0] py = _observed_lines(transverse, cfg.frame_prominence) + b[0] if len(px) < 6 or len(py) < 3: raise ValueError("unresolved_frame_lines") dx, correlation = _period(longitudinal[6:-6], cfg) dy = float(np.median(np.diff(py))) if min(dx, dy) / cfg.source_pixel_ratio < cfg.minimum_source_pitch: raise ValueError("insufficient_source_pitch") if np.mean(np.abs(np.diff(px) / dx - 1) <= cfg.spacing_tolerance) < 0.6: raise ValueError("inconsistent_frame_period") if len(cells) + (len(px) - 1) * (len(py) - 1) > maximum_cells: raise OverflowError("Detected lattice exceeds maximum_cells") except ValueError as error: rejected.append({"bounds_xyxy": bounds, "reason": str(error)}) continue table_id = len(tables) + 1 tables.append( LatticeTable( table_id, bounds, (float(centre[0]), float(centre[1])), float(np.degrees(np.arctan2(along[1], along[0]))), dx, dy, correlation, tuple(px.tolist()), tuple(py.tolist()), ) ) for row, (v0, v1) in enumerate(pairwise(py), 1): for col, (u0, u1) in enumerate(pairwise(px), 1): local = np.array([[u0, v0], [u1, v0], [u1, v1], [u0, v1]]) vertices = local @ basis.T + centre su, sv = np.meshgrid(np.linspace(u0, u1, 7), np.linspace(v0, v1, 7)) samples = np.stack([su, sv], axis=-1) @ basis.T + centre coordinates = [samples[..., 1], samples[..., 0]] inside = ndimage.map_coordinates(scope, coordinates, order=0, mode="constant") colour_samples = ndimage.map_coordinates(chroma, coordinates, order=1) fraction = float((colour_samples[2:-2, 2:-2] > cfg.minimum_chroma / 2).mean()) light = ndimage.map_coordinates(grey, coordinates, order=1) interior = light[2:-2, 2:-2].mean() contrast_x = light[2:-2, [0, -1]].mean() - interior contrast_y = light[[0, -1], 2:-2].mean() - interior reasons = [] if not inside.all(): reasons.append("outside_site_mask") if abs((u1 - u0) / dx - 1) > cfg.spacing_tolerance: reasons.append("unresolved_column_gap") if abs((v1 - v0) / dy - 1) > cfg.spacing_tolerance: reasons.append("unresolved_row_gap") if min(u1 - u0, v1 - v0) / cfg.source_pixel_ratio < cfg.minimum_source_pitch: reasons.append("insufficient_source_pitch") if fraction < cfg.minimum_panel_fraction: reasons.append("insufficient_panel_colour") if min(contrast_x, contrast_y) < cfg.minimum_cell_contrast: reasons.append("weak_local_frame_contrast") p0, p1, p2, p3 = ((float(p[0]), float(p[1])) for p in vertices) cells.append( ModuleCandidate( table_id, row, col, (p0, p1, p2, p3), "excluded" if reasons else "regular_candidate", tuple(reasons), fraction, ) ) return LatticeCount((h, w), cfg, tuple(tables), tuple(cells), tuple(rejected))