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

easy_eo-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.env
+.venv
+
+# Builds
+build/
+dist/
+
+# Data
+data/
+others/
+# ...but the recorded API responses under tests/data are fixtures the suite
+# needs, not scratch data: without them the STAC replay tests fail in CI.
+!tests/data/
+
+# Docs
+docs/build/
+
+# Tests
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Sample data (downloaded, not tracked)
+sample-data/
+scripts/build_sample_data.py

easy_eo-0.2.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: easy-eo
+Version: 0.2.0
+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: Topic :: Scientific/Engineering :: GIS
+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=".github/assets/eeo_logo.png" alt="Easy-EO logo" width="200">
+</p>
+
+[![CI](https://github.com/Tommy-Burns/easy-eo/actions/workflows/ci.yml/badge.svg)](https://github.com/Tommy-Burns/easy-eo/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Tommy-Burns/easy-eo/branch/main/graph/badge.svg)](https://codecov.io/gh/Tommy-Burns/easy-eo)
+[![PyPI](https://img.shields.io/pypi/v/easy-eo.svg)](https://pypi.org/project/easy-eo/)
+[![Python versions](https://img.shields.io/pypi/pyversions/easy-eo.svg)](https://pypi.org/project/easy-eo/)
+[![Documentation Status](https://readthedocs.org/projects/easy-eo/badge/?version=latest)](https://easy-eo.readthedocs.io/en/latest/?badge=latest)
+[![License: MIT](https://img.shields.io/github/license/Tommy-Burns/easy-eo)](https://github.com/Tommy-Burns/easy-eo/blob/main/LICENSE)
+
+Easy-EO is a lightweight, extensible Python library for raster-based Earth Observation (EO) analysis which allows for chainable raster processing, algebra, and visualization.
+It provides high-level abstractions over libraries such as Rasterio, NumPy, and Matplotlib, enabling users to perform common earth-observation analyses and visualization tasks efficiently, without dealing with the underlying complexity.
+
+---
+
+## Features
+
+- Raster operations with spatial awareness
+- Algebraic operations (`add`, `subtract`, `multiply`, `divide`)
+- Spectral index library (`ndvi`, `ndwi`, `ndmi`, `ndbi`, `evi`, `savi`)
+- Resampling, reprojection, and alignment
+- Clip rasters using vectors or bounding boxes
+- Normalization (min-max, percentile, z-score)
+- Named bands - address bands by name anywhere an index is accepted
+- STAC data access - search and load Sentinel-2/Landsat scenes, reading only the area of interest
+- xarray interoperability (`to_xarray()` / `from_xarray()`)
+- Hosted sample dataset, one call away (`eeo.datasets.load_sample_dataset()`)
+- Visualization helpers (bands, composites, histograms)
+- Backend-aware design (currently NumPy and Rasterio)
+
+---
+
+## Installation
+
+```bash
+conda create -n env_name python=3.10
+conda activate env_name
+pip install easy-eo
+```
+
+## 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/`](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](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](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](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`](examples/README.md) and in the
+[tutorials page](https://easy-eo.readthedocs.io/en/latest/tutorials.html) of the
+documentation.
+
+## 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

easy_eo-0.2.0/README.md

@@ -0,0 +1,117 @@
+# Easy-EO
+
+<p align="center">
+  <img src=".github/assets/eeo_logo.png" alt="Easy-EO logo" width="200">
+</p>
+
+[![CI](https://github.com/Tommy-Burns/easy-eo/actions/workflows/ci.yml/badge.svg)](https://github.com/Tommy-Burns/easy-eo/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Tommy-Burns/easy-eo/branch/main/graph/badge.svg)](https://codecov.io/gh/Tommy-Burns/easy-eo)
+[![PyPI](https://img.shields.io/pypi/v/easy-eo.svg)](https://pypi.org/project/easy-eo/)
+[![Python versions](https://img.shields.io/pypi/pyversions/easy-eo.svg)](https://pypi.org/project/easy-eo/)
+[![Documentation Status](https://readthedocs.org/projects/easy-eo/badge/?version=latest)](https://easy-eo.readthedocs.io/en/latest/?badge=latest)
+[![License: MIT](https://img.shields.io/github/license/Tommy-Burns/easy-eo)](https://github.com/Tommy-Burns/easy-eo/blob/main/LICENSE)
+
+Easy-EO is a lightweight, extensible Python library for raster-based Earth Observation (EO) analysis which allows for chainable raster processing, algebra, and visualization.
+It provides high-level abstractions over libraries such as Rasterio, NumPy, and Matplotlib, enabling users to perform common earth-observation analyses and visualization tasks efficiently, without dealing with the underlying complexity.
+
+---
+
+## Features
+
+- Raster operations with spatial awareness
+- Algebraic operations (`add`, `subtract`, `multiply`, `divide`)
+- Spectral index library (`ndvi`, `ndwi`, `ndmi`, `ndbi`, `evi`, `savi`)
+- Resampling, reprojection, and alignment
+- Clip rasters using vectors or bounding boxes
+- Normalization (min-max, percentile, z-score)
+- Named bands - address bands by name anywhere an index is accepted
+- STAC data access - search and load Sentinel-2/Landsat scenes, reading only the area of interest
+- xarray interoperability (`to_xarray()` / `from_xarray()`)
+- Hosted sample dataset, one call away (`eeo.datasets.load_sample_dataset()`)
+- Visualization helpers (bands, composites, histograms)
+- Backend-aware design (currently NumPy and Rasterio)
+
+---
+
+## Installation
+
+```bash
+conda create -n env_name python=3.10
+conda activate env_name
+pip install easy-eo
+```
+
+## 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/`](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](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](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](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`](examples/README.md) and in the
+[tutorials page](https://easy-eo.readthedocs.io/en/latest/tutorials.html) of the
+documentation.
+
+## 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

easy_eo-0.2.0/eeo/__init__.py

@@ -0,0 +1,41 @@
+"""Easy-EO: chainable raster processing for Earth Observation.
+
+A lightweight library of chainable raster operations, algebra, and
+visualization built on rasterio, NumPy, GeoPandas, and matplotlib.
+"""
+
+from . import datasets
+from ._show_versions import show_versions
+from .analysis import *
+from .core import (
+    AlignmentError,
+    BackendError,
+    CRSMismatchError,
+    EEOError,
+    MissingDependencyError,
+    ValidationError,
+    load_array,
+    load_raster,
+)
+from .core.adapters import *
+from .io import from_xarray, stac_search
+from .ops import *
+from .preprocessing import *
+from .viz import *
+
+__all__ = [
+    "datasets",
+    "load_raster",
+    "load_array",
+    "stac_search",
+    "from_xarray",
+    "show_versions",
+    "EEOError",
+    "ValidationError",
+    "CRSMismatchError",
+    "AlignmentError",
+    "BackendError",
+    "MissingDependencyError",
+]
+
+__version__ = "0.2.0"

easy_eo-0.2.0/eeo/_optional.py

@@ -0,0 +1,65 @@
+"""Import helper for the packages behind Easy-EO's optional extras.
+
+Heavier capabilities — STAC data access, xarray interop, the lazy backend —
+live behind optional extras so that a plain ``pip install easy-eo`` stays
+small. The modules implementing them import their third-party packages through
+:func:`import_optional`, which turns a missing package into a
+:class:`~eeo.MissingDependencyError` naming the exact install command instead
+of a bare ``ModuleNotFoundError``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+
+from .core.exceptions import MissingDependencyError
+
+
+def import_optional(module: str, *, extra: str, purpose: str) -> ModuleType:
+    """Import a module provided by an optional extra.
+
+    Parameters
+    ----------
+    module : str
+        Importable module name (e.g. ``"pystac_client"``), not the
+        distribution name.
+    extra : str
+        Name of the Easy-EO extra that provides the module (e.g. ``"stac"``),
+        used to build the ``pip install`` hint.
+    purpose : str
+        Short description of the feature needing the module (e.g. ``"STAC
+        search"``), used to open the error message.
+
+    Returns
+    -------
+    ModuleType
+        The imported module.
+
+    Raises
+    ------
+    MissingDependencyError
+        If the module is not installed. The message names the feature, the
+        missing package, and the ``pip install 'easy-eo[<extra>]'`` command
+        that provides it.
+
+    Examples
+    --------
+    >>> from eeo._optional import import_optional
+    >>> np = import_optional("numpy", extra="stac", purpose="STAC search")
+    >>> np.__name__
+    'numpy'
+    """
+    try:
+        return importlib.import_module(module)
+    except ModuleNotFoundError as err:
+        # A ModuleNotFoundError raised *inside* the optional package (one of
+        # its own dependencies missing) is a different problem; report it as-is
+        # rather than blaming the package the user did install.
+        if err.name is not None and err.name.split(".")[0] != module.split(".")[0]:
+            raise
+        raise MissingDependencyError(
+            f"{purpose} requires the optional '{module}' package, which is not "
+            f"installed. Install the '{extra}' extra with: "
+            f"pip install 'easy-eo[{extra}]'"
+        ) from err

easy_eo-0.2.0/eeo/_show_versions.py

@@ -0,0 +1,101 @@
+"""Environment reporting for bug reports and support requests."""
+
+from __future__ import annotations
+
+import platform
+from importlib.metadata import PackageNotFoundError, version
+
+# Optional dependencies that back the planned optional extras. Reported so a
+# bug report shows which extras are active. Maps the display label to the
+# installed distribution name.
+_OPTIONAL_DISTRIBUTIONS = {
+    "xarray": "xarray",
+    "rioxarray": "rioxarray",
+    "dask": "dask",
+    "pystac-client": "pystac-client",
+    "planetary-computer": "planetary-computer",
+}
+
+
+def _distribution_version(name: str) -> str:
+    """Return an installed distribution's version, or ``"not installed"``.
+
+    Parameters
+    ----------
+    name : str
+        Distribution (PyPI) name to look up.
+
+    Returns
+    -------
+    str
+        The installed version string, or ``"not installed"`` if the
+        distribution is not present.
+    """
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return "not installed"
+
+
+def _get_versions() -> dict[str, str]:
+    """Collect version information for Easy-EO and its dependencies.
+
+    Returns
+    -------
+    dict of str to str
+        Ordered mapping of component name to version string. Covers easy-eo,
+        the Python runtime and platform, the core geospatial stack (rasterio,
+        GDAL, numpy, geopandas, matplotlib), and each optional-extra
+        dependency (reported as ``"not installed"`` when absent).
+    """
+    # Imported lazily to keep `import eeo` light; all are hard dependencies.
+    import geopandas
+    import matplotlib
+    import numpy
+    import rasterio
+
+    gdal_version = getattr(rasterio, "__gdal_version__", None) or rasterio.gdal_version()
+
+    info = {
+        "easy-eo": _distribution_version("easy-eo"),
+        "python": platform.python_version(),
+        "OS": f"{platform.system()} {platform.release()}",
+        "rasterio": rasterio.__version__,
+        "GDAL": str(gdal_version),
+        "numpy": numpy.__version__,
+        "geopandas": geopandas.__version__,
+        "matplotlib": matplotlib.__version__,
+    }
+    for label, dist in _OPTIONAL_DISTRIBUTIONS.items():
+        info[label] = _distribution_version(dist)
+    return info
+
+
+def show_versions() -> None:
+    """Print Easy-EO, Python, and dependency version information.
+
+    Writes a human-readable report to standard output covering easy-eo, the
+    Python runtime and operating system, the core geospatial stack (rasterio,
+    GDAL, numpy, geopandas, matplotlib), and the optional-extra dependencies
+    (each shown as its version or ``not installed``). Intended for pasting
+    into bug reports.
+
+    Returns
+    -------
+    None
+        The report is printed; nothing is returned.
+
+    Examples
+    --------
+    >>> import eeo
+    >>> eeo.show_versions()  # doctest: +SKIP
+    Easy-EO version information
+    ...
+    """
+    info = _get_versions()
+    width = max(len(name) for name in info)
+
+    lines = ["Easy-EO version information", "=========================="]
+    for name, value in info.items():
+        lines.append(f"{name:<{width}} : {value}")
+    print("\n".join(lines))

easy_eo-0.2.0/eeo/analysis/__init__.py

@@ -0,0 +1,33 @@
+"""Analysis operations: spectral indices and pixel statistics."""
+
+from .indices import (
+    evi,
+    ndbi,
+    ndmi,
+    ndvi,
+    ndwi,
+    normalized_difference,
+    savi,
+)
+from .stats import (
+    extract_value_at_coordinate,
+    get_maximum_pixel,
+    get_mean_pixel,
+    get_minimum_pixel,
+    get_percentile_pixel,
+)
+
+__all__ = [
+    "extract_value_at_coordinate",
+    "normalized_difference",
+    "ndvi",
+    "ndwi",
+    "ndmi",
+    "ndbi",
+    "evi",
+    "savi",
+    "get_minimum_pixel",
+    "get_percentile_pixel",
+    "get_mean_pixel",
+    "get_maximum_pixel",
+]