GoogleStreetViewImageExtractor

GoogleStreetViewImageExtractor#

class rapidtools.processing.GoogleStreetViewImageExtractor(save_directory: str | Path, search_radius_m: float = 50.0, zoom: int = 3, max_images_per_asset: int = 1, fov_buffer_deg: float = 10.0, min_fov_deg: float = 30.0, vertical_crop: tuple[float, float] = (0.0, 1.0), save_panorama: bool = False, save_depth_map: bool = False, image_prefix: str = 'gsv', max_workers: int = 5, client: GoogleStreetViewClient | None = None, cancel_event: Event | None = None)[source]#

Bases: object

Street-view extractor that fetches keyless Google Street View crops of assets.

For every asset the extractor locates the nearest official Google Street View panorama (within search_radius_m of the asset centroid), downloads the panorama tiles, crops the horizontal span that covers the asset footprint and attaches the crop to the asset as an ImageAsset. Additional viewpoints are taken from the panorama’s neighbour links when max_images_per_asset is greater than one. No API key is required; the endpoints are the ones used by the Google Maps web app (as in BRAILS++), so availability may change.

Parameters:

  • save_directory (str | Path) – Directory where the JPEG crops (and optional panoramas/depth maps) are written.

  • search_radius_m (float, optional) – Radius around the asset centroid searched for panoramas. Defaults to 50.

  • zoom (int, optional) – Panorama tile zoom level 0-5 (zoom 3 is 4096 x 2048 px). Defaults to 3.

  • max_images_per_asset (int, optional) – Maximum number of viewpoints per asset; extra viewpoints come from neighbouring panoramas ordered by distance. Defaults to 1.

  • fov_buffer_deg (float, optional) – Horizontal margin added on both sides of the footprint. Defaults to 10.

  • min_fov_deg (float, optional) – Minimum horizontal field of view of a crop. Defaults to 30.

  • vertical_crop (tuple[float, float], optional) – (top, bottom) fractions of the panorama height to keep. Defaults to (0.0, 1.0) (full height).

  • save_panorama (bool, optional) – Also save the full stitched panorama next to the crop.

  • save_depth_map (bool, optional) – Also save the decoded depth map (.npy) of each panorama.

  • image_prefix (str, optional) – Prefix of the saved filenames. Defaults to 'gsv'.

  • max_workers (int, optional) – Number of assets processed concurrently. Defaults to 5.

  • client (GoogleStreetViewClient | None, optional) – Pre-configured client; one is created when omitted.

  • cancel_event (Event | None, optional) – Cooperative cancellation flag checked before each asset.

Example

>>> from rapidtools import PhysicalAssetCollection, Pipeline
>>> from rapidtools.processing import GoogleStreetViewImageExtractor
>>> buildings = PhysicalAssetCollection.from_geojson('buildings.geojson')
>>> extractor = GoogleStreetViewImageExtractor(
...     save_directory='output/streetview',
...     max_images_per_asset=2,
...     vertical_crop=(0.2, 0.9),
... )
>>> buildings = Pipeline([extractor]).run(buildings)
>>> buildings.get('bldg_01').image_assets[0].properties['pano_id']
'u3PxkEsnYto4l1N3yTmO_Q'