This package is a one-stop solution for downloading, cleaning, analyzing street view imagery. Detailed documentation can be found here.
$ pip install zensvi
Since zensvi
uses pytorch
and torchvision
, you may need to install them separately. Please refer to the official website for installation instructions.
Mapillary
For downloading images from Mapillary, utilize the MLYDownloader. Ensure you have a Mapillary client ID:
from zensvi.download import MLYDownloader
mly_api_key = "YOUR_OWN_MLY_API_KEY" # Please register your own Mapillary API key
downloader = MLYDownloader(mly_api_key=mly_api_key)
# with lat and lon:
downloader.download_svi("path/to/output_directory", lat=1.290270, lon=103.851959)
# with a csv file with lat and lon:
downloader.download_svi("path/to/output_directory", input_csv_file="path/to/csv_file.csv")
# with a shapefile:
downloader.download_svi("path/to/output_directory", input_shp_file="path/to/shapefile.shp")
# with a place name that works on OpenStreetMap:
downloader.download_svi("path/to/output_directory", input_place_name="Singapore")
To perform image segmentation, use the Segmenter
:
from zensvi.cv import Segmenter
segmenter = Segmenter(dataset="cityscapes", # or "mapillary"
task="semantic" # or "panoptic"
)
segmenter.segment("path/to/input_directory",
dir_image_output = "path/to/image_output_directory",
dir_summary_output = "path/to/segmentation_summary_output"
)
To perform scene classification, use the ClassifierPlaces365
:
# initialize the classifier
classifier = ClassifierPlaces365(
device="cpu", # device to use (either "cpu" or "gpu")
)
# set arguments
classifier = ClassifierPlaces365()
classifier.classify(
"path/to/input_directory",
dir_image_output="path/to/image_output_directory",
dir_summary_output="path/to/classification_summary_output"
)
To extract low-level features, use the get_low_level_features
:
from zensvi.cv import get_low_level_features
get_low_level_features(
"path/to/input_directory",
dir_image_output="path/to/image_output_directory",
dir_summary_output="path/to/low_level_feature_summary_output"
)
Transform images from panoramic to perspective or fisheye views using the ImageTransformer
:
from zensvi.transform import ImageTransformer
dir_input = "path/to/input"
dir_output = "path/to/output"
image_transformer = ImageTransformer(
dir_input="path/to/input",
dir_output="path/to/output"
)
image_transformer.transform_images(
style_list="perspective equidistant_fisheye orthographic_fisheye stereographic_fisheye equisolid_fisheye", # list of projection styles in the form of a string separated by a space
FOV=90, # field of view
theta=120, # angle of view (horizontal)
phi=0, # angle of view (vertical)
aspects=(9, 16), # aspect ratio
show_size=100, # size of the image to show (i.e. scale factor)
)
To visualize the results, use the plot_map
and plot_image
functions:
from zensvi.visualization import plot_map, plot_image
# Plotting a map
plot_map(
"path/to/pid_file.csv", # path to the file containing latitudes and longitudes
variable_name="vegetation",
plot_type="point" # this can be either "point", "line", or "hexagon"
)
# Plotting images in a grid
plot_image(
"path/to/image_directory",
4, # number of rows
5 # number of columns
)
Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
zensvi
was created by Koichi Ito. It is licensed under the terms of the CC BY-SA 4.0.
Please cite the following paper if you use zensvi
in a scientific publication:
(place holder for the paper citation)
@article{ito2024zensvi,
title={ZenSVI: One-Stop Python Package for Integrated Analysis of Street View Imagery},
author={Ito, Koichi, XXX, XXX, XXX, ...},
journal={XXX},
volume={XXX},
pages={XXX},
year={2024}
}
zensvi
was created with cookiecutter
and the py-pkgs-cookiecutter
template.