Whitebox Tools

1. 工具概述

Whitebox Tools 是一套面向地学分析的开源/商用混合工具库，覆盖数据处理、GIS 分析、地形/水文分析、影像处理、LiDAR 等多类任务。本软件将 Whitebox 工具以停靠面板（Dock）的形式集成，提供分类树 + 搜索的查找方式、参数表单自动生成、一键运行与日志查看。

小贴士：本面板定位于“快速调用 Whitebox 算法”。若需数据加载、图层管理、分割采样、Whitebox 独立说明等，请分别参见对应的 .md 文档（本页仅做概要提及）。

2. 界面结构

USDA-GeoProdStudio

打开“Whitebox Tools”停靠面板后，自上而下包含：

  1. 搜索框
  • 占位提示 Search tools…。键入关键字（支持中英文与工具名片段）即可即时过滤工具列表。
  1. 工具列表（Tool List）
  • 以分类树展示，分类示例：Data Tools、GIS Analysis、Geomorphometric Analysis、Hydrological Analysis、Image Processing Tools、LiDAR Tools、Math and Stats Tools、Machine Learning 等。
  • 单击某个工具名称将载入其说明与参数面板。
  1. 工具描述（Description）
  • 展示所选工具的功能简介，来源于 whitebox_tools.json 的 description 字段。
  1. 参数区（可滚动）
  • 按工具定义动态生成表单；包含输入/输出文件、数值、布尔开关、下拉选项等。
  • 面板自动根据参数类型提供浏览按钮或多文件选择等。
  1. 日志区（Log）
  • 运行过程的标准输出、进度与报错均在此滚动显示。支持一键复制与清空。
  1. 操作按钮
  • Run：执行当前工具
  • Copy Log：复制日志到剪贴板
  • Clear Log：清空日志

3. 工具检索与分类

3.1 关键词搜索

  • 在搜索框输入 flow、slope、aspect、contrast、lidar 等关键字，工具树会仅显示匹配项（支持匹配工具名与内部标识）。

3.2 分类快速定位（示例）

  • Hydrological Analysis：D8/D∞ 流向与汇流、集水分区、河网提取、DTW 等。
  • Geomorphometric Analysis：坡向、曲率、相对高程、地形分级等。
  • GIS Analysis：裁剪、缓冲、栅格聚合/叠加、栅格/矢量转换与构网等。
  • Image Processing Tools：滤波、边缘检测、色彩增强、多时相变化分析等。
  • Data Tools：格式转换、字段操作、CSV 转点等。
  • LiDAR Tools：LAS/Laz 转换、分类、叠色、点云裁剪等。
  • Math and Stats Tools：常用数学运算、逻辑栅格、统计分析等。

4. 参数面板与类型说明

Whitebox 工具的参数在 whitebox_tools.json 中定义，软件会自动渲染为合适控件：

参数类型 面板控件与使用方法
ExistingFile / NewFile 单文件路径 + Browse 按钮。ExistingFile 选择现有文件；NewFile 选择输出保存路径。
FileList 多文件输入，选择后会以 ; 分隔显示在输入框。
Boolean 复选框。选中为 true，未选中为 false。
Integer / Float 数字输入框，支持范围与小数位控制。
OptionList 下拉框列出枚举值（如 mean/sum/max/...、cells/sca/ca 等）。
字符串（String） 纯文本输入。
矢量/栅格/点云特定类型 仍以浏览文件的形式填写；类型仅用于提示与校验。

多文件输入：如工具要求 --inputs，可一次多选，界面会将路径以 ; 拼接。

5. 运行与日志

  • 点击 Run 即执行。面板会在日志区打印：

    • [INFO] Running tool: <tool_name>
    • [ARGS] --param1=... --param2=...（完整命令行参数）
    • [WBT] ... Whitebox 执行时的进度与信息
    • [SUCCESS] Tool execution completed. 或 [ERROR] ...

  • Copy Log 可复制命令与输出，便于复现实验或撰写报告。

  • 失败常见原因与排查见第 9 节。

6. 授权/受限工具提示

部分工具属于 Whitebox 的商业授权范畴（或源代码非公开），如：

  • dbscan、lidarKMeansClustering、mosaicImagesWeighted、assess_route 等。

当选择此类工具时，面板会弹出License Required提醒，并禁用运行按钮。若需要使用，请联系 Whitebox Geospatial Inc. 购买授权。

7. 常见工作流示例

以下示例仅示意参数填写思路。数据路径与文件名请根据实际工程替换。

7.1 地形与水文分析（D8 汇流）

  • 工具：D8 Pointer (d8_pointer) → D8 Flow Accumulation (d8_flow_accumulation)

  • 步骤：

    1. D8 Pointer：DEM 选入高程栅格，Output 指定输出。
    2. D8 Flow Accumulation：Input 选择 DEM 或上一步的 D8 Pointer（若为指针需勾选 --pntr），out_type 可选 cells / catchment area / specific contributing area。
    3. 运行后在地图中加载输出查看汇流/比流域结果。

7.2 提取坡向与曲率（地形形态）

  • 工具：Aspect (aspect)、Difference Curvature / Accumulation Curvature 等

  • 步骤：

    1. 选择 aspect，填入 DEM 与 Output，必要时设置 zfactor。
    2. 运行并加载查看结果。曲率工具同理。

7.3 栅格聚合（分辨率重采样）

  • 工具：Aggregate Raster (aggregate_raster)
  • 关键参数：--agg_factor（聚合像元数），--type（mean/sum/maximum/...）。
  • 场景：从 10 m 栅格聚合到 30 m 栅格等。

7.4 影像增强（颜色合成与对比度）

  • 工具：Create Colour Composite (create_colour_composite)、Balance Contrast Enhancement、Direct Decorrelation Stretch

  • 步骤：

    1. 为 red/green/blue 指定对应波段栅格；可选 --enhance 进行平衡对比度增强。
    2. 颜色增强工具可进一步提升显示效果。

7.5 GIS 叠置与裁剪

  • 工具：Clip (clip) / Clip Raster To Polygon (clip_raster_to_polygon) / Buffer Raster / Difference 等
  • 场景：用行政区矢量裁剪栅格或矢量、生成缓冲区、做矢量差异集等。

7.6 LiDAR 处理

  • 工具：Ascii To Las、Classify Buildings In Lidar、Clip Lidar To Polygon、Colourize Based On Class/Returns 等
  • 提示：大点云文件计算量大，建议先裁剪、分块处理，并确保输出路径有足够空间。

7.7 数学/统计快速计算

  • 工具：Absolute Value、Add、And、Conditional Evaluation 等
  • 场景：快速做阈值条件、逻辑运算、常数/栅格混合运算。

8. 与地图/图层的关系（概要）

  • 加载数据：请参考“加载数据.md”，用于将 DEM/影像/矢量/点云添加到地图与工作空间。
  • 图层管理：请参考“图层管理.md”（位于“分割采样（包含图层管理）.md”或独立文档），用于可见性、顺序、样式等管理。
  • Whitebox 工具（本页）：仅负责调用算法并输出文件。生成的结果文件可通过“加载数据”添加回地图进行显示。

9. 注意事项与故障排查

  1. 路径与权限
  • 输入/输出路径尽量使用本机可写目录；避免只读或含特殊字符的路径。
  • 输出文件若已存在，建议更换文件名或路径以避免覆盖冲突。
  1. 坐标系/单位
  • 不同工具对单位敏感（如 zfactor、buffer size、width/height）。当水平/垂直单位不一致时，务必设置 zfactor。
  • 多数据源叠加分析前请确保投影一致。
  1. 多文件参数
  • 采用 FileList 的参数会以 ; 连接多个路径；请勿手动加引号。
  • 某些工具要求波段顺序（如颜色合成），请严格对应。
  1. 授权限制
  • 出现“License Required”提示时无法运行该工具；请改用开源等价流程或联系官方授权。
  1. 日志查看
  • 运行失败请先查看日志中的 [ERROR] 行；常见为路径不合法、输入为空、参数拼写或取值不当。
  • 复制日志可用于问题反馈与复现实验。
  1. 性能建议
  • 大栅格/点云建议放在 SSD；必要时子区分析或降低分辨率测试参数后再跑全量。
  • 影像滤波类算法对窗口大小敏感，过大的 filterx/filtery 会显著增时。

10. 小抄：典型参数对照（GUI ⇄ 命令行）

面板会在日志中打印完整参数，便于复制到命令行/脚本环境复用。

  • D8 Flow Accumulation

      d8_flow_accumulation 
  --input=<DEM 或 D8 指针> 
  --out_type=cells|catchment area|specific contributing area 
  --output=<输出栅格>
  [--pntr] [--log] [--clip] [--esri_pntr]

  • Aggregate Raster

      aggregate_raster 
  --input=<栅格> 
  --agg_factor=2 
  --type=mean|sum|max|min|range 
  --output=<输出栅格>

  • Create Colour Composite

      create_colour_composite 
  --red=<R波段> --green=<G波段> --blue=<B波段> 
  [--opacity=<Alpha波段>] [--enhance] [--zeros] 
  --output=<输出栅格>

11. 版本与依赖（概览）

  • 本面板依赖 WhiteboxTools Python 包与工具可执行体（随应用一并分发）。
  • 面板实现文件：map/_whiteboxtools.py（UI 与运行逻辑）、map/whitebox_tools.json（工具元数据与参数定义）。
  • GUI：PySide6；地图相关功能由主程序提供（非本面板职责）。

12. 常见问题（FAQ）

Q1：运行按钮是灰的怎么办？ A：所选工具需要商业授权或被列为受限工具；请更换工具或联系官方获取许可。

Q2：多文件输入怎么选？ A：点击 Browse 后支持多选；面板会把结果用 ; 拼起来传给工具。

Q3：输出生成了但地图没显示？ A：Whitebox 只负责生成文件。请通过“加载数据”面板把结果添加为新图层；图层的样式与顺序在“图层管理”中调整。

Q4：DEM 的单位是度还是米？ A：若水平为度、垂直为米（或单位不一致），需在相关工具设置合理 zfactor，否则坡度/曲率等会失真。

Q5：为什么日志里显示 No such file or directory？ A：检查输入路径是否存在、是否有权限、是否含中文/空格等特殊字符；尽量使用英文与无空格路径。

13. 最佳实践与建议

  • 先小范围试跑再全域分析，逐步放大数据量。
  • 对输出进行命名规范（含方法与参数要点），便于复现：如 accum_cells_z1_30m.tif。
  • 将日志复制保存到工程记录中，方便审计与论文补充材料。
  • 充分利用分类+搜索快速定位目标工具；不确定时可先阅读“Description”了解算法假设与输出含义。