---

name: geospatial-utilities description: "Guides SamGeo geospatial utility workflows for CRS checks, tile downloads, image preparation, raster/vector conversion, split/merge, region analysis, and UTM helpers." disable-model-invocation: true metadata: disco-role: operating license: MIT

Geospatial utilities

Use this sub-skill when the task is primarily raster/vector preparation, coordinate handling, CRS troubleshooting, data conversion, or safe validation around samgeo.common rather than direct model inference.

Read this when

• The user needs tms_to_geotiff, image_to_cog, reproject, raster_to_vector, split_raster, merge_rasters, regularize, smooth_vector, or region_groups.
• The user asks how to prepare multi-band GeoTIFFs for SAM, choose bands, or inspect raster metadata/statistics.
• The task involves converting prompt coordinates or boxes from CRS coordinates to pixel coordinates.
• The user is debugging CRS distortion, empty vector outputs, out-of-bounds prompts, tile downloads, or vector driver issues.

Route elsewhere

• Model-specific automatic/prompt segmentation: core-segmentation.
• SAM3 tiled, text, or video workflows: samgeo3-workflows.
• Optional model wrappers and captioning: specialized-models.
• HTTP API request/response details: api-server.

Utility workflow order

1. Inspect the raster first: CRS, transform, width/height, band count, dtype, nodata, and stats.
2. Normalize imagery to uint8 RGB for SAM with read_image_for_sam or prepare_image_for_sam.
3. For map-tile workflows, keep bounding boxes small and confirm provider terms.
4. After segmentation, inspect mask values before vectorization.
5. Convert masks to vector formats, then optionally simplify, regularize, or smooth geometries.
6. Reproject only when the user explicitly wants a different CRS for downstream visualization or analysis.

References and scripts

• workflows.md gives data-preparation and conversion recipes for common SamGeo support tasks.
• api-reference.md records verified helper signatures and input/output assumptions.
• troubleshooting.md covers CRS, bands, all-zero masks, tile download, GDAL/vector, and large-raster failures.
• scripts/mini_geotiff_roundtrip.py creates a tiny GeoTIFF and empty mask, then validates image prep and vector conversion without network access.

Native validation candidates

• tests/test_utmconv.py is the safe native case for UTM math.
• The local subset of tests/test_common.py validates image prep, multi-band reads, and empty-mask vectorization.
• Network examples such as map tile downloads are optional and should be run only when network/provider access is authorized.