eoio.readers.subset.roi_subset module

eoio.readers.subset.roi_subset module#

Generic ROI-based subsetting for gridded raster Earth Observation products.

This module provides a small, product-agnostic utility for resolving a user-specified region of interest (ROI) into a form suitable for raster subsetting.

It is intentionally not Sentinel-2 specific and is designed to be reused by any reader that:

works with data on a fixed raster grid
wants to support spatial subsetting via bounding boxes or geometries

Out of scope#

Swath/orbit products with per-pixel latitude/longitude arrays
Vector-only products

Design principles#

Keep the public API small and explicit
Delay importing heavy geospatial dependencies until needed
Separate user intent (ROI specification) from reader mechanics

Typical usage#

::

roi_subset: ResolvedROISubset = ROISubsetResolver(roi, roi_crs_epsg, image_crs_epsg, image_bounds).run(): # within image_io.py access: roi_subset.clip_box roi_subset.geometries

class eoio.readers.subset.roi_subset.ROISubsetResolver(roi: Any, roi_crs_epsg: int | str, image_crs_epsg: str | int, image_bounds: Any | None = None)[source]#

Bases: object

Create resolved ROI for clipping in image_io.py (clip or clip_box)

Example usage: resolvedROIsubset: ResolvedROISubset = ROISubsetResolver(roi, roi_crs_epsg, image_crs_epsg, image_bounds).run()

Parameters:

roi –
Region of interest. Supported forms are:

Primary (recommended)
- shapely geometry (interpreted in roi_crs_epsg)
- bounding box tuple (xmin, ymin, xmax, ymax) in roi_crs_epsg
Convenience forms (accepted, but less strict):
- GeoJSON-like dict with a "type" key
- list of [x, y] coordinate pairs defining a polygon
- ((x, y), half_width_m) defining a square box around a point
roi_crs_epsg – EPSG code describing the CRS in which the ROI coordinates are expressed
image_crs_epsg – EPSG code describing the CRS in which the image coordinates are expressed. For rioxarray raster use raster.rio.crs.to_epsg() to obtain EPSG code.
image_bounds – Optional, if you want to test is roi is with the target image bounds. Supported forms are: * shapely geometry * tuple(x_min, y_min, x_max, y_max) (raster.rio.bounds) Must be in the crs image_crs_epsg

Returns ResolvedROISubset:

Dataclass with geometries or clip_box attributes

run() → ResolvedROISubset[source]#: Run ROISubsetResolver. :returns: ResolvedROISubset

exception eoio.readers.subset.roi_subset.RasterSubsetError[source]#

Bases: ValueError

Raised when ROI specification or resolution fails.

This error is raised when:

an unsupported ROI format is provided
an unsupported CRS format is provided
requested ROI is not within image bounds

class eoio.readers.subset.roi_subset.ResolvedROISubset(geometries: List[Dict[str, Any]] | None, clip_box: Tuple[float, float, float, float] | None, roi: Any, roi_crs_epsg: int | str, image_crs: Any, xy_clip_box: Tuple[float, float, float, float] | None = None, tie_clip_box: Tuple[float, float, float, float] | None = None)[source]#

Bases: object

Resolved spatial subset in the data CRS.

This is the form consumed by raster IO backends (e.g. rasterio/rioxarray).