🗺️ 地图工具（Leaflet × Qt WebChannel）

面板：地图工具 核心实现：map_widget.html（容器与控件）、map_logic.js（逻辑/交互/渲染）、map_style.css（样式）、_JSBridge.py（JS↔Python 桥）、_dataloader.py（数据加载 Dock，含栅格样式应用）、__init__.py（入口导出与 Dock 注册）。 说明：本页介绍“地图工具”本体与其通用能力；Whitebox 工具、加载数据、分割采样（含图层管理）均有独立 .md，此处仅做概要指引。

USDA-GeoProdStudio

① 功能概述

  • 在线底图切换（高德/OSM/Esri 影像）与 Canvas 渲染优化，支持大要素量平滑交互。
  • 图层管理浮窗：显隐、上/下移、删除、分割填充透明度滑条、RGB 显示调节卡片（亮度/对比/饱和/Gamma、cut 百分位占位）。
  • 绘图工具（Geoman）：点/线/面/矩形/圆绘制、编辑/拖拽/删除、一键导出 GeoJSON。
  • GeoTIFF 栅格加载与单波段渲染/伪彩/RGB 合成；支持 RGB 曲线式调节（gain/gamma/sat/contrast）。
  • 地图截图导出（PNG/JPG） 与 GeoJSON 保存。
  • JS↔Python 双向通讯：打开 Whitebox/数据加载/分割采样 Dock，保存文件到工作空间。
  • 数据加载 Dock（概览）：一键加载 Raster/Vector/CSV（经度 lon、纬度 lat）到地图，右键菜单缩放/设为当前/移除，栅格样式应用入口。详细参见《加载数据.md》。

② 界面与结构

  • HTML 容器：#map 为主视图；右上为浮动工具栏，左下为图层管理浮窗；RGB 调整卡片嵌于图层面板内部。
  • 样式要点：工具栏按钮/下拉统一样式；图层面板毛玻璃风格（backdrop-filter）、窄体滚动条、微交互（hover/active）。
  • 初始化：Leaflet preferCanvas: true，共享 canvasRenderer；底图默认高德。

③ 工具清单（地图工具本体）

A. 底图切换与工具栏

  • 打开工具栏 → 地图图层 → 下拉选择：高德 / OSM / Esri。对应 JS：changeBasemap(value) / toggleBasemapSelector()。

B. 绘图工具（点/线/面/矩形/圆）

  • 内置 Geoman 控件：绘制、编辑、拖拽、删除；统一收纳到 drawnLayers。
  • 清除绘图 与 导出 GeoJSON：将当前绘制导出为 GeoJSON 文件（桥接保存）。

C. 地图导出（截图）

  • 选择 PNG/JPG → html2canvas 截图 → 通过 Bridge saveFile 保存。

D. 栅格加载与渲染

  • 通过“加载数据”Dock 选择 GeoTIFF，地图端以 GeoRasterLayer 载入；
  • 单波段灰度 / 单波段伪彩 / RGB 合成 三种渲染；RGB 强化（gain/gamma/sat/contrast）。
  • 所有设置调用 applyRasterStyle(options) 与 setRasterRgbBlend() 实时刷新。
  • Dock 内可直接应用样式（“🎨 应用样式”按钮触发 JS）。详见独立文档。

E. 图层管理浮窗

  • 列表：显示每个图层的 id 与可见性；上移/下移/删除；点击行激活为 RGB 调整对象。
  • 填充透明度：分割采样面填充透明度滑条（底部），实时改变 fillOpacity。
  • RGB 调整卡片：亮度/对比/饱和/Gamma 滑条；↺ 一键恢复默认。

🔹 Whitebox 工具、加载数据、**分割采样（含图层管理与分类右键菜单）**为独立文档，这里仅指向：

  • Whitebox 工具：由 JSBridge.openWhiteboxDock() 打开 Dock。
  • 加载数据：JSBridge.openDataDock()；详见《加载数据.md》。
  • 分割采样：JSBridge.openSegDock()；详见《分割采样.md》。

④ 操作流程（最小闭环）

  1. 切换底图：右上“工具 → 地图图层”。
  2. 加载数据：打开“加载数据”Dock（道具按钮）→ 选 Raster/Vector/CSV → 加载。
  3. 查看与管理图层：左下浮窗勾选显隐、上/下移；视需要删除。
  4. 栅格渲染：Dock 侧选择“单波段灰度/伪彩/RGB”，并在面板内调整亮度/对比/饱和/Gamma。
  5. 绘制与导出：用 Geoman 工具绘图 → 导出 GeoJSON。
  6. 地图截图：选择 PNG/JPG → 导出。

⑤ 参数与控件（速查）

分组 控件/函数 说明
地图 changeBasemap(value) 切换底图（高德/OSM/Esri）。
绘图 Geoman 控件 点/线/面/矩形/圆/编辑/拖拽/删除；统一保存在 drawnLayers。
GeoJSON saveDrawings() / JSBridge.saveGeoJson() 导出绘制结果为 GeoJSON 文件。
截图 html2canvas + JSBridge.saveFile() 导出地图为 PNG/JPG。
栅格加载 loadRasterLayer(url, options) 加载 GeoTIFF，内部计算采样统计并构建 GeoRasterLayer。
单波段渲染 applyRasterStyle({renderType, colorRamp, opacity}) 灰度/伪彩（自带多套色带）。
RGB 合成 showRgbFromTif(url, spec) / setRasterRgbBlend(id, spec) 支持多波段自定义混合 + 亮度/对比/饱和/Gamma。
图层管理 refreshLayerManager() 列表、显隐、上/下移、删除、填充透明度滑条。
Dock 打开 openWhitebox()/openDataLoader()/openSegDock() 调用 JSBridge 打开对应 Dock。
入口导出 __all__ = [JSBridge, WhiteboxToolsDock, DataLoaderDock, SegSamplingDock] 统一导出模块入口（供主窗口装配）。

⑥ 内部机制（开发者要点）

  • WebChannel：window.bridge = channel.objects.bridge；JS 侧调用 bridge.openDataDock() 等打开 Dock；Python 侧 JSBridge 统一提供保存文件、日志回传、Dock 显隐等能力。
  • 图层注册表：window.layerRegistry 存放所有 Leaflet 图层；图层管理面板基于此构造；用户数据图层统一挂在 window.userDataLayers。
  • 栅格统计：加载时对宽度按步长抽样计算 {min,max,mean}，缓存到 georaster.stats，供样式函数重用。
  • RGB 调整：window.RGB_TUNE[layerId] = { gain, gamma, sat, contrast }；滑条实时刷新混合函数并 redraw()。
  • 图层面板：自动隐藏（无图层）→ 显示（有图层）；用户手动隐藏后保留“用户显隐状态”。
  • 入口装配：__init__.py 暴露 JSBridge、Whitebox/DataLoader/SegSampling 三个 Dock 供主窗口注册。

⑦ 日志与排错

  • JS --> Python: JS ready：WebChannel 正常。若无此行，检查 qwebchannel.js、bridge 注册。
  • GeoRaster 依赖库未加载！：确认 georaster.bundle.min.js / georaster-layer-for-leaflet.js 已正确引入。
  • 栅格空白/异常：检查 pixelValuesToColorFn 是否被覆盖；或统计 min/max 是否等值。
  • 图层面板不显示：确认 window.layerRegistry 非空且未被清空；或用户手动隐藏（LayerManagerUserHidden=true）。
  • 文件保存失败：查看 _JSBridge.saveFile/saveGeoJson 的异常日志与文件对话框权限。

⑧ 与其它模块的关系（仅概要）

  • Whitebox 工具：在地图上作为空间分析的算法面板和结果可视化入口，由 openWhiteboxDock() 打开。详见《Whitebox 工具.md》。
  • 加载数据：提供文件对话框、类型判断、矢量投影统一到 EPSG:4326、CSV（lon/lat）转点、栅格面板与样式应用。详见《加载数据.md》。
  • 分割采样：在地图中加载分割结果、右键分类菜单、颜色/透明度联动、图层管理整合。详见《分割采样.md》。

⑨ 使用建议

  1. 优先 Canvas 渲染：大要素集下性能更稳；尽量避免一次性加入超大 GeoJSON，可分批加载。
  2. 先载入后调样式：GeoTIFF 加载完成后再应用单波段/伪彩/RGB，可减少 redraw 次数。
  3. RGB “先粗后精”：先设 gain、再调 gamma、最后微调饱和与对比，易于获得清晰亮丽的显示。
  4. 图层管理“轻操作”：大量图层时，优先使用显隐与上/下移；删除前确认无后续依赖。