eoio.readers.planetscope.masks module

eoio.readers.planetscope.masks module#

eoio.readers.planetscope.masks - PlanetScope UDM2 (Usable Data Mask 2) reading

Each PlanetScope scene ships a *_udm2*.tif alongside its image: a raster on the same grid as the image, with one band per quality layer. Bands 1-6 are binary (0/1) classes, band 7 is Planet’s classification confidence (0-100) and band 8 is the legacy UDM1 flag (1 = unusable/no-data pixel). The band order is fixed by Planet’s UDM2 specification and recorded in the file’s own band descriptions (clear, snow, shadow, haze_light, haze_heavy, cloud, confidence, udm1), exposed here as the named variables in MASK_OPTIONS.

Pixels outside the ROI polygon are NaN, so the variables are float32 – unlike the Sentinel-2 mask, which keeps its 0/1 flags as uint8 – because a flag of 0 outside the polygon would otherwise be indistinguishable from “not flagged” inside it (and so, for clear, from “not clear”).

eoio.readers.planetscope.masks.add_masks(*, ds: Dataset, masks: List[str], layout: PlanetScopeLayout, subset: ResolvedROISubset | None, config: Any) → Dataset[source]#

Read the requested UDM2 mask layers and add them to ds.

Validates the selection, then delegates the IO to read_masks().

Parameters:

  • ds – dataset to add mask variables to.

  • masks – mask variable names to read (see MASK_OPTIONS).

  • layout – layout helper used to locate the mask file.

  • subset – resolved ROI subset to clip the mask to, or None.

  • config – resolved reader configuration.

Returns:

ds with the mask variables merged in.

Raises:

ValueError – if an unknown mask name is requested.

eoio.readers.planetscope.masks.read_masks(*, ds: Dataset, masks: List[str], layout: PlanetScopeLayout, subset: ResolvedROISubset | None = None, chunks: dict | None = None, use_chunks: bool = False) → Dataset[source]#

Read UDM2 layers from the scene’s *_udm2*.tif into ds.

The mask shares the image’s 3 m grid, so its variables use the same x_3m/y_3m dimensions as the measurement bands.

Parameters:

  • ds – dataset to add mask variables to.

  • masks – mask variable names to read.

  • layout – layout helper used to locate the mask file.

  • subset – resolved ROI subset to clip the mask to, or None.

  • chunks – explicit dask chunk spec passed to rioxarray.

  • use_chunks – whether to open the raster lazily (chunked).

Returns:

ds with the mask variables merged in.

Raises:

PlanetScopeLayoutError – if the scene has no (or more than one) UDM2 file.