easy-eo 0.1.0__tar.gz

easy_eo-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.env
+.venv
+
+# Builds
+build/
+dist/
+
+# Data
+data/
+
+# Docs
+docs/build/
+
+# Tests
+.pytest_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store

easy_eo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

easy_eo-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: easy-eo
+Version: 0.1.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<1.2,>=1.1
+Requires-Dist: matplotlib<3.11,>=3.10
+Requires-Dist: numpy<2.2,>=1.26
+Requires-Dist: rasterio<1.5,>=1.4
+Description-Content-Type: text/markdown
+
+# EasyEO
+
+**EasyEO** 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`)
+- Resampling, reprojection, and alignment
+- Clip rasters using vectors or bounding boxes
+- Normalization (min-max, percentile, z-score)
+- Visualization helpers (bands, composites, histograms)
+- Backend-aware design (NumPy ↔ 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)
+```
+
+## 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:
+
+👉 https://easyeo.readthedocs.io
+
+## 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.1.0/README.md

@@ -0,0 +1,67 @@
+# EasyEO
+
+**EasyEO** 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`)
+- Resampling, reprojection, and alignment
+- Clip rasters using vectors or bounding boxes
+- Normalization (min-max, percentile, z-score)
+- Visualization helpers (bands, composites, histograms)
+- Backend-aware design (NumPy ↔ 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)
+```
+
+## 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:
+
+👉 https://easyeo.readthedocs.io
+
+## 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.1.0/eeo/__init__.py

@@ -0,0 +1,20 @@
+"""
+Easy-EO
+A lightweight Earth Observation utilities library for chainable raster operations
+"""
+
+
+from .core import load_raster, load_array
+from .analysis import *
+from .ops import *
+from .viz import *
+from .preprocessing import *
+from .core.adapters import *
+
+
+__all__ = [
+    "load_raster",
+    "load_array",
+]
+
+__version__ = "0.1.0"

easy_eo-0.1.0/eeo/analysis/__init__.py

@@ -0,0 +1,13 @@
+from .stats import extract_value_at_coordinate, get_maximum_pixel, get_mean_pixel, get_minimum_pixel, get_percentile_pixel
+
+from .indices import normalized_difference
+
+
+__all__ = [
+    "extract_value_at_coordinate",
+    "normalized_difference",
+    "get_minimum_pixel",
+    "get_percentile_pixel",
+    "get_mean_pixel",
+    "get_maximum_pixel"
+]

easy_eo-0.1.0/eeo/analysis/indices.py

@@ -0,0 +1,62 @@
+"""
+This library exposes algebraic primitives instead of predefined indices.
+Most vegetation and water indices can be expressed directly using
+``normalized_difference`` or raster arithmetic.
+"""
+
+from typing import Union
+
+import numpy as np
+import rasterio as rio
+
+from eeo.common import align_raster_to_target
+from eeo.core.core import EEORasterDataset
+from eeo.core.decorators import eeo_raster_op
+
+
+@eeo_raster_op
+def normalized_difference(
+        ds: EEORasterDataset,
+        other: EEORasterDataset,
+        *,
+        auto_align: bool = True,
+        method: str = "bilinear",
+        return_as_ndarray: bool = False
+) -> Union[np.ndarray, EEORasterDataset]:
+    # Ensure reprojection for only rasterio-backend datasets
+    backend = ds._adapter.backend
+    if not isinstance(backend, rio.DatasetReader):
+        ds = ds.to_rasterio()
+    if ds.get_shape() != other.get_shape() or ds.get_transform() != other.get_transform():
+        if auto_align:
+            other = align_raster_to_target(other, ds, method=method)
+        else:
+            raise ValueError("Rasters must have the same shape and alignment")
+
+
+    a = ds.read().astype(rio.float32)
+    b = other.read().astype(rio.float32)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        nd = (a - b) / (a + b)
+        nd[np.isnan(nd)] = 0
+
+    if return_as_ndarray:
+        return nd
+
+    meta = ds.get_metadata().copy()
+
+    # Ensure correct metadata for writing
+    meta.update(
+        driver="GTiff",
+        dtype="float32",
+        height=nd.shape[-2],
+        width=nd.shape[-1],
+        count=nd.shape[0],
+    )
+
+    memfile = rio.io.MemoryFile()
+    out_ds = memfile.open(**meta)
+    out_ds.write(nd)
+
+    return EEORasterDataset.from_rasterio(out_ds)

easy_eo-0.1.0/eeo/analysis/indices.pyi

@@ -0,0 +1,35 @@
+from typing import Union
+
+import numpy as np
+
+from eeo.core.core import EEORasterDataset
+from eeo.core.decorators import eeo_raster_op
+
+
+@eeo_raster_op
+def normalized_difference(
+        ds: EEORasterDataset,
+        other: EEORasterDataset,
+        *,
+        auto_align: bool = True,
+        method: str = "bilinear",
+        return_as_ndarray: bool = False
+) -> Union[np.ndarray, EEORasterDataset]:
+    """
+        Compute the normalized difference index: (ds - other) / (ds + other)
+
+
+        :param ds: EEORasterDataset
+            First raster (e.g. NIR).
+        :param other: EEORasterDataset
+            Second raster (e.g. Red).
+        :param auto_align: bool, optional
+            Automatically resample `other` to match `ds`.
+        :param method: str, optional
+            Resampling method used if auto-aligning.
+        :param return_as_ndarray: bool, optional
+            If True, return a NumPy array instead of an EEORasterDataset.
+
+        :return: Union[np.ndarray, EEORasterDataset]
+    """
+    ...

easy_eo-0.1.0/eeo/analysis/stats.py

@@ -0,0 +1,127 @@
+from typing import Union
+
+import numpy as np
+import rasterio as rio
+from eeo.common import mask_nodata
+from eeo.core.core import EEORasterDataset
+from eeo.core.decorators import eeo_raster_op
+
+Coordinate = Union[tuple[float, float], list[float]]
+
+
+@eeo_raster_op
+def extract_value_at_coordinate(
+        ds: EEORasterDataset,
+        coordinates: Coordinate,
+        band_idx: int = 1
+) -> Union[int, float]:
+
+    if len(coordinates) != 2:
+        raise ValueError(f"Expected 2 coordinates, got {len(coordinates)}")
+
+    backend = ds._adapter.backend
+    if not isinstance(backend, rio.DatasetReader):
+        ds = ds.to_rasterio()
+        backend = ds._adapter.backend
+
+    x, y = coordinates
+    row, col = backend.index(x, y)
+
+    return ds.get_band(band_idx)[row, col]
+
+
+
+@eeo_raster_op
+def get_maximum_pixel(
+        ds: EEORasterDataset,
+        band_idx: int = 1,
+        *,
+        return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    band = ds.read() if ds.get_count() == 1 else ds.get_band(band_idx)
+    band = mask_nodata(ds, band)
+
+    # get max value
+    value = float(np.nanmax(band))
+    _, row, col = np.unravel_index(np.nanargmax(band), band.shape)
+
+    if return_position_as_pixel_coordinate:
+        position = (row, col)
+    else:
+        transform = ds.get_transform()
+        position = transform * (col, row)
+
+    return {"value": value, "position": position}
+
+
+@eeo_raster_op
+def get_minimum_pixel(
+        ds: EEORasterDataset,
+        band_idx: int = 1,
+        *,
+        return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    band = ds.read() if ds.get_count() == 1 else ds.get_band(band_idx)
+    band = mask_nodata(ds, band)
+
+    # get min value
+    value = float(np.nanmin(band))
+    _, row, col = np.unravel_index(np.nanargmin(band), band.shape)
+
+    if return_position_as_pixel_coordinate:
+        position = (row, col)
+    else:
+        transform = ds.get_transform()
+        position = transform * (col, row)
+
+    return {"value": value, "position": position}
+
+
+@eeo_raster_op
+def get_mean_pixel(
+        ds: EEORasterDataset,
+        band_idx: int = 1,
+        *,
+        return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    band = ds.read() if ds.get_count() == 1 else ds.get_band(band_idx)
+    band = mask_nodata(ds, band)
+
+    mean_value = float(np.nanmean(band))
+    diff = np.abs(band - mean_value)
+
+    _, row, col = np.unravel_index(np.nanargmin(diff), diff.shape)
+
+    if return_position_as_pixel_coordinate:
+        position = (row, col)
+    else:
+        transform = ds.get_transform()
+        position = transform * (col, row)
+
+    return {"value": mean_value, "position": position}
+
+
+@eeo_raster_op
+def get_percentile_pixel(
+        ds: EEORasterDataset,
+        percentile: float,
+        band_idx: int = 1,
+        *,
+        return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    band = ds.read() if ds.get_count() == 1 else ds.get_band(band_idx)
+    band = mask_nodata(ds, band)
+
+    perc_value = float(np.nanpercentile(band, percentile))
+    diff = np.abs(band - perc_value)
+
+    _, row, col = np.unravel_index(np.nanargmin(diff), band.shape)
+
+    if return_position_as_pixel_coordinate:
+        position = (row, col)
+    else:
+        transform = ds.get_transform()
+        position = transform * (col, row)
+
+    return {"value": perc_value, "position": position}
+

easy_eo-0.1.0/eeo/analysis/stats.pyi

@@ -0,0 +1,99 @@
+from typing import Union
+
+from eeo.core.core import EEORasterDataset
+
+Coordinate = Union[tuple[float, float], list[float]]
+
+def extract_value_at_coordinate(
+    ds: EEORasterDataset,
+    coordinates: Coordinate,
+    band_idx: int = 1,
+) -> Union[int, float]:
+    """
+    Extract the pixel value from an EEORasterDataset at a given geographic coordinate.
+
+    :param ds: The raster dataset from which to extract a value.
+    :type ds: EEORasterDataset
+    :param coordinates: A tuple of (x, y) coordinates. Must contain exactly two values.
+    :type coordinates: Coordinate
+    :param band_idx: The index of the raster band to sample from in case of a multiband raster.
+    :type band_idx: int
+
+    :return: The extracted pixel value from the specified band and coordinate.
+    :rtype: int or float
+
+    :raises ValueError: If the provided coordinates do not contain exactly two elements.
+    """
+    ...
+
+
+def get_maximum_pixel(
+    ds: EEORasterDataset,
+    band_idx: int = 1,
+    *,
+    return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    """
+    Get the maximum pixel value and its location from a raster band.
+
+    :param ds: Input raster dataset.
+    :param band_idx: Band index to evaluate (1-based).
+    :param return_position_as_pixel_coordinate: If True, return (row, col) instead of spatial coordinates.
+
+    :return: Dictionary containing the maximum value and its position.
+    :rtype: dict[str, float | tuple]
+    """
+    ...
+
+def get_minimum_pixel(
+    ds: EEORasterDataset,
+    band_idx: int = 1,
+    *,
+    return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    """
+    Get the minimum pixel value and its location from a raster band.
+
+    :param ds: Input raster dataset.
+    :param band_idx: Band index to evaluate (1-based).
+    :param return_position_as_pixel_coordinate: If True, return (row, col) instead of spatial coordinates.
+
+    :return: Dictionary containing the minimum value and its position.
+    :rtype: dict[str, float | tuple]
+    """
+    ...
+
+def get_mean_pixel(
+    ds: EEORasterDataset,
+    band_idx: int = 1,
+    *,
+    return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    """
+    Get the pixel whose value is closest to the mean of the raster band.
+
+    :param ds: Input raster dataset.
+    :param band_idx: Band index to evaluate (1-based).
+    :param return_position_as_pixel_coordinate: If True, return (row, col) instead of spatial coordinates.
+
+    :return: Dictionary containing the mean value and its position.
+    """
+    ...
+
+def get_percentile_pixel(
+    ds: EEORasterDataset,
+    percentile: float,
+    band_idx: int = 1,
+    *,
+    return_position_as_pixel_coordinate: bool = False,
+) -> dict:
+    """
+    Get the pixel corresponding to a given percentile of raster values.
+
+    :param ds: Input raster dataset.
+    :param percentile: Percentile in the range [0, 100].
+    :param band_idx: Band index to evaluate (1-based).
+    :param return_position_as_pixel_coordinate: If True, return (row, col) instead of spatial coordinates.
+    :return: Dictionary containing the percentile value and its position.
+    """
+    ...

easy_eo-0.1.0/eeo/common.py

@@ -0,0 +1,35 @@
+import numpy as np
+from rasterio.enums import Resampling
+
+from eeo.core.core import EEORasterDataset
+
+
+def normalize_resampling_method(value):
+    """Function to normalize resampling method either user passes a rasterio.enums.Resampling or a string"""
+    if isinstance(value, Resampling):
+        return value
+    if isinstance(value, str):
+        name = value.lower().strip()
+        try:
+            return Resampling[name]
+        except KeyError:
+            valid = ", ".join([r.name for r in Resampling])
+            raise ValueError(f"Invalid resampling method {value}. Valid values are: {valid}")
+    raise TypeError("resampling method must be one from rasterio.enums.Resampling or a string")
+
+
+# Helper function for raster auto-alignment
+def align_raster_to_target(ds: EEORasterDataset, target: EEORasterDataset,
+                            method: str = "bilinear") -> EEORasterDataset:
+    """Resample dataset to match target raster's shape and transform"""
+    if ds.get_shape() == target.get_shape() or ds.get_transform() == target.get_transform():
+        return ds
+    return ds.resample(size=target.get_shape(), resampling_method=method)
+
+
+# helper to mask nodata values from an EEORasterDataset
+def mask_nodata(ds: EEORasterDataset, array: np.ndarray) -> np.ndarray:
+    nodata = ds.get_metadata().get("nodata", None)
+    if nodata is not None:
+        array = np.where(array == nodata, np.nan, array)
+    return array

easy_eo-0.1.0/eeo/core/__init__.py

@@ -0,0 +1,11 @@
+from .core import EEORasterDataset
+from .loader import load_raster, load_array
+from .plugins import load_ops
+
+load_ops()
+
+__all__ = [
+    "EEORasterDataset",
+    "load_raster",
+    "load_array",
+]

easy_eo-0.1.0/eeo/core/adapters/__init__.py

@@ -0,0 +1,10 @@
+from .base import BaseRasterAdapter
+from .rasterio import RasterioAdapter
+from .numpy import NumpyRasterioAdapter
+
+
+__all__ = [
+    "BaseRasterAdapter",
+    "RasterioAdapter",
+    "NumpyRasterioAdapter",
+]