zensvi.download.MLYDownloader

class zensvi.download.MLYDownloader(mly_api_key, log_path=None, max_workers=None, verbosity=1)

Bases: zensvi.download.base.BaseDownloader

Mapillary Downloader class.

Parameters:

  • mly_api_key (str, optional) – Mapillary API key. Defaults to None.

  • log_path (str, optional) – Path to the log file. Defaults to None.

  • max_workers (int, optional) – Number of workers for parallel processing. Defaults to None.

  • verbosity (int, optional) – Level of verbosity for progress bars. Defaults to 1. 0 = no progress bars, 1 = outer loops only, 2 = all loops.

property mly_api_key

Property for Mapillary API key.

Returns:

mly_api_key

Return type:

str

property max_workers

Property for the number of workers for parallel processing.

Returns:

max_workers

Return type:

int

property verbosity

Property for the verbosity level of progress bars.

Returns:

verbosity level

Return type:

int

download_svi(dir_output, path_pid=None, lat=None, lon=None, input_csv_file='', input_shp_file='', input_place_name='', buffer=0, update_pids=False, resolution=1024, cropped=False, batch_size=1000, start_date=None, end_date=None, metadata_only=False, use_cache=True, additional_fields=['all'], **kwargs)

Downloads street view images from Mapillary using specified parameters.

Parameters:

  • dir_output (str) – Directory where output files and images will be stored.

  • path_pid (str, optional) – Path to a file containing panorama IDs. If not provided, IDs will be fetched based on other parameters.

  • lat (float, optional) – Latitude to fetch panorama IDs around this point. Must be used with lon.

  • lon (float, optional) – Longitude to fetch panorama IDs around this point. Must be used with lat.

  • input_csv_file (str, optional) – Path to a CSV file containing locations for which to fetch panorama IDs.

  • input_shp_file (str, optional) – Path to a shapefile containing geographic locations for fetching panorama IDs.

  • input_place_name (str, optional) – A place name for geocoding to fetch panorama IDs.

  • buffer (int, optional) – Buffer size in meters to expand the geographic area for panorama ID fetching.

  • update_pids (bool, optional) – If True, will update panorama IDs even if a valid path_pid is provided. Defaults to False.

  • resolution (int, optional) – The resolution of the images to download. Defaults to 1024.

  • cropped (bool, optional) – If True, images will be cropped to the upper half. Defaults to False.

  • batch_size (int, optional) – Number of images to process in each batch. Defaults to 1000.

  • start_date (str, optional) – Start date (YYYY-MM-DD) to filter images by capture date.

  • end_date (str, optional) – End date (YYYY-MM-DD) to filter images by capture date.

  • metadata_only (bool, optional) – If True, skips downloading images and only fetches metadata. Defaults to False.

  • use_cache (bool, optional) – If True, uses cached data to speed up the operation. Defaults to True.

  • additional_fields (list, optional) – Additional fields to fetch from the API. Defaults to [“all”]. Possible fields include: 1. altitude - float, original altitude from Exif 2. atomic_scale - float, scale of the SfM reconstruction around the image 3. camera_parameters - array of float, intrinsic camera parameters 4. camera_type - enum, type of camera projection (perspective, fisheye, or spherical) 5. captured_at - timestamp, capture time 6. compass_angle - float, original compass angle of the image 7. computed_altitude - float, altitude after running image processing 8. computed_compass_angle - float, compass angle after running image processing 9. computed_geometry - GeoJSON Point, location after running image processing 10. computed_rotation - enum, corrected orientation of the image 11. exif_orientation - enum, orientation of the camera as given by the exif tag 12. geometry - GeoJSON Point geometry 13. height - int, height of the original image uploaded 14. thumb_256_url - string, URL to the 256px wide thumbnail 15. thumb_1024_url - string, URL to the 1024px wide thumbnail 16. thumb_2048_url - string, URL to the 2048px wide thumbnail 17. merge_cc - int, id of the connected component of images that were aligned together 18. mesh - { id: string, url: string } - URL to the mesh 19. quality_score - float, how good the image is (experimental) 20. sequence - string, ID of the sequence 21. sfm_cluster - { id: string, url: string } - URL to the point cloud 22. width - int, width of the original image uploaded

  • **kwargs – Additional keyword arguments that are passed to the API.

Returns:

This method does not return a value but will save files directly to the specified output directory.

Return type:

None

Raises:

  • ValueError – If required parameters for fetching panorama IDs are not adequately specified.

  • FileNotFoundError – If path_pid is specified but the file does not exist.

Notes

This method logs significant events and errors, making it suitable for both interactive usage and automated workflows.

property log_path

Property for log_path.

Returns:

Path to the log file

Return type:

str