基于百度批量算路 / 腾讯距离矩阵 API ，绘制沿真实路网、可含实时路况的等时圈。
输入一个或多个出发点和一个研究范围，工具自动完成：
- 在范围内生成渔网终点（格心点）；
- 批量调用算路 API（百度批量算路 / 腾讯距离矩阵），获取每个终点到出发点的真实通行时间与距离；
- 反距离权重（IDW）插值为连续时间表面；
- 提取等时带（如 5/10/15/30 分钟），输出栅格、矢量与自包含交互式 HTML 地图。
与"以出发点画直线距离圆"的本质区别：所有时间沿真实路网计算，驾车模式可选实时路况策略。
- 范围界定：缓冲区（buffer）/ 行政区划（admin，DataV.GeoAtlas 边界）/ 矩形框（bbox）/ 矢量文件（file，shp·GeoJSON·KML·GeoPackage）四种来源。
- 多出发点：一次运行计算多个出发点的等时圈并分组出图；支持
merge_isochrones: true将各出发点时间栅格逐像元取最小值合并，输出一张合并等时圈 + 一张时间栅格。 - 地名解析随引擎：地名型出发点按引擎走不同平台——百度 Geocoding（BD-09→WGS84）、腾讯 geocoder/place（GCJ-02→WGS84）；纯 POI 名称自动地点检索兜底，命中详情打印在日志供核对。
- 多 key 容错轮换：百度 AK 与腾讯 key 均支持多 key 列表，配额耗尽或 key 级错误自动切换，各 key 用量留痕脱敏。
- 断点续跑：配额耗尽/中断自动保现场，
--resume续跑零浪费。 - 等时带可选开放带：
keep_over_threshold决定超过最大阈值的区域是显示 ">30" 开放带还是留空。 - 可调图层透明度：等时圈 / 时间栅格 / 渔网格心三图层透明度可配（默认不透明）。
- 全产物可视化：范围、出发点、渔网（按分钟着色）、不可达点、时间表面、等时带全部落入一张交互地图（leafmap + 天地图底图），图例随图层勾选联动。
- 纯开源栈：geopandas / shapely / rasterio / scipy。
推荐 conda（geopandas/rasterio 依赖最稳）：
conda env create -f environment.yml
conda activate baidu-isochrone或 pip（Python ≥ 3.10，先建虚拟环境）：
pip install -r requirements.txt
pip install -e . # 注册 isochrone 命令| 密钥 | 用途 | 申请入口 |
|---|---|---|
| 百度 AK | 批量算路 / 地理编码（engine=baidu） | 百度地图开放平台控制台 → 应用管理 → 创建应用（服务端类型），确认"批量算路"服务已开通 |
| 腾讯 key | 距离矩阵 / 地名解析（engine=tencent） | 腾讯位置服务控制台 → 应用管理 → 创建应用/Key，确认"WebService API"已启用 |
| 天地图 tk | 底图（可选，缺省退 CartoDB） | 天地图开放平台 → 创建应用 |
| CartoDB key | CartoDB 底图（可选，无 key 瓦片带 "API key required" 水印） | CARTO Basemaps → 邮箱免费申请，免费 5M 次/月 |
cp configs/keys.txt.example configs/keys.txt # 填入 baidu_ak、tencent_key、tianditu_tk 与 carto密钥统一存 configs/keys.txt。配置文件用 keys_file 字段指定其位置（相对路径相对配置文件所在目录解析，缺省为同目录的 keys.txt，即 configs/keys.txt）。
cp configs/example.yaml configs/config.yaml # 复制为默认配置文件
cp configs/keys.txt.example configs/keys.txt # 复制并填入平台密钥强烈建议第一轮用 2km 缓冲小样验证链路（约几十次请求），确认无误后再放大范围：
origins:
- [120.20979, 30.252714] # 出发点 [经度, 纬度]，或 {address: "地名"}
study_area:
type: buffer
radius_km: 2 # 小样先行；确认后改大或换 admin/file/bboxisochrone estimate
# 默认读取 configs/config.yaml；显式指定用 -c 其他配置.yaml
# 输出：终点数 / 请求次数 / 预计耗时 / 占日配额比例，超配额时给出调参建议isochrone run进度条按"点对"显示。中断（Ctrl+C、断网、配额耗尽）都不怕——已完成的点对已落盘。
isochrone run --resume runs/<文件夹名>打开 run 目录下的 map.html。想换底图或调样式后重出图（零 API 消耗）：
isochrone render runs/20260914_101530_driving_baidu # 天地图矢量（默认）
isochrone render runs/20260914_101530_driving_baidu --basemap tianditu-img # 天地图影像
isochrone render runs/20260914_101530_driving_baidu --basemap cartodb # CartoDB 浅色配置了 tianditu_tk 时，地图图层控制中始终同时提供天地图矢量 / 天地图影像 / CartoDB 三种底图与对应注记层，--basemap 只决定默认显示哪一个。
| 命令 | 说明 |
|---|---|
isochrone run [-c configs/config.yaml] [--dry-run] [--resume RUN_DIR] |
执行完整流水线；-c 缺省读 configs/config.yaml，--dry-run 只估算不请求，--resume 断点续跑 |
isochrone estimate [-c configs/config.yaml] |
仅估算请求次数与配额占用（-c 缺省读 configs/config.yaml） |
isochrone geocode "上海站" |
地名 → WGS84 坐标（走百度 Geocoding） |
isochrone render RUN_DIR [--basemap tianditu|tianditu-img|cartodb] |
从 run 目录零 API 重建交互地图 |
所有参数集中于一份 YAML（逐项注释见 configs/example.yaml，复制为 configs/config.yaml 使用）。
| 键 | 说明 |
|---|---|
origins |
出发点列表，元素为 [lon, lat] 或 {address: "地名"}；支持多个 |
origin_coord_type |
坐标型出发点的输入坐标系：wgs84 / gcj02 / bd09ll |
study_area |
研究范围，见下 |
engine |
算路引擎：baidu（默认）/ tencent（腾讯距离矩阵） |
keys_file |
密钥文件路径（key=value 格式，含百度 AK / 腾讯 key / 天地图 tk）；相对路径相对配置文件目录解析，缺省同目录 keys.txt（configs/keys.txt） |
baidu_aks |
百度 AK 列表（可选，不写回退 keys.txt）；单值可用 baidu_ak |
tencent_keys |
腾讯 key 列表（可选，不写回退 keys.txt）；单值可用 tencent_key |
trans_type |
出行方式；百度：driving / walking / riding，腾讯：driving / walking / bicycling / ebicycling（riding 为 bicycling 兼容别名） |
tactics |
驾车策略：10 不走高速 / 11 常规 / 12 短距含路况 / 13 短距无路况 |
qps |
每秒请求数（个人开发者建议 3–5，付费可提至 50） |
concurrency |
同时在途的批量请求数 |
max_retries |
单批失败重试次数（指数退避） |
merge_isochrones |
true 时各出发点时间栅格逐像元取最小值合并，只输出一张合并等时圈 + 一张时间栅格 |
keep_over_threshold |
true（默认）保留 ">最大阈值" 开放带；false 时超过最大阈值的区域为空 |
thresholds |
等时带阈值（分钟，升序），如 [5, 10, 15, 30] |
| type | 必填 | 可选 | 说明 |
|---|---|---|---|
buffer |
radius_km |
center: [lon, lat] |
圆形缓冲，center 缺省取首个出发点 |
admin |
adcode |
name |
按 6 位行政区划代码拉取 DataV.GeoAtlas 边界（自动 GCJ-02→WGS84） |
file |
path |
layer |
本地矢量文件；layer 用于 GPKG 等多图层文件 |
bbox |
bounds |
— | 矩形框 [xmin, ymin, xmax, ymax]（WGS84） |
| 段 | 键 | 说明 |
|---|---|---|
grid |
cell_size |
渔网间距（米） |
offset |
渔网范围外扩（米） | |
adaptive_beyond_km |
距出发点超过该公里数后放疏（可选） | |
adaptive_multiplier |
放疏倍数 | |
interpolate |
cell_size / power / k / expand |
栅格分辨率（米）/ IDW 幂 / 最近邻点数 / 插值范围外扩（米） |
outputs |
dir / formats / raster / html |
输出目录 / 矢量格式（gpkg·geojson·shp）/ 是否出 GeoTIFF / 是否出 HTML |
viz |
basemap |
tianditu（需 tianditu_tk）或 osm（退 CartoDB） |
isochrone_opacity / raster_opacity / fishnet_opacity |
三图层透明度，1.0=不透明（默认） |
Baidu_Isochrone/
├── configs/ # 配置与密钥模板（example.yaml→config.yaml、keys.txt.example→keys.txt）
├── src/baidu_isochrone/ # 核心包
│ ├── study_area/ # 范围界定（admin/buffer/bbox/file 及手绘 draw）
│ ├── api/ # 批量算路客户端（百度/腾讯）、地理编码（百度/腾讯）、配额管理、多 key 池（keys.py）
│ ├── grid.py # 渔网生成（支持自适应密度）
│ ├── coords.py # 坐标系转换（WGS84/GCJ-02/BD-09）
│ ├── cache.py # 结果缓存与断点续跑
│ ├── interpolate.py # IDW 插值 + 等时带提取（含多出发点栅格合并）
│ ├── viz.py # leafmap 全产物交互可视化
│ ├── export.py # GeoTIFF / GeoJSON / GPKG / shp 导出
│ ├── metadata.py # 运行元数据留痕
│ ├── config.py # 配置加载与校验
│ └── cli.py # 命令行入口（run / estimate / geocode / render）
└── tests/ # 117 项测试
runs/20260914_101530_driving_baidu/
├── config.yaml # 配置快照（可复现；baidu_aks 已脱敏）
├── results.csv # 点对结果（origin_id, oid, duration_min, distance_km）
├── outputs/
│ ├── study_area.* # 研究范围
│ ├── origins.* # 出发点
│ ├── fishnet_points.* # 渔网格心（多出发点含 time_o0/time_o1 分钟数列）
│ ├── isochrone.* # 等时带面（核心成果，lo/hi/label 属性；多出发点为 isochrone_o0.* 等）
│ ├── unreachable.* # 不可达点（灰色，排查路网孤岛用）
│ ├── idw_raster.tif # 时间表面栅格（多出发点非合并为 idw_raster_o0.tif 等）
│ └── _viz_idw.png # 时间栅格可视化叠加图（地图"时间栅格"图层；多出发点非合并为 _viz_idw_o0.png 等）
├── map.html # 自包含交互地图（浏览器直接打开）
└── metadata.json # 请求时刻、策略、统计、各 AK 用量（实时路况结果的可复现性靠它）
| 现象 | 原因与处理 |
|---|---|
日志出现 401 并发超限 |
QPS 设高了：调低配置 qps（个人开发者建议 3–5），工具会自动退避重试 |
日志出现 302 天配额超限 |
配置了多 AK 时会自动轮换；日志出现 所有 N 个百度 AK 均不可用 才是全部耗尽——运行自动暂停并保现场，补充新 AK 或次日 --resume 续跑 |
腾讯引擎日志出现 status=1023 配额/并发超限 |
腾讯配额或并发耗尽：配置了多 key 会自动轮换，全部耗尽才停跑；若为并发超限，调低 qps 或确认批量为一对多 1×5 |
腾讯引擎地名解析报 status=348 参数错误 |
腾讯 geocoder 要求地址至少含城市名；纯 POI 名称会自动转地点搜索兜底，兜底无果时改用含城市名的完整地址，或加 region 限定城市 |
| 地图上灰点（不可达）成堆 | 该区域路网孤岛（岛屿、封闭园区）或终点落在无路网处；少量灰点正常，成堆需检查范围 |
| 地名型出发点解析到城市中心/错误位置 | POI 名称（如"上海新国际博览中心"）会退化到城市级坐标，工具已内置地点检索兜底；若仍报"地点检索无结果"，请改用完整地址或 [lon, lat] 坐标，并确认 AK 已开通"地点检索"服务 |
| 两次运行结果对不上 | 除 tactics=13 外结果含实时路况，核对 metadata.json 的请求时刻 |
KeyError / 模块导入错误 |
依赖未装全：pip install -r requirements.txt，或确认 conda 环境已激活 |
isochrone 不是内部或外部命令 |
未安装包本体：在激活的环境中执行 pip install . |
| map.html 瓦片 403 / 无底图 | 配置 tianditu_tk 用天地图（默认），或用 render --basemap cartodb 换 CartoDB 底图重出图 |
| notebook 改了代码不生效 | 模块已被旧 kernel 缓存：重启 kernel 或用 %load_ext autoreload + %autoreload 2 |
- 百度地图开放平台·批量算路 API
- 腾讯位置服务·距离矩阵 / 地理编码
- 天地图开放平台
- leafmap · geopandas · shapely · rasterio · scipy
- 行政区划边界数据：DataV.GeoAtlas