Reproducible 3D PV scenes from candidate footprints#
The El Mirlo 3D gallery continues the module-counting pilot near Rengo. It combines the same 2,055 candidate module footprints in 22 tables with a pinned Copernicus GLO-30 elevation crop and explicit mounting scenarios. The result is 2.5D scenario geometry, not photogrammetry or a surveyed as-built model. It covers the same partial southern inspection block, not the complete farm.
Evidence and assumptions#
Component |
Input or rule |
Interpretation |
|---|---|---|
Module XY |
Existing image candidates, including review candidates |
Unvalidated horizontal footprints; exclusions stay excluded |
Table groups |
Counter’s connected table IDs |
A common mounting plane per detected table |
Elevation |
Native 48 × 47 crop of GLO-30, roughly 30 m sampling |
DSM including vegetation/buildings; not bare-earth terrain |
Vertical datum |
EGM2008 metres |
Preserved, with no conversion to ellipsoidal heights |
Local axes |
WGS84 azimuthal equidistant, east/north/up |
Origin −70.8615°, −34.4515°; Z=0 at 282 m EGM2008 |
Default mounting |
20° tilt, 0° facing azimuth, 0.8 m sampled clearance |
Illustrative assumptions; not measured or inferred |
Display grid |
81 × 121 bilinear samples |
Smooth display only; no new source resolution |
Scope |
2,055 candidates, 22 tables, 0 terrain exclusions |
Inherited candidates, not a verified asset inventory |
The original same-image audit matched 51 of 72 single-assistant reference centres, with 21 missed and no extras in the labelled regions. Those annotations were used during method development and are not independent human or held-out validation. Adding height does not improve the count’s evidence. Main TanDEM-X acquisitions for GLO-30 date to 2011–2015, with potentially older gap-fill sources. The elevation surface and the 2024 image need not represent the same physical state.
Run the pinned example offline#
From the repository root, with Python 3.12 or 3.13:
uv sync --locked --all-packages
uv run --no-sync python examples/analysis/plot_rengo_site_3d.py
The example verifies SHA256 hashes, re-runs the candidate detector, builds the scene and plots the evidence, 3D overview and tilt sensitivity. No provider calls are required. To write the interactive viewer and meshes to a new directory:
from pathlib import Path
from energy_analysis.site_3d import export_site_scene
from energy_analysis.site_3d.rengo import build_rengo_scene
data = Path("examples/analysis/data")
study = build_rengo_scene(data / "rengo_modules", data / "rengo_3d")
export_site_scene(
study["scene"],
"outputs/el-mirlo-3d",
title="El Mirlo · southern inspection block",
provenance={
"terrain": study["terrain_source"],
"configuration": study["configuration"],
"counting": study["counting"]["manifest"],
},
attribution=study["terrain_source"]["notice"],
evidence_note=study["configuration"]["assumptions_note"],
)
Open outputs/el-mirlo-3d/viewer.html directly in a WebGL-capable browser. The
viewer embeds Plotly, needs no server or internet and offers orbit/zoom, layer
toggles, camera presets and explicitly labelled vertical display factors. Its
default metric scale is 1:1. Display exaggeration does not alter exported geometry.
No basemap or imagery texture is embedded in the viewer.
The gallery’s ZIP includes both sets of fixtures, this guide, the gallery script,
the recapture script and the generated viewer/meshes. Extract it and run its
plot_rengo_site_3d.py using the installed workspace environment. The pinned
dependency versions remain in the repository’s uv.lock; the ZIP is not a
vendored Python environment.
Apply the method to another site#
Supply a north-up elevation GeoTIFF with metre heights and a declared vertical
datum. It may use a projected or geographic horizontal CRS. Supply a WGS84
GeoJSON FeatureCollection whose features are individual convex quadrilateral
modules, each with a unique id and a table property. Each ring has four
corners plus a closing repeat. Holes, multipolygons and altitude coordinates
are rejected rather than guessed. A table polygon is not automatically divided
into modules. Features marked status: excluded are omitted.
import json
from pathlib import Path
import numpy as np
from energy_data_retrieval.terrain import TerrainSource, read_terrain
from energy_analysis.site_3d import (
elevation_grid,
footprints_from_geojson,
export_site_scene,
)
from energy_methods.pv_site_3d import (
LocalSiteFrame,
MountingParameters,
build_pv_site_scene,
)
footprints = footprints_from_geojson(json.loads(Path("modules.geojson").read_text()))
descriptor = TerrainSource(
id="my_dem",
name="My elevation provider and acquisition date",
surface="Describe DSM or DTM",
vertical_datum="Declare the source datum",
reference_ids=(),
)
grid = elevation_grid(read_terrain("terrain.tif", descriptor))
points = np.concatenate([f.vertices_wgs84 for f in footprints])
lon, lat = points.mean(axis=0)
west, south = points.min(axis=0) - 0.0001
east, north = points.max(axis=0) + 0.0001
# Raster coverage needs enough native neighbours for interpolation.
origin_z = float(grid.sample([[lon, lat]])[0])
frame = LocalSiteFrame(float(lon), float(lat), origin_z)
scene = build_pv_site_scene(
footprints,
grid,
frame=frame,
bounds_wgs84=(west, south, east, north),
mounting=MountingParameters(tilt_degrees=20, azimuth_degrees=0, minimum_clearance_m=0.8),
# Optional: table_mounting={"table-7": MountingParameters(10, 180, 1.2)},
)
export_site_scene(
scene,
"outputs/my-site-3d",
attribution="Provider's required credit",
provenance={"source": "Record URL/date/hash and footprint provenance"},
)
Use measured mounting parameters when available, or label alternatives as
scenarios. Azimuth is clockwise from local north towards the module’s facing
direction: 0° north, 90° east, 180° south. The implementation supports sites in
either hemisphere without assuming which way they face.
To continue a counter directly, use footprints_from_count(result, bounds);
bounds must be the original north-up EPSG:4326 image’s outer pixel edges.
The adapter applies its half-pixel convention and retains table groups.
The Rengo GeoJSON export now includes table, row and column identifiers.
Geometry and missingness rules#
energy_methods.pv_site_3d contains provider-independent geometry. It uses a local
WGS84 azimuthal-equidistant projection with always_xy and a default 20 km radius
guard. Longitude/latitude input is never treated as Cartesian metres. Larger or
antimeridian sites should be split into local scenes. The local frame stores its
origin and WKT explicitly; elevation origin subtraction does not change datum.
For tilt β and facing azimuth α, the plane’s metric gradient is
g = -tan(β) × [sin(α), cos(α)]. For every table, the algorithm samples terrain
at each footprint’s four corners, four edge midpoints and centre, then sets
b = max(terrain_height − g · xy) + minimum_clearance over those points.
Every module in the table receives z = g · xy + b − elevation_origin.
This makes the table coplanar and enforces clearance at the sampled points.
It does not guarantee clearance between samples or account for support hardware.
Tilt is absolute to horizontal, not added to ground slope. Original XY remains
unchanged, so tilt changes slant dimensions; these are not inferred physical
module dimensions. Different tracker positions or mounting heights require
appropriate table groups and measured parameters.
Detected groups may join separate physical racks; split them when mounting differs.
Elevation sampling is bilinear at native pixel centres. It does not extrapolate, fill nodata or replace missing values with zero. A module lacking any required terrain sample is rejected with its ID and reason. Display triangles touching unsupported samples are omitted. Exact valid native centres remain valid next to nodata. Source features below native resolution remain unresolved even when the display mesh is dense. All-invalid inputs fail explicitly. Coordinates within 1e-8 native pixels of a centre are snapped to that centre to avoid projection round-off creating false nodata rejections.
energy_analysis.site_3d adapts the existing terrain connector and counter,
provides plots and exports, and holds the hash-checked Rengo composition.
Export contract#
File |
Contents |
|---|---|
|
Self-contained interactive scene; no network required |
|
Triangulated terrain and individually named module surfaces |
|
Full vertices, faces, module/table IDs, CRS, height origin, datum and provenance |
|
Counts, mounting parameters, source information and terrain rejections |
|
Import conventions and source credit |
Import OBJ as metres, Z up, keeping its MTL beside it. OBJ itself has no
geographic CRS field, so retain scene.json. Meshes are surfaces, not watertight
solids. This version does not reconstruct frames, foundations, wiring or trackers,
and performs no shading, irradiance, yield or engineering calculations.
Output directories must be new to prevent accidental overwrites.
Refresh the elevation capture explicitly#
uv run --no-sync python scripts/prepare_rengo_3d.py \
--output outputs/rengo-3d-recapture --download-directory data/copernicus-cache
Add --proxy-from-env only when an HTTPS proxy is required. The script uses the
existing Copernicus connector, downloads the full S35/W071 tile outside tracked
examples, crops native pixels without resampling, and records the original
receipt, metadata and hashes. It never refreshes imagery or silently replaces
the pinned fixture. Review hash or source changes before adopting a new capture.
Verification and sources#
Tests use analytic planes and multiple geographic origins to check projection, bilinear sampling, zero versus nodata, common table slopes, clearance, face winding, preserved XY, per-table overrides, explicit rejection and export indices. The offline Rengo integration checks the inherited 2,055 candidates, 22 tables and zero terrain rejections. These are software checks, not field-validation scores.
Primary references: PROJ azimuthal-equidistant projection, Copernicus DEM description and terms, AWS public DEM distribution, Plotly mesh API and self-contained HTML export. The table lifting rule is a documented implementation choice, not a published photogrammetric reconstruction method.
Required adapted-data credit:
produced using Copernicus WorldDEM-30 © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved