easy-eo 0.2.0__tar.gz → 0.3.1__tar.gz

{easy_eo-0.2.0 → easy_eo-0.3.1}/.gitignore

@@ -21,6 +21,12 @@ others/
 # Docs
 docs/build/
 
+# Generated by the dependency-audit, release, and linkcheck workflows
+# (and by running any of them locally)
+requirements-audit.txt
+.smoke-venv/
+.linkcheck/
+
 # Tests
 .pytest_cache/
 .ruff_cache/

easy_eo-0.3.1/PKG-INFO

@@ -0,0 +1,369 @@
+Metadata-Version: 2.5
+Name: easy-eo
+Version: 0.3.1
+Summary: A lightweight Earth Observation utilities library for chainable raster operations
+Project-URL: Homepage, https://github.com/tommy-burns/easy-eo
+Project-URL: Repository, https://github.com/tommy-burns/easy-eo
+Project-URL: Documentation, https://easy-eo.readthedocs.io
+Project-URL: Issues, https://github.com/tommy-burns/easy-eo/issues
+Author: Thomas Burns Botchwey
+License: MIT License
+        
+        Copyright (c) 2025 Thomas Burns Botchwey
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: earth observation,gis,raster,remote sensing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: geopandas<2,>=1.1
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: rasterio<2,>=1.4
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: stac
+Requires-Dist: planetary-computer<2,>=1.0; extra == 'stac'
+Requires-Dist: pystac-client<1,>=0.8; extra == 'stac'
+Provides-Extra: xarray
+Requires-Dist: rioxarray<1,>=0.17; extra == 'xarray'
+Requires-Dist: xarray>=2024.7; extra == 'xarray'
+Description-Content-Type: text/markdown
+
+# Easy-EO
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Tommy-Burns/easy-eo/main/.github/assets/eeo_logo.png" alt="Easy-EO logo" width="200">
+</p>
+
+|  |  |
+| :-- | :-- |
+| **Install** | [![PyPI][pypi-badge]][pypi] [![conda-forge][conda-badge]][conda] [![Python versions][pyversions-badge]][pypi] [![Platforms][platforms-badge]][ci] |
+| **Build & quality** | [![CI][ci-badge]][ci] [![Latest deps][latest-deps-badge]][latest-deps] [![Coverage][codecov-badge]][codecov] [![Ruff][ruff-badge]][ruff] [![Checked with mypy][mypy-badge]][mypy] |
+| **Security** | [![CodeQL][codeql-badge]][codeql] [![OpenSSF Scorecard][scorecard-badge]][scorecard] |
+| **Project** | [![Documentation][docs-badge]][docs] [![License: MIT][license-badge]][license] |
+
+[pypi]: https://pypi.org/project/easy-eo/
+[pypi-badge]: https://img.shields.io/pypi/v/easy-eo.svg
+[conda]: https://anaconda.org/conda-forge/easy-eo
+[conda-badge]: https://img.shields.io/conda/vn/conda-forge/easy-eo.svg
+[pyversions-badge]: https://img.shields.io/pypi/pyversions/easy-eo.svg
+[platforms-badge]: https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey.svg
+[ci]: https://github.com/Tommy-Burns/easy-eo/actions/workflows/ci.yml
+[ci-badge]: https://github.com/Tommy-Burns/easy-eo/actions/workflows/ci.yml/badge.svg
+[latest-deps]: https://github.com/Tommy-Burns/easy-eo/actions/workflows/latest-deps.yml
+[latest-deps-badge]: https://github.com/Tommy-Burns/easy-eo/actions/workflows/latest-deps.yml/badge.svg
+[codecov]: https://codecov.io/gh/Tommy-Burns/easy-eo
+[codecov-badge]: https://codecov.io/gh/Tommy-Burns/easy-eo/branch/main/graph/badge.svg
+[ruff]: https://github.com/astral-sh/ruff
+[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+[mypy]: https://mypy-lang.org/
+[mypy-badge]: https://img.shields.io/badge/mypy-checked-2a6db2.svg
+[codeql]: https://github.com/Tommy-Burns/easy-eo/actions/workflows/codeql.yml
+[codeql-badge]: https://github.com/Tommy-Burns/easy-eo/actions/workflows/codeql.yml/badge.svg
+[scorecard]: https://scorecard.dev/viewer/?uri=github.com/Tommy-Burns/easy-eo
+[scorecard-badge]: https://api.scorecard.dev/projects/github.com/Tommy-Burns/easy-eo/badge
+[docs]: https://easy-eo.readthedocs.io/en/latest/?badge=latest
+[docs-badge]: https://readthedocs.org/projects/easy-eo/badge/?version=latest
+[license]: https://github.com/Tommy-Burns/easy-eo/blob/main/LICENSE
+[license-badge]: https://img.shields.io/github/license/Tommy-Burns/easy-eo
+
+
+Easy-EO is a lightweight, extensible Python library for raster-based Earth
+Observation (EO) analysis: chainable raster processing, band algebra, spectral indices, 
+and visualization, in a few readable lines instead of dealing with complex boilerplate code.
+
+## From satellite archive to NDVI map
+
+```python
+import eeo
+
+results = eeo.stac_search(
+    "sentinel-2-l2a",
+    bbox=(11.0, 46.5, 11.2, 46.7),        # area of interest, WGS 84 lon/lat
+    datetime="2023-06-01/2023-08-31",
+    cloud_cover=20,
+    limit=1,
+)
+scene = results[0].load(["B04", "B08"])   # reads only the area of interest
+ndvi = scene.ndvi(red="B04", nir="B08")
+ndvi.plot_raster()
+```
+
+That is the whole workflow - no scene downloads, no GDAL wrangling. The search
+queries [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/)
+(any STAC catalog works, you have to pass `catalog="your stac catalog"`), and the load streams just the window covering your
+bounding box over HTTP: 14 MB out of a 240 MB Sentinel-2 tile, in a few seconds.
+
+The `stac_search` needs the STAC extra - `pip install "easy-eo[stac]"`, or the [conda equivalent](#installation). If you prefer to start offline, jump to the [hosted sample dataset](#quick-example), which needs no network after the first call.
+
+---
+
+## Features
+
+| | What you get | Guide |
+| --- | --- | --- |
+| **Data access** | `stac_search()` over any STAC catalog, loading only your area of interest over HTTP; GeoTIFF/COG and anything else GDAL reads; a hosted sample dataset one call away | [Satellite data](https://easy-eo.readthedocs.io/en/latest/user_guide/loading_satellite_data.html) · [Sample data](https://easy-eo.readthedocs.io/en/latest/user_guide/sample_data.html) |
+| **Spectral indices** | `ndvi`, `ndwi`, `ndmi`, `ndbi`, `evi`, `savi`, plus `normalized_difference` for anything else - all chainable and float32 | [Spectral indices](https://easy-eo.readthedocs.io/en/latest/user_guide/spectral_indices.html) |
+| **Band algebra** | `add`, `subtract`, `multiply`, `divide`, `power`, `sqrt`, `log`, `absolute`, and the matching operators | [Operations](https://easy-eo.readthedocs.io/en/latest/user_guide/ops.html) |
+| **Preprocessing** | Clip to a bounding box or a vector, resample, reproject, mosaic, stack, normalize (min-max, percentile, z-score) | [Preprocessing](https://easy-eo.readthedocs.io/en/latest/user_guide/preprocessing.html) |
+| **Named bands** | Address any band as `"red"` or `"nir"` wherever a 1-based index works; names survive a GeoTIFF round-trip | [Naming bands](https://easy-eo.readthedocs.io/en/latest/user_guide/band_names.html) |
+| **Statistics** | Per-band min/max/mean/percentile with their pixel locations, and value extraction at a coordinate | [Statistical locations](https://easy-eo.readthedocs.io/en/latest/user_guide/statistical_locations.html) |
+| **Visualization** | Single bands, RGB composites, histograms, and map-plus-histogram views, read at display resolution | [Visualization](https://easy-eo.readthedocs.io/en/latest/user_guide/visualization.html) |
+| **Predictable nodata & dtype** | One written-down contract every operation follows: mask before compute, nodata stays contagious, fractional results are float32 | [Nodata & dtype](https://easy-eo.readthedocs.io/en/latest/user_guide/nodata_and_dtype.html) |
+| **Ecosystem interop** | `to_xarray()` / `from_xarray()` in both directions; NumPy and Rasterio backends behind one interface | [xarray interop](https://easy-eo.readthedocs.io/en/latest/user_guide/xarray_interop.html) · [Backends](https://easy-eo.readthedocs.io/en/latest/backends.html) |
+| **Typed and tested** | Ships `py.typed`, 950+ tests, ~95% coverage, checked on Python 3.10-3.14 across Linux, macOS and Windows | [Contributing](https://github.com/Tommy-Burns/easy-eo/blob/main/CONTRIBUTING.md) |
+
+---
+
+## Before and after
+
+One ordinary task: clip a 4-band scene to an area of interest held in a vector
+file, compute NDVI, save it as a GeoTIFF. Both versions below run as written,
+against the same [hosted sample dataset](https://easy-eo.readthedocs.io/en/latest/user_guide/sample_data.html)
+- a 1024x1024 Sentinel-2 subset and a boundary polygon - so you can paste
+either one and watch it work.
+
+Here it is in raw Rasterio, GeoPandas and NumPy, with Easy-EO not installed at
+all -
+
+```python
+import geopandas as gpd
+import numpy as np
+import rasterio
+from rasterio.mask import mask
+
+BASE = "https://github.com/Tommy-Burns/easy-eo/releases/download/sample-data-v1/"
+
+with rasterio.open(BASE + "sentinel2_small_cog.tif") as src:
+    aoi = gpd.read_file(BASE + "roi.gpkg").to_crs(src.crs)
+    clipped, transform = mask(src, aoi.geometry.values, crop=True)
+    bands = {name: i for i, name in enumerate(src.descriptions)}
+    nodata = src.nodata
+    profile = src.profile
+
+red = clipped[bands["red"]].astype("float32")
+nir = clipped[bands["nir"]].astype("float32")
+
+valid = (red != nodata) & (nir != nodata)
+total = nir + red
+ndvi = np.where(valid & (total != 0), (nir - red) / np.where(total == 0, 1, total), 0.0)
+ndvi = np.where(valid, ndvi, np.nan).astype("float32")
+
+profile.update(
+    count=1, dtype="float32", nodata=np.nan,
+    height=ndvi.shape[0], width=ndvi.shape[1], transform=transform,
+)
+with rasterio.open("ndvi.tif", "w", **profile) as dst:
+    dst.write(ndvi, 1)
+```
+
+-- and in Easy-EO, where `load_sample_dataset()` fetches the same two files and
+caches them:
+
+```python
+import eeo
+from eeo.datasets import load_sample_dataset
+
+sd = load_sample_dataset()
+
+(
+    eeo.load_raster(sd.sentinel2_cog_stacked)
+    .clip_raster_with_vector(sd.boundary)
+    .ndvi(red="red", nir="nir")
+    .save_raster("ndvi.tif")
+)
+```
+
+Both blocks produce **byte-identical output** - same shape, CRS, transform,
+nodata, and every one of the pixel values, including all pixels the clip
+masks away (approx. a quarter of the image).
+So the point is not the line count. It is that Rasterio makes you take four decisions by hand, 
+each one a chance to be quietly wrong: reprojecting the AOI into the raster's CRS 
+(the sample boundary is lon/lat, the scene is UTM), mapping band names to indices, 
+masking nodata before the arithmetic, and rebuilding the output profile. Drop just the mask and NDVI comes out as `0.0` across the clipped-away quarter of the image - a value that looks like bare
+ground in your statistics and your plot, not like missing data.
+
+Easy-EO applies those same rules for you, consistently, on every operation. They
+are written down in the [nodata and dtype contract](https://easy-eo.readthedocs.io/en/latest/user_guide/nodata_and_dtype.html)
+and each one is backed by tests.
+
+---
+
+## What's next
+
+Easy-EO is built around one scene at a time, and everything above works that
+way today. These are the next capabilities, in the order they are being built:
+
+| Coming | What it unlocks |
+| --- | --- |
+| **Block-wise execution** | Pixel-wise operations stream window by window instead of holding whole arrays, so a chain runs in a bounded memory footprint. Today, loading is read-free and clipping is windowed, but an operation like `ndvi()` materialises the bands it touches. |
+| **Lazy backend** (`easy-eo[lazy]`) | An xarray/dask-backed adapter behind the existing interface: chains on rasters larger than RAM, and COGs read straight over HTTP, with no change to your code beyond the loader call. |
+| **Time series** (`EEOTimeSeries`) | Multi-date stacks as a first-class object - map any existing operation across timesteps, reduce to cloud-free median composites, pull per-pixel trajectories. STAC search results are already ordered and timestamped, ready to become one. |
+| **Citable releases** | A JOSS paper and Zenodo DOI, so the library can be cited in published work. |
+
+**Already using xarray?** You do not have to choose. `to_xarray()` and `from_xarray()` convert in both directions, so you can clip and compute indices
+here, hand the result to dask or anything else in the xarray ecosystem, and come back - which is also how to work past a single machine's memory today.
+See the [xarray interop guide](https://easy-eo.readthedocs.io/en/latest/user_guide/xarray_interop.html).
+
+---
+
+## Installation
+
+Python 3.10 or newer, from either package manager:
+
+```bash
+pip install easy-eo
+```
+
+```bash
+conda install -c conda-forge easy-eo
+```
+
+That is everything you need for the core: raster I/O, algebra, indices,
+preprocessing and plotting. Two heavier integrations are kept separate, so you
+only install them if you use them:
+
+| Adds | pip | conda |
+| --- | --- | --- |
+| `stac_search()` and loading scenes from STAC catalogs | `pip install "easy-eo[stac]"` | `conda install -c conda-forge easy-eo pystac-client planetary-computer` |
+| `to_xarray()` / `from_xarray()` | `pip install "easy-eo[xarray]"` | `conda install -c conda-forge easy-eo xarray rioxarray` |
+
+pip extras compose - `pip install "easy-eo[stac,xarray]"` installs both. conda
+has no concept of extras, so `conda install "easy-eo[stac]"` is not a valid
+command; the same packages are simply installed by name, as above.
+
+**Use one package manager, not both.** If Easy-EO came from conda, install the
+extras from conda too. conda's solver knows nothing about pip-installed files,
+so a later `conda install` or `conda update` can overwrite them or leave a
+second copy of a shared dependency in the environment. Every extra dependency
+is on conda-forge, so there is no reason to mix.
+
+Without an extra installed, the features that need it raise a
+`MissingDependencyError` telling you exactly what to install - nothing fails
+silently at import time.
+
+## Quick Example
+```python
+from eeo import load_raster
+
+ds_nir = load_raster("path/to/nir.tif")
+ds_red = load_raster("path/to/red.tif")
+
+# Chainable example: clip -> resample -> compute NDVI -> multiply
+result = (
+    ds_nir.clip_raster_with_bbox((0, 0, 1000, 1000))
+    .resample(scale_factor=2)
+    .normalized_difference(ds_red)
+    .multiply(100)
+)
+```
+
+***Or try with a hosted sample data***
+```python
+from eeo.datasets import load_sample_dataset
+from eeo import load_raster
+
+sd = load_sample_dataset()
+
+scene = load_raster(sd.sentinel2_cog_stacked)  # red, green, blue, nir bands
+
+ndvi = scene.ndvi(red="red", nir="nir")
+ndvi.plot_raster()
+```
+
+## Tutorials
+
+Sixteen runnable notebooks live in [`examples/`](https://github.com/Tommy-Burns/easy-eo/blob/main/examples/README.md), from first
+install through to complete analyses (flood mapping, drought stress, land cover,
+terrain). Each one opens in Colab with no local setup — the first cell installs
+Easy-EO when it detects Colab:
+
+| | |
+| --- | --- |
+| [Quickstart: NDVI](https://github.com/Tommy-Burns/easy-eo/blob/main/examples/00_getting_started/02_quickstart_ndvi.ipynb) — open a scene, compute an index, plot it | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Tommy-Burns/easy-eo/blob/main/examples/00_getting_started/02_quickstart_ndvi.ipynb) |
+| [Search and load from STAC](https://github.com/Tommy-Burns/easy-eo/blob/main/examples/02_data_access/02_stac_search_and_load.ipynb) — find real scenes, read them over HTTP | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Tommy-Burns/easy-eo/blob/main/examples/02_data_access/02_stac_search_and_load.ipynb) |
+| [Flood mapping with NDWI](https://github.com/Tommy-Burns/easy-eo/blob/main/examples/03_real_world/01_flood_mapping_ndwi.ipynb) — Pakistan 2022, before/after, area affected | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Tommy-Burns/easy-eo/blob/main/examples/03_real_world/01_flood_mapping_ndwi.ipynb) |
+
+The full index, including what each notebook covers, is in
+[`examples/README.md`](https://github.com/Tommy-Burns/easy-eo/blob/main/examples/README.md) and in the
+[tutorials page](https://easy-eo.readthedocs.io/en/latest/tutorials.html) of the
+documentation.
+
+---
+
+## Gallery
+
+Every image below is straight out of an Easy-EO plotting call on the sample
+dataset, with the library's own defaults - no touch-ups. Regenerate them all
+with `python scripts/build_gallery.py`.
+
+| | |
+| --- | --- |
+| <img src="https://raw.githubusercontent.com/Tommy-Burns/easy-eo/main/.github/assets/gallery/composite_true_colour.jpg" alt="True colour composite of a Sentinel-2 scene"> | <img src="https://raw.githubusercontent.com/Tommy-Burns/easy-eo/main/.github/assets/gallery/composite_false_colour.jpg" alt="False colour composite, vegetation in red"> |
+| `scene.plot_composite(["red", "green", "blue"])` | `scene.plot_composite(["nir", "red", "green"])` |
+| <img src="https://raw.githubusercontent.com/Tommy-Burns/easy-eo/main/.github/assets/gallery/index_ndvi.jpg" alt="NDVI map on a red-yellow-green colour scale"> | <img src="https://raw.githubusercontent.com/Tommy-Burns/easy-eo/main/.github/assets/gallery/dem_terrain.jpg" alt="Copernicus DEM elevation map"> |
+| `scene.ndvi(red="red", nir="nir", name="NDVI").plot_raster(cmap="RdYlGn")` | `dem.plot_raster(cmap="Spectral_r")` - the same call on a DEM |
+| <img src="https://raw.githubusercontent.com/Tommy-Burns/easy-eo/main/.github/assets/gallery/histogram_bands.png" alt="Value distribution of each of the four bands"> | <img src="https://raw.githubusercontent.com/Tommy-Burns/easy-eo/main/.github/assets/gallery/clip_ndvi_histogram.png" alt="NDVI clipped to a hexagonal boundary beside its histogram"> |
+| `scene.plot_histogram()` - every band at once | `clipped.plot_raster_with_histogram(cmap="RdYlGn")` |
+
+Bands are addressed by name throughout (`"red"`, `"nir"`) because the sample
+carries band descriptions; a 1-based index works anywhere a name does.
+
+## Supported Backends
+| Backend  | Description                                          |
+|----------|------------------------------------------------------|
+| NumPy    | Fast, in-memory arrays without I/O                   |
+| Rasterio | Full geospatial support (CRS, transform, resampling) |
+
+
+## Documentation
+
+📚 Full documentation is available at:
+
+👉 [Easy-EO Documentation](https://easy-eo.readthedocs.io/en/latest/index.html)
+
+## Project Status
+🚧 Active development
+The API is stabilizing but may change before v1.0.
+
+## Contributing
+Contributions are welcome!
+ - Bug reports
+ - Feature requests
+ - Documentation improvements
+
+Please open an issue or pull request on GitHub.
+
+## License
+MIT License © 2025 Thomas Burns Botchwey