eoio.readers.sentinel2.data_io module

eoio.readers.sentinel2.data_io module#

eoio.readers.sentinel2.data_io - data reading functionality for Sentinel-2 IMG_DATA layers

eoio.readers.sentinel2.data_io.read_bands_into_dataset(*, ds: Dataset, layout: S2Layout, meas_vars: List[str], subset: ResolvedROISubset | None, mtd: S2MSIMetadataExtractor, chunks: Dict[str, int] | None = None, use_chunks: bool = False, preferred_resolution: int | None = None, mask_zero_as_nodata: bool = True) → Dataset[source]#

Read Sentinel-2 JP2 IMG_DATA layers into an existing Dataset.

This function performs low-level raster IO: it opens each requested JP2 IMG_DATA layer using rioxarray, applies variable-specific decoding, optionally subsets the data spatially, and inserts the resulting DataArray into the provided Dataset.

For reflectance bands, additive offsets and quantification scaling are applied using metadata extracted from the product XML. For L2A auxiliary layers such as AOT and WVP, dedicated quantification values are used where available. Categorical or browse layers such as SCL and TCI are left unscaled.

Dimension names are rewritten using the raster resolution, for example x_10m / y_10m or x_60m / y_60m, so variables on different native grids can coexist safely in the same Dataset.

Parameters:

  • ds – Dataset to which band DataArrays will be added.

  • layout – Sentinel-2 SAFE layout helper used to locate JP2 image files.

  • meas_vars – List of measurement variable names to read.

  • subset – Optional resolved region-of-interest subset defining a clip box and/or vector geometries.

  • mtd – Metadata extractor providing product-level and variable-level metadata used for decoding the requested layers.

  • chunks – Optional mapping of dimension names to chunk sizes passed directly to rioxarray.open_rasterio. If provided, this overrides any automatically derived chunk sizes.

  • use_chunks – If True and chunks is not provided, enable Dask-backed lazy reading using block-aligned chunk sizes inferred from the raster metadata.

  • preferred_resolution – Optional preferred IMG_DATA resolution in metres. If supplied, layout selection will attempt to use this resolution when available.

  • mask_zero_as_nodata – If True, raw values equal to zero are masked as missing data for reflectance bands before radiometric scaling is applied.

Returns:

The input Dataset with the requested variables added.

Raises:

ValueError – If reflectance quantification metadata is missing or invalid when reflectance bands are requested.