georeader
georeader is a Python package for processing raster data from different satellite missions. It provides a unified interface for reading, manipulating, and saving geospatial raster data with a focus on machine learning workflows.
georeader is mainly used to process satellite data for scientific usage, to create ML-ready datasets and to implement end-to-end operational inference pipelines (e.g. the Kherson Dam Break floodmap). See georeader concepts and protocols for basic concepts and API.
Install
Requirements: Python ≥3.11
pip install georeader-spaceml
Optional dependencies for specific readers:
# For cloud storage access (GCS, S3, Azure)
pip install georeader-spaceml fsspec gcsfs s3fs adlfs
# For hyperspectral sensors (EMIT, PRISMA, EnMAP)
pip install georeader-spaceml h5py xarray h5netcdf
# For Google Earth Engine integration
pip install georeader-spaceml earthengine-api
Quick Start
Read a Sentinel-2 image from cloud storage
Read from a Sentinel-2 image a fixed size subimage on an specific
lon,latlocation:
from georeader.rasterio_reader import RasterioReader
from georeader import read
# S2 image from WorldFloodsv2 dataset
s2url = "https://huggingface.co/datasets/isp-uv-es/WorldFloodsv2/resolve/main/test/S2/EMSR264_18MIANDRIVAZODETAIL_DEL_v2.tif"
rst = RasterioReader(s2url)
# lazy loading bands
rst_rgb = rst.isel({"band": [3, 2, 1]}) # 1-based list as in rasterio
cords_read = (45.43, -19.53) # long, lat
crs_cords = "EPSG:4326"
# See also read.read_from_bounds, read.read_from_polygon for different ways of croping an image
data = read.read_from_center_coords(rst_rgb,
cords_read, shape=(504, 1040),
crs_center_coords=crs_cords)
data_memory = data.load() # this loads the data to memory
data_memory # GeoTensor object
>> Transform: | 10.00, 0.00, 539910.00|
| 0.00,-10.00, 7842990.00|
| 0.00, 0.00, 1.00|
Shape: (3, 504, 1040)
Resolution: (10.0, 10.0)
Bounds: (539910.0, 7837950.0, 550310.0, 7842990.0)
CRS: EPSG:32738
fill_value_default: 0
from georeader import plot
plot.show((data_memory / 3_500).clip(0, 1))
Saving the GeoTensor as a COG GeoTIFF:
from georeader.save import save_cog
# Supports writing in remote location (e.g. gs://bucket-name/s2_crop.tif)
save_cog(data_memory, "s2_crop.tif", descriptions=["B4","B3", "B2"])
Align images from different sensors
from georeader import read
# Load two images from different sensors
s2_data = read.read_from_tif("sentinel2.tif")
aviris_data = read.read_from_tif("aviris.tif")
# Reproject AVIRIS to match Sentinel-2 grid
aviris_aligned = read.read_reproject(
aviris_data,
dst_crs=s2_data.crs,
dst_transform=s2_data.transform,
dst_shape=s2_data.shape[-2:]
)
Core Concepts
GeoTensor
The central data structure is GeoTensor - a numpy array with geospatial metadata:
from georeader.geotensor import GeoTensor
gt = GeoTensor(
values=np_array, # Shape: (C, H, W) or (H, W)
transform=affine_transform, # Maps pixel to geographic coordinates
crs="EPSG:32613" # Coordinate Reference System
)
# Access properties
gt.bounds # (xmin, ymin, xmax, ymax)
gt.res # (x_res, y_res)
gt.footprint() # Shapely polygon of extent
Reader Protocol
All readers implement the GeoData protocol, providing a consistent interface:
# Any reader works with the same read functions
from georeader import read
data = read.read_from_bounds(reader, bounds, crs_bounds="EPSG:4326")
data = read.read_from_polygon(reader, polygon)
data = read.read_from_center_coords(reader, coords, shape=(512, 512))
Documentation
📚 Full documentation: spaceml-org.github.io/georeader
georeader makes easy to read specific areas of your image, to reproject images from different satellites to a common grid (georeader.read), to go from vector to raster formats (georeader.vectorize and georeader.rasterize) or to do radiance to reflectance conversions (georeader.reflectance).
georeader is mainly used to process satellite data for scientific usage, to create ML-ready datasets and to implement end-to-end operational inference pipelines (e.g. the Kherson Dam Break floodmap).
Tutorials
Sentinel-2
- Reading Sentinel-2 images from the public Google bucket
- Tiling and stitching predictions of an AI model
- Explore metadata of Sentinel-2 object
- Query Sentinel-2 images over a location and time span, mosaic and plot them
- Sentinel-2 images from GEE and CloudSEN12 cloud detection
Read rasters from different satellites
- Tutorial to read overlapping tiles from a GeoTIFF and a Sentinel-2 image
- Example of reading a Proba-V image overlapping with Sentinel-2 forcing same resolution
- Work with EMIT images
- Read overlapping images of PRISMA and EMIT
- Read EnMAP images, integrate them to Sentinel-2 bands, convert radiance to TOA reflectance and run CloudSEN12 cloud detection model
Used in other projects
- georeader with ml4floods to automatically download and produce flood extent maps: the Kherson Dam Break example
- georeader with STARCOP to simulate Sentinel-2 from AVIRIS images
- georeader with STARCOP to run plume detection in EMIT images
- georeader with CloudSEN12 to run cloud detection in Sentinel-2 images
Citation
If you find this code useful please cite:
@article{portales-julia_global_2023,
title = {Global flood extent segmentation in optical satellite images},
volume = {13},
issn = {2045-2322},
doi = {10.1038/s41598-023-47595-7},
number = {1},
urldate = {2023-11-30},
journal = {Scientific Reports},
author = {Portalés-Julià, Enrique and Mateo-García, Gonzalo and Purcell, Cormac and Gómez-Chova, Luis},
month = nov,
year = {2023},
pages = {20316},
}
@article{ruzicka_starcop_2023,
title = {Semantic segmentation of methane plumes with hyperspectral machine learning models},
volume = {13},
issn = {2045-2322},
url = {https://www.nature.com/articles/s41598-023-44918-6},
doi = {10.1038/s41598-023-44918-6},
number = {1},
journal = {Scientific Reports},
author = {Růžička, Vít and Mateo-Garcia, Gonzalo and Gómez-Chova, Luis and Vaughan, Anna, and Guanter, Luis and Markham, Andrew},
month = nov,
year = {2023},
pages = {19999},
}
Acknowledgments
This research has been supported by the DEEPCLOUD project (PID2019-109026RB-I00) funded by the Spanish Ministry of Science and Innovation (MCIN/AEI/10.13039/501100011033) and the European Union (NextGenerationEU).
1 maintainer
Metadata
1 maintainer
Release files for georeader-spaceml 2.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| georeader_spaceml-2.4.0.tar.gz | 1.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| georeader_spaceml-2.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.4 MB
Release files / georeader_spaceml-2.4.0.tar.gz
| Download URL | georeader_spaceml-2.4.0.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6ed1354e0a33dcbcf36d330f7403100deea40760f7fac4bb932ed20edb8eed3b
|
|
BLAKE2b-256 checksum How to use checksums |
15d327cd97f9522f96eb643e7957493fa9144ce6d5d0c7b0a8007a84b16ecff7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.16 Linux/6.17.0-1022-azure
|
Release files / georeader_spaceml-2.4.0-py3-none-any.whl
| Download URL | georeader_spaceml-2.4.0-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fbbf3bff841585867c92b01770d841ad3bca129d88ad107e2a86a063b16d3771
|
|
BLAKE2b-256 checksum How to use checksums |
697d43e36c1579bc98fcd8acd98fc25291c609cf963268aee67d94d8a929c274
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.16 Linux/6.17.0-1022-azure
|
