Metadata-Version: 2.4
Name: urbanhue
Version: 0.1.0
Summary: Visualizing the structure of high-dimensional urban features as a continuous perceptual color space
Project-URL: Homepage, https://github.com/wangsir1214/urbanhue
Project-URL: Repository, https://github.com/wangsir1214/urbanhue
Project-URL: Issues, https://github.com/wangsir1214/urbanhue/issues
Author-email: Wang Yuqing <yuqingwang25@stu.pku.edu.cn>
License: MIT
License-File: LICENSE
Keywords: CIELAB,color,dimensionality reduction,geovisualization,street view,urban analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Requires-Dist: colorspacious>=1.1
Requires-Dist: geopandas>=0.10
Requires-Dist: matplotlib>=3.4
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: scikit-learn>=1.0
Requires-Dist: scipy>=1.7
Requires-Dist: shapely>=1.8
Requires-Dist: umap-learn>=0.5
Provides-Extra: all
Requires-Dist: contextily>=1.2; extra == 'all'
Requires-Dist: torch>=1.10; extra == 'all'
Provides-Extra: basemap
Requires-Dist: contextily>=1.2; extra == 'basemap'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: torch>=1.10; extra == 'gpu'
Description-Content-Type: text/markdown

# 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

```bash
pip install urbanhue
```

Optional extras:

```bash
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)

```python
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)

```bash
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:

```python
result.save_colors("canonical_colors.csv")
```

## Examples

The [`examples/`](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](LICENSE).
