eoio.interface module

eoio.interface module#

eoio.interface - interface functions module

eoio.interface.product_options(path: str, read_params: Dict[str, Any] | None = None, *args, **kwargs) → dict[source]#

Return dictionary of available meas_vars options for the requested EO data product

Parameters:

path – satellite data product

:return : dictionary of available subsetting parameters

eoio.interface.product_processors(path: str, *args, **kwargs) → dict | None[source]#

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.

Parameters:

path – satellite data product

:return : dictionary of available post processors and their optional parameters

eoio.interface.read(path: str, vars_sel: Dict[str, List[str]] | None = None, subset: Dict[str, Any] | None = None, read_params: Dict[str, Any] | None = None, processors: Dict[str, Any] | None = None, *args, **kwargs) → Dataset[source]#

Reads an Earth Observation (EO) data product and returns the requested variables, optionally applying spatial subsetting and post-processing.

Parameters:

  • path – Path to the EO data product (file or directory, depending on product type).

  • 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.

  • 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

  • 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

  • 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.

Returns:

xarray.Dataset containing the requested variables and associated metadata from the EO data product.

Examples

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",
...     },
... )