{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Download Street View Images\n",
    "\n",
    "*zensvi.download: A module to download street view images*\n",
    "\n",
    "This tutorial demostrates how to use ZenSVI to download street view image from Mapillary, KartaView, and Amsterdam."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mapillary\n",
    "\n",
    "You can use zensvi to download Mapillary street view images in four different ways:\n",
    " - by latitude and longitude of a location\n",
    " - by a csv file with latitude and longitude of several locations\n",
    " - by a shapefile covering the area for downloading, points(e.g. several locations), polyline(e.g. road networks), or polygon(e.g. area boundary) are supported.\n",
    " - by a place name that works on OpenStreetMap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Preparation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If zen-svi is not installed\n",
    "%pip install --upgrade zensvi \n",
    "\n",
    "import zensvi\n",
    "\n",
    "print(zensvi.__version__)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prepare downloading module\n",
    "from zensvi.download import MLYDownloader\n",
    "import os\n",
    "\n",
    "# Input Mapillary API key\n",
    "mly_api_key = \"Your_Mapillary_API_key\"  # Please register your own Mapillary API key (\"Client Token\") at https://www.mapillary.com/dashboard/developers, \n",
    "downloader = MLYDownloader(mly_api_key=mly_api_key)\n",
    "\n",
    "# Output directory(folder) to save the SVI images\n",
    "output_folder = \"./download_SVI_images\" \n",
    "if not os.path.exists(output_folder):\n",
    "    os.makedirs(output_folder)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### To download SVI images, you can use one of the following methods:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Latitude and longitude of a location"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Getting pids...\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Loading cache files: 0it [00:00, ?it/s]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[Vector Tiles API] Fetching 1 tile for images ...\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Processing tiles: 100%|██████████| 1/1 [00:04<00:00,  4.69s/it]\n",
      "Filtering data: 100%|██████████| 53610/53610 [00:00<00:00, 662375.58it/s]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The panorama IDs have been saved to download_SVI_images/mly_pids.csv\n",
      "The cache directory for tiles has been deleted\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Getting urls for batch #1: 100%|██████████| 10/10 [00:01<00:00,  9.78it/s]\n",
      "Getting urls by batch size 10: 100%|██████████| 1/1 [00:01<00:00,  1.04s/it]\n",
      "Downloading images for batch #1: 100%|██████████| 10/10 [00:01<00:00,  9.69it/s]\n",
      "Downloading images by batch size 10: 100%|██████████| 1/1 [00:01<00:00,  1.05s/it]"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The cache directory has been deleted\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "# Input latitude and longitude of a location\n",
    "lat=1.290270 \n",
    "lon=103.851959\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location, buffer cannot be 0\n",
    "buffer = 10\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, lat=lat, lon=lon, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "CSV file with latitude and longitude of several locations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input path to CSV file /home/yihan/IPYNB_Yihan/ZenSVI/CSV_ZenSVI_test.csv\n",
    "input_csv_file=\"path/to/csv_file.csv\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location, buffer cannot be 0\n",
    "buffer = 10\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_csv_file=input_csv_file, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Shapefile containing the location information, points, polyline, or polygon are supported"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input path to shapefile\n",
    "input_shp_file=\"path_to_shp_file\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location\n",
    "buffer = 1\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_shp_file=input_shp_file, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Place Name that works on OpenStreetMap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input the Place Name, for example \"NUS, Singapore\"\n",
    "input_place_name=\"Chinatown, Singapore\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location\n",
    "buffer = 0\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_place_name=input_place_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## KartaView\n",
    "\n",
    "For downloading images from KartaView, utilize the KartaViewDownloader, similar to Mapillary, you can download KartaView Street Views in four ways:\n",
    "\n",
    " - by latitude and longitude of a location\n",
    " - by a csv file with latitude and longitude of several locations\n",
    " - by a shapefile covering the area for downloading, points(e.g. several locations), polyline(e.g. road networks), or polygon(e.g. area boundary) are supported.\n",
    " - by a place name that works on OpenStreetMap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Preparation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If zen-svi is not installed\n",
    "%pip install --upgrade zensvi \n",
    "\n",
    "import zensvi\n",
    "\n",
    "print(zensvi.__version__)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prepare downloading module, KartaView dataset does not require API key\n",
    "from zensvi.download import KVDownloader\n",
    "import os\n",
    "\n",
    "# Output directory(folder) to save the SVI images\n",
    "output_folder = \"./download_SVI_images\" \n",
    "if not os.path.exists(output_folder):\n",
    "    os.makedirs(output_folder)\n",
    "\n",
    "downloader = KVDownloader(\n",
    "    log_path=\"path_to_the_log_file.log\",  # path to the log file\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Latitude and longitude of a location"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input latitude and longitude of a location\n",
    "lat=1.296339198344591\n",
    "lon=103.77095139306607\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location, buffer cannot be 0\n",
    "buffer = 10\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, lat=lat, lon=lon, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "CSV file with latitude and longitude of several locations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input path to CSV file /home/yihan/IPYNB_Yihan/ZenSVI/CSV_ZenSVI_test.csv\n",
    "input_csv_file=\"path/to/csv_file.csv\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location, buffer cannot be 0\n",
    "buffer = 10\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_csv_file=input_csv_file, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Shapefile containing the location information, points, polyline, or polygon are supported"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input path to shapefile\n",
    "input_shp_file=\"path_to_shp_file\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location\n",
    "buffer = 1\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_shp_file=input_shp_file, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Place Name that works on OpenStreetMap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input the Place Name, for example \"NUS, Singapore\"\n",
    "input_place_name=\"Chinatown, Singapore\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location\n",
    "buffer = 0\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_place_name=input_place_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Amsterdam\n",
    "\n",
    "For downloading images from Amsterdam, utilize the AMSDownloader:, similar to Mapillary, you can download KartaView Street Views in four ways:\n",
    "\n",
    " - by latitude and longitude of a location\n",
    " - by a csv file with latitude and longitude of several locations\n",
    " - by a shapefile covering the area for downloading, points(e.g. several locations), polyline(e.g. road networks), or polygon(e.g. area boundary) are supported.\n",
    " - by a place name that works on OpenStreetMap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Preparation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If zen-svi is not installed\n",
    "%pip install --upgrade zensvi \n",
    "\n",
    "import zensvi\n",
    "\n",
    "print(zensvi.__version__)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prepare downloading module, Amsterdam dataset does not require API key\n",
    "from zensvi.download import AMSDownloader\n",
    "import os\n",
    "\n",
    "# Output directory(folder) to save the SVI images\n",
    "output_folder = \"./download_SVI_images\" \n",
    "if not os.path.exists(output_folder):\n",
    "    os.makedirs(output_folder)\n",
    "\n",
    "downloader = AMSDownloader()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Latitude and longitude of a location"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Getting pids: 100%|██████████| 1/1 [00:00<00:00,  1.22it/s]\n",
      "Downloading images and metadata: 100%|██████████| 25/25 [00:05<00:00,  4.46it/s]"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Metadata saved to download_SVI_images/ams_pids.csv\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "# Input latitude and longitude of a location\n",
    "lat=52.366554089348334\n",
    "lon=4.894944584367074\n",
    "# Setting downloading buffer size in meters around the input location, buffer cannot be 0\n",
    "buffer = 10\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, lat=lat, lon=lon, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "CSV file with latitude and longitude of several locations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input path to CSV file /home/yihan/IPYNB_Yihan/ZenSVI/CSV_ZenSVI_test.csv\n",
    "input_csv_file=\"path/to/csv_file.csv\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location, buffer cannot be 0\n",
    "buffer = 10\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_csv_file=input_csv_file, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Shapefile containing the location information, points, polyline, or polygon are supported"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input path to shapefile\n",
    "input_shp_file=\"path_to_shp_file\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location\n",
    "buffer = 1\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_shp_file=input_shp_file, buffer=buffer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Place Name that works on OpenStreetMap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Input the Place Name, for example \"Amsterdam\" or \"Grand Hotel, Amsterdam, Netherlands\"\n",
    "input_place_name=\"Amsterdam\"\n",
    "\n",
    "# Setting downloading buffer size in meters around the input location\n",
    "buffer = 10\n",
    "\n",
    "# Start downloading\n",
    "downloader.download_svi(output_folder, input_place_name=input_place_name)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}