`build_mask` with all masking modes combined

This final notebook of the masking series combines everything covered so far: a valid geometry, one or more invalid geometries, and a low-resolution input raster mask. We then verify the result is exactly the binary AND of the per-mode outputs.

What you’ll learn

How the three masking modes combine inside build_mask
The AND semantics: a pixel is valid only if it is valid in every mode that contributes to the call
How to reproduce the combined mask manually from the per-mode masks

Setting things up

We reuse the same inputs as the previous notebooks: the valid/invalid geometries of notebook 003 and the low-resolution input mask of notebook 004.

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

# Geometry inputs (notebook 003).
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),
])
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),
    ]),
]

# Input mask (notebook 004).
input_mask_lowres = np.full((3, 3), grid_mask.Validity.INVALID, dtype=np.uint8)
input_mask_lowres[0, 1] = grid_mask.Validity.VALID
input_mask_lowres[1, 1] = grid_mask.Validity.VALID
input_mask_lowres[1, 0] = grid_mask.Validity.VALID
input_mask_lowres[2, 1] = grid_mask.Validity.VALID
input_mask_lowres[2, 0] = grid_mask.Validity.VALID
input_mask_lowres_resolution = (4, 4)

Combined `build_mask` call

raster = grid_mask.build_mask(
    shape                    = shape,
    resolution               = (1, 1),
    out                      = None,
    geometry_origin          = geometry_origin,
    geometry_pair            = [geometry_valid, geometry_invalid],
    mask_in                  = input_mask_lowres,
    mask_in_target_win       = None,
    mask_in_resolution       = input_mask_lowres_resolution,
    oversampling_dtype       = np.float64,
    mask_in_binary_threshold = 0.99,
    rasterize_kwargs         = rasterize_kwargs,
)

Only three pixels remain valid: those that survive all three masking modes simultaneously. The combination rule is the same one we saw between valid and invalid geometries – a binary AND across modes.

Verifying the AND combination

For full transparency, we recompute the per-mode masks separately and verify that their binary AND equals the combined build_mask output.

Mask from geometries only

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,
)
print(raster_geom)

[[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]]

Mask from input raster only

raster_mask_in = grid_mask.build_mask(
    shape                    = shape,
    resolution               = (1, 1),
    out                      = None,
    mask_in                  = input_mask_lowres,
    mask_in_target_win       = None,
    mask_in_resolution       = input_mask_lowres_resolution,
    oversampling_dtype       = np.float64,
    mask_in_binary_threshold = 0.99,
)
print(raster_mask_in)

[[0 0 0 0 1 0 0 0]
 [0 0 0 0 1 0 0 0]
 [0 0 0 0 1 0 0 0]
 [0 0 0 0 1 0 0 0]
 [1 1 1 1 1 0 0 0]
 [1 1 1 1 1 0 0 0]]

Binary AND merge

print(raster_geom & raster_mask_in)

[[0 0 0 0 0 0 0 0]
 [0 0 0 0 0 0 0 0]
 [0 0 0 0 0 0 0 0]
 [0 0 0 0 1 0 0 0]
 [0 0 0 1 1 0 0 0]
 [0 0 0 0 0 0 0 0]]

This is exactly the combined build_mask output above, confirming the documented merge semantics.

build_mask with all masking modes combined