MapillaryObjectImageExtractor

class rapidtools.processing.MapillaryObjectImageExtractor(save_directory: str | Path, access_token: str | None = None, max_images_per_asset: int = 2, view_selection: str = 'widest', image_size: str = '2048', crop_buffer: float | str = '25%', min_crop_px: int = 256, overlay_asset_outline: bool = False, outline_shape: str = 'geometry', outline_buffer: float | str = 0, outline_width: int | float | str = 6, outline_color: str | tuple[int, int, int] = 'red', image_prefix: str = 'street', max_workers: int = 5, cancel_event: Event | None = None, client: MapillaryClient | None = None)

Bases: object

Crop each detected object out of the street-level images that saw it.

Reads the observations written by MapillaryFeatureExtractor, picks the closest distinct views of every asset, downloads those images at the requested thumbnail size, crops the detection with a margin and attaches the crops as ImageAsset objects. The detection outline can be drawn on the crop with the same outline_* options as AerialImageryExtractor.

Parameters:

• save_directory (str | Path) – Where the crops are written.

• access_token (str | None) – Mapillary API token. Not needed when client is given.

• max_images_per_asset (int) – Views to keep per object, from distinct images. Defaults to 2.

• view_selection (str) – Which views to keep: 'widest' (default, by the outline’s angular width) or 'closest' (by ground range). The widest views show the most of the object and are what a verifying model should judge; the closest can be an end-on sliver or a bumper at 3 m, and on a labelled block they let a bush through the verifier as a car where the widest views let nothing through.

• image_size (str) – Thumbnail size to download: '1024', '2048' or 'original'. Defaults to '2048'.

• crop_buffer (float | str) – Margin around the detection: a percentage of its longest side ('25%', the default), pixels, or a distance such as '1 m' converted at the object’s range.

• min_crop_px (int) – Crops are grown to at least this many pixels on their shorter side. Defaults to 256.

• overlay_asset_outline (bool) – Draw the detection outline on the crop. Defaults to False.

• outline_shape (str) – Outline shape, as in AerialImageryExtractor: 'geometry', 'bbox', 'rotated_bbox', 'convex_hull' or 'corners'. Defaults to 'geometry'.

• outline_buffer (float | str) – Outline offset in pixels, percent, or a distance such as '0.5 m' converted at the object’s range. Defaults to 0.

• outline_width (int | float | str) – Stroke width in pixels or percent of the shorter crop side. Defaults to 6.

• outline_color (str | tuple[int, int, int]) – PIL colour of the outline. Defaults to 'red'.

• image_prefix (str) – Prefix of the crop filenames and image IDs. Defaults to 'street'.

• max_workers (int) – Concurrent downloads. Each source image is downloaded once, cropped for every asset that needs it and released, so at most this many decoded images are in memory at a time. Defaults to 5.

• cancel_event (Event | None) – Cooperative cancellation flag checked between images.

• client (MapillaryClient | None) – Pre-configured client; one is created from access_token otherwise.

Example

>>> extractor = MapillaryObjectImageExtractor(
...     'output/vehicle_crops', access_token='MLY|...',
...     max_images_per_asset=2, overlay_asset_outline=True,
...     outline_shape='corners',
... )
>>> vehicles = extractor(vehicles)
>>> vehicles[0].image_assets[0].properties['range_m']
6.1

Methods

select_observations

Pick the closest (or widest) views of an object, one per image.

static select_observations(observations: Sequence[Observation], limit: int, by: str = 'closest') → list[Observation]

Pick the closest (or widest) views of an object, one per image.

Parameters:

• observations – The object’s sightings.

• limit – How many to keep.

• by – 'closest' ranks by ground range, nearest first; 'widest' by the outline’s angular width, widest first.

Example

>>> from rapidtools.core import Observation
>>> def obs(i, rng):
...     o = Observation(str(i), 'car', [(0, 0), (1, 0), (1, 1)], 0, 0, 0)
...     o.range_m = rng
...     return o
>>> [o.image_id for o in MapillaryObjectImageExtractor.select_observations(
...     [obs(1, 9.0), obs(2, 4.0), obs(2, 3.0), obs(3, 6.0)], 2)]
['2', '3']