Ground satellite imagery and renewable-energy features#
Retrieve Sentinel-2 images for a geographic area through Python, then retain the acquisition metadata alongside the pixels. The ground connector uses Element 84’s public Earth Search STAC API and Sentinel-2 Collection 1 Level-2A COGs. Public HTTPS assets need no API key or AWS account. [3]
This supports inspection of terrestrial PV sites and preparation of inputs for later mapping methods. It complements OrbitalPV’s spacecraft telemetry and orbit connectors.
Relationship to the requested paper#
Dunnett et al. (2020), Harmonised global datasets of wind and solar farm
locations and power, starts with OpenStreetMap features retrieved through
Overpass. It selects generator:source or plant:source tags with values
solar and wind. The workflow also uses 2015 GHSL settlement classes
to flag urban areas and water, spatial grouping of features, and independent
capacity records to calibrate estimates. [1]
The connectors here retrieve imagery and the raw OSM input features. Satellite imagery is an extension for visual inspection or a future mapping method; the paper does not infer its global inventory from satellite pixels. The additional PV footprints, farm grouping and capacity methods implement image classification, GHSL retrieval, polygon deduplication, farm grouping and capacity calibration. They distinguish inferred footprints from source OSM features and report validation separately. A current OSM query is a different snapshot from the study’s original extract; the examples do not recreate its complete inventory.
The original data and scripts are available in the authors’ versioned
Figshare archive, DOI 10.6084/m9.figshare.11310269.v2. Its GeoPackage files
retain geometries; centroid-only tables are insufficient for recovering
panel outlines. [2]
Install the new API#
This connector is unreleased. Install the repository revision containing it, including the optional raster reader and plotting packages:
python -m pip install "orbital-pv[ground,examples] @ git+https://github.com/julianascencio/orbital-pv.git"
For a reproducible analysis, pin the Git commit and keep the returned STAC metadata, OSM response, query parameters, and output imagery together.
Search and read a small image#
This example searches near Cestas, France. Bounding boxes use WGS84 longitude
and latitude in the order (west, south, east, north). Search results are a
STAC FeatureCollection dictionary. Its features list contains items,
and each item’s assets dictionary describes the available files.
Time bounds are inclusive and interpreted in UTC; a date without a time
means midnight. For example, time_max="2024-09-01" includes midnight
at the start of 1 September, not the whole day.
from pathlib import Path
import orbitalpv as opv
output = Path("data")
output.mkdir(exist_ok=True)
bbox = (-0.833, 44.709, -0.795, 44.742)
with opv.Sentinel2GroundConnector() as connector:
scenes = connector.search(
bbox=bbox,
time_min="2024-06-01",
time_max="2024-09-01",
max_cloud_cover=10,
max_items=10,
cache_path=output / "cestas-scenes.json",
)
if not scenes["features"]:
raise RuntimeError("No scenes; broaden the dates or cloud limit.")
item = scenes["features"][0]
print(item["id"], item["properties"]["datetime"])
print(item["properties"].get("eo:cloud_cover"))
print(sorted(item["assets"]))
print("Result cap reached:", scenes["context"]["limit_reached"])
rgb = connector.read_image(item, bbox=bbox, asset="visual")
rgb.save_geotiff(output / "cestas-rgb.tif")
max_items caps the returned scenes; a bounded search is not a complete
inventory of every matching acquisition. Inspect
scenes["context"]["limit_reached"] when completeness matters. Search uses
spatial intersection, but read_image requires the entire requested bbox
to fit within the scene’s native raster bounds. It raises an error for
partial coverage instead of silently returning a smaller area. Pixels within
the raster can still be nodata; inspect the returned mask.
read_image reads an area from a Cloud-Optimized GeoTIFF instead of
downloading the full scene. GroundImage.data is a masked array ordered
(band, row, column). crs identifies its coordinate system,
transform contains six affine coefficients, and bounds are expressed
in that projected coordinate system. These bounds are not the input
longitude/latitude bbox. save_geotiff writes raw values with georeferencing
and provenance. read_image also enforces max_pixels as a limit on
the total number of band samples: bands multiplied by rows and columns.
A three-band RGB crop therefore uses three samples per spatial pixel.
For an intentional full-file download, use:
with opv.Sentinel2GroundConnector() as connector:
connector.download_asset(item, "visual", output / "full-scene.tif")
Full scenes are substantially larger than site crops; inspect the asset’s size metadata first.
Choose the right pixels#
Asset key |
Pixel size |
Meaning |
|---|---|---|
|
10 m |
Display-ready three-band RGB; not quantitative reflectance. |
|
10 m |
Spectral bands stored as digital numbers with calibration metadata. |
|
20 m |
Shortwave infrared bands; a different native grid from RGB. |
|
20 m |
Categorical scene classification, including cloud and shadow classes. |
Sentinel-2 Level-2A includes surface reflectance and scene classification products. [5] A 10 m pixel is useful for large-site context but does not provide individual panel boundaries. Enlarging a display or resampling to a finer grid does not add spatial information.
eo:cloud_cover describes the scene, not cloudiness at the selected farm.
Use scl to inspect local cloud, shadow and snow classes. Align it to the
image grid before applying a pixel mask; use nearest-neighbour resampling
for categorical classes. A low scene-wide cloud percentage cannot guarantee
a clear site.
Spectral crops preserve the original digital numbers. Conversion is explicit:
with opv.Sentinel2GroundConnector() as connector:
red = connector.read_image(item, bbox=bbox, asset="red")
surface_reflectance = red.reflectance()
red.save_geotiff(output / "cestas-red-raw.tif")
reflectance() uses the spectral asset’s scale and offset, preserving its
missing-data mask. Retain the distinction between the converted array and
the raw GeoTIFF saved above. Do not apply reflectance conversion to the
display-ready RGB product or categorical SCL values.
The default collection is sentinel-2-c1-l2a. Earth Search documents
collection-specific processing, including offsets; its legacy
sentinel-2-l2a collection has reported calibration-metadata inconsistencies.
Mixing the collections or applying a fixed offset to every source is not a
safe substitute for inspecting metadata. [4] [6]
Retrieve the paper’s OSM feature inputs#
with opv.OpenStreetMapEnergyConnector() as connector:
osm = connector.fetch_energy_features(
bbox=bbox,
sources=("solar",),
cache_path=output / "cestas-osm.json",
)
print(len(osm["elements"]))
print(osm.get("osm3s", {}))
The result retains the Overpass response, including raw elements, tags,
relation members, geometry and available snapshot timestamps. It is input
data, not a normalized inventory of unique power plants. Multiple OSM
features can represent panels and the enclosing plant. Missing features
can reflect incomplete mapping.
The query selects generator:source, plant:source, and legacy
power_source tags. Including the legacy key extends the paper’s stated
selection. A solar source tag alone does not establish photovoltaic
technology; inspect method tags such as generator:method=photovoltaic
and retain uncertain cases for review rather than treating every solar
feature as PV.
Relations can describe multipolygons with holes or multiple outer rings.
Automatic polygon assembly needs explicit topology handling; treating a
relation’s member coordinates as one closed ring can produce an incorrect
footprint. This connector preserves the source structure for subsequent
processing. OSM queries are capped at one square degree of bbox area
((east - west) * (north - south)), a geographic limit rather than a
fixed area in square kilometres. Large studies should use appropriately
bounded queries or bulk OSM extracts instead of treating a public Overpass
instance as an unlimited global download service. [7]
The executable image-and-feature walkthroughs cover Cestas, France, Rinconada near Rengo, Chile and Icor in Tenerife.
Attribution and primary sources#
For imagery, retain acquisition identifiers, source assets and the Copernicus Sentinel attribution; distinguish modifications when publishing processed images. Follow the Sentinel data legal notice linked by the collection. OSM data require attribution to OpenStreetMap contributors and are available under the Open Database License; derived database redistribution should follow those terms. [8] The repository’s software license does not replace the input-data licenses.