地图工作台（Leaflet × Qt × Dock）

1. 模块定位

地图页由 tab_map.py 提供。当前版本的地图模块不只是浏览器壳，而是整个系统的空间操作中枢，承担三类职责：

  • 空间结果展示
  • 空间数据加载与回显
  • 空间工具与采样流程的入口

2. 核心类

2.1 Map(QMainWindow)

主类 Map 继承 QMainWindow，原因是需要原生支持多个 Dock：

  • WhiteboxToolsDock
  • DataLoaderDock
  • SegSamplingDock

这意味着地图模块采用的是“中心地图视图 + 右侧工具栈”的组织模式。

2.2 TileRequestInterceptor

TileRequestInterceptor 用于拦截地图底图请求，并附加用户代理：

  USDA-GeoProdStudio/<version> (QtWebEngine map client)

它的主要作用是保证公共瓦片服务能识别请求来源，减少匿名客户端被拒绝的风险。

3. 技术架构

3.1 Web 地图内核

地图渲染采用：

  • Qt WebEngine
  • 本地 HTML
  • JavaScript 地图库
  • QWebChannel

对应链路可写成：

$$ \text{Qt Widget} \leftrightarrow \text{QWebEngineView} \leftrightarrow \text{HTML/JS Map} \leftrightarrow \text{QWebChannel} \leftrightarrow \text{Python Bridge} $$

3.2 双向通信

JSBridge 负责前端和 Python 之间的双向消息交换，典型用途包括：

  • 地图点击、对象选取等事件回传。
  • Python 侧控制图层加载、样式和地图状态。
  • 分割采样模块与地图联动。

4. Dock 模块说明

4.1 WhiteboxToolsDock

用于调用 WhiteboxTools 地学工具。适合：

  • 地形分析
  • 水文分析
  • 距离与成本分析
  • 滤波、分割、形态学与地表处理

4.2 DataLoaderDock

用于将外部文件快速加载到地图。适合：

  • GeoTIFF
  • Shapefile / GeoJSON
  • CSV 坐标数据
  • 中间结果回显

4.3 SegSamplingDock

用于图像分割、样本区划、采样与标注，是地图页和样本生产之间的关键桥梁。

5. 工作流

常见地图页工作流如下：

  1. 打开地图页。
  2. 使用 DataLoader 加载底图数据或结果图层。
  3. 需要空间处理时打开 WhiteboxToolsDock。
  4. 需要样本划分时打开 SegSamplingDock。
  5. 将结果重新加载回地图进行核查。

6. 关键实现细节

6.1 本地 HTML 加载

_load_html() 会读取本地地图 HTML，并自动补充 qwebchannel.js 引用，以保证桥接通信可用。

6.2 WebEngine 配置

_configure_webengine() 负责：

  • 允许本地内容访问远程 URL
  • 开启 LocalStorage
  • 开启 JavaScript
  • 设置持久缓存和 Cookie

6.3 Dock 初始化策略

三个 Dock 默认初始化后隐藏，只在用户需要时显示。这种策略兼顾了：

  • 主界面简洁
  • 模块解耦
  • 延迟暴露复杂功能

7. 参数与可扩展点

7.1 Map(html_file=...)

主要参数：

  • html_file：地图前端 HTML 路径，默认使用 map/map_widget.html。

适合扩展的方向：

  • 多前端地图模板切换
  • 专题地图页面切换
  • 结果自动回图脚本

8. 开发者建议

如果要继续扩展地图页，建议遵循以下原则：

  • 地图状态放在前端，业务逻辑放在 Python。
  • 需要长期存在的工具用 Dock；一次性小功能优先用弹窗或右键菜单。
  • 任何分析模块若要“回图”，尽量通过统一的数据加载路径进入地图，而不是各模块各自写渲染逻辑。