Metadata-Version: 2.4
Name: citygaze
Version: 0.1.0
Summary: Street view landmark detection and urban analysis: DeepGaze eye-tracking, OneFormer segmentation, DepthAnything depth estimation, and GHS statistical analysis
Author: CityGaze Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/citygaze
Project-URL: Documentation, https://github.com/your-org/citygaze#readme
Project-URL: Repository, https://github.com/your-org/citygaze
Keywords: street-view,landmark-detection,eye-tracking,deepgaze,segmentation,depth-estimation,urban-analysis,GHS
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: geopandas>=0.10.0
Requires-Dist: requests>=2.26.0
Requires-Dist: tqdm>=4.62.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: rasterio>=1.2.0
Requires-Dist: pyproj>=3.0.0
Requires-Dist: shapely>=2.0.0
Requires-Dist: osmnx>=1.2.0
Requires-Dist: mapillary>=1.0.0
Requires-Dist: torch>=1.10.0
Requires-Dist: torchvision>=0.11.0
Requires-Dist: py360convert>=0.1.0
Requires-Dist: h3>=3.7.0
Provides-Extra: deepgaze
Requires-Dist: einops; extra == "deepgaze"
Requires-Dist: ftfy; extra == "deepgaze"
Requires-Dist: regex; extra == "deepgaze"
Provides-Extra: full
Requires-Dist: detectron2; extra == "full"
Requires-Dist: fvcore; extra == "full"
Requires-Dist: iopath; extra == "full"
Provides-Extra: depth
Requires-Dist: depth-anything-v3; extra == "depth"
Dynamic: license-file

# 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 安装（仅需基础功能）

```bash
pip install citygaze
```

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

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

### Conda 环境（推荐）

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

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

```bash
# 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. 下载街景

```python
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 眼动模拟

```python
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. 深度估计

```python
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. 语义标注与地标定位

```python
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 统计分析

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

## 命令行使用

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

## 使用自定义街景

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

```python
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. **构建并上传**：

```bash
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](LICENSE)。
