urbanhue 0.1.0

Visualizing the structure of high-dimensional urban features as a continuous perceptual color space

UrbanHue

Visualizing the structure of high-dimensional urban features as a continuous perceptual color field.

UrbanHue turns any high-dimensional description of urban places — street-view visual embeddings, POI text vectors, spatial-interaction representations, census features — into a continuous, perceptually uniform color field on a map. The color difference between two places reflects how similar their underlying features are: similar places get similar colors, dissimilar places get contrasting colors. Unlike discrete clustering, which can only express category membership, a continuous perceptual color field makes the degree of similarity directly visible in geographic space.

The method projects the N × D feature matrix to a 3D manifold (UMAP by default), then fits that manifold into the displayable CIELAB gamut by a seven-parameter rigid transformation with uniform scaling, following the U-CIE framework (Koutrouli et al., 2022). Geographic coordinates are used only to position points on the map — never to determine color.

Installation

pip install urbanhue

Optional extras:

pip install "urbanhue[basemap]"   # contextily, for OSM/Positron basemaps
pip install "urbanhue[gpu]"       # torch, for GPU-accelerated UMAP
pip install "urbanhue[all]"       # both

Requires Python ≥ 3.9.

Quickstart (Python API)

from urbanhue import UrbanHue

uh = UrbanHue(dr_method="umap", n_init=25, seed=42)
result = uh.fit_transform(features, coordinates)   # features: (N, D), coordinates: (N, 2)

result.plot_map(basemap=True, output="colorfield.png")
result.to_geodataframe().to_file("colors.gpkg")
print("clip_ratio:", result.clip_ratio)            # gamut-fit diagnostic (rho)

Quickstart (command line)

urbanhue points.parquet --feat_prefix emb_ --dr_method umap --n_init 25 --out_dir results/

Writes a per-point color CSV, a GeoPackage, a map preview, and a JSON record of all run parameters.

Reproducibility

The optimization landscape has multiple near-optimal minima related by rigid rotations, so absolute color assignment can vary across runs and hardware while preserving the internal similarity structure. To reproduce a specific figure exactly, archive the per-point color output:

result.save_colors("canonical_colors.csv")

Examples

The examples/ directory contains three runnable minimal scripts:

Script	Modality
example_visual_embeddings.py	street-view visual embeddings
example_spatial_interaction.py	spatial-interaction representations per tract
example_multimodal.py	combining visual + POI features

Interoperability

• ZenSVI embedding CSVs can be used directly as input.
• Exported GeoDataFrames work with QGIS, GeoPandas, and Folium.
• Color fields overlay onto OSMnx street networks and OpenStreetMap basemaps.

Citation

If you use UrbanHue, please cite the paper (see CITATION.cff).

License

MIT — see LICENSE.