---

name: features-masks description: "Routes Rasterio raster/vector feature extraction, rasterization, sieving, geometry windows, dataset masks, and nodata-mask workflows." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

Features and Masks

Use this sub-skill when a user wants to extract GeoJSON-like shapes from raster values, burn vector shapes into rasters, crop/mask rasters by geometry, or debug nodata masks.

Typical requests

• "Polygonize the valid pixels of this raster."
• "Rasterize this GeoJSON polygon into a GeoTIFF."
• "Mask and crop a raster to a shape."
• "Why do nodata masks and masked arrays look inverted?"

What this sub-skill owns

• rasterio.features.shapes, rasterize, sieve, bounds, geometry_mask, geometry_window, and dataset_features.
• rasterio.mask.raster_geometry_mask and rasterio.mask.mask.
• Valid-data masks, nodata values, masked arrays, alpha masks, and sidecar mask behavior.
• GeoJSON-like geometry validation and __geo_interface__ objects.

What it excludes

• Basic dataset open/write profile construction; use dataset-io-profiles first if the output profile is missing.
• Generic Window math and MemoryFile handling; use windows-memory-vsi.
• Reprojection or CRS transformation of geometries; use reprojection-merge-vrt when geometry CRS changes are part of the task.
• rio shapes, rio rasterize, and rio mask command construction; use rio-cli for CLI-specific flag routing.

Read first

• references/api-reference.md for verified signatures and parameter notes.
• references/workflows.md for shape extraction, rasterization, mask/crop, and nodata cleanup recipes.
• references/troubleshooting.md for invalid geometries, no-overlap crops, all_touched, dtype, and mask-sense issues.

Helper scripts

• scripts/extract_shapes.py — output a limited GeoJSON-like FeatureCollection from raster values.
• scripts/rasterize_geometry.py — rasterize a GeoJSON geometry/feature/collection to a small GeoTIFF.
• scripts/sieve_raster.py — remove small regions from a raster band and write the result.

Workflow shape

1. Confirm whether the geometry and raster coordinates are already in the same CRS.
2. Extract features with shapes or burn features with rasterize depending on direction.
3. For crop/mask workflows, use mask or raster_geometry_mask and update the output profile with the returned transform.
4. For valid-data cleanup, distinguish GDAL masks from NumPy masked-array masks.
5. Use sieve only when removing small connected regions is the intended cleanup.

Decision points

• Use all_touched=True only when every touched pixel should be included.
• Use skip_invalid=False when invalid geometry should be a hard failure.
• Use filled=False in mask when the caller needs a numpy.ma.MaskedArray.
• Use geometry_window when you need a pixel window around shapes before reading data.
• Route to reprojection-merge-vrt before masking if the shape CRS does not match the dataset CRS.

Common mistakes

• Cropping with shapes outside the raster extent.
• Forgetting that GDAL masks and NumPy masked arrays use opposite boolean senses.
• Rasterizing without a two-dimensional out_shape, out, or destination path.
• Assuming all_touched=True and center-based rasterization produce identical pixels.
• Writing a mask without checking whether nodata, alpha, sidecar, or internal masks should take precedence.

Good validation path

• tests/test_features.py::test_rasterize_polygon
• tests/test_features.py::test_rasterize_invalid_geom
• tests/test_features.py::test_geometry_window_north_up
• tests/test_mask.py::test_mask_crop
• tests/test_mask.py::test_mask_filled

What a future agent should be able to do here

A future agent should be able to answer shape-extraction, rasterization, mask-cropping, and nodata-mask-repair questions from this sub-skill plus its bundled files.