================================================================
  SV_collect — 百度街景批量采集工具  使用说明
================================================================

【软件简介】
  本工具用于批量采集百度地图街景图像。
  通过读取坐标 CSV 文件中的点位信息，自动调用百度地图 API
  下载对应位置的街景图片，支持多年份、多方向采集。

----------------------------------------------------------------
【快速启动】
----------------------------------------------------------------

  1. 双击 "启动.bat"
     - 首次运行会自动安装所需依赖包（需要联网）
     - 安装完成后浏览器自动打开 http://127.0.0.1:5731
     - 关闭命令行窗口即可停止程序

  注意：需要提前安装 Python 3.8 或以上版本
  下载地址：https://www.python.org/downloads/
  安装时勾选 "Add Python to PATH"

----------------------------------------------------------------
【准备工作：获取百度地图 API Key】
----------------------------------------------------------------

  1. 访问 https://lbsyun.baidu.com/ 注册账号
  2. 进入"控制台" → "创建应用"
  3. 应用类型选择"服务端"，勾选以下两项服务：
     - 坐标转换（geoconv）
     - 全景静态图（panorama）
  4. 创建后复制 AK（即 API Key）

  ⚠️  配额说明（重要）：
  每个百度账号每天的免费配额为：
    - 坐标转换：5000 次/天
    - 全景静态图：5000 次/天

  每个采样点消耗 1 次坐标转换配额。
  每张图片消耗 1 次静态图配额（4 方向 × N 年份）。

  如果你的采样点超过 5000 个，解决方案：
  ┌─────────────────────────────────────────────────────────┐
  │  方案一（推荐）：注册多个百度账号，每个账号创建一个 AK  │
  │  在软件"API Key 管理"中添加多个 Key，程序会自动轮换    │
  │  例如：5 个 Key = 每天可处理约 25000 个点位            │
  │                                                         │
  │  方案二：分批运行                                       │
  │  将 CSV 文件拆分为多个（每个 < 5000 行），              │
  │  每天运行一批，程序支持断点续传，不会重复下载           │
  └─────────────────────────────────────────────────────────┘

  当某个 Key 配额耗尽时，程序会自动切换到下一个 Key，
  并在日志中显示警告。所有 Key 都耗尽后任务自动停止，
  已下载的图片不会丢失，第二天配额刷新后可继续运行。

----------------------------------------------------------------
【坐标文件格式（CSV）】
----------------------------------------------------------------

  点击界面中的"下载模板"按钮获取示例文件，
  用 Excel 或记事本编辑后保存为 .csv 格式。

  必须包含以下列（第一行为列名）：

    pointID   — 点位唯一编号（整数或字符串）
    lng       — 经度（WGS84 坐标系，小数格式）
    lat       — 纬度（WGS84 坐标系，小数格式）
    direction — 道路朝向角（0-360 度，正东为 0，逆时针为正）

  示例：
    pointID,lng,lat,direction
    1001,116.3974,39.9093,45.0
    1002,116.4012,39.9105,90.0
    1003,116.4055,39.9118,135.0

  如果没有道路朝向数据，direction 列填 0 即可（前视图朝正东）。
  如需精确朝向，可使用"道路方向计算"功能从线要素 Shapefile 生成。

----------------------------------------------------------------
【功能说明】
----------------------------------------------------------------

  ▌ 街景下载
  ─────────
  · 坐标 CSV：选择准备好的坐标文件
  · 输出文件夹：图片保存位置（不存在会自动创建）
  · API Key：添加一个或多个百度地图 API Key
  · 采集参数：
      焦距 fovy    — 视野角度，建议 85（值越小视野越窄）
      图像质量     — 建议 100（最高质量）
      俯仰角 pitch — 0 为水平视角，负值向下，正值向上
      宽度/高度    — 图片像素尺寸，最大 1024×1024
  · 年份选项：
      所有年份 — 下载该点位所有历史街景
      最新年份 — 只下载最近一期街景
      指定年份 — 输入年份如 2015,2018,2020
  · 采集方向：前视(F)、左视(L)、后视(B)、右视(R)

  输出文件命名规则：{年份}_{点位ID}_{方向}.jpg
  例如：2019_1001_F.jpg

  断点续传：已存在的图片文件会自动跳过，
  中途停止后重新运行不会重复下载。

  ▌ 道路方向计算
  ─────────────
  上传线要素 Shapefile（.shp/.shx/.dbf，.prj 可选），
  程序计算每条线段的起终点方向角，添加 DIREC 字段后
  打包为 zip 文件下载。可将结果中的 DIREC 列复制到坐标 CSV。

  ▌ 获取情况统计
  ─────────────
  输入坐标 CSV 和图片文件夹路径，生成覆盖情况统计表：
  行为点位 ID，列为年份，值为该点位该年份已下载的图片数量。
  结果以 CSV 格式下载，可用 Excel 打开查看。

  ▌ 图像预览
  ─────────
  输入图片文件夹路径，点击"加载"浏览已下载的街景图片。
  点击缩略图可放大查看。

----------------------------------------------------------------
【常见问题】
----------------------------------------------------------------

  Q：点击"选择"按钮没有弹出文件选择框？
  A：需要 Python 安装了 tkinter（标准安装默认包含）。
     也可以直接在输入框中粘贴完整路径。

  Q：日志显示"坐标转换失败"？
  A：检查 API Key 是否正确，以及是否开通了"坐标转换"服务。

  Q：日志显示"无街景数据"？
  A：该点位百度地图没有街景覆盖，属于正常情况。

  Q：下载速度很慢？
  A：程序默认 4 线程并发，每次请求间隔 0.5 秒以避免触发限流。
     不建议调高并发，否则容易被封 IP。

  Q：所有 Key 耗尽后如何继续？
  A：等待次日配额刷新（北京时间 0 点重置），
     或添加新的 API Key，直接点击"开始采集"即可续传。

  Q：图片下载后如何使用？
  A：图片为标准 JPEG 格式，可直接用于深度学习、
     城市环境分析、绿视率计算等研究场景。

----------------------------------------------------------------
【目录结构】
----------------------------------------------------------------

  web_app/
  ├── 启动.bat          ← 双击启动
  ├── app.py            ← 程序主文件
  ├── config.json       ← 自动保存的配置（API Key 等）
  ├── core/             ← 核心功能模块
  └── templates/        ← 界面文件

----------------------------------------------------------------
  版本：1.0  |  运行环境：Python 3.8+  |  界面访问：http://127.0.0.1:5731
================================================================
