Mapillary Imagery Explorer

Build a utility that discovers street-level imagery around a location, downloads a small sample, presents it on an interactive map, and produces a simple GIF from the retrieved frames. The focus is on using the package's Mapillary imagery helpers and related media utilities.

Capabilities

Search Mapillary coverage

• Given a bounding box ordered as [west, south, east, north], an access token, optional ISO 8601 start/end timestamps, and a limit, return imagery metadata sorted by capture time and constrained to the limit. Each record must include an id, coordinates, capture timestamp, and an image URL. @test

Download imagery assets

• Save the first N image URLs from the metadata to a target directory, preserving extensions, and return the saved file paths in capture order. Reuse existing files when overwrite is false. @test

Interactive viewer

• Build an interactive map widget that drops a marker for each image, displays a clickable thumbnail or link in each popup, and optionally overlays coverage geometry if available in the metadata. @test

Timelapse generation

• Produce an animated GIF from an ordered list of downloaded images using a configurable frame rate, writing to the requested output path and erroring when fewer than two frames are provided. @test

Implementation

@generates

API

from pathlib import Path
from typing import Iterable, List, Mapping, Optional, Sequence

def fetch_mapillary_metadata(
    bbox: Sequence[float],
    access_token: str,
    limit: int = 10,
    start_time: Optional[str] = None,
    end_time: Optional[str] = None,
) -> List[Mapping[str, object]]:
    """Return imagery metadata within bbox ordered as [west, south, east, north], sorted by capture time ascending; each record must include id, coordinate tuple (lon, lat), captured_at ISO string, and image_url."""


def download_mapillary_images(
    metadata: Iterable[Mapping[str, object]],
    output_dir: Path,
    max_items: Optional[int] = None,
    overwrite: bool = False,
) -> List[Path]:
    """Download image assets referenced by metadata to output_dir, reusing existing files when allowed, and return saved paths in capture order."""


def build_mapillary_viewer(
    metadata: Iterable[Mapping[str, object]],
    basemap: Optional[str] = None,
    show_tracks: bool = True,
):
    """Create an interactive map widget with markers and popups for each image plus optional coverage lines, ready for notebook or HTML embedding."""


def create_imagery_gif(
    images: Sequence[Path],
    output_path: Path,
    fps: int = 2,
) -> Path:
    """Create a GIF timelapse from ordered images at the given frame rate and return output_path."""

Dependencies { .dependencies }

leafmap { .dependency }

Provides Mapillary imagery search, download, visualization, and media helpers.