CityGaze

Street view landmark detection and urban analysis toolkit.
街景地标检测与城市分析工具包。发布到 PyPI 后，任何人都可通过 pip install citygaze 安装，与 numpy 一样。

功能概览

安装

从 PyPI 安装（仅需基础功能）

pip install citygaze

从源码安装（开发或使用 Conda）

# 克隆后安装
git clone https://github.com/your-org/citygaze && cd citygaze
pip install -e .

Conda 环境（推荐）

# 从源码目录执行
conda env create -f environment.yml
conda activate citygaze
pip install -e .

完整功能依赖（按需安装）

# DeepGaze 眼动模拟（一次性装齐依赖：DeepGaze + CLIP + einops 等）
pip install -r requirements-deepgaze.txt

# 下载 centerbias 文件
# https://github.com/matthias-k/DeepGaze/releases/download/v1.0.0/centerbias_mit1003.npy

# Depth Anything v3 深度估计
pip install git+https://github.com/ByteDance-Seed/Depth-Anything-3.git
pip install py360convert

# OneFormer 分割（需单独克隆并安装）
git clone https://github.com/SHI-Labs/OneFormer
cd OneFormer && pip install -e .

快速开始

1. 下载街景

from citygaze import download_road_network, fetch_mapillary_metadata, download_images_fast

place = "Boston, Massachusetts, USA"
data_root = "./data"

# 下载路网
download_road_network(place, data_root)

# 获取元数据（需 Mapillary Token）
df = fetch_mapillary_metadata(edges, token="YOUR_TOKEN", place=place, data_root=data_root)

# 下载图片
download_images_fast(df, token="YOUR_TOKEN", place=place, data_root=data_root)

2. DeepGaze 眼动模拟

from citygaze import run_deepgaze_pipeline

run_deepgaze_pipeline(
    images_dir="./data/Boston_Massachusetts_USA/images",
    output_dir="./output/deepgaze",
    centerbias_path="./centerbias_mit1003.npy",
    gpu_ids="0,1",
)

3. 深度估计

from citygaze import run_depth_pipeline

run_depth_pipeline(
    input_csv_path="./output/deepgaze/deepgaze_raw/deepgaze_raw_results.csv",
    image_root="./data/Boston_Massachusetts_USA/images",
    output_csv_path="./output/deepgaze_with_depth.csv",
)

4. 语义标注与地标定位

from citygaze import label_gaze_with_segment, merge_filter_and_locate

# 将眼动点与分割结果结合（需先运行 OneFormer 分割）
label_gaze_with_segment(
    gaze_csv_path="./output/deepgaze_raw_results.csv",
    segment_output_root="./output/segment",
    output_csv_path="./output/deepgaze_segment.csv",
)

# 地标地理定位
merge_filter_and_locate(
    segment_csv_path="./output/deepgaze_segment.csv",
    depth_csv_path="./output/deepgaze_with_depth.csv",
    meta_csv_path="./data/mapillary_Boston_Massachusetts_USA_images_meta.csv",
    image_dir="./data/Boston_Massachusetts_USA/images",
    output_csv_path="./output/landmark_geo_located.csv",
)

5. GHS 统计分析

from citygaze import download_ghs_data, run_ghs_analysis

# 下载 GHS 数据（可选，也可手动下载）
download_ghs_data(output_dir="./data/GHS_time", years=(1975, 2000, 2025))

# 运行分析
run_ghs_analysis(
    landmark_csv_path="./output/landmark_clustered.csv",
    output_dir="./output/GHS_analysis",
    edges_path="./data/edges.gpkg",
    all_pano_meta_path="./data/mapillary_meta.csv",
    ghs_root="./data/GHS_time",
)

命令行使用

# 1. 街景下载（或使用自定义街景）
citygaze-streetview --place "Singapore" --data-root ./data --token YOUR_TOKEN \
  --download-network --fetch-metadata --download-images

# 2. DeepGaze 眼动模拟
citygaze-deepgaze --images-dir ./images --output-dir ./out --centerbias ./centerbias.npy

# 3. OneFormer 分割
citygaze-segment --input ./images --output ./segment_out

# 4. 眼动点语义标注
citygaze-label --gaze-csv ./deepgaze_raw_results.csv --segment-root ./segment_out \
  --output-csv ./deepgaze_segment.csv

# 5. DepthAnything 深度估计
citygaze-depth --input-csv ./deepgaze.csv --image-root ./images --output-csv ./depth.csv

# 6. 地标地理定位
citygaze-locate --segment-csv ./deepgaze_segment.csv --depth-csv ./depth.csv --meta-csv ./meta.csv \
  --image-dir ./images --output-csv ./located.csv

# 7. 地标空间聚类
citygaze-cluster --input-csv ./located.csv --output-csv ./landmark_clustered.csv --min-votes 3

# 8. GHS 统计分析
citygaze-ghs --landmark-csv ./landmark_clustered.csv --output-dir ./ghs_out --ghs-root ./GHS_time

使用自定义街景

若您已有街景图片和元数据：

from citygaze import use_custom_streetview

place_dir, meta_df = use_custom_streetview(
    images_dir="/path/to/your/images",
    meta_csv_path="/path/to/meta.csv",  # 需含 image_id, lon, lat, compass_angle
    place_name="my_city",
    data_root="./data",
)
# 后续流程使用 place_dir 和 meta_df

维护者：发布到 PyPI（供大家 pip 安装）

发布后，用户可直接 pip install citygaze，无需克隆仓库。

1. 注册 PyPI 账号：https://pypi.org/account/register/
2. 创建 API Token：PyPI → Account settings → API tokens → Add API token（范围选整个账号或仅此项目）。
3. 构建并上传：

pip install build twine
python -m build
twine upload dist/*

按提示输入用户名 __token__、密码为你的 API token。
首次发布后，更新版本时只需在 pyproject.toml 和 citygaze/__init__.py 里改 version，再执行上述 build 与 twine upload 即可。

数据流程

街景下载/自定义 → DeepGaze 眼动 → OneFormer 分割 → 语义标注
                                    ↓
              DepthAnything 深度 ← 合并
                                    ↓
              地标定位 (经纬度) → 聚类 → GHS 统计分析

许可证

MIT，详见 LICENSE。