AerialImageryExtractor

AerialImageryExtractor#

class rapidtools.processing.AerialImageryExtractor(dataset: str | Path | list[str | Path], save_directory: str | Path, max_missing_data_ratio: float = 0.2, overlay_asset_outline: bool = False, image_prefix: str = 'aerial', keep_multiple_copies: bool = False, buffer_asset: float | str = '20%', buffer_m: float | None = None, force_square_image: bool = True, cancel_event: Event | None = None, min_footprint_coverage: float | None = None, pad_edges: bool | None = None, outline_shape: str = 'geometry', outline_buffer: float | str = 0, outline_width: int | float | str = 6, outline_color: str | tuple[int, int, int] = 'red')[source]#

Bases: object

Component that extracts aerial imagery patches for a collection of assets.

This extractor reads from one or more high-resolution orthomosaic TIFF files, crops the imagery around each asset’s bounding box, saves the patches to disk, and automatically attaches the new digital media to the corresponding PhysicalAsset objects in the collection.

Each saved ImageAsset gets the ID '<asset_id>_<image_prefix>' and three properties: 'wgs84_bounds' ((min_lon, min_lat, max_lon, max_lat) of the patch), 'native_georef' (the patch’s affine transform and CRS, see PatchGeoref) and 'source_raster' (the TIFF file name).

Parameters:

  • dataset (str | Path | list[str | Path]) – The file path to a single local orthomosaic TIFF dataset, a directory containing TIFFs (searched recursively), or a list of TIFF file paths.

  • save_directory (str | Path) – The directory where the extracted JPEG images will be saved. Will be created if it does not exist.

  • max_missing_data_ratio (float, optional) – The maximum acceptable proportion of nodata pixels (0.0 to 1.0). Crops exceeding it are skipped, which drops assets on the edge of the imagery unless min_footprint_coverage is used.

  • min_footprint_coverage (float | None, optional) – Keep an asset as long as at least this fraction of its footprint is covered by valid imagery (e.g. 0.3), instead of the patch-level nodata test. Assets partially outside the raster are then cropped with nodata padding so every crop keeps its size. Defaults to None (previous behaviour).

  • pad_edges (bool | None, optional) – Pad edge crops with nodata to their full size. Defaults to True when min_footprint_coverage is set. If a cropped patch exceeds this, it is discarded. Defaults to 0.2.

  • overlay_asset_outline (bool, optional) – If True, draws an outline of the asset directly onto the saved image so a downstream model knows which asset to look at. With the default outline_* settings this is a thick red trace of the asset’s geometry (a red dot for point assets). Defaults to False.

  • outline_shape (str, optional) – What the outline traces. 'geometry' follows the asset’s own geometry, 'bbox' its axis-aligned bounding box, 'rotated_bbox' its minimum rotated rectangle, 'convex_hull' its convex hull, and 'corners' draws L-shaped brackets at the corners of the rotated rectangle so the asset’s edges stay unobstructed. Defaults to 'geometry'.

  • outline_buffer (float | str, optional) – How far to expand the outline shape away from the asset before drawing it. A bare number or '12 px' is in pixels, a percentage ('10%') is relative to the asset’s longest pixel extent, and a real-world distance ('2 m', '5 ft') is converted with the crop’s ground sampling distance. Point assets with a buffer are drawn as a ring of that radius instead of a dot. Defaults to 0.

  • outline_width (int | str, optional) – Stroke width in pixels, or a percentage of the shorter image side ('1%') so outlines look alike across crop sizes. Defaults to 6.

  • outline_color (str | tuple[int, int, int], optional) – Any PIL colour name, hex string or RGB tuple. Defaults to 'red'.

  • image_prefix (str, optional) – The prefix to use for the saved image filenames and asset IDs. Defaults to 'aerial'.

  • keep_multiple_copies (bool, optional) – If True, prevents overwriting existing images with the same coordinates by appending a numeric counter to the filename and ID. Defaults to False.

  • buffer_asset (float | str, optional) – The padding applied around the asset’s geometry before cropping. Can be a percentage (e.g., '20%'), an absolute CRS distance (e.g., 50.0), or a real-world distance (e.g., '50 ft', '10 m'). Defaults to '20%'.

  • force_square_image (bool, optional) – If True, guarantees the extracted image patch covers a perfectly square area in the real world. Defaults to True.

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

Example

>>> from rapidtools.core import PhysicalAssetCollection
>>> from rapidtools.processing import AerialImageryExtractor
>>>
>>> collection = PhysicalAssetCollection.from_geojson('bldgs.geojson')
>>> extractor = AerialImageryExtractor(
...     dataset='data/rasters/',
...     save_directory='output/aerial_crops',
...     overlay_asset_outline=True,
...     outline_shape='rotated_bbox',
...     outline_buffer='2 m',
...     outline_width='1%',
...     image_prefix='post_disaster',
...     keep_multiple_copies=True,
...     buffer_asset='20 ft',
...     force_square_image=True
... )
>>> processed_assets = extractor(collection)
>>> processed_assets[0].image_assets[0].id
'bldg_001_post_disaster'