`build_mask` with geometries

grid_mask.build_mask is the GridR API for assembling a binary validity mask from any combination of vector geometries and raster input masks. This notebook covers the geometry-only path: how to specify valid and invalid polygons through geometry_pair.

What you’ll learn

The build_mask signature and the Validity enum
How to provide a valid geometry through geometry_pair
How to provide an invalid geometry through geometry_pair
How both interact when used together

Setting things up

from gridr.core.grid import grid_mask

The `build_mask` signature

def build_mask(
        shape: Tuple[int, int],
        resolution: Tuple[int, int],
        out: np.ndarray,
        geometry_origin: Optional[Tuple[float, float]] = None,
        geometry_pair: Optional[Tuple[Optional[GeometryType],
                Optional[GeometryType]]] = None,
        mask_in: Optional[np.ndarray] = None,
        mask_in_target_win: Optional[np.ndarray] = None,
        mask_in_resolution: Optional[Tuple[int, int]] = None,
        oversampling_dtype: Optional[np.dtype] = None,
        mask_in_binary_threshold: float = 0.999,
        rasterize_kwargs: Optional[Dict] = None,
        init_out: bool = False,
        ) -> Optional[np.ndarray]

From the docstring:

build_mask operates solely on raster data and does not perform I/O. It combines information from two distinct mask types to build a binary raster mask at a target resolution (currently only full resolution, i.e. (1, 1), is implemented).

The `Validity` convention

class Validity(IntEnum):
    INVALID = 0
    VALID   = 1

This is the convention every GridR mask must follow.

The `geometry_pair` argument

geometry_pair is a length-2 sequence:

index 0 – the valid geometry (GeometryType or None),
index 1 – the invalid geometry (GeometryType or None).

GeometryType is defined in grid_rasterize:

GeometryType = Union[
    shapely.geometry.Polygon,
    List[shapely.geometry.Polygon],
    shapely.geometry.MultiPolygon,
]

Valid geometry only

With a single valid polygon, pixels inside the polygon are set to Validity.VALID and the rest to Validity.INVALID.

rasterize_kwargs = {
    "alg": grid_rasterize.GridRasterizeAlg.RASTERIO_RASTERIZE,
    "kwargs_alg": {},
}

geometry_origin = (0.5, 0.5)
geometry_valid = shapely.geometry.Polygon([
    (3.5, 2.5),
    (6.5, 2.5),
    (6.5, 4.5),
    (3.5, 4.5),
])

raster = grid_mask.build_mask(
    shape            = shape,
    resolution       = (1, 1),
    out              = None,
    geometry_origin  = geometry_origin,
    geometry_pair    = [geometry_valid, None],
    rasterize_kwargs = rasterize_kwargs,
)

Invalid geometry only

A list of polygons can be passed to flag multiple disjoint invalid areas at once.

geometry_invalid = [
    shapely.geometry.Polygon([
        (1.5, 1.5),
        (4.5, 1.5),
        (4.5, 2.5),
        (1.5, 2.5),
    ]),
    shapely.geometry.Polygon([
        (5.5, 3.5),
        (6.5, 3.5),
        (6.5, 4.5),
        (5.5, 4.5),
    ]),
]

raster = grid_mask.build_mask(
    shape            = shape,
    resolution       = (1, 1),
    out              = None,
    geometry_origin  = geometry_origin,
    geometry_pair    = [None, geometry_invalid],
    rasterize_kwargs = rasterize_kwargs,
)

Both at the same time

When both a valid and an invalid geometry are provided, internally two separate rasterisations are performed and merged with a binary AND: a pixel is valid in the output only if it is valid in both masks.

In practice this means the invalid geometry punches holes in the valid geometry.

raster_geom = grid_mask.build_mask(
    shape            = shape,
    resolution       = (1, 1),
    out              = None,
    geometry_origin  = geometry_origin,
    geometry_pair    = [geometry_valid, geometry_invalid],
    rasterize_kwargs = rasterize_kwargs,
)
display(raster_geom)

array([[0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 1, 1, 0],
       [0, 0, 0, 1, 1, 0, 0, 0],
       [0, 0, 0, 1, 1, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0]], dtype=uint8)

The next notebook covers the raster-input mode of build_mask – supplying a pre-existing mask raster, possibly at a coarser resolution than the output.

build_mask with geometries