SAM3OrthoFeatureExtractor

class rapidtools.processing.SAM3OrthoFeatureExtractor(prompt: str, patch_size: float = 30.0, unit: str = 'feet', overlap_ratio: float = 0.15, model_id: str = 'facebook/sam3', device: str = 'auto', batch_size: int = 4, load_in_4bit: bool = True, threshold: float = 0.5, mask_threshold: float = 0.5, max_missing_data_ratio: float = 0.95, merge_overlaps: bool = True, cancel_event: Event | None = None, raster_path: str | Path | None = None)

Bases: object

Pipeline component that uses local SAM 3 to discover real-world assets.

The extractor tiles a high-resolution orthomosaic raster into square patches of patch_size (in real-world units), runs SAM 3 on each batch of patches with the given text prompt, and maps the resulting pixel masks back to WGS84 polygons. Because neighbouring tiles overlap, the same object is frequently detected more than once; by default a final unary_union melts those duplicates into a single geometry per physical feature. That suits area features (roofs, roads, vegetation) but also fuses countable objects that touch, such as cars parked side by side. Pass merge_overlaps=False to keep one asset per SAM 3 instance instead: each asset then carries the model’s confidence, and duplicates of the same object seen from overlapping tiles are removed with a greedy overlap suppression (highest confidence wins).

Parameters:

• prompt (str) – The text prompt describing the feature to extract (e.g., 'building', 'swimming pool').

• patch_size (float, optional) – Edge length of each square scanning tile, expressed in unit. Defaults to 30.0.

• unit (str, optional) – Spatial unit of patch_size: 'pixels', 'meters', 'feet', 'yards', 'kilometers' or 'miles'. Defaults to 'feet'.

• overlap_ratio (float, optional) – Fractional overlap between adjacent tiles (0.0 <= r < 1.0). Higher values reduce edge artefacts at the cost of more inference. Defaults to 0.15.

• model_id (str, optional) – Hugging Face repository ID of the SAM 3 model. Defaults to 'facebook/sam3'.

• device (str, optional) – Compute device ('cuda', 'cpu' or 'auto'). Defaults to 'auto'.

• batch_size (int, optional) – Number of tiles sent to the model per inference call. Defaults to 4.

• load_in_4bit (bool, optional) – Whether to load the model with 4-bit quantization. Defaults to True.

• threshold (float, optional) – Detection confidence threshold. Defaults to 0.5.

• mask_threshold (float, optional) – Threshold for binarizing the predicted masks. Defaults to 0.5.

• max_missing_data_ratio (float, optional) – Tiles whose nodata fraction exceeds this value are skipped. Defaults to 0.95.

• merge_overlaps (bool, optional) – True dissolves all touching or overlapping detections into single polygons (area features). False keeps one asset per detected instance with a confidence attribute and only removes cross-tile duplicates (countable objects). Defaults to True.

• cancel_event (Event | None, optional) – Cooperative cancellation flag checked before every tile. When set, OperationCancelled is raised. Defaults to None.

Example

Discover buildings in a Bing-derived orthomosaic and feed the result into a downstream pipeline:

>>> from rapidtools.core import BoundingBox
>>> from rapidtools.processing import (
...     BingOrthomosaicExtractor, SAM3OrthoFeatureExtractor
... )
>>> region = BoundingBox(-118.15, 34.18, -118.14, 34.19)
>>> tiff = BingOrthomosaicExtractor(zoom_level=19)(region, 'area.tiff')
>>> extractor = SAM3OrthoFeatureExtractor(
...     prompt='building', patch_size=200, unit='feet', batch_size=8
... )
>>> buildings = extractor(tiff)
>>> buildings[0].attributes['asset_type']
'building'

Methods

detect

Scan the raster, extract features, and merge overlaps into a collection.

detect(raster_path: str | Path) → PhysicalAssetCollection

Scan the raster, extract features, and merge overlaps into a collection.

Parameters:

raster_path (str | Path) – Path to a GeoTIFF orthomosaic (any CRS understood by rasterio; output geometries are always WGS84).

Returns:

PhysicalAssetCollection – One PhysicalAsset per merged feature (or per detected instance when merge_overlaps is False). Each asset carries the attributes 'asset_type' (the prompt), 'source_model' and 'extraction_scale'; instance assets also carry 'confidence'. The collection is empty if nothing was detected.

Raises:

• OperationCancelled – If cancel_event is set between two tiles.

• FileNotFoundError – If raster_path does not exist.

Example

>>> extractor = SAM3OrthoFeatureExtractor(prompt='road')
>>> roads = extractor('data/ortho.tif')
>>> len(roads)
12