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