eoio 0.1.2__py3-none-any.whl

eoio/__init__.py

@@ -0,0 +1,20 @@
+"""eoio - Data readers and preprocessing for satellite data"""
+
+# import h5py  # type: ignore
+
+# from eoio._show_versions import show_versions
+from eoio.interface import read, product_options  # (
+
+#     product_bounds,
+#     product_processors,
+#     product_subsetting_params,
+#     read,
+#     write,
+# )
+
+# __all__ = ["read", "write" "show_versions"]
+
+from ._version import get_versions
+
+__version__ = get_versions()["version"]
+del get_versions

eoio/_version.py

@@ -0,0 +1,21 @@
+
+# This file was generated by 'versioneer.py' (0.29) from
+# revision-control system data, or from the parent directory name of an
+# unpacked source archive. Distribution tarballs contain a pre-generated copy
+# of this file.
+
+import json
+
+version_json = '''
+{
+ "date": "2026-04-12T15:50:31+0100",
+ "dirty": false,
+ "error": null,
+ "full-revisionid": "198b8c0b0998d0857c3687e2065feb303b389480",
+ "version": "0.1.2"
+}
+'''  # END VERSION_JSON
+
+
+def get_versions():
+    return json.loads(version_json)

eoio/deps.py

@@ -0,0 +1,67 @@
+"""eoio.deps - Lazy imports for optional dependencies."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pyproj  # noqa: F401
+    import rasterio  # noqa: F401
+    import rioxarray  # noqa: F401
+    import cfgrib  # noqa: F401
+    from osgeo import gdal, ogr, osr  # noqa: F401
+    import shapely  # noqa: F401
+
+
+def _require_extra(extra: str, import_name: str) -> None:
+    raise ModuleNotFoundError(
+        f"Optional dependency '{import_name}' is required for this operation. "
+        f"Install with: pip install eoio[{extra}]"
+    )
+
+
+def lazy_pyproj():
+    try:
+        import pyproj  # type: ignore
+    except ModuleNotFoundError:
+        _require_extra("geo", "pyproj")
+    return pyproj
+
+
+def lazy_shapely():
+    try:
+        from shapely.geometry import Polygon, box, mapping, shape  # type: ignore
+        from shapely.ops import transform as shp_transform  # type: ignore
+    except ModuleNotFoundError:
+        _require_extra("geo", "shapely")
+    return Polygon, box, mapping, shape, shp_transform
+
+
+def lazy_rasterio():
+    try:
+        import rasterio  # type: ignore
+    except ModuleNotFoundError:
+        _require_extra("raster", "rasterio")
+    return rasterio
+
+
+def lazy_rioxarray():
+    try:
+        import rioxarray as rxr  # type: ignore
+    except ModuleNotFoundError:
+        _require_extra("raster", "rioxarray")
+    return rxr
+
+
+def lazy_cfgrib():
+    try:
+        import cfgrib  # type: ignore
+    except ModuleNotFoundError:
+        raise ModuleNotFoundError(
+            f"Dependency 'cfgrib' is required for this operation."
+            f"Please see the 'cfgrib' instructions at: https://github.com/ecmwf/cfgrib?tab=readme-ov-file#installation"
+        )
+    return cfgrib
+
+
+if __name__ == "__main__":
+    pass

eoio/interface.py

@@ -0,0 +1,300 @@
+"""eoio.interface - interface functions module"""
+
+from typing import Any, Dict, Optional, List
+import xarray as xr
+import os
+from processor_tools import Context
+from eoio.processors.processor_pipeline import ProcessorPipeline
+from eoio.processors.registry import PROCESSOR_REGISTRY
+from eoio.readers.factory import ReaderFactory
+from eoio.utils.read_utils import setup_file
+
+__all__ = [
+    "read",
+    # "product_bounds",
+    "product_processors",
+    # "mid_lon_lat",
+    "product_options",
+]
+
+
+def read(
+    path: str,
+    vars_sel: Dict[str, List[str]] = None,
+    subset: Optional[Dict[str, Any]] = None,
+    read_params: Optional[Dict[str, Any]] = None,
+    processors: Optional[Dict[str, Any]] = None,
+    *args,
+    **kwargs,
+) -> xr.Dataset:
+    """
+    Reads an Earth Observation (EO) data product and returns the requested variables,
+    optionally applying spatial subsetting and post-processing.
+
+    :param path:
+        Path to the EO data product (file or directory, depending on product type).
+
+    :param vars_sel:
+        Variable selection dictionary defining which variables to read from the product.
+
+        Supported keys are:
+
+        * ``"meas"`` (*list[str] | str | None*, default: ``"all"``) –
+          Measurement variables to read. Options are:
+
+          - ``"all"`` – read all available measurement variables
+          - ``list[str]`` – explicit list of measurement variable names
+          - ``None`` – do not read any measurement variables
+
+        * ``"mask"`` (*list[str] | None*, default: ``None``) –
+          Mask variable names to read. Use ``None`` to disable mask reading.
+
+        * ``"aux"`` (*list[str] | None*, default: ``None``) –
+          Auxiliary data variable names to read. Use ``None`` to disable auxiliary data reading.
+
+        Available variable names and supported combinations for a given product
+        can be inspected via ``eoio.product_options``.
+
+    :param subset:
+        Optional definition of subsetting parameters. If omitted or ``None``,
+        the full data product is read without subsetting.
+
+        Supported keys (availability depends on the product type):
+
+        * ``"roi"`` –
+          Spatial region of interest for raster data. Supported forms are:
+
+          - ``None`` – no spatial subsetting
+          - ``shapely`` geometry (interpreted in ``roi_crs_epsg``)
+          - Bounding box tuple ``(xmin, ymin, xmax, ymax)`` in ``roi_crs_epsg``
+          - GeoJSON-like ``dict`` with a ``"type"`` key
+          - List of ``[x, y]`` coordinate pairs defining a polygon
+          - ``((x, y), half_width_m)`` defining a square region centred on a point
+
+        * ``"roi_crs_epsg"`` (*str*) –
+          EPSG code defining the coordinate reference system of ``roi``
+          (e.g. ``"EPSG:4326"``).
+
+        * ``"angle"`` – (*Not implemented*) Observation geometry range of interest
+
+        * ``"spectral"`` – (*Not implemented*) Spectral range of interest
+
+    :param read_params:
+        Optional parameters controlling how the data are read.
+        If omitted, default behaviour is used.
+
+        Supported options include:
+
+        * ``"save_extracted"`` (*bool*, default: ``False``) –
+          If the data product is extracted or uncompressed during reading,
+          controls whether the extracted files are saved to disk.
+
+        * ``"metadata_level"`` (*None | bool*, default: ``None``) –
+          Level of metadata to read:
+
+          - ``None`` – Standard/core metadata only
+          - ``False`` – Do not read metadata
+          - ``True`` – Read all available metadata
+
+    :param processors:
+        Optional definition of post-processing steps to apply after reading
+        (e.g. interpolation, unit conversion, etc.).
+
+        Dictionary keys should be the names of the processors to run.
+        The associated entry should be a subdictionary of parameters for that processor.
+        Required parameters are defined at the processor level.
+
+    :return:
+        ``xarray.Dataset`` containing the requested variables and associated
+        metadata from the EO data product.
+
+    Examples
+    --------
+    .. doctest-skip::
+
+    Read all measurement variables from an EO product:
+
+    >>> ds = eoio.read("/path/to/product")
+
+    Read selected variables over a spatial region of interest:
+
+    >>> from shapely.geometry import box
+    >>> ds = read_product(
+    ...     path="/path/to/product",
+    ...     vars_sel={
+    ...         "meas": ["B02", "B03", "B04"],
+    ...         "mask": ["cloud_mask"],
+    ...     },
+    ...     subset={
+    ...         "roi": box(-2.0, 50.0, 0.0, 52.0),
+    ...         "roi_crs_epsg": "EPSG:4326",
+    ...     },
+    ... )
+    """
+
+    if path is None:
+        raise TypeError("path must not be None")
+
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"File not found: {path}")
+
+    # setup_file uncompresses file if necessary, and cleans up files after run
+    with setup_file(path, read_params) as path:
+
+        # Initialise reader
+        reader_factory = ReaderFactory()
+        reader_cls = reader_factory.get_reader(path)
+        reader_obj = reader_cls(
+            path, vars_sel=vars_sel, subset=subset, read_params=read_params
+        )
+
+        # Open dataset
+        ds = reader_obj.open()
+
+        # No post-processing requested
+        if not processors:
+            return ds
+
+        # Normalise context passed to processors
+        context = Context({**(subset or {}), "path": path})
+
+        # Run processor pipeline
+        pp = ProcessorPipeline(processor_params=processors, context=context)
+
+        ds = pp.run(ds)
+
+        return ds
+
+
+# def write(
+#     path_original: Union[str, List[str]],
+#     correction: Dict[str, Union[float, np.ndarray, int]],
+#     write_params: Optional[Dict[str, Any]] = None,
+# ) -> None:
+#     """
+#     writer function
+#
+#     :param path_original: satellite data product
+#     :param correction: dictionary with band names to be corrected as keys, and either corrected data or bias correction per band as values
+#     :param write_params: definition of desired writing parameters, by default None
+#     """
+#     if isinstance(path_original, str) or len(list(path_original)) == 1:
+#         path_original = [path_original]
+#
+#     for fn in path_original:
+#         with setup_file(fn, write_params) as path:
+#             writer_factory = WriterFactory()
+#
+#             writer = writer_factory.get_writer(path)
+#
+#             writer_obj = writer()
+#
+#             writer_obj.write(path, correction, write_params)
+#
+#
+# def product_bounds(
+#     path: str,
+#     read_params: Optional[Dict[str, Any]] = None,
+#     *args,
+#     **kwargs,
+# ) -> dict:
+#     """
+#     Return coordinate bounds of the product.
+#
+#     Example output:
+#         {
+#             'EPSG:4326':
+#                 [
+#                     [108.60281738078888, 41.52685230104365],
+#                     [109.91862807140421, 41.54675989693983],
+#                     [109.93470404984265, 40.55774811423141],
+#                     [108.63842218519015, 40.5385178383516]],
+#             'EPSG:32649':
+#                 [
+#                     [300000.0, 4600020.0],
+#                     [409810.0, 4600020.0],
+#                     [409810.0, 4490210.0],
+#                     [300000.0, 4490210.0]
+#                 ]
+#         }
+#
+#     :param path: satellite data product
+#     :return: dictionary with coordinate reference system as a key and the corresponding coordinate bounds as values
+#     """
+#     with setup_file(path, read_params) as path:
+#         reader_factory = ReaderFactory()
+#
+#         reader = reader_factory.get_reader(path)
+#
+#         reader_obj = reader(path)
+#
+#         try:
+#             return dict(
+#                 [(k, list(v.exterior.coords)) for k, v in reader_obj.bounds.items()]
+#             )
+#         except AttributeError:
+#             raise ValueError(
+#                 """'product_bounds' cannot be determined from '{}'.
+#             Either the bounds of the product cannot be parsed without reading in
+#             the full product or the reader is not yet fully configured.""".format(
+#                     path
+#                 )
+#             )
+#
+#
+# def mid_lon_lat(
+#     path: str,
+#     *args,
+#     **kwargs,
+# ) -> Tuple[float, float]:
+#     """
+#     Return mid point of satellite product in as a (lon, lat) coordinate
+#
+#     :param path: satellite data product
+#     :return : tuple of the (lon, lat) coordinate for the centre of the satellite product
+#     """
+#     bounds = product_bounds(path, *args, **kwargs)["EPSG:4326"]
+#
+#     lons, lats = [*set([i[0] for i in bounds])], [*set([i[1] for i in bounds])]
+#     lon_0, lon_1, lat_0, lat_1 = min(lons), max(lons), min(lats), max(lats)
+#     return lon_0 + (lon_1 - lon_0) / 2, lat_0 + (lat_1 - lat_0) / 2
+
+
+def product_processors(path: str, *args, **kwargs) -> Optional[dict]:
+    """
+    Return dictionary of available post processors for the requested satellite data product
+    and their optional parameters. Return None if none available or the product is not recognised.
+
+    :param path: satellite data product
+    :return : dictionary of available post processors and their optional parameters
+    """
+    from eoio.processors.registry import PROCESSOR_REGISTRY
+
+    processor_info = {}
+    for processor_name in PROCESSOR_REGISTRY:
+        processor_info[processor_name] = PROCESSOR_REGISTRY[processor_name]._all_options
+    return processor_info
+
+
+def product_options(
+    path: str, read_params: Optional[Dict[str, Any]] = None, *args, **kwargs
+) -> dict:
+    """
+    Return dictionary of available `meas_vars` options for the requested EO
+    data product
+
+    :param path: satellite data product
+    :return : dictionary of available subsetting parameters
+    """
+    with setup_file(path, read_params) as path:
+        reader_factory = ReaderFactory()
+
+        reader = reader_factory.get_reader(path)
+
+        reader_obj = reader(path)
+
+        return reader_obj.all_options
+
+
+if __name__ == "__main__":
+    pass

eoio/processors/__init__.py

@@ -0,0 +1,4 @@
+# from . import units
+from . import interpolate
+from . import add_lat_lon
+from . import s2_rut

eoio/processors/add_lat_lon/__init__.py

@@ -0,0 +1,4 @@
+import pkgutil, importlib
+
+for m in pkgutil.walk_packages(__path__, prefix=__name__ + "."):
+    importlib.import_module(m.name)

eoio/processors/add_lat_lon/processor.py

@@ -0,0 +1,203 @@
+"""
+eoio.processors.add_lat_lon.processor
+-------------------------------
+
+Top-level latitude/longitude processor.
+
+This processor provides a single, stable user-facing interface (``add_lat_lon``).
+
+User config example
+-------------------
+processors= {
+    "add_lat_lon": {
+        "geometry_id": ["10m", "60m"],
+      },
+    }
+
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Sequence
+from processor_tools import BaseProcessor
+import xarray as xr
+from eoio.processors.registry import register_processor
+from eoio.deps import lazy_pyproj
+import numpy as np
+
+
+@dataclass(frozen=True)
+class AddLatLonConfig:
+    """
+    Parameters for the add_lat_lon processor.
+    """
+
+    geometry_id: Optional[Sequence[str]] = None  # e.g. ["10m", "60m"]
+    on_missing: str = "error"  # "error" | "skip"
+
+
+@register_processor("add_lat_lon")
+class AddLatLon(BaseProcessor):
+    """
+    Add latitude and longitude coordinates to a dataset.
+
+    Processor parameters
+    --------------------
+
+    The following parameters can be provided in the `params` dict:
+
+    :param geometry_id:
+        Optional, List of geometry IDs to add (e.g. ``["10m", "60m"]``), if omitted lat/lon will be added for all grid resolutions found in the dataset.
+    :param on_missing:
+        Behaviour if required metadata for conversion is missing.
+        Supported values are ``"error"`` (default, if omitted) or ``"skip"``.
+
+    Notes
+    -----
+    - This processor is intended to run after reading.
+    """
+
+    _all_options = {
+        "geometry_id": "Optional, List of geometry IDs to add (e.g. ['10m', '60m']), if omitted lat/lon will be added for all grid resolutions found in the dataset.",
+        "on_missing": "Behaviour if required metadata for conversion is missing. Supported values are 'error' (default, if omitted) or 'skip'.",
+    }
+
+    def __init__(
+        self,
+        params: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Create an add_lat_lon processor.
+
+        :param params:
+            Processor parameters (see class docstring for details)
+        :param context:
+            Processing context provided by eoio (reader info, metadata view, logger, etc.).
+        """
+
+        super().__init__(context=context)
+        self.add_lat_lon_config = self._parse_params(params or {})
+
+    def _parse_params(self, params: Dict[str, Any]) -> AddLatLonConfig:
+        """
+        Validate and normalise processor parameters.
+
+        :param params:
+            Raw params dict from the processor spec.
+        :return:
+            Parsed AddLatLonParams.
+        :raises ValueError:
+            If required parameters are missing or invalid.
+        """
+
+        # resolve "geometry_id" param
+        geometry_id = params.get("geometry_id", None)
+
+        # resolve "on_missing" param
+        on_missing = str(params.get("on_missing", "error")).lower()
+        if on_missing not in {"error", "skip"}:
+            raise ValueError("interpolate: 'on_missing' must be 'error' or 'skip'.")
+
+        return AddLatLonConfig(
+            geometry_id=geometry_id,
+            on_missing=on_missing,
+        )
+
+    def _format_geometry_id(self, ds: xr.Dataset, geometry_id: Sequence) -> Sequence:
+        """
+        Format the geometry ids to ensure they are in the correct format for lat/lon processing.
+
+        :param ds:
+            Input dataset (used for context, e.g. to check available coordinates).
+        :param geometry_id:
+            List of geometry ids to process lat/lon for  (e.g. ``["10m", "60m"]``).
+        """
+        # available_geoms = list(set(ds.geometry_id))
+        available_geoms = list(
+            set([x.split("_")[-1] for x in ds.coords if "x_" in x or "y_" in x])
+        )
+        # Check all coords exist in the dataset
+        if geometry_id is not None:
+            for geom in geometry_id:
+                if geom not in available_geoms:
+                    raise ValueError(
+                        f"AddLatLon: geometry_id '{geom}' not found in dataset."
+                    )
+        else:
+            geometry_id = available_geoms
+
+        return geometry_id
+
+    def run(self, ds: xr.Dataset) -> xr.Dataset:
+        """
+        Run add lat/lon on the dataset.
+
+        :param ds:
+            Input dataset.
+        :return:
+            Output dataset with lat/lon coords.
+        """
+
+        if not isinstance(ds, xr.Dataset):
+            raise TypeError("add_lat_lon: input must be an xarray.Dataset.")
+
+        context: Mapping[str, Any] = self.context or {}
+
+        # get geometry ids
+        geometry_id = self._format_geometry_id(ds, self.add_lat_lon_config.geometry_id)
+
+        # instantiate transformer
+        pyproj = lazy_pyproj()
+        crs_src = ds.rio.crs
+        crs_dst = pyproj.CRS.from_epsg(4326)
+        transformer = pyproj.Transformer.from_crs(crs_src, crs_dst, always_xy=True)
+
+        # add lat/lon as coords
+        for geom in geometry_id:
+            x, y = np.meshgrid(ds[f"x_{geom}"].values, ds[f"y_{geom}"].values)
+            lons, lats = transformer.transform(x, y)
+
+            lat_lon_dict = {
+                f"latitude_{geom}": ([f"y_{geom}", f"x_{geom}"], lats),
+                f"longitude_{geom}": ([f"y_{geom}", f"x_{geom}"], lons),
+            }
+
+            ds = ds.assign_coords(coords=lat_lon_dict)
+
+        # Record processing history
+        ds = self._record_provenance(ds)
+
+        return ds
+
+    def _record_provenance(
+        self,
+        ds: xr.Dataset,
+    ) -> xr.Dataset:
+        """
+        Record a minimal provenance entry at processor level.
+
+        :param ds:
+            Output dataset.
+        :return:
+            Dataset (same object, attrs updated).
+        """
+
+        steps: list = ds.attrs.get("eoio:processing_steps", [])
+        if not isinstance(steps, list):
+            steps = [str(steps)]
+
+        steps.append(
+            {
+                "processor": "add_lat_lon",
+                "geometry_ids": self._format_geometry_id(
+                    ds, self.add_lat_lon_config.geometry_id
+                ),
+            }
+        )
+        ds.attrs["eoio:processing_steps"] = steps
+        return ds
+
+
+if __name__ == "__main__":
+    pass