BuildingRegularizer

BuildingRegularizer#

class rapidtools.processing.BuildingRegularizer(prompt: str | list[str] = 'building', batch_size: int = 4, load_in_4bit: bool = True, min_overlap_ratio: float = 0.15, max_gap_bridge_ft: float = 15.0, confidence_threshold: float = 0.5, mask_threshold: float = 0.5, retry_dropped: bool = True, retry_confidence_threshold: float = 0.3, retry_mask_threshold: float = 0.3, snap_tolerance_ft: float = 0.5, cancel_event: Event | None = None)[source]#

Bases: object

Pipeline component to regularize and refine preliminary building polygons.

This regularizer takes assets that have preliminary building geometries and associated cropped imagery, runs a batched SAM 3 segmentation to find the exact physical boundaries of the buildings, and maps the resulting pixel masks back to real-world WGS84 coordinates.

It filters out AI hallucinations and giant blobs using IoU, splits merged preliminary shapes using Recall, and runs a second low-threshold pass on dropped assets to rescue shadowed buildings.

Every image attached to an input asset must carry a 'wgs84_bounds' property ((min_lon, min_lat, max_lon, max_lat)), as written by AerialImageryExtractor; images without it are ignored.

Parameters:

  • prompt (str | list[str], optional) – The text prompt(s) used for SAM 3 segmentation (e.g., 'building roof'). Lists are joined with '. '. Defaults to 'building'.

  • batch_size (int, optional) – Batch size for SAM 3 inference. Defaults to 4.

  • load_in_4bit (bool, optional) – Whether to load the SAM 3 model in 4-bit precision to save memory. Defaults to True.

  • min_overlap_ratio (float, optional) – Minimum Intersection over Union (IoU) between a mask and its preliminary seed required to keep the mask. A mask is also kept if it covers at least 50% of the seed (recall). Defaults to 0.15.

  • max_gap_bridge_ft (float, optional) – Maximum distance in feet to dynamically bridge fragmented polygons. Defaults to 15.0.

  • confidence_threshold (float, optional) – Primary confidence threshold for SAM 3 mask generation. Defaults to 0.5.

  • mask_threshold (float, optional) – Primary threshold for SAM 3 mask binarization. Defaults to 0.5.

  • retry_dropped (bool, optional) – Whether to run a second pass with lower thresholds on dropped assets. Defaults to True.

  • retry_confidence_threshold (float, optional) – Lower confidence threshold for the retry pass. Defaults to 0.3.

  • retry_mask_threshold (float, optional) – Lower mask threshold for the retry pass. Defaults to 0.3.

  • snap_tolerance_ft (float, optional) – Tolerance in feet for snapping polygon vertices. Defaults to 0.5.

  • cancel_event (Event | None, optional) – Cooperative cancellation flag shared with the internal segmenter. When set, OperationCancelled is raised between SAM 3 batches or between pipeline stages. Defaults to None.

Example

>>> from rapidtools.processing import (
...     AerialImageryExtractor, BuildingRegularizer, Pipeline
... )
>>> pipeline = Pipeline([
...     AerialImageryExtractor('ortho.tif', 'crops', buffer_asset='30%'),
...     BuildingRegularizer(prompt=['building', 'roof'], batch_size=8),
... ])
>>> refined = pipeline.run(prelim_buildings)
>>> refined[0].attributes['asset_type']
'building_footprint'

Methods

process

Execute the full building regularization pipeline.
process(input_assets: PhysicalAssetCollection) → PhysicalAssetCollection[source]#

Execute the full building regularization pipeline.

This pipeline consists of:

  1. Running batched SAM 3 segmentation on the image crops.

  2. Georeferencing masks and applying geometric/spatial filters.

  3. (Optional) Retrying dropped assets with lower thresholds.

  4. Dissolving overlapping duplicates.

  5. Truncating neighboring intrusions to form clean property lines.

  6. Removing degenerate geometries.

Parameters:

input_assets (PhysicalAssetCollection) – Collection of preliminary building assets.

Returns:

PhysicalAssetCollection – Collection of refined, georeferenced, and non-overlapping building assets. The output assets carry new IDs ('bldg_merged_<hash>') and the attribute 'asset_type': 'building_footprint'. Returns an empty collection when input_assets is empty.

Raises:

OperationCancelled – If cancel_event is set during processing.

Example

>>> refined = BuildingRegularizer(retry_dropped=False).process(prelim)
>>> len(refined) <= len(prelim) + 5
True