Installation¶

The recommended way to install Urbanity is to clone the repository and run the provided setup script, which handles the full environment automatically.

Requirements¶

Git
Miniconda or Anaconda

Step 1 — Clone the repository¶

git clone https://github.com/winstonyym/urbanity.git
cd urbanity

Step 2 — Run the setup script¶

The script detects your OS and GPU, installs all dependencies into a conda environment, and optionally installs a deep learning backend.

chmod +x setup.sh
./setup.sh

What the script does

Installs mamba in your conda base if not present (for faster dependency resolution).
Creates a fresh urbanity conda environment from environment.yml.
Installs GeoPandas via conda-forge, then installs urbanity and all dependencies.
Installs networkit via conda-forge.
Installs optional OSM tools (pyrosm, osmium-tool, geemap, etc.).
Installs the selected deep learning backend (PyG or DGL).

Step 3 — Activate the environment¶

conda activate urbanity

Step 4 — Verify the installation¶

import urbanity
print(urbanity.__version__)

External API Keys (Optional)¶

Some features require free API tokens. Create a .env file in your project root:

touch .env

Add your tokens:

.env

MAPILLARY_API_SECRET=MLY|XXXXXXXXXXXXXXX|XXXXXXXXXXXXXXX
MAPILLARY_API_TOKEN=MLY|XXXXXXXXXXXXXXX|XXXXXXXXXXXXXXX
MAPBOX_API_TOKEN=pk.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Service	Purpose	Sign up
Mapillary	Street view imagery	Free
Mapbox	Satellite imagery tiles	Free tier
Google Earth Engine	Remote sensing layers	Free for researchers

Authenticate Google Earth Engine:

import ee
ee.Authenticate()
ee.Initialize(project="your-project-id")

OS-Specific Notes¶

macOSLinuxWindows

The script works natively. Ensure conda is initialised in your shell:

conda init zsh   # or bash

The script installs gcc via apt-get before setting up the environment. Requires sudo.

Run inside Anaconda Prompt or Git Bash with Anaconda on the PATH. The script expects the Anaconda installation at C:\Users\<you>\anaconda3.