Overview

streetscapes is a package to extract metadata, download, segment and analyse street view images from various open sources, such as Mapillary, Kartaview and Amsterdam Open Panorama. The package also builds upon the Global Streetscapes, making it possible to use the dataset for analysis and download images with certain properties.

This package is a subproject of (Urban-M4), which aims to model the Urban Heat Island effect by evaluating the properties of individual objects in the images (such as buildings, roads and sidewalks).

For more information, please refer to the documentation.

📥 Setup

Create and activate a virtual environment using the tool of your choice, such as venv. You can also use Conda (or Mamba) if you prefer, but please note that all dependencies are installed by pip from PyPI.

Using venv:

sh python -m venv .venv source .venv/bin/activate

Using conda:

sh conda create -n myenv -c conda-forge python=3.12 pip conda activate myenv

⚙️ Installation

The streetscapes package can be installed from PyPI:

shell pip install streetscapes

Alternatively, the in-development version of streetscapes can be installed by cloning the repository and installing the package locally with pip:

shell git clone git@github.com:Urban-M4/streetscapes.git cd streetscapes pip install -e .

⚠️ If one or more dependencies fail to install, check the Python version - it might be too new. While streetscapes itself specifies only the minimal required Python verion, some dependencies might be slow to make releases for the latest Python version.

Configuring the package for development

To install with optional dependencies:

shell git clone git@github.com:Urban-M4/streetscapes.git cd streetscapes pip install -e .[dev]

Building and running the documentation

The streetscapes project documentation is based on MkDocs. To build and view the documentation:

shell mkdocs build

The documentation can then be viewed locally:

shell mkdocs serve

This will start an HTTP server which can be accessed by visiting http://127.0.0.1:8000 in a browser.

🌲 Environment variables

To facilitate the use of streetscapes when dowloading images, access tokens can be added to an .env file in the root directory of the streetscapes repository. You can get and access token for Mapillary here.

| Variable | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | MAPILLARY_TOKEN | A Mapillary token string used for authentication when querying Mapillary via their API. |

Contributing and publishing

If you want to contribute to the development of streetscapes, have a look at the contribution guidelines.

🪪 Licence

streetscapes is licensed under CC-BY-SA-4.0.

🎓 Acknowledgements and citation

This repository uses the data and work from the Global Streetscapes project.

[1] Hou Y, Quintana M, Khomiakov M, Yap W, Ouyang J, Ito K, Wang Z, Zhao T, Biljecki F (2024): Global Streetscapes — A comprehensive dataset of 10 million street-level images across 688 cities for urban science and analytics. ISPRS Journal of Photogrammetry and Remote Sensing 215: 216-238. doi:10.1016/j.isprsjprs.2024.06.023

The streetscapes package can be cited using the supplied citation information. For reproducibility, you can also cite a specific version by finding the corresponding DOI on Zenodo.