{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to visualize the results\n",
    "*zensvi.visualization: A module to visualize the results*\n",
    "\n",
    "The visualization sub-package, built with [Matplotlib](https://matplotlib.org/), provides four high-level plotting functions to streamline the presentation of SVI analysis for quick initial data exploration. \n",
    "ZenSVI supports histogram generation for discrete data visualization, such as object detection counts, and kernel density estimation plots for continuous variables, such as semantic segmentation ratios. \n",
    "Users can create image grids to display SVI samples, either randomly selected or sorted by specified variables.\n",
    "\n",
    "For spatial visualization, the package implements three map formats: point maps showing individual SVI locations, line maps using [OpenStreetMap](https://www.openstreetmap.org/) street segments, and hexagonal maps using [Uber's H3 grid](https://h3geo.org/). \n",
    "In both line and hexagonal maps, SVI values are aggregated to the nearest features, defaulting to point counts when no specific variable is specified.\n"
   ]
  },
  {
   "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": [
    "# Import the required libraries\n",
    "from zensvi.visualization import plot_map, plot_image, plot_kde, plot_hist"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Point map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dir_input = \"path/to/input/folder\" # path where the images are stored\n",
    "path_output = \"./visualization/output.png\"  # output file path \"path/to/output.png\"\n",
    "path_pid = \"path/to/pid\"  # path to the panorama ID file with latitude and longitude \"path/to/pid\"\n",
    "csv_file_pattern = \"pixel_ratios.csv\"  # pattern of the CSV files that contain the pixel ratios (or any other variable to plot)\n",
    "variable = \"vegetation\"  # variable to plot (e.g. vegetation, building, sky, etc.). This should be the column name in the CSV file. If None, count of the number of images is plotted\n",
    "plot_type = \"point\"  # plot type (either \"point\", \"line\", or \"hexagon\")\n",
    "fig, ax = plot_map(\n",
    "    path_pid,\n",
    "    dir_input=dir_input,\n",
    "    csv_file_pattern=csv_file_pattern,\n",
    "    variable_name=variable,\n",
    "    plot_type=plot_type,\n",
    "    path_output=path_output,\n",
    "    resolution=13,\n",
    "    cmap=\"viridis\",\n",
    "    legend=True,\n",
    "    title=\"Point Map\",\n",
    "    legend_title=\"Vegetation\",\n",
    "    dark_mode=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Line map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dir_input = \"path/to/input\"\n",
    "path_output = \"path/to/output.png\"  # output file path\n",
    "path_pid = \"path/to/pid\"  # path to the panorama ID file with latitude and longitude\n",
    "csv_file_pattern = \"pixel_ratios.csv\"  # pattern of the CSV files that contain the pixel ratios (or any other variable to plot)\n",
    "variable = \"vegetation\"  # variable to plot (e.g. vegetation, building, sky, etc.). This should be the column name in the CSV file. If None, count of the number of images is plotted\n",
    "plot_type = \"line\"  # plot type (either \"point\", \"line\", or \"hexagon\")\n",
    "fig, ax = plot_map(\n",
    "    path_pid,\n",
    "    dir_input=dir_input,\n",
    "    csv_file_pattern=csv_file_pattern,\n",
    "    variable_name=variable,\n",
    "    plot_type=plot_type,\n",
    "    path_output=path_output,\n",
    "    resolution=13,\n",
    "    cmap=\"viridis\",\n",
    "    legend=True,\n",
    "    title=\"Point Map\",\n",
    "    legend_title=\"Vegetation\",\n",
    "    dark_mode=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hexagon map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dir_input = \"path/to/input\"\n",
    "path_output = \"path/to/output.png\"  # output file path\n",
    "path_pid = \"path/to/pid\"  # path to the panorama ID file with latitude and longitude\n",
    "csv_file_pattern = \"pixel_ratios.csv\"  # pattern of the CSV files that contain the pixel ratios (or any other variable to plot)\n",
    "variable = \"vegetation\"  # variable to plot (e.g. vegetation, building, sky, etc.). This should be the column name in the CSV file. If None, count of the number of images is plotted\n",
    "plot_type = \"hexagon\"  # plot type (either \"point\", \"line\", or \"hexagon\")\n",
    "fig, ax = plot_map(\n",
    "    path_pid,\n",
    "    dir_input=dir_input,\n",
    "    csv_file_pattern=csv_file_pattern,\n",
    "    variable_name=variable,\n",
    "    plot_type=plot_type,\n",
    "    path_output=path_output,\n",
    "    resolution=13,\n",
    "    cmap=\"viridis\",\n",
    "    legend=True,\n",
    "    title=\"Point Map\",\n",
    "    legend_title=\"Vegetation\",\n",
    "    dark_mode=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot images as grid"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dir_image_input = \"path/to/input\"\n",
    "path_output = \"path/to/output.png\"  # output file path\n",
    "image_file_pattern = \"*.png\"  # pattern of the image files to plot\n",
    "dir_csv_input = \"path/to/csv\"  # directory of the CSV files\n",
    "csv_file_pattern = \"pixel_ratios.csv\"  # pattern of the CSV files\n",
    "sort_by = \"random\"  # sort the images by either \"random\" or names of variables in the CSV files (e.g. \"vegetation\")\n",
    "fig, ax = plot_image(\n",
    "    dir_image_input,\n",
    "    4,  # number of rows\n",
    "    5,  # number of columns\n",
    "    dir_csv_input=dir_csv_input,  # directory of the CSV files\n",
    "    csv_file_pattern=csv_file_pattern,  # pattern of the CSV files\n",
    "    sort_by=sort_by,  # sort the images by either \"random\" or names of variables in the CSV files (e.g. \"vegetation\")\n",
    "    title=\"Image Grid\",\n",
    "    path_output=path_output,\n",
    "    dark_mode=False,  # if True, the background is dark\n",
    "    random_seed=123,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot variables as Kernel Density Estimation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "path_input = \"path/to/input.csv\" # input CSV file\n",
    "columns = [\"vegetation\", \"building\", \"sky\"] # list of columns to plot\n",
    "path_output = \"path/to/output.png\"  # output file path\n",
    "kwargs = {\n",
    "    \"clip\": (0, 1),  # clip the values\n",
    "    \"palette\": \"twilight\",  # color palette. This can be any color palette from the seaborn library or matplotlib library or your own color palette\n",
    "}\n",
    "\n",
    "plot_kde(\n",
    "    path_input,\n",
    "    columns,\n",
    "    path_output = path_output,\n",
    "    legend = True,\n",
    "    title = \"KDE Plot\",\n",
    "    legend_title = \"Categories\",\n",
    "    dpi = 300,\n",
    "    font_size = 30,\n",
    "    dark_mode = False,\n",
    "    **kwargs,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot variables as histograms"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "path_input = \"path/to/input.csv\" # input CSV file\n",
    "columns = [\"truck\", \"person\", \"car\"] # list of columns to plot\n",
    "path_output = \"path/to/output.png\"  # output file path\n",
    "kwargs = {\n",
    "    \"clip\": (0, 1),  # clip the values\n",
    "    \"palette\": \"twilight\",  # color palette. This can be any color palette from the seaborn library or matplotlib library or your own color palette\n",
    "}\n",
    "\n",
    "plot_hist(\n",
    "    path_input,\n",
    "    columns,\n",
    "    path_output = path_output,\n",
    "    legend = True,\n",
    "    title = \"Histogram\",\n",
    "    legend_title = \"Count\",\n",
    "    dpi = 300,\n",
    "    font_size = 30,\n",
    "    dark_mode = False,\n",
    "    **kwargs,\n",
    ")"
   ]
  }
 ],
 "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
}