citygaze 0.1.0

Street view landmark detection and urban analysis: DeepGaze eye-tracking, OneFormer segmentation, DepthAnything depth estimation, and GHS statistical analysis

CityGaze

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

功能概览

功能	模块	说明
1	streetview	下载 Mapillary 街景或使用用户自己的街景
2	deepgaze	DeepGaze IIE 眼动模拟，提取显著性注视点
3	segment	OneFormer 全景语义分割
4	depth	DepthAnything v3 相对/绝对深度估计
5	locate	绝对深度 + 街景源数据对 landmark 进行地理定位
6	ghs	下载 GHS 数据，与街景进行统计分析

安装

从 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。