@dsh-gis/dsh-opengis-skill 0.1.2 → 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.
Files changed (97) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +79 -43
  3. package/THIRD_PARTY_NOTICES.md +9 -0
  4. package/adaptations/brutile.md +8 -0
  5. package/adaptations/cesiumjs.md +8 -0
  6. package/adaptations/common.md +16 -0
  7. package/adaptations/deck-gl.md +8 -0
  8. package/adaptations/duckdb-spatial.md +8 -0
  9. package/adaptations/gdal-api.md +8 -0
  10. package/adaptations/gdal.md +8 -0
  11. package/adaptations/geolibre.md +8 -0
  12. package/adaptations/geometry-api-java.md +8 -0
  13. package/adaptations/geometry-api-net.md +8 -0
  14. package/adaptations/geonode.md +8 -0
  15. package/adaptations/geopandas.md +8 -0
  16. package/adaptations/geopipe-agent.md +8 -0
  17. package/adaptations/geoserver-cloud.md +8 -0
  18. package/adaptations/geoserver-rest-api.md +8 -0
  19. package/adaptations/geoserver.md +8 -0
  20. package/adaptations/geotools.md +8 -0
  21. package/adaptations/grass-gis.md +8 -0
  22. package/adaptations/jts.md +8 -0
  23. package/adaptations/kepler-gl.md +8 -0
  24. package/adaptations/leaflet.md +8 -0
  25. package/adaptations/mapbox-gl-js.md +8 -0
  26. package/adaptations/mapserver.md +8 -0
  27. package/adaptations/mapsui.md +8 -0
  28. package/adaptations/nettopologysuite.md +8 -0
  29. package/adaptations/opengis-all.md +8 -0
  30. package/adaptations/opengis-daf.md +8 -0
  31. package/adaptations/opengis-utils-for-java.md +8 -0
  32. package/adaptations/opengis-utils-for-net.md +8 -0
  33. package/adaptations/openlayers.md +8 -0
  34. package/adaptations/pdal.md +8 -0
  35. package/adaptations/postgis.md +8 -0
  36. package/adaptations/proj.md +8 -0
  37. package/adaptations/projnet4geoapi.md +8 -0
  38. package/adaptations/pyqgis.md +8 -0
  39. package/adaptations/qgis-process.md +8 -0
  40. package/adaptations/qgis-server.md +8 -0
  41. package/adaptations/shapely.md +8 -0
  42. package/adaptations/sharpmap.md +8 -0
  43. package/adaptations/spatialite.md +8 -0
  44. package/adaptations/whitebox-tools.md +8 -0
  45. package/assets/brutile/SKILL.md +289 -0
  46. package/assets/cesiumjs/SKILL.md +78 -29
  47. package/assets/deck-gl/SKILL.md +20 -20
  48. package/assets/duckdb-spatial/SKILL.md +370 -0
  49. package/assets/gdal/SKILL.md +50 -55
  50. package/assets/gdal-api/SKILL.md +12 -29
  51. package/assets/geolibre/SKILL.md +364 -0
  52. package/assets/geometry-api-java/SKILL.md +11 -19
  53. package/assets/geometry-api-net/SKILL.md +66 -29
  54. package/assets/geonode/SKILL.md +347 -0
  55. package/assets/geopandas/SKILL.md +22 -28
  56. package/assets/geopipe-agent/SKILL.md +25 -30
  57. package/assets/geoserver/SKILL.md +21 -24
  58. package/assets/geoserver-cloud/SKILL.md +23 -34
  59. package/assets/geoserver-rest-api/SKILL.md +18 -23
  60. package/assets/geotools/SKILL.md +13 -21
  61. package/assets/grass-gis/SKILL.md +19 -20
  62. package/assets/jts/SKILL.md +12 -17
  63. package/assets/kepler-gl/SKILL.md +313 -0
  64. package/assets/leaflet/SKILL.md +42 -17
  65. package/assets/mapbox-gl-js/SKILL.md +19 -18
  66. package/assets/mapserver/SKILL.md +18 -18
  67. package/assets/mapsui/SKILL.md +87 -58
  68. package/assets/nettopologysuite/SKILL.md +96 -27
  69. package/assets/opengis-all/SKILL.md +80 -292
  70. package/assets/opengis-all/reference/data-stages.md +262 -4
  71. package/assets/opengis-daf/SKILL.md +12 -14
  72. package/assets/opengis-utils-for-java/SKILL.md +52 -47
  73. package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
  74. package/assets/opengis-utils-for-net/SKILL.md +106 -40
  75. package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
  76. package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
  77. package/assets/openlayers/SKILL.md +71 -14
  78. package/assets/pdal/SKILL.md +21 -15
  79. package/assets/postgis/SKILL.md +66 -18
  80. package/assets/proj/SKILL.md +29 -42
  81. package/assets/projnet4geoapi/SKILL.md +299 -0
  82. package/assets/pyqgis/SKILL.md +28 -54
  83. package/assets/qgis-process/SKILL.md +67 -39
  84. package/assets/qgis-server/SKILL.md +21 -32
  85. package/assets/shapely/SKILL.md +133 -84
  86. package/assets/sharpmap/SKILL.md +96 -61
  87. package/assets/spatialite/SKILL.md +365 -0
  88. package/assets/whitebox-tools/SKILL.md +269 -0
  89. package/lib/adaptations.d.ts +47 -0
  90. package/lib/adaptations.js +268 -0
  91. package/lib/index.d.ts +1 -1
  92. package/lib/index.js +14 -2
  93. package/lib/skill-file.js +31 -7
  94. package/locale/en.json +1 -1
  95. package/locale/zh.json +1 -1
  96. package/package.json +12 -2
  97. package/upstream.json +56 -40
@@ -0,0 +1,370 @@
1
+ ---
2
+ name: duckdb-spatial
3
+ description: "Use when doing spatial analysis inside a DuckDB database or SQL pipeline — INSTALL spatial / LOAD spatial, ST_Read over Shapefile/GeoPackage/GeoJSON, ST_Point/ST_GeomFromText, ST_Intersects/ST_Contains/ST_Buffer joins, ST_Area_Spheroid, ST_AsMVT tiles, DuckDB-WASM in the browser; also for 'Extension spatial is not installed' or spatial function does not exist, GEOMETRY vs WKB_BLOB friction, and exporting query results to GeoParquet. DuckDB 2.0 built-in spatial extension."
4
+ tags:
5
+ - duckdb
6
+ - sql
7
+ - python
8
+ - spatial
9
+ - geospatial
10
+ - extension
11
+ - vector
12
+ - geoparquet
13
+ - analysis
14
+ - cli
15
+ ---
16
+
17
+ > **项目地址:** <https://github.com/duckdb/duckdb-spatial>
18
+ >
19
+ > **官方文档:** <https://duckdb.org/docs/stable/core_extensions/spatial/overview>
20
+ >
21
+ > **函数参考:** <https://duckdb.org/docs/stable/core_extensions/spatial/functions>
22
+ >
23
+ > **DuckDB 包(PyPI):** 2.0.0(截至 2026-10)
24
+ >
25
+ > **扩展分发:** 随 DuckDB 版本自动匹配,INSTALL spatial 从 extensions.duckdb.org 拉取(无独立版本号)
26
+ >
27
+ > **许可证:** MIT
28
+
29
+ ## 概述
30
+
31
+ DuckDB Spatial 是 DuckDB 官方的核心扩展,把列式分析数据库变成可读写地理数据的空间分析工具。它基于 OGC Simple Features 模型增加 GEOMETRY 类型,底层用 GEOS 做拓扑运算、用 PROJ 做坐标转换、用 GDAL 读文件。
32
+
33
+ - **零服务依赖**:进程内运行,扩展按需安装,无需 PostGIS 或服务器
34
+ - **轻量几何类型**:POINT_2D / LINESTRING_2D / POLYGON_2D / BOX_2D 有原生函数重载,比通用 GEOMETRY 路径快
35
+ - **ST_Read 表函数**:通过 GDAL 直接查询 Shapefile、GeoPackage、GeoJSON、FlatGeoBuf 等
36
+ - **SQL 即分析**:空间谓词、聚合(ST_Union_Agg、ST_Extent_Agg)、瓦片编码(ST_AsMVT)
37
+ - **与 Parquet/CSV/JSON 同库联查**:空间表可直接 JOIN 普通表,无须导入导出
38
+ - **WASM 可用**:同一扩展编译为 WebAssembly,GeoLibre 与 DuckDB-WASM 前端都靠它
39
+
40
+ 扩展自带 GEOS/PROJ/GDAL 静态链接版本,机器上不需要另外安装 GDAL。
41
+
42
+ ## 环境准备
43
+
44
+ ### 安装 DuckDB
45
+
46
+ ```bash
47
+ # 1) Python(推荐用于脚本与 Notebook)
48
+ pip install duckdb==2.0.0
49
+
50
+ # 2) conda / mamba
51
+ conda install -c conda-forge duckdb
52
+
53
+ # 3) 官方 CLI(单文件可执行)
54
+ # Windows: 下载 duckdb_cli-windows-amd64.zip 后解压
55
+ # macOS: brew install duckdb
56
+ ```
57
+
58
+ ### 安装 spatial 扩展
59
+
60
+ ```sql
61
+ INSTALL spatial;
62
+ LOAD spatial;
63
+ ```
64
+
65
+ INSTALL 会把扩展写入用户目录(~/.duckdb/extensions/<version>/<platform>/),只需一次;之后每次会话 LOAD spatial 即可。spatial 不属于 autoloadable 扩展,忘记 LOAD 时所有 ST_* 函数都会报"不存在"。
66
+
67
+ ### 验证
68
+
69
+ ```python
70
+ import duckdb
71
+ con = duckdb.connect()
72
+ con.execute("INSTALL spatial; LOAD spatial;")
73
+ print(con.execute("SELECT duckdb_version()").fetchone())
74
+ print(con.execute("SELECT ST_AsText(ST_Point(116.39, 39.90))").fetchone())
75
+ print(con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name='spatial'").fetchone())
76
+ print(con.execute("SELECT duckdb_proj_version()").fetchone())
77
+ ```
78
+
79
+ 预期能打印 POINT (116.39 39.9) 与 PROJ 版本号;任一失败即扩展未正确加载。
80
+
81
+ ## 核心 API
82
+
83
+ ### 几何构造与序列化
84
+
85
+ | 函数 | 作用 | 返回 |
86
+ |------|------|------|
87
+ | ST_Point(x, y) / ST_MakePoint(x, y) | 构造点(两者等价,后者为 PostGIS 兼容名) | GEOMETRY |
88
+ | ST_GeomFromText(wkt [, ignore_invalid]) | 从 WKT 解析 | GEOMETRY |
89
+ | ST_GeomFromGeoJSON(json) / ST_AsGeoJSON(geom) | GeoJSON fragment 互转 | GEOMETRY / JSON |
90
+ | ST_GeomFromWKB(blob) / ST_AsWKB(geom) | WKB 互转 | GEOMETRY / WKB_BLOB |
91
+ | ST_MakeEnvelope(minx, miny, maxx, maxy) | 矩形面 | GEOMETRY |
92
+ | ST_MakeLine(list_of_points) / ST_MakePolygon(ring) | 线/面构造 | GEOMETRY |
93
+ | ST_AsText(geom) | 输出 WKT | VARCHAR |
94
+
95
+ ```sql
96
+ SELECT ST_AsText(ST_Point(116.39, 39.90)) AS pt,
97
+ ST_AsText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY) AS poly,
98
+ ST_AsWKB('POINT(1 2)'::GEOMETRY)::BLOB AS wkb;
99
+ ```
100
+
101
+ 字符串可以直接带类型转换写成 'POINT(...)'::GEOMETRY,这是最短路径。DuckDB Spatial 的 GEOMETRY 不保存 SRID,因此没有 ST_SetSRID 这类函数。
102
+
103
+ ### 空间关系谓词
104
+
105
+ | 函数 | 说明 |
106
+ |------|------|
107
+ | ST_Intersects(a, b) | 相交(含接触) |
108
+ | ST_Contains(a, b) / ST_Within(a, b) | 包含 / 被包含 |
109
+ | ST_Covers(a, b) / ST_CoveredBy(a, b) | 覆盖(边界计入,比 Contains 宽松) |
110
+ | ST_Disjoint(a, b) | 不相交 |
111
+ | ST_Touches(a, b) / ST_Crosses(a, b) | 接触 / 穿越 |
112
+ | ST_DWithin(a, b, dist) | 距离小于阈值 |
113
+ | ST_Intersects_Extent(a, b) | 仅比较包围盒,最快的粗筛 |
114
+
115
+ ```sql
116
+ -- 点落在面内:用 EXISTS 半连接,避免笛卡尔积
117
+ SELECT c.name
118
+ FROM cities c
119
+ WHERE EXISTS (
120
+ SELECT 1 FROM countries k
121
+ WHERE ST_Intersects(k.geom, c.geom)
122
+ );
123
+ ```
124
+
125
+ ### 度量与构造
126
+
127
+ | 函数 | 说明 | 单位 |
128
+ |------|------|------|
129
+ | ST_Area(geom) | 平面面积(非面返回 0) | 与坐标系一致 |
130
+ | ST_Area_Spheroid(geom) | 椭球面积,假定输入为 EPSG:4326 | 平方米 |
131
+ | ST_Length(geom) | 平面长度 | 与坐标系一致 |
132
+ | ST_Length_Spheroid(geom) | 椭球长度 | 米 |
133
+ | ST_Distance(a, b) | 平面距离(忽略 Z) | 与坐标系一致 |
134
+ | ST_Distance_Sphere(a, b) | 大圆距离 | 米 |
135
+ | ST_Centroid(geom) | 质心 | GEOMETRY |
136
+ | ST_Buffer(geom, dist [, num_triangles]) | 缓冲,num_triangles 默认 8 | 与坐标系一致 |
137
+ | ST_Simplify / ST_SimplifyPreserveTopology | 简化 | — |
138
+ | ST_MakeValid / ST_IsValid | 修复 / 校验 | — |
139
+
140
+ ```sql
141
+ -- 经纬度下 ST_Area 的单位是"平方度",要米制面积就用椭球版本
142
+ SELECT name,
143
+ ST_Area(geom) AS planar_deg2,
144
+ ST_Area_Spheroid(geom) AS spheroid_m2
145
+ FROM countries
146
+ ORDER BY spheroid_m2 DESC
147
+ LIMIT 5;
148
+ ```
149
+
150
+ ### 坐标转换
151
+
152
+ ```sql
153
+ -- 显式给出源与目标 CRS;always_xy 决定是否强制 x=经度
154
+ SELECT ST_AsText(
155
+ ST_Transform(ST_Point(116.39, 39.90), 'EPSG:4326', 'EPSG:3857')
156
+ );
157
+
158
+ -- 包围盒同样可以转换
159
+ SELECT ST_Transform({min_x: -180, min_y: -85, max_x: 180, max_y: 85}::BOX_2D,
160
+ 'EPSG:4326', 'EPSG:3857');
161
+ ```
162
+
163
+ CRS 字符串支持 PROJ 认得的写法('EPSG:4326'、'+proj=longlat +datum=WGS84'、WKT)。ST_Transform 不会替你猜坐标系,源 CRS 必须由你给出。
164
+
165
+ ### 聚合与瓦片
166
+
167
+ | 函数 | 说明 |
168
+ |------|------|
169
+ | ST_Union_Agg(geom) | 合并要素(GEOS union) |
170
+ | ST_Extent_Agg(geom) | 最小包围盒多边形 |
171
+ | ST_Intersection_Agg(geom) | 批量求交 |
172
+ | ST_CoverageUnion_Agg(geom) | 覆盖合并(共享边界时更快) |
173
+ | ST_AsMVT(row, layer_name, extent, geom_col, id_col) | 生成 Mapbox Vector Tile |
174
+ | ST_AsMVTGeom(geom, bounds, extent, buffer, clip) | 裁剪到瓦片边界 |
175
+
176
+ ```sql
177
+ -- 按省合并成一条 MultiPolygon,并给出总包围盒
178
+ SELECT province,
179
+ ST_AsText(ST_Union_Agg(geom)) AS merged,
180
+ ST_AsText(ST_Extent_Agg(geom)) AS bbox
181
+ FROM counties
182
+ GROUP BY province;
183
+ ```
184
+
185
+ ### 文件读写(GDAL 表函数)
186
+
187
+ | 函数 | 说明 |
188
+ |------|------|
189
+ | ST_Read(path, ...) | 读矢量文件,参数见下表 |
190
+ | ST_Read_Meta(path) | 只读元数据(图层、CRS、字段) |
191
+ | ST_ReadSHP(path, encoding) | 不依赖 GDAL 的 Shapefile 读取(快,基础类型) |
192
+ | ST_ReadOSM(path) | 直接解析 .osm.pbf,输出原始 Nodes/Ways/Relations |
193
+ | ST_Drivers() | 列出编译进来的 GDAL 驱动 |
194
+
195
+ 常用 ST_Read 参数:
196
+
197
+ | 参数 | 类型 | 说明 |
198
+ |------|------|------|
199
+ | layer | VARCHAR | 图层名或索引(0 起);多图层文件必给 |
200
+ | spatial_filter_box | BOX_2D | 按包围盒过滤(部分驱动可下推) |
201
+ | spatial_filter | WKB_BLOB | 按任意几何过滤 |
202
+ | open_options | VARCHAR[] | 透传 GDAL 打开选项,如 FLATTEN_NESTED_ATTRIBUTES=YES |
203
+ | allowed_drivers | VARCHAR[] | 限制可用驱动 |
204
+ | keep_wkb | BOOLEAN | 返回 wkb_geometry(WKB_BLOB)而非 GEOMETRY |
205
+
206
+ ```sql
207
+ -- 单图层文件
208
+ CREATE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');
209
+
210
+ -- 指定图层 + 包围盒过滤
211
+ SELECT * FROM ST_Read('data/city.gpkg',
212
+ layer := 'buildings',
213
+ spatial_filter_box := {min_x: 116.0, min_y: 39.5,
214
+ max_x: 116.6, max_y: 40.1}::BOX_2D);
215
+
216
+ -- 先看元数据,再决定读哪个图层
217
+ SELECT unnest(layers).name FROM ST_Read_Meta('data/city.gpkg');
218
+ ```
219
+
220
+ 替换扫描(replacement scan):.shp、.gpkg、.fgb 三种扩展名可以直接当表名查,无需 ST_Read:
221
+
222
+ ```sql
223
+ SELECT * FROM 'data/roads.shp' LIMIT 5;
224
+ ```
225
+
226
+ 这只是 ST_Read 的语法糖,性能一致;要传参数时仍应显式调用 ST_Read。
227
+
228
+ ## 典型工作流:Shapefile → 空间分析 → GeoParquet
229
+
230
+ 输入 data/roads.shp(线)与 data/districts.shp(面),目标是从每条道路提取落在各区的长度并输出 Parquet。
231
+
232
+ ```python
233
+ import duckdb
234
+
235
+ con = duckdb.connect("analysis.duckdb")
236
+ con.execute("INSTALL spatial; LOAD spatial;")
237
+
238
+ # 1) 读入并落到持久表(避免每次查询重复解析 Shapefile)
239
+ con.execute("CREATE OR REPLACE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');")
240
+ con.execute("CREATE OR REPLACE TABLE districts AS SELECT * FROM ST_Read('data/districts.shp');")
241
+
242
+ # 2) 探明列名与 CRS
243
+ print(con.execute("DESCRIBE roads").fetchall())
244
+ print(con.execute("""
245
+ SELECT layers[1].geometry_fields[1].crs.auth_name,
246
+ layers[1].geometry_fields[1].crs.auth_code
247
+ FROM ST_Read_Meta('data/roads.shp')
248
+ """).fetchone())
249
+
250
+ # 3) 统一到投影坐标系后再算长度(米),避免把"度"当"米"
251
+ con.execute("""
252
+ CREATE OR REPLACE TABLE roads_m AS
253
+ SELECT *, ST_Transform(geom, 'EPSG:4326', 'EPSG:3857') AS geom_m,
254
+ ST_Length(ST_Transform(geom, 'EPSG:4326', 'EPSG:3857')) AS length_m
255
+ FROM roads;
256
+ """)
257
+ con.execute("""
258
+ CREATE OR REPLACE TABLE districts_m AS
259
+ SELECT *, ST_Transform(geom, 'EPSG:4326', 'EPSG:3857') AS geom_m
260
+ FROM districts;
261
+ """)
262
+
263
+ # 4) 叠加:相交取交线,按区汇总长度
264
+ con.execute("""
265
+ CREATE OR REPLACE TABLE road_length_by_district AS
266
+ SELECT d.name AS district,
267
+ SUM(ST_Length(ST_Intersection(r.geom_m, d.geom_m))) AS length_m
268
+ FROM roads_m r
269
+ JOIN districts_m d
270
+ ON ST_Intersects(r.geom_m, d.geom_m)
271
+ GROUP BY d.name
272
+ ORDER BY length_m DESC;
273
+ """)
274
+
275
+ # 5) 输出:几何列写成 WKB
276
+ con.execute("""
277
+ COPY (SELECT ST_AsWKB(geom_m) AS geometry, name, length_m FROM roads_m)
278
+ TO 'out/roads_m.parquet' (FORMAT parquet);
279
+ """)
280
+
281
+ print(con.execute("SELECT * FROM road_length_by_district LIMIT 10").fetchall())
282
+ ```
283
+
284
+ 输出 out/roads_m.parquet 与一张按区汇总的长度表。要点:先把 Shapefile 落到持久表(重复 ST_Read 很慢)、先投影再算长度、按区名分组而不是逐行比较。
285
+
286
+ ## 与 Python / pandas 协作
287
+
288
+ ```python
289
+ import duckdb, geopandas as gpd
290
+
291
+ con = duckdb.connect()
292
+ con.execute("INSTALL spatial; LOAD spatial;")
293
+
294
+ # 查询结果直接转 DataFrame
295
+ rows = con.execute("SELECT name, ST_AsText(geom) FROM ST_Read('data/cities.shp')").fetchdf()
296
+
297
+ # GeoDataFrame 注册成视图后即可用 SQL 查询
298
+ districts = gpd.read_file("data/districts.gpkg")
299
+ con.register("districts", districts)
300
+ print(con.execute("SELECT name, ST_Area(geom) AS area FROM districts ORDER BY area DESC LIMIT 5").fetchall())
301
+ ```
302
+
303
+ register 只在当前会话有效;跨进程请建表或直接读文件。
304
+
305
+ ## 输出 GeoParquet 与矢量瓦片
306
+
307
+ ```sql
308
+ -- GeoParquet:几何列写成 WKB,字段名用 geometry 便于下游识别
309
+ COPY (SELECT ST_AsWKB(geom) AS geometry, name, pop FROM cities)
310
+ TO 'out/cities.parquet' (FORMAT parquet);
311
+
312
+ -- MVT:先裁剪到瓦片,再聚合
313
+ WITH tile AS (
314
+ SELECT ST_AsMVTGeom(
315
+ ST_Transform(geom, 'EPSG:4326', 'EPSG:3857'),
316
+ ST_TileEnvelope(12, 3423, 1586)
317
+ ) AS geom,
318
+ name
319
+ FROM cities
320
+ WHERE ST_Intersects_Extent(
321
+ ST_Transform(geom, 'EPSG:4326', 'EPSG:3857'),
322
+ ST_TileEnvelope(12, 3423, 1586))
323
+ )
324
+ SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
325
+ ```
326
+
327
+ ## 性能优化
328
+
329
+ 1. **落表再查**:对同一文件重复 ST_Read 会反复走 GDAL 解析,先 CREATE TABLE AS 物化。GDAL 是单线程的,ST_Read 无法并行。
330
+ 2. **没有空间索引,先做包围盒粗筛**:DuckDB Spatial 不提供 R-Tree 索引,join 前用 ST_Intersects_Extent 缩小候选集,再用 ST_Intersects 精确判断。
331
+ 3. **优先用轻量类型**:能落成 POINT_2D / POLYGON_2D 的列走原生实现,必要时用 ST_Force2D 去掉 Z/M。
332
+ 4. **面积/长度单位要有依据**:经纬度下 ST_Area 的单位是平方度,应改用 ST_Area_Spheroid 或先投影。
333
+ 5. **投影一次即可**:ST_Transform 是 CPU 热点,放在建表阶段,不要写在 WHERE 里逐行算。
334
+ 6. **减少字符串往返**:几何尽量保持二进制形态,只在最终输出时 ST_AsText / ST_AsWKB。
335
+ 7. **大文件用列裁剪**:SELECT name, geom 比 SELECT * 少读属性列。
336
+
337
+ ## 常见问题
338
+
339
+ | 问题 | 原因 | 解决方案 |
340
+ |------|------|---------|
341
+ | Extension spatial is not installed | 只写了 LOAD 没写 INSTALL,或离线环境拉不到扩展 | 先执行 INSTALL spatial;离线时复用扩展目录,或下载官方 unsigned 构建后 INSTALL '<path>'(需 -unsigned 启动) |
342
+ | Catalog Error: Scalar Function with name ST_Intersects does not exist | 当前连接没 LOAD spatial | 每个新连接都要 LOAD spatial;Python 里可在建连后立即执行 |
343
+ | ST_Area 返回 0 或很小的数 | 输入是经纬度,单位是平方度 | 用 ST_Area_Spheroid,或先 ST_Transform 到米制投影 |
344
+ | ST_Transform 报 CRS 解析失败 | 源/目标 CRS 字符串拼错或 PROJ 未识别 | 用 'EPSG:4326' 这类标准写法;SELECT duckdb_proj_version() 确认 PROJ 可用 |
345
+ | 读 GeoPackage 只拿到第一个图层 | 多图层文件未指定 layer | 用 ST_Read_Meta 先看 layers,再 ST_Read(..., layer := '...') |
346
+ | Shapefile 中文属性乱码 | DBF 编码与默认 UTF-8 不一致 | 用 ST_ReadSHP(path, encoding := 'GBK'),或在 open_options 里给驱动指定编码 |
347
+ | 空间 join 极慢 | 没有空间索引,也没做包围盒粗筛 | 先 ST_Intersects_Extent 粗筛,再 ST_Intersects 精筛 |
348
+ | 写出的 Parquet 没有 CRS | ST_AsWKB 只写几何,不写 CRS 元数据 | 落盘后用 GeoPandas/GDAL 补写 crs,或用 ogr2ogr 转出 |
349
+ | ST_ReadOSM 只返回 node/way 原始表 | 该函数不做几何装配 | 需要成品几何时改用 ST_Read 的 OSM 驱动 |
350
+
351
+ ## AI 使用建议
352
+
353
+ - **先验扩展再写 SQL**:执行前跑 SELECT extension_name, loaded FROM duckdb_extensions() WHERE extension_name='spatial'; 确认 loaded=true;未加载就先 LOAD,不要把"函数不存在"当语法错误去改。
354
+ - **版本敏感**:2.0.0 与旧版函数集合有差异(ST_Area_Spheroid、ST_CoverageUnion_Agg 属较新函数)。写示例前用 SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'ST_%'; 探测实际可用函数。
355
+ - **大文件不要整读进内存**:优先用 ST_Read 的 spatial_filter_box / layer 参数与 Parquet 列裁剪;反复查询时先落表。
356
+ - **验证产物**:写完 Parquet/MVT 后回读核对 count、ST_IsValid、ST_GeometryType 分布,以及坐标范围是否落在预期 CRS 内。
357
+ - **写操作确认**:COPY ... TO、CREATE OR REPLACE TABLE、DROP TABLE 会覆盖文件或表;执行前确认目标路径已被授权覆盖。
358
+
359
+ ## 相关技能
360
+
361
+ - **postgis** — 服务端空间数据库,DuckDB 的常见替代:[../postgis/SKILL.md](../postgis/SKILL.md)
362
+ - **geopandas** — Python 矢量分析,可与 DuckDB 互转:[../geopandas/SKILL.md](../geopandas/SKILL.md)
363
+ - **gdal** — ST_Read 背后的读写引擎与格式转换:[../gdal/SKILL.md](../gdal/SKILL.md)
364
+ - **proj** — CRS 定义与 ST_Transform 的底层库:[../proj/SKILL.md](../proj/SKILL.md)
365
+ - **geolibre** — 浏览器里用 DuckDB-WASM Spatial 做 SQL 分析:[../geolibre/SKILL.md](../geolibre/SKILL.md)
366
+
367
+ ## 参考资源
368
+ - 扩展仓库:<https://github.com/duckdb/duckdb-spatial>
369
+ - 函数总表:<https://duckdb.org/docs/stable/core_extensions/spatial/functions>
370
+ - DuckDB 文档:<https://duckdb.org/docs/stable/>
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: gdal
3
- description: "Use when processing geospatial raster/vector data via command line — format conversion (Shapefile to GeoJSON), reprojection, DEM analysis, NDVI calculation, mosaicking. GDAL/OGR CLI: the industry standard for batch geospatial data processing with 50+ command-line tools (ogr2ogr, gdalwarp, gdal_translate, gdal_calc)."
3
+ description: "Use when processing geospatial raster/vector data via GDAL/OGR CLI — ogr2ogr format conversion (Shapefile/GeoPackage/GeoJSON), gdalwarp reprojection, gdal_translate, gdal_calc.py NDVI, COG, mosaicking, DEM contours, gdalinfo -json checks — or diagnosing \"not recognized as a supported file format\"; also covers the 3.11+ unified gdal raster / gdal vector CLI."
4
4
 
5
5
  tags:
6
6
  - gdal
@@ -37,7 +37,7 @@ GDAL 是地理空间数据处理的事实标准库。它提供了 **50+ 个命
37
37
 
38
38
  ### 前置条件
39
39
 
40
- GDAL 3.0+ 已预装在大多数 Linux 发行版的地理信息处理环境中。确保工具在 `PATH` 中:
40
+ 部分 Linux 发行版与 GIS 软件栈会预装 GDAL(QGIS、PostGIS 客户端等),先用下面的命令确认工具在 `PATH` 中:
41
41
 
42
42
  ```bash
43
43
  gdalinfo --version # 验证 GDAL 版本
@@ -73,8 +73,10 @@ conda install -c conda-forge gdal
73
73
 
74
74
  #### Docker
75
75
 
76
+ Docker Hub 上的 `osgeo/gdal` 已迁移(该镜像最后一次更新为 2023 年),现由 GHCR 发布:
77
+
76
78
  ```bash
77
- docker run -it osgeo/gdal:latest bash
79
+ docker run --rm -it ghcr.io/osgeo/gdal:latest bash
78
80
  ```
79
81
 
80
82
  ### Python 绑定(可选)
@@ -91,19 +93,31 @@ conda install -c conda-forge gdal
91
93
 
92
94
  ## 核心命令结构
93
95
 
94
- ### 新式 CLI (GDAL 3.9+)
96
+ ### 新式 CLI (GDAL 3.11+)
95
97
 
96
- GDAL 3.9 引入了统一的 CLI 接口(最新稳定版 **3.13.3**,2026-08 发布,见 [下载页](https://gdal.org/download.html)),并在后续版本持续完善,新增 `gdal vector concave-hull/convex-hull/dissolve/sort`、`gdal dataset check` 等子命令:
98
+ GDAL 3.11 引入了统一的 `gdal` 命令行入口(官方文档标注 "Added in version 3.11";最新稳定版 **3.13.3**,2026-08-18 发布,见 [下载页](https://gdal.org/download.html)),后续版本持续加入 `gdal vector concave-hull/convex-hull/dissolve/sort` 等子命令,`gdal dataset check` 自 3.13 起提供:
97
99
 
98
100
  ```bash
99
101
  gdal <command> <subcommand> [options] <inputs>
100
102
  ```
101
103
 
102
104
  主要命令:
103
- - `gdal info` — 获取数据信息(自动检测栅格或矢量)
104
- - `gdal vector` — 矢量操作入口
105
- - `gdal raster` — 栅格操作入口
106
- - `gdal dataset` — 数据集管理
105
+ - `gdal info` — 获取数据信息(自动检测栅格或矢量,等价 `gdal raster info` / `gdal vector info`)
106
+ - `gdal vector` — 矢量操作入口(`convert`、`reproject`、`clip`、`buffer`、`dissolve`、`make-valid`、`sql` 等)
107
+ - `gdal raster` — 栅格操作入口(`convert`、`reproject`、`mosaic`、`clip`、`calc`、`contour` 等)
108
+ - `gdal dataset` — 数据集管理(`check`、`copy`、`rename`、`delete`、`identify`)
109
+ - `gdal pipeline` — 把多个步骤串成一条命令
110
+
111
+ ```bash
112
+ # 矢量重投影 + 格式转换(等价 ogr2ogr -t_srs ... -f GPKG)
113
+ gdal vector reproject --output-crs EPSG:3857 -o out.gpkg in.shp
114
+
115
+ # 栅格镶嵌(等价 gdal_merge.py / gdalwarp 多输入)
116
+ gdal raster mosaic -o mosaic.tif tile1.tif tile2.tif tile3.tif
117
+
118
+ # 数据集体检(3.13+)
119
+ gdal dataset check data.gpkg
120
+ ```
107
121
 
108
122
  ### 传统 CLI(广泛使用)
109
123
 
@@ -194,6 +208,21 @@ gdal_translate -outsize 50% 50% input.tif output.tif
194
208
  gdal_translate -projwin -180 90 -170 80 input.tif output.tif
195
209
  ```
196
210
 
211
+ ### COG / 云优化 GeoTIFF
212
+
213
+ COG 是带内部金字塔和分块的 GeoTIFF,便于 HTTP Range 按需读取(S3、对象存储、静态服务器):
214
+
215
+ ```bash
216
+ # GeoTIFF → COG(压缩 + 金字塔一次生成)
217
+ gdal_translate -of COG -co COMPRESS=DEFLATE -co OVERVIEWS=AUTO input.tif output_cog.tif
218
+
219
+ # 3.11+ 新式 CLI 等价写法
220
+ gdal raster convert --of COG -o output_cog.tif input.tif
221
+
222
+ # 校验:分块、金字塔、是否被识别为 COG
223
+ gdalinfo -json output_cog.tif | grep -E 'COMPRESSION|LAYOUT|BLOCK'
224
+ ```
225
+
197
226
  ### gdalwarp — 栅格重投影和镶嵌
198
227
 
199
228
  ```bash
@@ -415,52 +444,6 @@ gdaltindex -recursive -of GPKG \
415
444
 
416
445
  ---
417
446
 
418
- ## AI 使用建议
419
-
420
- ### 推荐工作流
421
-
422
- 1. **探索数据**:
423
- ```bash
424
- gdalinfo input.tif # 栅格信息
425
- ogrinfo input.shp # 矢量信息
426
- ```
427
-
428
- 2. **检查支持的格式和驱动**:
429
- ```bash
430
- gdalinfo --formats
431
- ogrinfo --formats
432
- ```
433
-
434
- 3. **分步处理**(避免大内存操作):
435
- ```bash
436
- # 不要直接镶嵌所有文件
437
- # 改为逐个处理和合并
438
- ```
439
-
440
- 4. **使用 JSON 输出**(便于解析):
441
- ```bash
442
- gdalinfo -json input.tif | jq '.coordinateSystem'
443
- ogrinfo -json input.shp | jq '.layers[0].featureCount'
444
- ```
445
-
446
- 5. **优化性能**:
447
- ```bash
448
- # 启用多线程、内存缓存、COG 格式
449
- export GDAL_NUM_THREADS=ALL_CPUS
450
- export GDAL_CACHEMAX=2048
451
- ```
452
-
453
- ### 关键注意事项
454
-
455
- - **始终备份**:GDAL 可以就地修改文件(如 `gdal_edit.py`)
456
- - **使用绝对路径**:避免工作目录问题
457
- - **验证坐标系**:重投影前确认源和目标坐标系
458
- - **测试小数据**:在大数据集上运行前,用小样本测试
459
- - **使用 VRT(虚拟数据集)**:避免创建多个副本
460
- - **环境变量**:设置适当的 `GDAL_CACHEMAX` 和 `GDAL_NUM_THREADS`
461
-
462
- ---
463
-
464
447
  ## 常见问题
465
448
 
466
449
  | 问题 | 解决 |
@@ -476,6 +459,18 @@ gdaltindex -recursive -of GPKG \
476
459
 
477
460
  ---
478
461
 
462
+ ## AI 使用建议
463
+
464
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/data-formats.md`、`reference/raster-tools.md`、`reference/vector-tools.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
465
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell)。正文的 `apt-get`、`sudo`、`export VAR=` 是 Bash 写法:Windows 改为 `$env:GDAL_NUM_THREADS = "ALL_CPUS"`,无 `sudo`/`apt` 时改用 conda-forge 或 `docker run --rm -v "${PWD}:/data" -w /data ghcr.io/osgeo/gdal:latest ...`。
466
+ - **先探测版本**:`gdalinfo --version`、`ogrinfo --version`;本技能按 GDAL 3.13.3 编写,低于 3.11 没有 `gdal <command>` 新式 CLI(`gdal vector`/`gdal raster`),须退回 `ogr2ogr`/`gdalwarp`;`gdal dataset check` 需 3.13+,且 `gdal_calc.py` 等脚本工具还需要 Python 绑定。
467
+ - **验证产物**:栅格用 `gdalinfo -json out.tif` 核对 `driverShortName`、`size`、`coordinateSystem.wkt`、`bands[].noDataValue`;矢量用 `ogrinfo -so out.shp layer`(或 `ogrinfo -json out.gpkg`)核对 `Feature Count`、`Geometry`、字段列表;不要只凭退出码报告成功。
468
+ - **先看错误再改参数**:`ERROR 4: ... not recognized as a supported file format` 先查路径与 `gdalinfo --formats`;`--debug on` 或 `CPL_DEBUG=ON` 看驱动细节;输出很长时重定向到文件再分段读取,不要一次打印全文。
469
+ - **批处理与中间产物**:批量循环建议用 Python 生成命令,中间结果用 `gdalbuildvrt` 写 `.vrt` 而不是反复 `gdalwarp`;耗时命令放后台运行,避免一次重投影全部数据。
470
+ - **安全与权限**:`gdal_edit.py`、`ogr2ogr` 写已有目标、`-overwrite`/`-append` 会就地改写或覆盖数据,先备份或换输出名;安装 GDAL、改 `GDAL_DATA`/`PROJ_LIB`、访问 `/vsis3/`(需 `AWS_SECRET_ACCESS_KEY`)前先征得用户同意,回答里不要回显密钥。
471
+
472
+ ---
473
+
479
474
  ## 相关技能
480
475
 
481
476
  - **gdal-api** — GDAL 编程 API(C/C++/Python/.NET):[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: gdal-api
3
- description: "Use when programming against GDAL/OGR in C, C++, Python, Java, or .NET for raster/vector I/O, coordinate transformation, or custom geospatial algorithms. GDAL API: low-level programming interface for reading/writing 70+ geospatial formats."
3
+ description: "Use when programming against GDAL/OGR in C, C++, Python, Java, or .NET — raster/vector I/O, gdal.UseExceptions, OGRSpatialReference transforms, gdal.Translate / gdal.Warp, VRT/COG, or fixing \"no driver registered\" and UnsatisfiedLinkError; C++ gdal-config, Maven org.gdal:gdal 3.13.0, NuGet MaxRev.Gdal.Core."
4
4
 
5
5
  tags:
6
6
  - gdal
@@ -102,7 +102,7 @@ dotnet add package MaxRev.Gdal.LinuxRuntime.Minimal # Linux
102
102
  dotnet add package MaxRev.Gdal.WindowsRuntime.Minimal # Windows
103
103
  ```
104
104
 
105
- **注意:** 官方 SWIG 绑定命名空间为 `OSGeo.GDAL`、`OSGeo.OGR`、`OSGeo.OSR`。NuGet 包 `MaxRev.Gdal.Core` 是社区维护的跨平台封装。
105
+ **注意:** 官方 SWIG 绑定命名空间为 `OSGeo.GDAL`、`OSGeo.OGR`、`OSGeo.OSR`。NuGet 包 `MaxRev.Gdal.Core` 是社区维护的跨平台封装,2026-10 的最新版为 `3.13.3.583`(对应 GDAL 3.13.3),运行时包需与 `MaxRev.Gdal.Core` 主版本一致。
106
106
 
107
107
  ---
108
108
 
@@ -174,7 +174,8 @@ if (transform->Transform(1, &x, &y)) {
174
174
  // x, y 已变换为 EPSG:3857 坐标
175
175
  }
176
176
 
177
- OCTDestroyCoordinateTransformation(transform);
177
+ // C++ 用 DestroyCT 归还;OCTDestroyCoordinateTransformation 是 C API(接收 OGRCoordinateTransformationH)
178
+ OGRCoordinateTransformation::DestroyCT(transform);
178
179
  ```
179
180
 
180
181
  ### Python
@@ -305,6 +306,7 @@ src_ds = None # 释放数据源
305
306
  | 通用 | 大栅格内存溢出 | 用 `RasterIO` 指定窗口分块读写,避免一次性读入整个影像 |
306
307
  | 通用 | 报错信息不明确 | C++ 用 `CPLGetLastErrorMsg()`,Python 用 `gdal.GetLastErrorMsg()` 获取详细错误 |
307
308
  | C++ | WKT 等 C 字符串泄漏 | 用 `CPLFree()` 释放(如 `exportToWkt` 返回值);几何用 `OGRGeometryFactory::destroyGeometry()` |
309
+ | C++ | 坐标变换释放方式混用 | C++ 用 `OGRCoordinateTransformation::DestroyCT()`;`OCTDestroyCoordinateTransformation()` 只接收 C API 的 `OGRCoordinateTransformationH` |
308
310
  | C++ | 编译 / 链接失败 | 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL)` 配置编译参数 |
309
311
  | Python | 出错却不抛异常 | 脚本开头调用 `gdal.UseExceptions()` 启用异常模式 |
310
312
  | Python | 如何高效读写像素 | `band.ReadAsArray()` / `band.WriteArray(array)` 直接与 NumPy 数组互转 |
@@ -317,32 +319,13 @@ src_ds = None # 释放数据源
317
319
 
318
320
  ## AI 使用建议
319
321
 
320
- ### 推荐工作流
321
-
322
- 1. **语言选择**:Python 优先(NumPy 集成、语法简洁),性能敏感用 C++,.NET 项目用 C#,Java 项目用 Java
323
- 2. **驱动注册**:任何 GDAL 操作前先调用注册函数(C++: `GDALAllRegister()`, Python 默认已注册)
324
- 3. **探索数据**:先 `gdalinfo`/`ogrinfo` 命令行查数据结构,再编写 API 代码
325
- 4. **异常处理**:Python 脚本开头加 `gdal.UseExceptions()` 启用异常模式
326
- 5. **分块读写**:大栅格使用 `RasterIO` 指定窗口,避免全量加载到内存
327
-
328
- ### 关键注意事项
329
-
330
- - **资源释放**:C++ 用 `GDALClose()`,Python 赋值 `None`,Java 用 `.delete()`,C# 用 `.Dispose()`
331
- - **坐标轴顺序**:GDAL 3.0+ 默认纬度在前,可用 `SetAxisMappingStrategy` 切换
332
- - **Python NumPy 集成**:`ReadAsArray()` 直接返回 NumPy 数组,是 Python 最大优势
333
- - **CS 平台依赖**:C# 需安装对应平台运行时包(Linux/Windows)
334
- - **JA 本地库**:Java 需确保 `gdalalljni` 在 `java.library.path` 中
335
-
336
- ### 各语言适用场景
337
-
338
- | 场景 | Python | C++ | Java | C# |
339
- |------|--------|-----|------|-----|
340
- | 数据处理脚本 | (推荐)首选 | | | |
341
- | 生产级服务 | | (推荐)首选 | (推荐) | (推荐) |
342
- | GIS 桌面插件 | (推荐) | | | |
343
- | .NET 企业应用 | | | | (推荐) |
344
- | Android GIS | | | (推荐) | |
345
- | 嵌入式系统 | | (推荐) | | |
322
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/raster-api.md`、`reference/vector-api.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
323
+ - **执行环境**:编译与运行在终端 / shell 中执行(Windows 用 PowerShell)。C++ 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL REQUIRED)`;Python 用装好绑定的解释器;Java 的 `gdalalljni`、.NET 的 MaxRev 运行时包必须与平台、架构匹配。
324
+ - **先探测版本**:`ogrinfo --version`、`python -c "from osgeo import gdal; print(gdal.VersionInfo())"`(返回 `3130300` 这类数字)、`mvn -v`、`dotnet --version`;本技能按 GDAL 3.13.3、Java 绑定 3.13.0 编写,低版本缺少新驱动与部分 SWIG 方法,回答里要说明差异。
325
+ - **验证产物**:写完后重新打开核对——`python -c "from osgeo import gdal; ds=gdal.Open('out.tif'); print(ds.GetDriver().ShortName, ds.RasterCount, ds.GetSpatialRef().GetAuthorityCode(None))"`;矢量用 `ogrinfo -al -so out.gpkg` 看要素数与字段;Python 一律先 `gdal.UseExceptions()`,否则错误被静默吞掉。
326
+ - **语言选择**:数据处理脚本优先 Python(`ReadAsArray()` 直通 NumPy);生产服务与嵌入式优先 C++;Java 注意用 `java.util.Vector<String>` 传选项;.NET 用 `OSGeo.GDAL`/`OSGeo.OGR` 命名空间,或 MaxRev 封装 + 对应平台运行时包。
327
+ - **资源与轴序**:Python 置 `ds = None`、C++ `GDALClose()`、Java `.delete()`、C# `.Dispose()` 之后才算落盘;GDAL 3+ 默认纬度在前,需要经度在前时用 `SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER)`,轴序改错是坐标错位最常见的原因。
328
+ - **安全与权限**:以更新模式(`gdal.GA_Update`、`GDALOpen(..., GA_Update)`)打开会直接改原文件;覆盖已有输出前先确认;安装 `libgdal-dev`、`dotnet add package`、写系统目录前先征得用户同意。
346
329
 
347
330
  ## 相关技能
348
331