zensvi.download.KVDownloader

class zensvi.download.KVDownloader(log_path: str | None = None, distance: int = 50, grid: bool = True, grid_size: int = 50, radius: int = 50, max_workers: int | None = None, verbosity: int = 1)

Bases: zensvi.download.base.BaseDownloader

KartaView Downloader class.

Parameters:

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

  • distance (int, optional) – Spacing in meters between sample points when grid is False (OSM street-network sampling); matched to the proximity search radius. Defaults to 50.

  • grid (bool, optional) – Use an equal-distance grid to generate sample points. Defaults to True. A grid avoids the slow, network-dependent OSM street-network lookup and is faster and more reliable for typical areas; set to False to sample along the street network, which can be more efficient for very large regions.

  • grid_size (int, optional) – Grid cell size in meters when grid is True. Defaults to 50.

  • radius (int, optional) – Proximity search radius in meters per sample point. Defaults to 50.

  • 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 max_workers: int | None

Property for the number of workers for parallel processing.

Returns:

max_workers

Return type:

int

property verbosity: int

Property for the verbosity level of progress bars.

Returns:

verbosity level

Return type:

int

download_svi(dir_output: str, path_pid: str | None = None, lat: float | None = None, lon: float | None = None, input_csv_file: str = '', input_shp_file: str = '', input_place_name: str = '', buffer: int = 10, update_pids: bool = False, cropped: bool = False, batch_size: int = 1000, start_date: str | None = None, end_date: str | None = None, metadata_only: bool = False, max_workers: int | None = None) → None

Downloads street view images from KartaView 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.

  • 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.

  • max_workers (int, optional) – Number of workers for parallel processing. If None, it will be set to min(32, os.cpu_count() + 4).

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: str | None

Property for log_path.

Returns:

Path to the log file

Return type:

str