@dsh-gis/dsh-opengis-skill 0.1.3 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +40 -0
- package/README.md +48 -22
- package/THIRD_PARTY_NOTICES.md +9 -0
- package/adaptations/brutile.md +8 -0
- package/adaptations/cesiumjs.md +8 -0
- package/adaptations/common.md +16 -0
- package/adaptations/deck-gl.md +8 -0
- package/adaptations/duckdb-spatial.md +8 -0
- package/adaptations/gdal-api.md +8 -0
- package/adaptations/gdal.md +8 -0
- package/adaptations/geolibre.md +8 -0
- package/adaptations/geometry-api-java.md +8 -0
- package/adaptations/geometry-api-net.md +8 -0
- package/adaptations/geonode.md +8 -0
- package/adaptations/geopandas.md +8 -0
- package/adaptations/geopipe-agent.md +8 -0
- package/adaptations/geoserver-cloud.md +8 -0
- package/adaptations/geoserver-rest-api.md +8 -0
- package/adaptations/geoserver.md +8 -0
- package/adaptations/geotools.md +8 -0
- package/adaptations/grass-gis.md +8 -0
- package/adaptations/jts.md +8 -0
- package/adaptations/kepler-gl.md +8 -0
- package/adaptations/leaflet.md +8 -0
- package/adaptations/mapbox-gl-js.md +8 -0
- package/adaptations/mapserver.md +8 -0
- package/adaptations/mapsui.md +8 -0
- package/adaptations/nettopologysuite.md +8 -0
- package/adaptations/opengis-all.md +8 -0
- package/adaptations/opengis-daf.md +8 -0
- package/adaptations/opengis-utils-for-java.md +8 -0
- package/adaptations/opengis-utils-for-net.md +8 -0
- package/adaptations/openlayers.md +8 -0
- package/adaptations/pdal.md +8 -0
- package/adaptations/postgis.md +8 -0
- package/adaptations/proj.md +8 -0
- package/adaptations/projnet4geoapi.md +8 -0
- package/adaptations/pyqgis.md +8 -0
- package/adaptations/qgis-process.md +8 -0
- package/adaptations/qgis-server.md +8 -0
- package/adaptations/shapely.md +8 -0
- package/adaptations/sharpmap.md +8 -0
- package/adaptations/spatialite.md +8 -0
- package/adaptations/whitebox-tools.md +8 -0
- package/assets/brutile/SKILL.md +289 -0
- package/assets/cesiumjs/SKILL.md +73 -23
- package/assets/deck-gl/SKILL.md +19 -20
- package/assets/duckdb-spatial/SKILL.md +370 -0
- package/assets/gdal/SKILL.md +50 -21
- package/assets/gdal-api/SKILL.md +6 -4
- package/assets/geolibre/SKILL.md +364 -0
- package/assets/geometry-api-java/SKILL.md +5 -6
- package/assets/geometry-api-net/SKILL.md +65 -21
- package/assets/geonode/SKILL.md +347 -0
- package/assets/geopandas/SKILL.md +17 -15
- package/assets/geopipe-agent/SKILL.md +25 -20
- package/assets/geoserver/SKILL.md +6 -4
- package/assets/geoserver-cloud/SKILL.md +14 -15
- package/assets/geoserver-rest-api/SKILL.md +13 -8
- package/assets/geotools/SKILL.md +7 -5
- package/assets/grass-gis/SKILL.md +19 -20
- package/assets/jts/SKILL.md +7 -4
- package/assets/kepler-gl/SKILL.md +313 -0
- package/assets/leaflet/SKILL.md +41 -19
- package/assets/mapbox-gl-js/SKILL.md +18 -19
- package/assets/mapserver/SKILL.md +17 -19
- package/assets/mapsui/SKILL.md +85 -48
- package/assets/nettopologysuite/SKILL.md +91 -20
- package/assets/opengis-all/SKILL.md +78 -270
- package/assets/opengis-all/reference/data-stages.md +262 -4
- package/assets/opengis-daf/SKILL.md +6 -5
- package/assets/opengis-utils-for-java/SKILL.md +52 -39
- package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
- package/assets/opengis-utils-for-net/SKILL.md +105 -39
- package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
- package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
- package/assets/openlayers/SKILL.md +66 -9
- package/assets/pdal/SKILL.md +21 -17
- package/assets/postgis/SKILL.md +61 -11
- package/assets/proj/SKILL.md +28 -30
- package/assets/projnet4geoapi/SKILL.md +299 -0
- package/assets/pyqgis/SKILL.md +28 -20
- package/assets/qgis-process/SKILL.md +71 -22
- package/assets/qgis-server/SKILL.md +20 -20
- package/assets/shapely/SKILL.md +132 -75
- package/assets/sharpmap/SKILL.md +93 -50
- package/assets/spatialite/SKILL.md +365 -0
- package/assets/whitebox-tools/SKILL.md +269 -0
- package/lib/adaptations.d.ts +47 -0
- package/lib/adaptations.js +268 -0
- package/lib/index.d.ts +1 -1
- package/lib/index.js +14 -2
- package/lib/skill-file.js +31 -7
- package/locale/en.json +1 -1
- package/locale/zh.json +1 -1
- package/package.json +12 -2
- package/upstream.json +56 -40
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spatialite
|
|
3
|
+
description: "Use when adding spatial SQL to a single-file SQLite database with SpatiaLite — mod_spatialite loading, InitSpatialMetaData, AddGeometryColumn, CreateSpatialIndex/MbrWithin, ST_Transform and GEOS predicates, spatialite_tool or ogr2ogr import of Shapefile, and GPKG fallback; also for 'no such module: mod_spatialite', 'no such function: InitSpatialMetaData', and 'the SPATIALITE_SECURITY environment variable' errors. libspatialite 5.1.0."
|
|
4
|
+
tags:
|
|
5
|
+
- spatialite
|
|
6
|
+
- sqlite
|
|
7
|
+
- sql
|
|
8
|
+
- gis
|
|
9
|
+
- spatial
|
|
10
|
+
- geospatial
|
|
11
|
+
- python
|
|
12
|
+
- vector
|
|
13
|
+
- gpkg
|
|
14
|
+
- command-line
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
> **项目地址:** <https://www.gaia-gis.it/fossil/libspatialite/index>
|
|
18
|
+
>
|
|
19
|
+
> **官方文档:** <https://www.gaia-gis.it/gaia-sins/spatialite-sql-latest.html>
|
|
20
|
+
>
|
|
21
|
+
> **当前版本:** libspatialite 5.1.0(2023-08-04);spatialite-tools 5.1.0a(2023-08-13),截至 2026-10 仍为最新
|
|
22
|
+
>
|
|
23
|
+
> **安装包:** Debian/Ubuntu `libsqlite3-mod-spatialite` 5.1.0-3、`spatialite-bin` 5.1.0a-2;conda-forge `libspatialite` 5.1.0
|
|
24
|
+
>
|
|
25
|
+
> **许可证:** MPL-1.1 / GPL-2.0+ / LGPL-2.1+ 三许可(libspatialite);spatialite-tools 为 GPL-3.0+
|
|
26
|
+
|
|
27
|
+
## 概述
|
|
28
|
+
|
|
29
|
+
SpatiaLite 是 SQLite 的空间扩展库。它把完整的空间 SQL 能力加进 SQLite:几何类型、空间索引、坐标转换与 OGC 关系谓词,而数据库仍然是**单个普通文件**,不需要任何服务端进程。官方把它定位为"SQLite 上的 PostGIS 替代品",适合嵌入式、桌面应用与只读发布场景。
|
|
30
|
+
|
|
31
|
+
核心组件:
|
|
32
|
+
|
|
33
|
+
- **libspatialite**:扩展库本体,以 `mod_spatialite` 模块形式加载进 SQLite,提供 SQL 函数
|
|
34
|
+
- **spatialite-tools**:命令行工具集(`spatialite` shell、`spatialite_tool` 导入导出等)
|
|
35
|
+
- **元数据表**:`geometry_columns` 与 `spatial_ref_sys`,由 `InitSpatialMetaData` 创建
|
|
36
|
+
- **RTree 空间索引**:`CreateSpatialIndex` 建立并与主表触发器保持同步
|
|
37
|
+
- **GPKG 兼容**:同一套函数能读写 OGC GeoPackage
|
|
38
|
+
|
|
39
|
+
**与 GeoPackage 的关系:** GeoPackage 是 SQLite 表格结构的标准封装;SpatiaLite 是功能更全的扩展实现。要跨工具交换数据时优先 GPKG,要完整空间 SQL 能力时用 SpatiaLite。
|
|
40
|
+
|
|
41
|
+
## 环境准备
|
|
42
|
+
|
|
43
|
+
### 方式一:系统包(Debian / Ubuntu)
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# 扩展模块(Python 与 sqlite3 CLI 都用它)
|
|
47
|
+
sudo apt install libsqlite3-mod-spatialite
|
|
48
|
+
|
|
49
|
+
# 命令行工具(spatialite shell、spatialite_tool 等)
|
|
50
|
+
sudo apt install spatialite-bin
|
|
51
|
+
|
|
52
|
+
# 开发头文件(自己编译或链接 libspatialite 时需要)
|
|
53
|
+
sudo apt install libspatialite-dev
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Debian trixie 上的版本为 5.1.0,与上游一致;更老的发行版(如 bookworm 的 5.0.1)会落后一个小版本。
|
|
57
|
+
|
|
58
|
+
### 方式二:conda / mamba
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
conda install -c conda-forge libspatialite
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
conda-forge 的 `libspatialite` 为 5.1.0,Windows / macOS / Linux 均有构建,是跨平台最省事的方式。
|
|
65
|
+
|
|
66
|
+
### 方式三:Windows 预编译包
|
|
67
|
+
|
|
68
|
+
官方站点提供 Windows 二进制(`mod_spatialite-x.y.z-win-x86_64.zip` 一类命名),解压后把目录加入 `PATH`,或把 `mod_spatialite.dll` 放到与 sqlite3.exe 同级的目录。用 conda 装则无需手工放置 DLL。
|
|
69
|
+
|
|
70
|
+
### 方式四:源码编译
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
curl -LO https://www.gaia-gis.it/gaia-sins/libspatialite-5.1.0-RC0.tar.gz
|
|
74
|
+
tar xzf libspatialite-5.1.0-RC0.tar.gz
|
|
75
|
+
cd libspatialite-5.1.0
|
|
76
|
+
./configure --disable-rttopo # 按需启用 GEOS/PROJ/RTTOPO 等依赖
|
|
77
|
+
make -j"$(nproc)"
|
|
78
|
+
sudo make install
|
|
79
|
+
sudo ldconfig
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
依赖链较长(SQLite、GEOS、PROJ、FreeXL、libxml2 等),没有特殊需求时优先用包管理器。
|
|
83
|
+
|
|
84
|
+
### 验证
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
# 1) 库文件是否存在
|
|
88
|
+
ls /usr/lib/x86_64-linux-gnu/mod_spatialite.so # Linux
|
|
89
|
+
# Windows 下为 mod_spatialite.dll,macOS 下为 mod_spatialite.dylib
|
|
90
|
+
|
|
91
|
+
# 2) CLI 能否加载扩展并报出版本
|
|
92
|
+
spatialite :memory: "SELECT spatialite_version();"
|
|
93
|
+
|
|
94
|
+
# 3) Python 侧能否加载
|
|
95
|
+
python -c "import sqlite3; c=sqlite3.connect(':memory:'); c.enable_load_extension(True); c.load_extension('mod_spatialite'); print(c.execute('SELECT spatialite_version()').fetchone())"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
三条任一失败,先解决加载问题再写 SQL。
|
|
99
|
+
|
|
100
|
+
## 核心 API
|
|
101
|
+
|
|
102
|
+
### 加载扩展
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# CLI:进入 shell 后加载
|
|
106
|
+
spatialite mydb.sqlite
|
|
107
|
+
spatialite> .load mod_spatialite
|
|
108
|
+
|
|
109
|
+
# CLI:一次性执行(把扩展加载与 SQL 放在同一次调用里)
|
|
110
|
+
spatialite mydb.sqlite -cmd ".load mod_spatialite" "SELECT spatialite_version();"
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
import sqlite3
|
|
115
|
+
|
|
116
|
+
con = sqlite3.connect("mydb.sqlite")
|
|
117
|
+
con.enable_load_extension(True) # Python 3.10+ 需要显式开启
|
|
118
|
+
con.load_extension("mod_spatialite") # 找不到时传绝对路径
|
|
119
|
+
con.enable_load_extension(False)
|
|
120
|
+
|
|
121
|
+
print(con.execute("SELECT spatialite_version()").fetchone())
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 初始化空间元数据
|
|
125
|
+
|
|
126
|
+
每个数据库**只需执行一次**:
|
|
127
|
+
|
|
128
|
+
```sql
|
|
129
|
+
-- 创建 geometry_columns 与 spatial_ref_sys(1 = 成功)
|
|
130
|
+
SELECT InitSpatialMetaData(1);
|
|
131
|
+
|
|
132
|
+
-- 只要 WGS84 相关 SRID,体积更小
|
|
133
|
+
SELECT InitSpatialMetaData(1, 'WGS84');
|
|
134
|
+
|
|
135
|
+
-- 完全不插入 EPSG 定义(自己管理 SRID)
|
|
136
|
+
SELECT InitSpatialMetaData(1, 'NONE');
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
返回 1 表示创建成功;对已初始化的库重复调用会返回 0,不会破坏数据。
|
|
140
|
+
|
|
141
|
+
### 建表并声明几何列
|
|
142
|
+
|
|
143
|
+
先建普通表,再用 `AddGeometryColumn` 注册几何列(不要手写 geometry 列):
|
|
144
|
+
|
|
145
|
+
```sql
|
|
146
|
+
CREATE TABLE poi (
|
|
147
|
+
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
148
|
+
name TEXT
|
|
149
|
+
);
|
|
150
|
+
|
|
151
|
+
SELECT AddGeometryColumn('poi', 'geom', 4326, 'POINT', 'XY');
|
|
152
|
+
|
|
153
|
+
INSERT INTO poi (name, geom)
|
|
154
|
+
VALUES ('tiananmen', MakePoint(116.397, 39.908, 4326)),
|
|
155
|
+
('waitan', MakePoint(121.490, 31.241, 4326));
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
`AddGeometryColumn` 会同时建触发器,保证写入的几何类型与 SRID 与声明一致。
|
|
159
|
+
|
|
160
|
+
### 空间索引
|
|
161
|
+
|
|
162
|
+
```sql
|
|
163
|
+
-- 建 RTree 索引(自动创建同步触发器)
|
|
164
|
+
SELECT CreateSpatialIndex('poi', 'geom');
|
|
165
|
+
|
|
166
|
+
-- 校验索引一致性;参数省略时检查全部
|
|
167
|
+
SELECT CheckSpatialIndex('poi', 'geom');
|
|
168
|
+
|
|
169
|
+
-- 更新图层统计信息(要素数与总范围)
|
|
170
|
+
SELECT UpdateLayerStatistics('poi', 'geom');
|
|
171
|
+
|
|
172
|
+
-- 需要停用时
|
|
173
|
+
-- SELECT DisableSpatialIndex('poi', 'geom');
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### 常用空间函数
|
|
177
|
+
|
|
178
|
+
| 类别 | 函数 | 说明 |
|
|
179
|
+
|------|------|------|
|
|
180
|
+
| 构造 | MakePoint(x, y [, srid]) | 构造点 |
|
|
181
|
+
| 构造 | GeomFromText(wkt [, srid]) / ST_GeomFromText | WKT 转几何 |
|
|
182
|
+
| 输出 | AsText(geom) / ST_AsText | 几何转 WKT |
|
|
183
|
+
| 输出 | AsBinary(geom) / AsGeoJSON(geom) | WKB / GeoJSON |
|
|
184
|
+
| 谓词 | ST_Intersects / ST_Contains / ST_Within / ST_Touches / ST_Crosses / ST_Disjoint | OGC 关系 |
|
|
185
|
+
| 谓词 | MbrWithin / MbrIntersects / MbrDisjoint | 仅比较包围盒,最快 |
|
|
186
|
+
| 度量 | ST_Area / ST_Length / ST_Distance / ST_Perimeter | 平面度量(单位随 SRID) |
|
|
187
|
+
| 运算 | ST_Buffer / ST_Intersection / ST_Union / ST_Difference / ST_ConvexHull | GEOS 运算 |
|
|
188
|
+
| 转换 | ST_Transform(geom, srid) | 坐标转换(需 PROJ) |
|
|
189
|
+
| 修复 | ST_MakeValid / GeosMakeValid / ST_IsValid | 无效几何处理 |
|
|
190
|
+
|
|
191
|
+
```sql
|
|
192
|
+
-- 5 公里内的点(先用 MBR 粗筛走索引,再精算距离)
|
|
193
|
+
SELECT a.name, b.name, ST_Distance(a.geom, b.geom) AS deg
|
|
194
|
+
FROM poi a, poi b
|
|
195
|
+
WHERE a.id < b.id
|
|
196
|
+
AND MbrWithin(b.geom, ST_Buffer(a.geom, 0.05))
|
|
197
|
+
AND ST_Distance(a.geom, b.geom) < 0.05;
|
|
198
|
+
|
|
199
|
+
-- 投影到米制后再算距离,避免"度"当"米"
|
|
200
|
+
SELECT ST_Distance(ST_Transform(a.geom, 3857), ST_Transform(b.geom, 3857)) AS meters
|
|
201
|
+
FROM poi a, poi b
|
|
202
|
+
WHERE a.id = 1 AND b.id = 2;
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### 元数据与图层信息
|
|
206
|
+
|
|
207
|
+
```sql
|
|
208
|
+
-- 库里有哪些几何列
|
|
209
|
+
SELECT f_table_name, f_geometry_column, geometry_type, srid, spatial_index_enabled
|
|
210
|
+
FROM geometry_columns;
|
|
211
|
+
|
|
212
|
+
-- 某图层的包围盒
|
|
213
|
+
SELECT ST_AsText(ST_Envelope(ST_Collect(geom))) FROM poi;
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## 典型工作流:Shapefile → SpatiaLite → 空间查询 → 导出
|
|
217
|
+
|
|
218
|
+
输入 `data/roads.shp` 与 `data/cities.shp`,目标是找出每条道路 2 公里内的城市并导出结果表。
|
|
219
|
+
|
|
220
|
+
**步骤 1:导入(两种方式任选)**
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
# 方式 A:spatialite_tool(参数随版本略有差异,先跑 --help 确认)
|
|
224
|
+
spatialite_tool --help
|
|
225
|
+
|
|
226
|
+
# 方式 B:ogr2ogr(GDAL,最稳定,强烈推荐)
|
|
227
|
+
ogr2ogr -f SQLite -dsco SPATIALITE=YES out.gis.sqlite data/roads.shp -nln roads
|
|
228
|
+
ogr2ogr -f SQLite -dsco SPATIALITE=YES -append out.gis.sqlite data/cities.shp -nln cities
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`-dsco SPATIALITE=YES` 让 GDAL 按 SpatiaLite 格式写库(而不是纯 SQLite 表);导入后 GDAL 会建好元数据与索引。
|
|
232
|
+
|
|
233
|
+
**步骤 2:初始化并核对**
|
|
234
|
+
|
|
235
|
+
```python
|
|
236
|
+
import sqlite3
|
|
237
|
+
|
|
238
|
+
con = sqlite3.connect("out.gis.sqlite")
|
|
239
|
+
con.enable_load_extension(True)
|
|
240
|
+
con.load_extension("mod_spatialite")
|
|
241
|
+
con.enable_load_extension(False)
|
|
242
|
+
|
|
243
|
+
# 若库是新建的空库,先执行一次
|
|
244
|
+
# con.execute("SELECT InitSpatialMetaData(1)")
|
|
245
|
+
|
|
246
|
+
for row in con.execute("""
|
|
247
|
+
SELECT f_table_name, f_geometry_column, geometry_type, srid, spatial_index_enabled
|
|
248
|
+
FROM geometry_columns
|
|
249
|
+
"""):
|
|
250
|
+
print(row)
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
**步骤 3:空间查询**
|
|
254
|
+
|
|
255
|
+
```python
|
|
256
|
+
rows = con.execute("""
|
|
257
|
+
SELECT r.name AS road, c.name AS city,
|
|
258
|
+
ST_Distance(ST_Transform(r.geom, 3857),
|
|
259
|
+
ST_Transform(c.geom, 3857)) AS meters
|
|
260
|
+
FROM roads r
|
|
261
|
+
JOIN cities c
|
|
262
|
+
ON MbrWithin(c.geom, ST_Buffer(r.geom, 0.02))
|
|
263
|
+
AND ST_Distance(r.geom, c.geom) < 0.02
|
|
264
|
+
ORDER BY meters
|
|
265
|
+
""").fetchall()
|
|
266
|
+
print(len(rows), "pairs")
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
**步骤 4:导出结果**
|
|
270
|
+
|
|
271
|
+
```python
|
|
272
|
+
con.execute("""
|
|
273
|
+
CREATE TABLE road_city AS
|
|
274
|
+
SELECT r.name AS road, c.name AS city,
|
|
275
|
+
ST_Distance(ST_Transform(r.geom, 3857),
|
|
276
|
+
ST_Transform(c.geom, 3857)) AS meters
|
|
277
|
+
FROM roads r
|
|
278
|
+
JOIN cities c
|
|
279
|
+
ON MbrWithin(c.geom, ST_Buffer(r.geom, 0.02))
|
|
280
|
+
AND ST_Distance(r.geom, c.geom) < 0.02
|
|
281
|
+
""")
|
|
282
|
+
con.commit()
|
|
283
|
+
print(con.execute("SELECT count(*) FROM road_city").fetchone())
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
# 用 GDAL 把结果导成 GeoPackage / GeoJSON
|
|
288
|
+
ogr2ogr -f GPKG out/road_city.gpkg out.gis.sqlite road_city
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
**步骤 5:验收**
|
|
292
|
+
|
|
293
|
+
```bash
|
|
294
|
+
ogrinfo -so out/road_city.gpkg road_city | head -20
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
确认要素数、几何类型与 SRID 与预期一致。
|
|
298
|
+
|
|
299
|
+
## 与 Python 生态配合
|
|
300
|
+
|
|
301
|
+
```python
|
|
302
|
+
import sqlite3
|
|
303
|
+
import geopandas as gpd
|
|
304
|
+
|
|
305
|
+
con = sqlite3.connect("out.gis.sqlite")
|
|
306
|
+
con.enable_load_extension(True)
|
|
307
|
+
con.load_extension("mod_spatialite")
|
|
308
|
+
con.enable_load_extension(False)
|
|
309
|
+
|
|
310
|
+
# 读成 GeoDataFrame(GeoPandas 走 pyogrio/GDAL,会自动识别 SpatiaLite)
|
|
311
|
+
gdf = gpd.read_file("out.gis.sqlite", layer="cities")
|
|
312
|
+
|
|
313
|
+
# 用 SQL 结果再构造 GeoDataFrame
|
|
314
|
+
rows = con.execute("SELECT name, AsText(geom) FROM cities").fetchall()
|
|
315
|
+
print(rows[:3])
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
注意:GeoPandas 读 SpatiaLite 依赖 GDAL 的 SQLite 驱动;写回时用 `gdf.to_file("out.gis.sqlite", layer="new_layer", driver="SQLite")` 即可。
|
|
319
|
+
|
|
320
|
+
## 最佳实践
|
|
321
|
+
|
|
322
|
+
1. **几何列一定用 AddGeometryColumn 建**:手写 geometry 列会绕过元数据与触发器,后续空间函数找不到列。
|
|
323
|
+
2. **InitSpatialMetaData 只跑一次**:新库初始化后不要重复执行;用 `'WGS84'` 模式可以显著缩小 spatial_ref_sys。
|
|
324
|
+
3. **先 MBR 粗筛再精算**:`MbrWithin` / `MbrIntersects` 能吃到 RTree 索引,直接对全部行跑 ST_Distance 会很慢。
|
|
325
|
+
4. **SRID 必须一致**:不同 SRID 的几何不能直接比较,先 `ST_Transform` 统一。
|
|
326
|
+
5. **单位意识**:4326 下 ST_Distance 返回"度"、ST_Area 返回"平方度";要米就投到米制投影(如 3857)。
|
|
327
|
+
6. **空间索引用 CheckSpatialIndex 体检**:批量导入或大量 UPDATE 之后跑一次,确认索引与主表同步。
|
|
328
|
+
7. **交换数据优先 GPKG**:SpatiaLite 专有函数多,跨工具可移植性不如 GeoPackage。
|
|
329
|
+
8. **写事务要提交**:Python 里 `con.commit()`,否则 `CreateSpatialIndex` 的触发器与数据都不落盘。
|
|
330
|
+
|
|
331
|
+
## 常见问题
|
|
332
|
+
|
|
333
|
+
| 问题 | 原因 | 解决方案 |
|
|
334
|
+
|------|------|---------|
|
|
335
|
+
| no such function: InitSpatialMetaData | 扩展未加载,或加载的是空壳库 | 先 `.load mod_spatialite`(CLI)或 `load_extension("mod_spatialite")`(Python),用 `spatialite_version()` 验证 |
|
|
336
|
+
| no such module: mod_spatialite | 动态库不在搜索路径 | 指定绝对路径加载;Linux 装 `libsqlite3-mod-spatialite`,Windows 把 DLL 放同目录或加 PATH |
|
|
337
|
+
| Python 报 "not authorized" / 无法 enable_load_extension | 解释器禁用了扩展加载 | 用系统 Python 或开启 `--enable-loadable-sqlite-extensions` 的构建;PyPI 的 `pysqlite3-binary` 可用于替换 |
|
|
338
|
+
| CLI 里 `.load` 报加载失败 | 动态库路径不对,或 shell 与库的位数/构建不匹配 | 先用 `python -c` 那条验证库本身可加载,再在 CLI 里给绝对路径;仍失败时改用 Python 或 GDAL 路径 |
|
|
339
|
+
| CreateSpatialIndex 返回 -1 | 表里存在名为 rowid 的物理列,遮蔽了真实 ROWID | 重命名该列后再建索引 |
|
|
340
|
+
| ST_Intersects 报 "geometry has invalid SRID" | 混入了 SRID 为 -1 或 0 的几何 | 用 `GeomFromText(wkt, 4326)` 或 `ST_Transform` 赋上正确 SRID |
|
|
341
|
+
| 空间查询依旧很慢 | 只用了 ST_Distance,没有 MBR 前置条件 | 先加 `MbrWithin` 或 `MbrIntersects` 条件让 RTree 生效,再精确判断 |
|
|
342
|
+
| apt 装的版本比官网旧 | 发行版冻结版本 | 需要 5.1.0 特性时用 conda-forge,或从源码编译 |
|
|
343
|
+
| 用 GDAL 打开 SQLite 库看不到图层 | 库不是 SpatiaLite 格式 | 导入时加 `-dsco SPATIALITE=YES`;已存在的库可用 GDAL 的 `SQLite` 驱动按层读取 |
|
|
344
|
+
|
|
345
|
+
## AI 使用建议
|
|
346
|
+
|
|
347
|
+
- **先确认库能被加载**:任何排查都从 `python -c "import sqlite3; c=sqlite3.connect(':memory:'); c.enable_load_extension(True); c.load_extension('mod_spatialite')"` 开始;库加载不了时,SQL 报错没有诊断价值。
|
|
348
|
+
- **版本差异**:SpatiaLite 5.x 的函数集与 4.x 不同(如 `GeosMakeValid`、`InitSpatialMetaData` 的重载)。动手前查 `spatialite_version()`,并按官方函数参考核对函数名与参数。
|
|
349
|
+
- **优先用 ogr2ogr 导入**:命令行工具的参数在不同构建间不一致,GDAL 的 `-dsco SPATIALITE=YES` 路径最稳定;确需 `spatialite_tool` 时先跑 `--help` 核对参数。
|
|
350
|
+
- **验证产物**:导入或建索引后回读 `geometry_columns`(几何列、SRID、spatial_index_enabled)与 `CheckSpatialIndex(`…`)`,确认索引真的生效,再宣称"查询已优化"。
|
|
351
|
+
- **写操作确认**:`DROP TABLE`、`DisableSpatialIndex`、批量 `DELETE` 不可回滚到旧状态(SQLite 事务只保护单次会话);执行前备份 .sqlite 文件。
|
|
352
|
+
|
|
353
|
+
## 相关技能
|
|
354
|
+
|
|
355
|
+
- **postgis** — 服务端空间数据库,能力更完整:[../postgis/SKILL.md](../postgis/SKILL.md)
|
|
356
|
+
- **gdal** — ogr2ogr 导入导出,事实上的稳定路径:[../gdal/SKILL.md](../gdal/SKILL.md)
|
|
357
|
+
- **geopandas** — Python 侧读写 SpatiaLite/GPKG:[../geopandas/SKILL.md](../geopandas/SKILL.md)
|
|
358
|
+
- **duckdb-spatial** — 另一种嵌入式空间分析方案:[../duckdb-spatial/SKILL.md](../duckdb-spatial/SKILL.md)
|
|
359
|
+
- **proj** — ST_Transform 依赖的坐标转换库:[../proj/SKILL.md](../proj/SKILL.md)
|
|
360
|
+
|
|
361
|
+
## 参考资源
|
|
362
|
+
- 官方主页(fossil 仓库):<https://www.gaia-gis.it/fossil/libspatialite/index>
|
|
363
|
+
- SQL 函数参考:<https://www.gaia-gis.it/gaia-sins/spatialite-sql-latest.html>
|
|
364
|
+
- spatialite-tools:<https://www.gaia-gis.it/fossil/spatialite-tools/index>
|
|
365
|
+
- GeoPackage 标准:<https://www.geopackage.org/>
|
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: whitebox-tools
|
|
3
|
+
description: "Use when doing advanced raster, terrain or LiDAR geoprocessing with WhiteboxTools v2.4.0 — whitebox_tools --run=Slope/FillDepressions/BreachDepressions/FlowAccumulationFullWorkflow/Watershed/ExtractStreams, lidar_* tools for LAS point clouds, or the whitebox (whitebox-python 2.3.6) WhiteboxTools wrapper in Python. Also for 'whitebox_tools: command not found', mismatched Python frontend versions, and missing DEM/flow-accumulation intermediate outputs."
|
|
4
|
+
tags:
|
|
5
|
+
- geospatial
|
|
6
|
+
- raster
|
|
7
|
+
- terrain-analysis
|
|
8
|
+
- hydrology
|
|
9
|
+
- lidar
|
|
10
|
+
- dem
|
|
11
|
+
- command-line
|
|
12
|
+
- python
|
|
13
|
+
- rust
|
|
14
|
+
- geoprocessing
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
> **项目地址:** <https://github.com/jblindsay/whitebox-tools>
|
|
18
|
+
>
|
|
19
|
+
> **官方文档:** 用户手册站 <https://www.whiteboxgeo.com/manual/wbt_book/preface.html>(2026-10 实测返回 404,暂以仓库 README 与 `UserManual.txt` 为可访问入口)
|
|
20
|
+
>
|
|
21
|
+
> **最新版本:** 2.4.0(GitHub Release,截至 2026-10)
|
|
22
|
+
>
|
|
23
|
+
> **PyPI 前端:** `whitebox` 2.3.6(whitebox-python 封装,仅负责下载与调用二进制,版本号落后于核心库)
|
|
24
|
+
>
|
|
25
|
+
> **许可证:** MIT
|
|
26
|
+
>
|
|
27
|
+
> **注意:** 上游仓库 README 已标记为 legacy,新开发转向 <https://github.com/jblindsay/whitebox_next_gen>;但 2.4.0 仍是当前稳定可用的开源版本,本文以其为基准。
|
|
28
|
+
|
|
29
|
+
## 概述
|
|
30
|
+
|
|
31
|
+
WhiteboxTools 是圭尔夫大学 GHRG 实验室(John Lindsay)用 Rust 编写的独立地理空间分析引擎,面向「分析后端」而非制图:它不渲染地图,只接收栅格/矢量/LAS 输入并产出分析结果。相比通用 GIS 桌面软件,它的优势在于命令行与脚本化,几百个工具都能通过统一参数形式批量执行,适合 DEM 地形分析、水文建模与 LiDAR 处理流水线。
|
|
32
|
+
|
|
33
|
+
- **地形分析**:坡度、坡向、曲率、山体阴影、相对高程、地形位置指数(TPI)、多尺度位置分析
|
|
34
|
+
- **水文分析**:洼地填充/决口、D8/DInf/FD8 流向与流量累积、河网提取、Strahler 分级、流域划分
|
|
35
|
+
- **LiDAR**:点云信息与直方图、按类别过滤、去噪、地面点分类、插值成 DEM、密度与强度栅格
|
|
36
|
+
- **栅格与矢量工具**:栅格计算器、重分类、分区统计、矢量栅格互转、要素裁剪与合并
|
|
37
|
+
- **统一接口**:`whitebox_tools --run=<ToolName> [参数]`,另有 `--toolhelp`、`--toolparameters` 查询元数据
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 环境准备
|
|
42
|
+
|
|
43
|
+
### 方式一:下载预编译二进制(推荐)
|
|
44
|
+
|
|
45
|
+
到 <https://github.com/jblindsay/whitebox-tools/releases> 下载对应平台的预编译压缩包,解压后目录内含 `whitebox_tools`(Windows 为 `whitebox_tools.exe`)与 `WBT` 插件目录。
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
cd /opt/WBT # 解压后的 WBT 目录
|
|
49
|
+
./whitebox_tools --version
|
|
50
|
+
./whitebox_tools --listtools slope | head -5
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```powershell
|
|
54
|
+
# Windows PowerShell
|
|
55
|
+
cd C:\Tools\WBT
|
|
56
|
+
.\whitebox_tools.exe --version
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### 方式二:源码编译(适合无预编译包的平台)
|
|
60
|
+
|
|
61
|
+
需要 Rust 工具链;Windows 上还需 MSVC 或 GNU 链接器。仓库根目录的 `build.py` 会调用 `cargo` 并把产物整理到 `WBT/`。
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
git clone https://github.com/jblindsay/whitebox-tools.git
|
|
65
|
+
cd whitebox-tools
|
|
66
|
+
python build.py
|
|
67
|
+
./WBT/whitebox_tools --version
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### 方式三:Python 前端(`whitebox` 包)
|
|
71
|
+
|
|
72
|
+
`whitebox-python` 是社区维护的封装,首次运行会下载 / 复用 WBT 二进制;它不提升核心工具版本,因此工具能力以二进制实际版本为准。
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
pip install whitebox==2.3.6
|
|
76
|
+
|
|
77
|
+
# 或 conda
|
|
78
|
+
conda install -c conda-forge whitebox
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
import whitebox
|
|
83
|
+
print(whitebox.__version__) # 2.3.6 —— 这是 Python 封装版本
|
|
84
|
+
|
|
85
|
+
wbt = whitebox.WhiteboxTools()
|
|
86
|
+
wbt.set_verbose_mode(False)
|
|
87
|
+
print(wbt.version()) # 打印底层 WhiteboxTools 二进制版本
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**验证要点**:`--version` 输出的是核心库版本;Python 包版本号与核心库不一致属正常现象,排错时以 `--version` 为准。
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 核心命令
|
|
95
|
+
|
|
96
|
+
### 命令行骨架
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
whitebox_tools --wd="data/" --run=Slope --dem=input.tif --output=slope.tif --units=degrees -v
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
| 参数 | 作用 |
|
|
103
|
+
|------|------|
|
|
104
|
+
| `--wd` / `--cd` | 切换工作目录;与 `--run` 连用,之后的相对路径都基于它 |
|
|
105
|
+
| `-r` / `--run` | 指定工具名(CamelCase),如 `Slope`、`FillDepressions` |
|
|
106
|
+
| `-v` | 详细模式,打印进度与耗时;`-v=false` 关闭 |
|
|
107
|
+
| `--listtools [关键词]` | 列出工具及描述,可按关键词过滤 |
|
|
108
|
+
| `--toolhelp=<Tool>` | 打印某工具的使用帮助 |
|
|
109
|
+
| `--toolparameters=<Tool>` | 以 JSON 输出参数定义,适合脚本动态组装参数 |
|
|
110
|
+
| `--version` | 版本信息 |
|
|
111
|
+
|
|
112
|
+
**不要凭记忆写参数名**:不同工具的参数差异很大(例如坡度用 `--units`,流量累积工作流用五个 `--out_*` 参数)。写脚本前先 `--toolparameters` 取 JSON,再据此拼参数。
|
|
113
|
+
|
|
114
|
+
### 常用工具速查
|
|
115
|
+
|
|
116
|
+
| 工具名 | 作用 | 关键参数 |
|
|
117
|
+
|--------|------|----------|
|
|
118
|
+
| `Slope` | 坡度栅格 | `--dem`、`--output`、`--units`(degrees/radians/percent)、`--zfactor` |
|
|
119
|
+
| `Aspect` | 坡向 | `--dem`、`--output` |
|
|
120
|
+
| `Hillshade` | 山体阴影 | `--dem`、`--output`、`--azimuth`、`--altitude`、`--zfactor` |
|
|
121
|
+
| `FillDepressions` | 填洼 | `--dem`、`--output`、`--fix_flats`、`--flat_increment` |
|
|
122
|
+
| `BreachDepressions` | 洼地决口(保留更多地形细节) | `--dem`、`--output`、`--max_depth`、`--max_length`、`--fill_pits` |
|
|
123
|
+
| `D8Pointer` | D8 流向 | `--dem`、`--output`、`--esri_pntr` |
|
|
124
|
+
| `D8FlowAccumulation` | D8 流量累积 | `--input`、`--output`、`--out_type` |
|
|
125
|
+
| `FlowAccumulationFullWorkflow` | 一键:决口 + 流向 + 累积 | `--dem`、`--out_dem`、`--out_pntr`、`--out_accum`、`--out_type` |
|
|
126
|
+
| `ExtractStreams` | 阈值法提取河网 | `--flow_accum`、`--output`、`--threshold` |
|
|
127
|
+
| `StrahlerStreamOrder` | 河网 Strahler 分级 | `--streams`、`--d8_pntr`、`--output` |
|
|
128
|
+
| `Watershed` | 由流向与倾泻点划分流域 | `--d8_pntr`、`--pour_pts`、`--output` |
|
|
129
|
+
| `LidarInfo` | LAS/LAZ 基本信息 | `--input` |
|
|
130
|
+
| `LidarPointDensity` | 点密度栅格 | `--input`、`--output`、`--cell_size` |
|
|
131
|
+
| `LidarHillshade` | 点云生成山体阴影 | `--input`、`--output`、`--azimuth`、`--altitude` |
|
|
132
|
+
| `Mosaic` | 多栅格拼接 | `--inputs`、`--output` |
|
|
133
|
+
| `Clip` | 按矢量范围裁剪栅格 | `--input`、`--clip`、`--output` |
|
|
134
|
+
|
|
135
|
+
完整列表用 `whitebox_tools --listtools`;以下为常用子集,参数以 `--toolparameters` 输出为准。
|
|
136
|
+
|
|
137
|
+
### Python 调用
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from whitebox import WhiteboxTools
|
|
141
|
+
|
|
142
|
+
wbt = WhiteboxTools()
|
|
143
|
+
wbt.set_working_dir("data")
|
|
144
|
+
wbt.set_verbose_mode(False)
|
|
145
|
+
|
|
146
|
+
# 方法名是工具名的 snake_case 形式,参数名与 CLI 的路由一致
|
|
147
|
+
wbt.slope(dem="dem.tif", output="slope.tif", units="degrees")
|
|
148
|
+
wbt.hillshade(dem="dem.tif", output="hillshade.tif", azimuth=315.0, altitude=30.0)
|
|
149
|
+
|
|
150
|
+
# 任何工具都能用 run_tool 统一调用
|
|
151
|
+
wbt.run_tool("FillDepressions", ["--dem=dem.tif", "--output=dem_filled.tif", "--fix_flats=true"])
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
`run_tool(tool_name, args)` 的 `args` 是 `--flag=value` 字符串列表,适合官方封装尚未覆盖的新工具;两种方式可混用。
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## 典型工作流
|
|
159
|
+
|
|
160
|
+
从原始 DEM 到河网与流域的完整水文分析:
|
|
161
|
+
|
|
162
|
+
**输入**:`data/dem.tif`(投影坐标系 DEM,水平与垂直单位一致)
|
|
163
|
+
**输出**:`watershed.tif`、`streams.tif`、`accum.tif`
|
|
164
|
+
|
|
165
|
+
1. 先检查 DEM 是否有异常值与坐标系单位
|
|
166
|
+
2. 用 `FlowAccumulationFullWorkflow` 一次完成决口、流向与流量累积,避免中间文件散落
|
|
167
|
+
3. 用流量累积的阈值提取河网
|
|
168
|
+
4. 按倾泻点划分流域(倾泻点可先用 `SnapPourPoints` 吸附到河网)
|
|
169
|
+
5. 如需河网矢量,用 `RasterStreamsToVector`
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
cd /opt/WBT
|
|
173
|
+
|
|
174
|
+
# 1) 决口 + D8 流向 + 流量累积
|
|
175
|
+
./whitebox_tools --wd="D:/work/hydro" --run=FlowAccumulationFullWorkflow \
|
|
176
|
+
--dem=dem.tif --out_dem=dem_breached.tif \
|
|
177
|
+
--out_pntr=flow_pntr.tif --out_accum=accum.tif --out_type=cells -v
|
|
178
|
+
|
|
179
|
+
# 2) 阈值提取河网(阈值随分辨率与气候区调整,先看累积值分布)
|
|
180
|
+
./whitebox_tools --wd="D:/work/hydro" --run=ExtractStreams \
|
|
181
|
+
--flow_accum=accum.tif --output=streams.tif --threshold=1000 -v
|
|
182
|
+
|
|
183
|
+
# 3) 倾泻点吸附后划分流域
|
|
184
|
+
./whitebox_tools --wd="D:/work/hydro" --run=SnapPourPoints \
|
|
185
|
+
--pour_pts=pour_pts.shp --flow_accum=accum.tif --snap_dist=3 --output=pour_pts_snapped.shp -v
|
|
186
|
+
./whitebox_tools --wd="D:/work/hydro" --run=Watershed \
|
|
187
|
+
--d8_pntr=flow_pntr.tif --pour_pts=pour_pts_snapped.shp --output=watershed.tif -v
|
|
188
|
+
|
|
189
|
+
# 4) 河网转矢量(可选)
|
|
190
|
+
./whitebox_tools --wd="D:/work/hydro" --run=RasterStreamsToVector \
|
|
191
|
+
--streams=streams.tif --d8_pntr=flow_pntr.tif --output=streams.shp -v
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Python 等价写法:
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
from whitebox import WhiteboxTools
|
|
198
|
+
|
|
199
|
+
wbt = WhiteboxTools()
|
|
200
|
+
wbt.set_working_dir("D:/work/hydro")
|
|
201
|
+
|
|
202
|
+
wbt.flow_accumulation_full_workflow(
|
|
203
|
+
dem="dem.tif",
|
|
204
|
+
out_dem="dem_breached.tif",
|
|
205
|
+
out_pntr="flow_pntr.tif",
|
|
206
|
+
out_accum="accum.tif",
|
|
207
|
+
out_type="cells",
|
|
208
|
+
)
|
|
209
|
+
wbt.extract_streams(flow_accum="accum.tif", output="streams.tif", threshold=1000)
|
|
210
|
+
wbt.watershed(d8_pntr="flow_pntr.tif", pour_pts="pour_pts_snapped.shp", output="watershed.tif")
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
**检查点**:`accum.tif` 的极值应与流域面积量级相符;若所有像元值都是 1,通常是 DEM 单位不一致或流向计算被平坦区阻断。
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## 最佳实践
|
|
218
|
+
|
|
219
|
+
1. **统一单位与坐标系**:DEM 用投影坐标系,水平/垂直单位不同时显式传 `--zfactor`,否则坡度与累积结果会有系统性偏差
|
|
220
|
+
2. **决口优先于填洼**:`BreachDepressions` 保留更多真实地形细节,平坦区多时才回退 `FillDepressions`
|
|
221
|
+
3. **阈值要试算**:`ExtractStreams` 的 `--threshold` 与分辨率强相关,先统计累积栅格分布,再取值对比
|
|
222
|
+
4. **用 `--toolparameters` 驱动脚本**:自动化流水线里先取 JSON 参数定义,避免版本升级后参数改名导致静默失败
|
|
223
|
+
5. **中间文件显式命名**:把 `dem_breached`、`flow_pntr`、`accum` 分开存,便于复算与排错
|
|
224
|
+
6. **LiDAR 先探测再处理**:`LidarInfo` 确认点数、范围与坐标系,再做分类与插值;大文件先 `LidarTile` 分块
|
|
225
|
+
7. **批量任务按 CPU 数并行**:多个独立工具调用可并行,同一 DEM 的上下游步骤必须串行
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 常见问题
|
|
230
|
+
|
|
231
|
+
| 问题 | 原因与解决 |
|
|
232
|
+
|------|------------|
|
|
233
|
+
| `whitebox_tools: command not found` | 二进制目录未加入 PATH:`cd` 到 WBT 目录执行,或把该目录加进 PATH;Windows 注意加 `.exe` |
|
|
234
|
+
| 运行后没有任何输出文件,也没有报错 | 相对路径基于 `--wd`:确认 `--wd` 指向数据目录,或全部改用绝对路径 |
|
|
235
|
+
| `--run` 后提示工具不存在 | 工具名必须是 CamelCase(如 `FillDepressions`);用 `--listtools` 确认真实名称 |
|
|
236
|
+
| 参数名报错或参数被忽略 | 参数名随工具而异:用 `--toolparameters=<Tool>` 取 JSON 定义,不要照抄别的工具的参数 |
|
|
237
|
+
| Python 里 `wbt.version()` 与 pip 版本不一致 | 正常现象:pip 版本是 Python 封装版本,二进制版本由下载器决定;能力差异以二进制为准 |
|
|
238
|
+
| 水系的流量累积结果异常(全为 1 或极大值) | DEM 未决口/填洼,或单位不一致;先跑 `BreachDepressions` 并检查 `--zfactor` |
|
|
239
|
+
| 平坦区出现大片无流向像元 | 填洼时未处理平坦区:`FillDepressions` 打开 `--fix_flats=true`,或改用 `BreachDepressions` |
|
|
240
|
+
| LiDAR 工具报格式不支持 | 输入需为 LAS/LAZ;若为其他点云格式,先用 PDAL 转换 |
|
|
241
|
+
| 处理大 DEM 时内存占用过高 | 先 `Clip` 到研究区,或分块处理后再 `Mosaic` 合并 |
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## AI 使用建议
|
|
246
|
+
|
|
247
|
+
- **执行环境**:`python build.py` 编译耗时可达数分钟,放后台任务;`pip install whitebox` 首次调用会联网下载二进制,离线环境需先手动放置 WBT。
|
|
248
|
+
- **先探测版本**:`whitebox_tools --version` 确认核心版本(本文基准 2.4.0);`python -c "import whitebox; print(whitebox.__version__)"` 确认前端(2.3.6)。两者不一致时以二进制为准并明确告知用户。
|
|
249
|
+
- **验证产物**:用 `ls -l` 检查输出文件是否生成,再用 GDAL(`gdalinfo` / `python -c "import rasterio..."`)读取数值范围做断言;只看命令退出码不足以证明分析正确。
|
|
250
|
+
- **失败信号**:无输出且无报错几乎都是工作目录或路径问题;参数被忽略多为参数名拼错,用 `--toolparameters` 核对。
|
|
251
|
+
- **常见症状**:累积值异常先查决口与单位;平坦区无流向查 `--fix_flats`;LiDAR 报错先查 LAS/LAZ 格式。
|
|
252
|
+
- **安全与权限**:编译、安装、下载二进制前先征得用户同意;批量处理前确认磁盘占用。
|
|
253
|
+
|
|
254
|
+
## 相关技能
|
|
255
|
+
|
|
256
|
+
- **gdal** — 栅格/矢量格式转换与重投影,常作为 WBT 前后处理:[../gdal/SKILL.md](../gdal/SKILL.md)
|
|
257
|
+
- **pdal** — LiDAR 点云格式转换与滤波,与 WBT 的 LiDAR 工具互补:[../pdal/SKILL.md](../pdal/SKILL.md)
|
|
258
|
+
- **grass-gis** — 另一套水文与地形分析工具链,可交叉验证结果:[../grass-gis/SKILL.md](../grass-gis/SKILL.md)
|
|
259
|
+
- **qgis-process** — 通过 qgis_process 调用 QGIS 原生算法,做流程编排与出图:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
|
|
260
|
+
- **proj** — 坐标系定义与转换,处理 DEM CRS 时常用:[../proj/SKILL.md](../proj/SKILL.md)
|
|
261
|
+
|
|
262
|
+
## 参考资源
|
|
263
|
+
|
|
264
|
+
- 用户手册(上游 README 标注的地址,2026-10 实测 404):<https://www.whiteboxgeo.com/manual/wbt_book/preface.html>
|
|
265
|
+
- 可访问的用法说明:仓库 README 与 `UserManual.txt` <https://github.com/jblindsay/whitebox-tools>
|
|
266
|
+
- 源码与 Issue:<https://github.com/jblindsay/whitebox-tools>
|
|
267
|
+
- 后继项目:<https://github.com/jblindsay/whitebox_next_gen>
|
|
268
|
+
- Python 封装:<https://github.com/opengeos/whitebox-python>
|
|
269
|
+
- 预编译二进制:<https://github.com/jblindsay/whitebox-tools/releases>
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/** Directory (relative to the package root) holding the DSH adaptation files. */
|
|
2
|
+
export declare const ADAPTATION_DIRECTORY: "adaptations";
|
|
3
|
+
|
|
4
|
+
/** File name of the guidance shared by every skill. */
|
|
5
|
+
export declare const COMMON_FILE: "common.md";
|
|
6
|
+
|
|
7
|
+
/** Heading the shared guidance must start with. */
|
|
8
|
+
export declare const COMMON_HEADING: "## DeepSeek Harness 通用约定";
|
|
9
|
+
|
|
10
|
+
/** Heading every per-skill guidance must start with. */
|
|
11
|
+
export declare const SKILL_HEADING: "## DeepSeek Harness 使用建议";
|
|
12
|
+
|
|
13
|
+
/** Separator between the upstream body and the DSH guidance block. */
|
|
14
|
+
export declare const SKILL_SEPARATOR: string;
|
|
15
|
+
|
|
16
|
+
/** Labels every per-skill guidance must keep, in this order. */
|
|
17
|
+
export declare const REQUIRED_LABELS: readonly string[];
|
|
18
|
+
|
|
19
|
+
/** Build the path of one per-skill adaptation file. */
|
|
20
|
+
export declare function adaptationFile(root: string, name: string): string;
|
|
21
|
+
|
|
22
|
+
/** Build the path of the shared adaptation file. */
|
|
23
|
+
export declare function commonFile(root: string): string;
|
|
24
|
+
|
|
25
|
+
/** Read and normalize one per-skill adaptation file (synchronous). */
|
|
26
|
+
export declare function readAdaptationSync(root: string, name: string): string;
|
|
27
|
+
|
|
28
|
+
/** Read and normalize the shared adaptation file (synchronous). */
|
|
29
|
+
export declare function readCommonSync(root: string): string;
|
|
30
|
+
|
|
31
|
+
/** Read one per-skill adaptation file (asynchronous). */
|
|
32
|
+
export declare function readAdaptation(root: string, name: string, signal?: AbortSignal): Promise<string>;
|
|
33
|
+
|
|
34
|
+
/** Read the shared adaptation file (asynchronous). */
|
|
35
|
+
export declare function readCommon(root: string, signal?: AbortSignal): Promise<string>;
|
|
36
|
+
|
|
37
|
+
/** List the adaptation file base names (without ".md"), sorted. */
|
|
38
|
+
export declare function listAdaptations(root: string): string[];
|
|
39
|
+
|
|
40
|
+
/** Append the DSH guidance block to one upstream skill body. */
|
|
41
|
+
export declare function composeSkillContent(base: string, adaptation: string, common: string): string;
|
|
42
|
+
|
|
43
|
+
/** Report every problem with one per-skill adaptation file. */
|
|
44
|
+
export declare function adaptationProblems(name: string, text: string): string[];
|
|
45
|
+
|
|
46
|
+
/** Report every problem with the shared adaptation file. */
|
|
47
|
+
export declare function commonProblems(text: string): string[];
|