[](https://doi.org/10.1038/s41598-023-47595-7) [](https://github.com/spaceml-org/georeader/releases) [](https://pypi.org/project/georeader-spaceml/) [](https://pypi.org/project/georeader-spaceml/) [](https://github.com/spaceml-org/georeader/blob/main/LICENSE) [](https://spaceml-org.github.io/georeader/)
# <img src="https://raw.githubusercontent.com/spaceml-org/georeader/main/docs/images/logo_georeader.png" alt="Logo" width='7%'> georeader
**georeader** is a package to process raster data from different satellite missions. **georeader** makes easy to [read specific areas of your image](https://github.com/spaceml-org/georeader/blob/main/docs/read_S2_SAFE_from_bucket.ipynb), to [reproject images from different satellites to a common grid](https://github.com/spaceml-org/georeader/blob/main/docs/reading_overlapping_sentinel2_aviris.ipynb) ([`georeader.read`](https://spaceml-org.github.io/georeader/modules/read_module/)), to go from vector to raster formats ([`georeader.vectorize`](https://spaceml-org.github.io/georeader/modules/vectorize_module/) and [`georeader.rasterize`](https://spaceml-org.github.io/georeader/modules/rasterize_module/)) or to do [radiance to reflectance conversions](https://spaceml-org.github.io/georeader/enmap_with_cloudsen12/) ([`georeader.reflectance`](https://spaceml-org.github.io/georeader/modules/reflectance_module/)).
**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](https://spaceml-org.github.io/ml4floods/content/ml4ops/HOWTO_postprocess_inference.html)).
## Install
The core package dependencies are `numpy`, `rasterio`, `shapely` and `geopandas`.
```bash
pip install georeader-spaceml
```
## Getting started
> Read from a Sentinel-2 image a fixed size subimage on an specific `lon,lat` location (directly from the [S2 public Google Cloud bucket](https://cloud.google.com/storage/docs/public-datasets/sentinel-2?hl=es-419)):
```python
# This snippet requires:
# pip install fsspec gcsfs google-cloud-storage
import os
os.environ["GS_NO_SIGN_REQUEST"] = "YES"
from georeader.readers import S2_SAFE_reader
from georeader import read
cords_read = (-104.394, 32.026) # long, lat
crs_cords = "EPSG:4326"
s2_safe_path = S2_SAFE_reader.s2_public_bucket_path("S2B_MSIL1C_20191008T173219_N0208_R055_T13SER_20191008T204555.SAFE")
s2obj = S2_SAFE_reader.s2loader(s2_safe_path,
out_res=10, bands=["B04","B03","B02"])
# copy to local avoids http errors specially when not using a Google Cloud project.
# This will only copy the bands set up above B04, B03 and B02
s2obj = s2obj.cache_product_to_local_dir(".")
# See also read.read_from_bounds, read.read_from_polygon for different ways of croping an image
data = read.read_from_center_coords(s2obj,cords_read, shape=(2040, 4040),
crs_center_coords=crs_cords)
data_memory = data.load() # this loads the data to memory
data_memory # GeoTensor object
```
```
>> Transform: | 10.00, 0.00, 537020.00|
| 0.00,-10.00, 3553680.00|
| 0.00, 0.00, 1.00|
Shape: (3, 2040, 4040)
Resolution: (10.0, 10.0)
Bounds: (537020.0, 3533280.0, 577420.0, 3553680.0)
CRS: EPSG:32613
fill_value_default: 0
```
In the `.values` attribute we have the plain numpy array that we can plot with `show`:
```python
from rasterio.plot import show
show(data_memory.values/3500, transform=data_memory.transform)
```
<img src="https://raw.githubusercontent.com/spaceml-org/georeader/main/notebooks/images/sample_read.png" alt="awesome georeader" width="50%">
Saving the `GeoTensor` as a COG GeoTIFF:
```python
from georeader.save import save_cog
# Supports writing in bucket location (e.g. gs://bucket-name/s2_crop.tif)
save_cog(data_memory, "s2_crop.tif", descriptions=s2obj.bands)
```
## Tutorials
### Sentinel-2
- [Reading Sentinel-2 images from the public Google bucket](https://github.com/spaceml-org/georeader/blob/main/docs/read_S2_SAFE_from_bucket.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/read_S2_SAFE_from_bucket.ipynb)
- [Tiling and stitching predictions of an AI model](https://github.com/spaceml-org/georeader/blob/main/docs/advanced/tiling_and_stitching.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/advanced/tiling_and_stitching.ipynb)
- [Explore metadata of Sentinel-2 object](https://github.com/spaceml-org/georeader/blob/main/docs/Sentinel-2/explore_metadata_s2.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/Sentinel-2/explore_metadata_s2.ipynb)
- [Query Sentinel-2 images over a location and time span, mosaic and plot them](https://github.com/spaceml-org/georeader/blob/main/docs/Sentinel-2/query_mosaic_s2_images.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/Sentinel-2/query_mosaic_s2_images.ipynb)
- [Sentinel-2 images from GEE and CloudSEN12 cloud detection](https://github.com/spaceml-org/georeader/blob/main/docs/Sentinel-2/run_in_gee_image.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/Sentinel-2/run_in_gee_image.ipynb)
### Read rasters from different satellites
* [Tutorial to read overlapping tiles from a GeoTIFF and a Sentinel-2 image](https://github.com/spaceml-org/georeader/blob/main/docs/reading_overlapping_sentinel2_aviris.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/reading_overlapping_sentinel2_aviris.ipynb)
* [Example of reading a Proba-V image overlapping with Sentinel-2 forcing same resolution](https://github.com/spaceml-org/georeader/blob/main/docs/read_overlapping_probav_and_sentinel2.ipynb)
* [Work with EMIT images](https://github.com/spaceml-org/georeader/blob/main/docs/emit_explore.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/emit_explore.ipynb)
* [Read overlapping images of PRISMA and EMIT](https://github.com/spaceml-org/georeader/blob/main/docs/simultaneous_prisma_emit.ipynb)
* [Read EnMAP images, integrate them to Sentinel-2 bands, convert radiance to TOA reflectance and run CloudSEN12 cloud detection model](https://github.com/spaceml-org/georeader/blob/main/docs/enmap_with_cloudsen12.ipynb)
### Used in other projects
* [georeader with ml4floods to automatically download and produce flood extent maps: the Kherson Dam Break example](https://spaceml-org.github.io/ml4floods/content/ml4ops/HOWTO_postprocess_inference.html)
* [georeader with STARCOP to simulate Sentinel-2 from AVIRIS images](https://github.com/spaceml-org/STARCOP/blob/main/notebooks/simulate_aviris_2_sentinel2.ipynb)
* [georeader with STARCOP to run plume detection in EMIT images](https://github.com/spaceml-org/STARCOP/blob/main/notebooks/inference_on_raw_EMIT_nc_file.ipynb)
* [georeader with CloudSEN12 to run cloud detection in Sentinel-2 images](https://github.com/IPL-UV/cloudsen12_models/blob/main/notebooks/run_in_gee_image.ipynb)
## 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).
<img width="300" title="DEEPCLOUD project (PID2019-109026RB-I00, University of Valencia) funded by MCIN/AEI/10.13039/501100011033." alt="DEEPCLOUD project (PID2019-109026RB-I00, University of Valencia) funded by MCIN/AEI/10.13039/501100011033." src="https://www.uv.es/chovago/logos/logoMICIN.jpg">
Raw data
{
"_id": null,
"home_page": "https://github.com/spaceml-org/georeader",
"name": "georeader-spaceml",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Gonzalo Mateo-Garc\u00eda",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/36/d3/c9d7ea84b6dc56eb2b90fad4cc8de1542d508d8136193ec1d8645d3d4d03/georeader_spaceml-1.5.5.tar.gz",
"platform": null,
"description": "[](https://doi.org/10.1038/s41598-023-47595-7) [](https://github.com/spaceml-org/georeader/releases) [](https://pypi.org/project/georeader-spaceml/) [](https://pypi.org/project/georeader-spaceml/) [](https://github.com/spaceml-org/georeader/blob/main/LICENSE) [](https://spaceml-org.github.io/georeader/)\n\n# <img src=\"https://raw.githubusercontent.com/spaceml-org/georeader/main/docs/images/logo_georeader.png\" alt=\"Logo\" width='7%'> georeader\n\n**georeader** is a package to process raster data from different satellite missions. **georeader** makes easy to [read specific areas of your image](https://github.com/spaceml-org/georeader/blob/main/docs/read_S2_SAFE_from_bucket.ipynb), to [reproject images from different satellites to a common grid](https://github.com/spaceml-org/georeader/blob/main/docs/reading_overlapping_sentinel2_aviris.ipynb) ([`georeader.read`](https://spaceml-org.github.io/georeader/modules/read_module/)), to go from vector to raster formats ([`georeader.vectorize`](https://spaceml-org.github.io/georeader/modules/vectorize_module/) and [`georeader.rasterize`](https://spaceml-org.github.io/georeader/modules/rasterize_module/)) or to do [radiance to reflectance conversions](https://spaceml-org.github.io/georeader/enmap_with_cloudsen12/) ([`georeader.reflectance`](https://spaceml-org.github.io/georeader/modules/reflectance_module/)). \n\n**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](https://spaceml-org.github.io/ml4floods/content/ml4ops/HOWTO_postprocess_inference.html)). \n\n## Install\n\nThe core package dependencies are `numpy`, `rasterio`, `shapely` and `geopandas`.\n\n```bash\npip install georeader-spaceml\n```\n\n## Getting started\n\n> Read from a Sentinel-2 image a fixed size subimage on an specific `lon,lat` location (directly from the [S2 public Google Cloud bucket](https://cloud.google.com/storage/docs/public-datasets/sentinel-2?hl=es-419)):\n \n```python\n# This snippet requires:\n# pip install fsspec gcsfs google-cloud-storage\nimport os\nos.environ[\"GS_NO_SIGN_REQUEST\"] = \"YES\"\n\nfrom georeader.readers import S2_SAFE_reader\nfrom georeader import read\n\ncords_read = (-104.394, 32.026) # long, lat\ncrs_cords = \"EPSG:4326\"\ns2_safe_path = S2_SAFE_reader.s2_public_bucket_path(\"S2B_MSIL1C_20191008T173219_N0208_R055_T13SER_20191008T204555.SAFE\")\ns2obj = S2_SAFE_reader.s2loader(s2_safe_path, \n out_res=10, bands=[\"B04\",\"B03\",\"B02\"])\n\n# copy to local avoids http errors specially when not using a Google Cloud project.\n# This will only copy the bands set up above B04, B03 and B02\ns2obj = s2obj.cache_product_to_local_dir(\".\")\n\n# See also read.read_from_bounds, read.read_from_polygon for different ways of croping an image\ndata = read.read_from_center_coords(s2obj,cords_read, shape=(2040, 4040),\n crs_center_coords=crs_cords)\n\ndata_memory = data.load() # this loads the data to memory\n\ndata_memory # GeoTensor object\n\n```\n```\n>> Transform: | 10.00, 0.00, 537020.00|\n| 0.00,-10.00, 3553680.00|\n| 0.00, 0.00, 1.00|\n Shape: (3, 2040, 4040)\n Resolution: (10.0, 10.0)\n Bounds: (537020.0, 3533280.0, 577420.0, 3553680.0)\n CRS: EPSG:32613\n fill_value_default: 0\n```\n\nIn the `.values` attribute we have the plain numpy array that we can plot with `show`:\n\n```python\nfrom rasterio.plot import show\nshow(data_memory.values/3500, transform=data_memory.transform)\n\n```\n<img src=\"https://raw.githubusercontent.com/spaceml-org/georeader/main/notebooks/images/sample_read.png\" alt=\"awesome georeader\" width=\"50%\">\n\n\nSaving the `GeoTensor` as a COG GeoTIFF: \n\n```python\nfrom georeader.save import save_cog\n\n# Supports writing in bucket location (e.g. gs://bucket-name/s2_crop.tif)\nsave_cog(data_memory, \"s2_crop.tif\", descriptions=s2obj.bands)\n```\n\n## Tutorials\n\n### Sentinel-2\n\n- [Reading Sentinel-2 images from the public Google bucket](https://github.com/spaceml-org/georeader/blob/main/docs/read_S2_SAFE_from_bucket.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/read_S2_SAFE_from_bucket.ipynb)\n- [Tiling and stitching predictions of an AI model](https://github.com/spaceml-org/georeader/blob/main/docs/advanced/tiling_and_stitching.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/advanced/tiling_and_stitching.ipynb)\n- [Explore metadata of Sentinel-2 object](https://github.com/spaceml-org/georeader/blob/main/docs/Sentinel-2/explore_metadata_s2.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/Sentinel-2/explore_metadata_s2.ipynb)\n- [Query Sentinel-2 images over a location and time span, mosaic and plot them](https://github.com/spaceml-org/georeader/blob/main/docs/Sentinel-2/query_mosaic_s2_images.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/Sentinel-2/query_mosaic_s2_images.ipynb)\n- [Sentinel-2 images from GEE and CloudSEN12 cloud detection](https://github.com/spaceml-org/georeader/blob/main/docs/Sentinel-2/run_in_gee_image.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/Sentinel-2/run_in_gee_image.ipynb)\n\n### Read rasters from different satellites\n\n * [Tutorial to read overlapping tiles from a GeoTIFF and a Sentinel-2 image](https://github.com/spaceml-org/georeader/blob/main/docs/reading_overlapping_sentinel2_aviris.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/reading_overlapping_sentinel2_aviris.ipynb)\n * [Example of reading a Proba-V image overlapping with Sentinel-2 forcing same resolution](https://github.com/spaceml-org/georeader/blob/main/docs/read_overlapping_probav_and_sentinel2.ipynb)\n * [Work with EMIT images](https://github.com/spaceml-org/georeader/blob/main/docs/emit_explore.ipynb) [](https://colab.research.google.com/github/spaceml-org/georeader/blob/main/docs/emit_explore.ipynb)\n * [Read overlapping images of PRISMA and EMIT](https://github.com/spaceml-org/georeader/blob/main/docs/simultaneous_prisma_emit.ipynb) \n * [Read EnMAP images, integrate them to Sentinel-2 bands, convert radiance to TOA reflectance and run CloudSEN12 cloud detection model](https://github.com/spaceml-org/georeader/blob/main/docs/enmap_with_cloudsen12.ipynb) \n\n### Used in other projects\n\n * [georeader with ml4floods to automatically download and produce flood extent maps: the Kherson Dam Break example](https://spaceml-org.github.io/ml4floods/content/ml4ops/HOWTO_postprocess_inference.html)\n * [georeader with STARCOP to simulate Sentinel-2 from AVIRIS images](https://github.com/spaceml-org/STARCOP/blob/main/notebooks/simulate_aviris_2_sentinel2.ipynb)\n * [georeader with STARCOP to run plume detection in EMIT images](https://github.com/spaceml-org/STARCOP/blob/main/notebooks/inference_on_raw_EMIT_nc_file.ipynb)\n * [georeader with CloudSEN12 to run cloud detection in Sentinel-2 images](https://github.com/IPL-UV/cloudsen12_models/blob/main/notebooks/run_in_gee_image.ipynb)\n\n\n## Citation\n\nIf you find this code useful please cite:\n```\n@article{portales-julia_global_2023,\n\ttitle = {Global flood extent segmentation in optical satellite images},\n\tvolume = {13},\n\tissn = {2045-2322},\n\tdoi = {10.1038/s41598-023-47595-7},\n\tnumber = {1},\n\turldate = {2023-11-30},\n\tjournal = {Scientific Reports},\n\tauthor = {Portal\u00e9s-Juli\u00e0, Enrique and Mateo-Garc\u00eda, Gonzalo and Purcell, Cormac and G\u00f3mez-Chova, Luis},\n\tmonth = nov,\n\tyear = {2023},\n\tpages = {20316},\n}\n@article{ruzicka_starcop_2023,\n\ttitle = {Semantic segmentation of methane plumes with hyperspectral machine learning models},\n\tvolume = {13},\n\tissn = {2045-2322},\n\turl = {https://www.nature.com/articles/s41598-023-44918-6},\n\tdoi = {10.1038/s41598-023-44918-6},\n\tnumber = {1},\n\tjournal = {Scientific Reports},\n\tauthor = {R\u016f\u017ei\u010dka, V\u00edt and Mateo-Garcia, Gonzalo and G\u00f3mez-Chova, Luis and Vaughan, Anna, and Guanter, Luis and Markham, Andrew},\n\tmonth = nov,\n\tyear = {2023},\n\tpages = {19999},\n}\n```\n\n## Acknowledgments\nThis 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).\n\n<img width=\"300\" title=\"DEEPCLOUD project (PID2019-109026RB-I00, University of Valencia) funded by MCIN/AEI/10.13039/501100011033.\" alt=\"DEEPCLOUD project (PID2019-109026RB-I00, University of Valencia) funded by MCIN/AEI/10.13039/501100011033.\" src=\"https://www.uv.es/chovago/logos/logoMICIN.jpg\">\n",
"bugtrack_url": null,
"license": "\tLGPL-3.0",
"summary": "\ud83d\udef0\ufe0f Process raster data in python",
"version": "1.5.5",
"project_urls": {
"Documentation": "https://spaceml-org.github.io/georeader/",
"Homepage": "https://github.com/spaceml-org/georeader",
"Repository": "https://github.com/spaceml-org/georeader"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "43f88bf419fdd4392e6c06fe50f4ee253ff9a57275b6e841b2d940656a0b8b27",
"md5": "b0d10e6df52a820044250157f8cbe8ba",
"sha256": "6ca1438c360cbb30892c93f863d6bcd0d79f147e0d6ffb5e68c49bde09cd23dc"
},
"downloads": -1,
"filename": "georeader_spaceml-1.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0d10e6df52a820044250157f8cbe8ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 174695,
"upload_time": "2025-07-24T09:20:02",
"upload_time_iso_8601": "2025-07-24T09:20:02.846852Z",
"url": "https://files.pythonhosted.org/packages/43/f8/8bf419fdd4392e6c06fe50f4ee253ff9a57275b6e841b2d940656a0b8b27/georeader_spaceml-1.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "36d3c9d7ea84b6dc56eb2b90fad4cc8de1542d508d8136193ec1d8645d3d4d03",
"md5": "3b0da538f1d1bf81d44109918b1a12c6",
"sha256": "7bab85db2c9d2a351a57c16dd4dab51d55996488a1cd3eefbd9e0595a41507e2"
},
"downloads": -1,
"filename": "georeader_spaceml-1.5.5.tar.gz",
"has_sig": false,
"md5_digest": "3b0da538f1d1bf81d44109918b1a12c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 163573,
"upload_time": "2025-07-24T09:20:04",
"upload_time_iso_8601": "2025-07-24T09:20:04.666237Z",
"url": "https://files.pythonhosted.org/packages/36/d3/c9d7ea84b6dc56eb2b90fad4cc8de1542d508d8136193ec1d8645d3d4d03/georeader_spaceml-1.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 09:20:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spaceml-org",
"github_project": "georeader",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "georeader-spaceml"
}
JSON
