第12章 - 地理处理工具箱

GeoLibre 的 Processing 菜单里装着两套互不相干的工具箱，外加 SQL、Python、AI、建模、看板等入口。菜单上”Vector”“Raster”“Conversion”这些名字各出现两次——一次属于 Whitebox 工具箱，一次属于 GeoLibre 自己的工具箱。它们不是重复实现，也不打开同一个对话框。

本章先把这两套工具箱彻底分开，再讲工具怎么找、参数怎么填、任务怎么跑、结果落到哪、缺依赖时怎么修。阅读顺序建议照此进行：先分清工具箱，再谈工具。

说明：本章基于 GeoLibre 3.4。工具名、参数名与菜单路径保留英文原文。事实来源为 docs/user-guide/processing.md、docs/tutorials/vector-analysis.md、docs/tutorials/terrain-analysis.md、docs/architecture.md（Python sidecar 小节），以及源码 packages/processing/src/{types,registry,runner,vector-tools,vector-tool-runner,wasm-tool-runner}.ts、apps/geolibre-desktop/src/lib/{whitebox-menu-catalog,whitebox-tool-url,whitebox-semantic-search,processing-params}.ts。

12.1 两类工具箱：一张图分清

12.1.1 菜单的真实结构

Processing
├─ AI Assistant
├─────────────────────────
├─ Whitebox Toolbox        ← 打开工具箱对话框
├─ Conversion       ▸  ┐
├─ Hydrology        ▸  │
├─ LiDAR            ▸  │
├─ Network          ▸  │
├─ Projection       ▸  ├ 同一个工具箱，按分类浏览（1,000+ 工具）
├─ Raster           ▸  │
├─ Remote Sensing   ▸  │
├─ Terrain          ▸  │
├─ Vector           ▸  ┘
├─────────────────────────
├─ GeoLibre Toolbox ▸      ← GeoLibre 自带工具
│   ├─ Conversion         ▸
│   ├─ Vector             ▸
│   ├─ Network            ▸
│   ├─ Spatial Statistics ▸
│   ├─ Raster             ▸
│   ├─ DGGS               ▸
│   ├──────────────────────
│   ├─ Geocode Addresses
│   ├─ Batch tools
│   ├─ AI Segmentation
│   ├─ Object Detection
│   └─ Segment Everything
├─────────────────────────
├─ Model Builder
├─ Object-Based Analysis
├─ SQL Workspace
├─ Python Console
├─ Jupyter Notebook
├─ Dashboard
├─ History
├─ Planetary Computer
└─ Earth Engine

两个分隔线之间的整块都属于 Whitebox Toolbox；GeoLibre Toolbox 下面的所有东西都是 GeoLibre 自己的。同一个分类名在菜单里出现两次，是因为它们真的属于两套东西。

12.1.2 两套工具箱的差异

12.1.3 最容易混的两条路径

同样”撞名”的还有单个工具：

提示：本教程后面提到”Conversion 工具”时，一律指 GeoLibre Toolbox → Conversion 那一个（有文件选择器的那套）。

12.1.4 该用哪个

警告：Whitebox 对话框里还有一个 source 下拉框（All sources / GeoLibre tools / Whitebox tools）。它只过滤Whitebox 目录内的工具来源，”GeoLibre tools”在那里指的是同一批 WASM 工具，与 GeoLibre Toolbox 的对话框毫无关系。这是第三个容易混淆的”GeoLibre”字样。

12.2 GeoLibre Toolbox 全览

12.2.1 Vector：最常用的一个

Processing → GeoLibre Toolbox → Vector 打开矢量工具对话框：左侧工具列表，右侧参数，顶部有引擎选择器。工具按分组排列：

Geometry

Overlay

Join

Select

Movement & time

Data management / Data quality

12.2.2 三个引擎

矢量工具对话框顶部有引擎选择器（Run 之前）：

Pyodide 的运行时默认从公共 jsDelivr CDN 加载，这是一条信任假设；生产或离线环境可用 VITE_PYODIDE_INDEX_URL 指向自建镜像，彻底去掉 CDN 依赖。

警告：客户端引擎在经纬度上按”度”计算。1000 米的缓冲写进 Client 引擎会变成 1000 度，结果绕地球。要做米制缓冲，选 Sidecar 或 Pyodide（它们会先重投影）。

12.2.3 Raster：地形与遥感

Processing → GeoLibre Toolbox → Raster 打开栅格对话框。多数工具是”文件路径进、文件路径出”，在 rasterio sidecar 上跑，结果再上地图。八个工具有 Client (browser) 引擎，完全不需要 sidecar：

同一个子菜单里还有两个特殊条目：

• Download Global DEM 在顶部：从公开的 AWS Terrain Tiles 下载当前视图或手绘框的 DEM（无需 key），然后在 Whitebox 对话框里打开；
• Georeferencing 在底部：用地面控制点把无地理参考的影像钉到地图上，最小二乘仿射拟合，报告逐点残差与 RMS。

12.2.4 Conversion、Network、Spatial Statistics、DGGS

这四组在 12.7 与下面几段分别展开，这里先给一张”能不能在浏览器跑”的速查：

Network 的三个工具是 Isochrone / service area、OD cost matrix、Sequential route (directions)，全部请求 Valhalla 服务器；默认用公共 FOSSGIS 实例（valhalla1.openstreetmap.de），所以提交的坐标会离开设备，自托管部署可指向自己的服务器。

Spatial Statistics 的七个工具：Global Moran’s I、Local Moran’s I (LISA)、Getis-Ord Gi* hotspots、Average nearest neighbor、Kernel density (heatmap)、Emerging Hot Spot (space-time cube)、Composite score (suitability index)。

其中 Composite score 是”适宜性指数”的完整实现：

1. 选两个以上数值字段；
2. 每个字段选归一化：Min-max、Z-score、Rank、Quantile；
3. 给相对权重（界面同时显示它占总权重的百分比）；
4. 选方向：Higher is better / Lower is better；
5. 选合成方式：加权算术平均，或”强项不能补偿弱项”时的几何平均；
6. 决定缺值怎么处理：从结果中去掉，或按已有字段重新归一化权重（没有默认值，两者都合理，但只有一个是你想要的那个）；
7. 可选 Keep normalized components（把每个字段的归一化值写成独立列，便于审计）；
8. 设 Score range（默认 0–100，也可 0–1）与 Score field name。

Rank 与 Quantile 对并列值采用中位秩，所以相等的输入永远得到相等的分数。结果以新图层落图，并自动用分级渲染按分数着色。

DGGS 三个工具：DGGS Generator（按图层几何/范围、地图视图或手工 bbox 铺格）、DGGS Binning（把点聚合到格子里，计数或 sum/mean/min/max）、DGGS Compact（压缩或展开到统一分辨率）。

12.2.5 其余入口

12.3 Whitebox Toolbox：1,000+ 个工具

12.3.1 来源与规模

工具来自两处，混在同一个目录里：

1. Whitebox Next Gen 套件（上游项目 Whitebox-Next-Gen-ArcGIS 的工具清单）；
2. GeoLibre 自己的 WASM 工具（geolibre-rust 编译成 WebAssembly），在菜单里以 GeoLibre (WASM) 子标题标出。

菜单目录是自动生成的（scripts/gen-whitebox-menu-catalog.mjs），文件头明确写着”不要手改”。仓库快照里是 1,068 个工具、9 个分类：

Projection 分类只有 4 个工具，值得单独记住：

另有 assign_projection_vector（Assign Projection Vector，在 Vector 分类的 WASM 子标题下）与 assign_projection_raster（在 Raster 分类下）——这两个只改声明，不动坐标。

12.3.2 在哪运行：Run locally (WASM)

Whitebox 工具跑在浏览器里，通过一个带栅格与矢量 I/O 的 WebAssembly 运行时——不需要 Python sidecar，不需要服务器，数据不出本机。因此整套工具箱在 GeoLibre Web、Android、iOS 上都能用。

Run locally (WASM) 复选框控制执行引擎：

Mac App Store 构建没有 sidecar 可切，所以那个复选框根本不出现，WASM 是唯一运行时。工具列表在两种模式下完全相同，只有执行引擎变。

12.3.3 输入与输出

注意：Whitebox 的矢量输出下拉里那句 projectedHint 很重要——选了投影 CRS 的输出会下载成文件而不上地图，因为地图只显示 EPSG:4326。要看到结果，就输出 4326，或改用矢量工具。

12.4 找到工具：四条路径

12.4.1 分类浏览

Processing 菜单里每个 Whitebox 分类都有子菜单，子菜单里再分子类。工具名直接来自清单，跟随上游命名（英文，即使界面语言是中文）。目录是离线打包的，所以没网也能浏览。

12.4.2 搜索

• Whitebox 对话框左侧顶部有 Search tools 过滤框（子串匹配，即时）；
• Processing 菜单自身也有 Search processing tools…（菜单层面的搜索，可跨两套工具箱）；
• 命令面板（Ctrl/Cmd + K）会把每个处理工具单独列出：Tools 下面是 GeoLibre Toolbox 的矢量、网络、统计工具，Whitebox Toolbox 下面是每个 Whitebox 工具。选一个就打开对话框并预选该工具。

命令面板的排序规则值得一提：工具名在任何语言下都保持英文可搜，完全匹配的标题排第一，且会隐藏当前界面配置隐藏掉的条目。

12.4.3 语义搜索

Whitebox 对话框的搜索框还支持按意思找工具——输入 “remove sinks so water drains off the edge”，它会找到 fill_depressions，而子串匹配一条也找不到。

它的三条设计规则决定了你什么时候会看到它：

1. 不可用时就完全隐形：没有配置 System One 端点（默认）时，什么都不会发生，界面与之前一模一样；
2. 很少触发：不是每敲一个字就查——输入停顿 500 ms 后才发请求，且要求查询是多词短语，或单词但子串命中的工具少于 3 个；
3. 只增不重排：语义结果作为独立的”Best matches”分组显示在子串结果上方，不会把你正在读的列表打乱。

提示：语义搜索依赖 AI provider 的 System One 端点（第18章）。没有配置时它是”不存在”而不是”坏了”——别把它当成 bug 排查。

12.4.4 深链接 ?tool=

Whitebox 对话框里的 Copy link 会生成一个带 ?tool=<工具 id> 的 URL，打开即预选该工具、并带上当前参数：

https://web.geolibre.app/?tool=extract_cog_subset&url=https%3A%2F%2F…%2Fdem.tif&bbox_crs=4326

规则：

文档、教学、bug 报告都适合用这种链接——它把”哪个工具 + 哪些参数”变成一条可复现的记录。

12.5 参数表单：从清单长出来的界面

12.5.1 参数类型

Whitebox 对话框的表单是根据工具清单生成的，而 GeoLibre Toolbox 的表单是手写的。两套都建立在同一组参数类型上（packages/processing/src/types.ts）：

三个”条件显示”能力让长表单变得可用：

12.5.2 三种”智能参数”

参数名与类型会被进一步识别，换成专门的控件：

距离单位这一项要特别说明，因为它是”结果差一万倍”的常见来源：

对话框会显示换算结果与提示 Sent to the tool as N°, converted at <lat>. A degree varies with latitude and direction, so this is approximate.。这条便利只在所有数据集输入都是地图图层的内存 GeoJSON 时提供——理由是 RFC 7946 固定了这些坐标是 WGS84；一旦有栅格、LiDAR 或文件路径输入，坐标单位就不可知，选择器不会出现。

12.5.3 文件与输出

• path 参数带 Choose file 按钮与扩展名过滤；
• 数据输入参数（raster_in、vector_in、lidar_in、file_in）与输出参数（*_out）总是带路径选择；
• 矢量输出有格式下拉：GeoJSON (add to map)、GeoParquet (download, keeps CRS)、FlatGeobuf、Shapefile；
• 输出文件名会按工具与输入自动给一个默认值。

12.6 运行、进度、取消与历史

12.6.1 一次运行的完整过程

1. 选工具（菜单、搜索、命令面板或深链接）；
2. 填参数——必填项标 required；
3. 选引擎（矢量工具的引擎选择器，或 Whitebox 的 Run locally (WASM)）；
4. Run；
5. 状态在 Pending → Running → Succeeded / Failed 之间变化，右侧日志滚动；
6. 结果落图；栅格是 COG，LiDAR 是点云图层；
7. 一次运行写入 Processing → History。

12.6.2 进度与取消

• 长任务（网络分析、大栅格、LiDAR）在运行中可取消；取消通过 AbortSignal 传给工具，网络请求会被中止；
• Whitebox 的 sidecar 路径是”提交任务 + 轮询”模型，所以取消意味着停止轮询并通知 sidecar；
• 关闭对话框不保证后台任务停止——矢量工具的取消是显式的按钮，不是关窗。

12.6.3 结果落图

多数工具在完成后会 fitBounds 到结果范围；可以在 Settings → Map Preferences 里关掉”添加数据后自动缩放”（zoomToNewLayers）。

12.6.4 Processing History

Processing → History 记录本项目里的每一次处理运行，新的在前：

两套工具箱写的是同一个历史，右键快速分析（buffer / drive-time / viewshed）也写进去。Clear history 清空；工具下线后再点 Re-run 会提示 Tool "<id>" is no longer available。

提示：Copy Python 是”把手工操作变成脚本”的最短路径。先在界面里把参数调对，再复制 Python，比直接写脚本试参数快得多。

12.7 转换工具与云原生输出

Processing → GeoLibre Toolbox → Conversion 有 9 个工具，全部围绕”写出现代格式”：

12.7.1 为什么要 Hilbert 排序

Hilbert 曲线把二维空间上邻近的要素映射到一维上邻近的位置，于是文件里的要素按空间局部性排列。对带空间索引/范围读取的格式（FlatGeobuf、GeoParquet）来说，这意味着按视口读时命中更少的页。这就是那三个工具都强调 “Hilbert-sorted” 的原因。

12.7.2 引擎与格式矩阵

对话框的状态行会写明它准备用哪个引擎。所有 Conversion 工具都有客户端引擎，所以在浏览器与 Mac App Store 构建上都能用。

12.7.3 输出位置的限制

sidecar 可以把转换的输入与输出限制在白名单目录里，通过 GEOLIBRE_CONVERSION_ROOTS 设置（Docker 镜像默认 /data）。桌面版不设这个变量——路径就是你自己的文件系统，没有什么要限制的。Docker 必须设，因为那里的 sidecar 通过 nginx 同源可达，不能让它读写容器里任意路径。

警告：Processing → Conversion（分隔线以上那个）是 Whitebox 的转换分类，与这里讲的 GeoLibre Toolbox → Conversion 不是一回事。两处都有 “Vector to PMTiles” 与 “Raster to PMTiles”，但对话框、参数、输出都不一样。

12.8 侧车（sidecar）与 extras

12.8.1 它是什么

一个本地 FastAPI 服务（127.0.0.1:8765），桌面版按需启动，可选。它承担三类工作：

1. 栅格工具（rasterio）；
2. sidecar 版转换工具；
3. 可选的 GeoPandas 矢量引擎。

Whitebox 工具箱可以用它，但不需要它（默认走 WASM）。矢量工具的客户端引擎与浏览器版转换也不需要。

12.8.2 安装与 extras

基础安装刻意做得很小，每组工具一个 extra：

cd backend/geolibre_server
python -m venv .venv
source .venv/bin/activate
pip install -e .

# 转换工具（DuckDB、rio-cogeo、freestiler）
pip install -e ".[conversion]"

# 矢量工具，GeoPandas 引擎（GeoPandas、Shapely）
pip install -e ".[vector]"

# 栅格工具（rasterio、numpy、contourpy）
pip install -e ".[raster]"

# AI Segmentation 代理（只是 HTTP 客户端；模型在 samgeo-api）
pip install -e ".[ml]"

从仓库根目录安装时用完整路径，例如 pip install -e "backend/geolibre_server[conversion]"。另有 sedona extra（SedonaDB sidecar，第11章）与 mssql extra（SQL Server）。

运行：

uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765

sidecar 会自举一个受管运行时；要复用当前环境，设 GEOLIBRE_CONVERSION_PYTHON=$(which python)。

12.8.3 自动回退

12.8.4 状态检测

Whitebox 对话框会显示 Checking runtime. → N tools available. 或 Whitebox runtime is unavailable.；sidecar 模式下还有 Start server / Stop server 按钮。CORS 只对 localhost:5173 与 Tauri 的 origin 开放，所以从别的端口提供 Web 构建时 sidecar 会拒绝。

12.8.5 amd64 限制

freestiler 与 whitebox-workflows 没有发布 linux/arm64 的 wheel，所以在 amd64 上才会安装；在 arm64 上 sidecar 会把这些工具报告为不可用。这不影响浏览器自己的 PMTiles 与 Whitebox 引擎——它们是 WebAssembly，任何架构都能跑。

提示：遇到”某些转换工具在 arm64 上灰掉”不是配置错误，而是上游 wheel 的架构限制。用 WASM 引擎或换 amd64 主机即可。

12.9 批处理与输出

12.9.1 Batch tools

Processing → GeoLibre Toolbox → Batch tools 有两个模式：

两个模式都建立在客户端矢量工具之上，都跑客户端引擎。

12.9.2 与 Model Builder 的分工

图形化建模的完整内容见 第13章 模型构建器与自动化工作流。

12.9.3 输出到底去了哪

警告：浏览器版”写文件”最终是下载。批量转换几十个文件时，浏览器会连续触发下载，需要允许”多文件下载”，否则只有第一个成功。

12.10 常见错误与限制

12.10.1 三条硬边界

1. 引擎决定能力：WASM 引擎读不了任意本机路径；sidecar 读不了浏览器里选的文件；两者不能互相替代。
2. 浏览器版没有 sidecar 的格式广度：Vector to Vector 在浏览器里只写六种格式。
3. Whitebox 的矢量输出不是”图层”：默认格式是 GeoJSON 才加入地图，其余格式只下载。

12.11 本章小结

1. 两套工具箱：Whitebox（1,000+ 工具、单一对话框、WASM 优先）与 GeoLibre Toolbox（手写对话框、Turf.js/Pyodide/sidecar 引擎）。菜单里 Vector/Raster/Conversion 各出现两次，不是重复。
2. GeoLibre Toolbox 的 Vector 分 Geometry / Overlay / Join / Select / Movement & time / Data management / Data quality 七组；Reproject 与投影感知的缓冲需要 Sidecar 或 Pyodide。
3. Raster 有八个工具能在浏览器跑（Hillshade、Slope、Aspect、Clip by extent、Raster calculator、Spectral index、Reclassify、Focal statistics），其余需要 rasterio sidecar。
4. Whitebox 目录自动生成，仓库快照 1,068 个工具、9 个分类；Projection 只有 4 个工具。
5. Run locally (WASM) 决定引擎：浏览器默认勾选、桌面默认不勾、MAS 构建没有这个选项。
6. 参数表单从清单生成：layer / number / string / boolean / select / field / path / field-weights；epsg 参数变 CRS 选择器，*_field 变字段下拉，double 型的距离参数带单位换算器。
7. 距离换算依赖 WGS84 假设：只要有栅格/LiDAR/文件路径输入，单位选择器就不出现——因为坐标单位不可知。
8. Processing History 统一记录两套工具箱与快速分析，提供 Re-run、Edit & re-run、Copy JSON、Copy Python。
9. Conversion 九个工具全部有客户端引擎，Hilbert 排序是为了范围读取效率；Vector to Vector 在桌面能写任意 GDAL 格式，浏览器只写六种；Raster to PMTiles 永远走 WASM。
10. sidecar 可选：extras 为 conversion / vector / raster（另有 ml、sedona、mssql），失败自动回退，GEOLIBRE_CONVERSION_ROOTS 限制转换路径，arm64 上缺两个 wheel。
11. 批处理两条路：Batch tools 的 Batch（多图层）与 Models（链式），对比 Model Builder 的图形态。
12. 输出分三类：落图（矢量/栅格/LiDAR）、下载文件（非 GeoJSON 的矢量输出、所有转换产物）、以及”投影结果不加入地图”这条刻意设计。

12.12 实践练习

1. 分清两套工具箱：从 Processing → Vector → GeoLibre (WASM) 打开一个工具，记录对话框标题与参数控件；再从 Processing → GeoLibre Toolbox → Vector → Buffer 打开，比较两者的引擎选择器、工具列表与输出方式，写一段话说明为什么它们不是重复实现。

2. 引擎差异：对同一个面图层做 1000 米缓冲，分别用 Client (Turf.js) 与 Python (Pyodide)，比较结果范围与面积；解释为什么客户端引擎的结果大得离谱，以及对话框的距离单位选择器如何缓解这个问题。

3. CRS 参数：打开 Processing → Projection → Reproject Vector，观察 dst_epsg 参数的 Browse 按钮，用 utm 17n 搜出两个候选并选一个；再打开 Assign Projection Vector，比较两者的参数与”是否真的改坐标”。

4. 转换与体积：把同一个图层分别转成 GeoParquet、FlatGeobuf、GeoPackage 与 Zipped Shapefile，记录四份文件的大小与字段名；解释 Shapefile 的字段名变化原因，以及为什么前两者强调 “Hilbert-sorted”。

5. 历史与复现：随便跑三个工具（一个矢量、一个栅格、一个转换），打开 Processing → History，对其中一条用 Edit & re-run 改一个参数再跑，然后用 Copy Python 把结果贴进 Python 控制台执行，比较两种方式的结果是否一致。

6. 缺依赖排查：在浏览器构建里打开 GeoLibre Toolbox → Raster → Contour，记录引擎选择器的可选值；再打开 Reproject，记录两者差异，并说明哪些工具必须有 sidecar、为什么浏览器版无法提供。

延伸阅读

• 仓库文档：docs/user-guide/processing.md、docs/tutorials/vector-analysis.md、docs/tutorials/terrain-analysis.md、docs/architecture.md（Python sidecar）、docs/getting-started.md（Optional extras）
• 源码：packages/processing/src/{types,registry,runner,vector-tools,vector-tool-runner,wasm-tool-runner,raster-client,sidecar-client}.ts、apps/geolibre-desktop/src/lib/{whitebox-menu-catalog,whitebox-tool-url,whitebox-semantic-search,processing-params}.ts、apps/geolibre-desktop/src/components/processing/
• 相关章节：第11章 SQL 工作区与 DuckDB 空间分析、第13章 模型构建器与自动化工作流、第14章 地形与水文分析、第15章 矢量空间分析