MapillaryImageExtractor

MapillaryImageExtractor#

class rapidtools.processing.MapillaryImageExtractor(access_token: str | None = None, save_directory: str | Path = 'streetview', start_date: str = '', end_date: str = '', filter_rapid_only: bool = True, cast_corner_rays: bool = False, smart_crop: bool = True, strict_content_filter: bool = False, label_mapper: Any = None, asset_type_mapping: dict[str, list[str]] | None = None, image_prefix: str = 'street', max_images_per_asset: int = 8, max_workers: int = 10, cancel_event: Event | None = None, api_key: str | None = None)[source]#

Bases: object

Street-view extractor that fetches unobstructed Mapillary panoramas of assets.

This extractor acts as an intelligent pipeline component. Instead of making thousands of API calls, it fetches regional metadata once, builds spatial indexes (KDTree and STRtree), and uses ray-casting to simulate lines of sight. It actively culls occluded views (e.g., if a neighboring building blocks the camera) and downloads only the valid panoramas, one per viewing direction (major/minor building axes and, optionally, the corners).

If strict_content_filter is enabled, the extractor checks the semantic contents of the image before downloading the heavy JPEG. If the target asset type is not actually visible in the image, it skips it to save bandwidth.

Parameters:

  • access_token (str) – Mapillary API Access Token.

  • save_directory (str | Path) – The directory where the final cropped JPEG images will be saved.

  • start_date (str, optional) – Inclusive lower bound for the image capture date (YYYY-MM-DD). Defaults to '' (no lower bound).

  • end_date (str, optional) – Inclusive upper bound for the image capture date (YYYY-MM-DD). Defaults to '' (no upper bound).

  • filter_rapid_only (bool, optional) – If True, strictly fetches images uploaded by the RAPID organization. Set to False to search all public street-view images. Defaults to True.

  • cast_corner_rays (bool, optional) – If False, limits extraction to the 4 principal axes (faces) of the building. If True, also extracts views pointing directly at the 4 corners (up to 8 images). Defaults to False.

  • smart_crop (bool, optional) – If True, downloads the semantic mask for the panorama and intelligently crops out the sky and the data-collection vehicle. Defaults to True.

  • strict_content_filter (bool, optional) – If True, verifies that the target asset type is semantically present in the image before downloading the high-resolution JPEG. Defaults to False.

  • label_mapper (Any, optional) – An instance of MapillaryLabelMapper that uses an LLM to dynamically map asset types to Mapillary labels. Used if strict_content_filter is True. Defaults to None.

  • asset_type_mapping (dict[str, list[str]] | None, optional) – A manual dictionary mapping your asset types to official Mapillary labels (e.g., {'building': ['construction--structure--building']}). Used as a fallback or alternative to the label_mapper. Defaults to None.

  • image_prefix (str, optional) – Prefix applied to the saved image filenames. Defaults to 'street'.

  • max_images_per_asset (int, optional) – The maximum number of panorama crops to extract per asset. Panoramas aligned with the major axes are prioritized over minor axes and corners. Defaults to 8.

  • max_workers (int, optional) – The number of concurrent threads used to download and crop images. Defaults to 10.

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

Example

>>> from rapidtools.processing import MapillaryImageExtractor
>>>
>>> # Option 1: Using manual dictionary mapping
>>> extractor = MapillaryImageExtractor(
...     access_token='YOUR_TOKEN',
...     save_directory='output/streetview',
...     strict_content_filter=True,
...     asset_type_mapping={
...         'building': ['construction--structure--building'],
...         'pole': ['object--support--utility-pole']
...     }
... )
>>>
>>> # Option 2: Using the Gemma LLM Mapper for dynamic mapping
>>> from rapidtools.models import Gemma4Inference
>>> from rapidtools.processing.label_mappers import MapillaryLabelMapper
>>> mapper = MapillaryLabelMapper(Gemma4Inference())
>>> extractor_llm = MapillaryImageExtractor(
...     access_token='YOUR_TOKEN',
...     save_directory='output/streetview',
...     strict_content_filter=True,
...     label_mapper=mapper
... )
>>>
>>> processed_assets = extractor(my_asset_collection)
>>> processed_assets['bldg_01'].image_assets[0].properties['view_angle']
'major_axis_0'