@dsh-gis/dsh-opengis-skill 0.3.0 → 0.5.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 (86) hide show
  1. package/CHANGELOG.md +89 -1
  2. package/README.md +78 -21
  3. package/adaptations/brutile.md +19 -6
  4. package/adaptations/cesiumjs.md +14 -5
  5. package/adaptations/common.md +49 -16
  6. package/adaptations/deck-gl.md +19 -6
  7. package/adaptations/duckdb-spatial.md +20 -6
  8. package/adaptations/gdal-api.md +24 -6
  9. package/adaptations/gdal.md +22 -6
  10. package/adaptations/geolibre.md +20 -6
  11. package/adaptations/geometry-api-java.md +14 -6
  12. package/adaptations/geometry-api-net.md +17 -6
  13. package/adaptations/geonode.md +17 -6
  14. package/adaptations/geopandas.md +21 -6
  15. package/adaptations/geopipe-agent.md +21 -6
  16. package/adaptations/geos.md +23 -0
  17. package/adaptations/geoserver-cloud.md +17 -6
  18. package/adaptations/geoserver-rest-api.md +17 -6
  19. package/adaptations/geoserver.md +18 -6
  20. package/adaptations/geotools.md +19 -6
  21. package/adaptations/grass-gis.md +24 -6
  22. package/adaptations/jts.md +18 -6
  23. package/adaptations/kepler-gl.md +18 -5
  24. package/adaptations/leaflet.md +25 -6
  25. package/adaptations/mapbox-gl-js.md +23 -6
  26. package/adaptations/maplibre-gl-js.md +20 -0
  27. package/adaptations/maplibre-native.md +19 -0
  28. package/adaptations/mapserver.md +22 -6
  29. package/adaptations/mapsui.md +22 -6
  30. package/adaptations/nettopologysuite.md +19 -6
  31. package/adaptations/opendronemap.md +21 -0
  32. package/adaptations/opengis-all.md +16 -5
  33. package/adaptations/opengis-daf.md +16 -5
  34. package/adaptations/opengis-utils-for-java.md +20 -6
  35. package/adaptations/opengis-utils-for-net.md +23 -6
  36. package/adaptations/openlayers.md +20 -6
  37. package/adaptations/pdal.md +26 -6
  38. package/adaptations/postgis.md +20 -6
  39. package/adaptations/proj.md +20 -6
  40. package/adaptations/projnet4geoapi.md +21 -6
  41. package/adaptations/pyqgis.md +18 -6
  42. package/adaptations/qgis-process.md +21 -6
  43. package/adaptations/qgis-server.md +18 -6
  44. package/adaptations/shapely.md +22 -6
  45. package/adaptations/sharpmap.md +19 -6
  46. package/adaptations/spatialite.md +23 -6
  47. package/adaptations/stac-cog-titiler.md +23 -0
  48. package/adaptations/whitebox-tools.md +19 -6
  49. package/assets/deck-gl/SKILL.md +1 -0
  50. package/assets/duckdb-spatial/SKILL.md +36 -13
  51. package/assets/gdal/SKILL.md +6 -6
  52. package/assets/gdal-api/SKILL.md +2 -2
  53. package/assets/geolibre/SKILL.md +1 -0
  54. package/assets/geonode/SKILL.md +3 -3
  55. package/assets/geopandas/SKILL.md +42 -8
  56. package/assets/geopandas/reference/core-api.md +51 -0
  57. package/assets/geos/SKILL.md +372 -0
  58. package/assets/geoserver/SKILL.md +1 -1
  59. package/assets/geoserver-cloud/SKILL.md +0 -2
  60. package/assets/grass-gis/SKILL.md +31 -7
  61. package/assets/kepler-gl/SKILL.md +1 -0
  62. package/assets/leaflet/SKILL.md +2 -2
  63. package/assets/mapbox-gl-js/SKILL.md +1 -0
  64. package/assets/maplibre-gl-js/SKILL.md +478 -0
  65. package/assets/maplibre-native/SKILL.md +383 -0
  66. package/assets/mapserver/SKILL.md +7 -5
  67. package/assets/mapsui/SKILL.md +4 -2
  68. package/assets/opendronemap/SKILL.md +309 -0
  69. package/assets/opengis-all/SKILL.md +1 -0
  70. package/assets/pdal/SKILL.md +9 -1
  71. package/assets/projnet4geoapi/SKILL.md +1 -1
  72. package/assets/shapely/SKILL.md +24 -4
  73. package/assets/shapely/reference/operations-reference.md +30 -0
  74. package/assets/spatialite/SKILL.md +8 -2
  75. package/assets/stac-cog-titiler/SKILL.md +420 -0
  76. package/assets/whitebox-tools/SKILL.md +20 -4
  77. package/lib/adaptations.d.ts +22 -1
  78. package/lib/adaptations.js +166 -20
  79. package/lib/index.d.ts +13 -9
  80. package/lib/index.js +58 -12
  81. package/lib/taxonomy.d.ts +41 -0
  82. package/lib/taxonomy.js +332 -0
  83. package/locale/en.json +1 -1
  84. package/locale/zh.json +1 -1
  85. package/package.json +10 -4
  86. package/upstream.json +36 -26
@@ -1,6 +1,6 @@
1
1
  ---
2
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."
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; also for 'Extension spatial is not installed' or spatial function does not exist, GEOMETRY vs WKB_BLOB friction, CRS type modifiers, and exporting query results to GeoParquet. GEOMETRY became a built-in type in DuckDB 1.5."
4
4
  license: MIT
5
5
  metadata:
6
6
  category: gis
@@ -13,15 +13,17 @@ metadata:
13
13
  >
14
14
  > **函数参考:** <https://duckdb.org/docs/stable/core_extensions/spatial/functions>
15
15
  >
16
+ > **GEOMETRY 类型:** <https://duckdb.org/docs/stable/sql/data_types/geometry>
17
+ >
16
18
  > **最新版本:** DuckDB 2.0.0(截至 2026-11,[PyPI](https://pypi.org/project/duckdb/) / [GitHub Releases](https://github.com/duckdb/duckdb/releases))
17
19
  >
18
- > **扩展分发:** 随 DuckDB 版本自动匹配,INSTALL spatial 从 extensions.duckdb.org 拉取(无独立版本号)
20
+ > **扩展分发:** 随 DuckDB 版本自动匹配,INSTALL spatial 从 extensions.duckdb.org 拉取(无独立版本号);GEOMETRY 类型自 DuckDB 1.5 起内置,空间函数仍由 spatial 扩展提供
19
21
  >
20
22
  > **许可证:** MIT
21
23
 
22
24
  ## 概述
23
25
 
24
- DuckDB Spatial 是 DuckDB 官方的核心扩展,把列式分析数据库变成可读写地理数据的空间分析工具。它基于 OGC Simple Features 模型增加 GEOMETRY 类型,底层用 GEOS 做拓扑运算、用 PROJ 做坐标转换、用 GDAL 读文件。
26
+ DuckDB Spatial 是 DuckDB 官方的核心扩展(core extension),把列式分析数据库变成可读写地理数据的空间分析工具。它按 OGC Simple Features 模型提供空间函数,底层用 GEOS 做拓扑运算、用 PROJ 做坐标转换、用 GDAL 读文件;GEOMETRY 数据类型自 DuckDB 1.5 起已是内置类型,但**绝大多数空间函数(ST_Area、ST_Buffer、ST_Intersects 等)仍然装在 spatial 扩展里**,装扩展这一步不能省。
25
27
 
26
28
  - **零服务依赖**:进程内运行,扩展按需安装,无需 PostGIS 或服务器
27
29
  - **轻量几何类型**:POINT_2D / LINESTRING_2D / POLYGON_2D / BOX_2D 有原生函数重载,比通用 GEOMETRY 路径快
@@ -29,8 +31,9 @@ DuckDB Spatial 是 DuckDB 官方的核心扩展,把列式分析数据库变成
29
31
  - **SQL 即分析**:空间谓词、聚合(ST_Union_Agg、ST_Extent_Agg)、瓦片编码(ST_AsMVT)
30
32
  - **与 Parquet/CSV/JSON 同库联查**:空间表可直接 JOIN 普通表,无须导入导出
31
33
  - **WASM 可用**:同一扩展编译为 WebAssembly,GeoLibre 与 DuckDB-WASM 前端都靠它
34
+ - **内建与扩展分层**:内置的只有 ST_GeomFromWKB、ST_AsWKB、ST_AsWKT(别名 ST_AsText)、ST_Intersects_Extent(别名 `&&`)、ST_CRS、ST_SetCRS 这少数几个;其余 ST_* 函数要 LOAD spatial 才有
32
35
 
33
- 扩展自带 GEOS/PROJ/GDAL 静态链接版本,机器上不需要另外安装 GDAL。
36
+ 官方发布的扩展二进制(`INSTALL spatial` 拉的那种)已经把 GEOS、PROJ、GDAL 等依赖静态链接进扩展,机器上不需要另外安装 GDAL;只有从源码自建时才需要系统里备好这些库(`vcpkg.json` 里声明了 geos、proj、gdal>=3.12.4 等)。
34
37
 
35
38
  ## 环境准备
36
39
 
@@ -51,18 +54,22 @@ conda install -c conda-forge duckdb
51
54
  ### 安装 spatial 扩展
52
55
 
53
56
  ```sql
57
+ -- DuckDB 2.0 起可用一条语句完成安装 + 加载
58
+ INSTALL AND LOAD spatial;
59
+
60
+ -- 等价的分两步写法(旧版本也支持)
54
61
  INSTALL spatial;
55
62
  LOAD spatial;
56
63
  ```
57
64
 
58
- INSTALL 会把扩展写入用户目录(~/.duckdb/extensions/<version>/<platform>/),只需一次;之后每次会话 LOAD spatial 即可。spatial 不属于 autoloadable 扩展,忘记 LOAD 时所有 ST_* 函数都会报"不存在"。
65
+ INSTALL 会把扩展写入用户目录(~/.duckdb/extensions/<version>/<platform>/),只需一次;之后每次会话 LOAD spatial 即可。spatial 不属于 autoloadable 扩展,忘记 LOAD 时空函数都会报"不存在"(内置的 ST_CRS / ST_SetCRS / ST_AsWKT 等除外)。
59
66
 
60
67
  ### 验证
61
68
 
62
69
  ```python
63
70
  import duckdb
64
71
  con = duckdb.connect()
65
- con.execute("INSTALL spatial; LOAD spatial;")
72
+ con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
66
73
  print(con.execute("SELECT duckdb_version()").fetchone())
67
74
  print(con.execute("SELECT ST_AsText(ST_Point(116.39, 39.90))").fetchone())
68
75
  print(con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name='spatial'").fetchone())
@@ -83,7 +90,8 @@ print(con.execute("SELECT duckdb_proj_version()").fetchone())
83
90
  | ST_GeomFromWKB(blob) / ST_AsWKB(geom) | WKB 互转 | GEOMETRY / WKB_BLOB |
84
91
  | ST_MakeEnvelope(minx, miny, maxx, maxy) | 矩形面 | GEOMETRY |
85
92
  | ST_MakeLine(list_of_points) / ST_MakePolygon(ring) | 线/面构造 | GEOMETRY |
86
- | ST_AsText(geom) | 输出 WKT | VARCHAR |
93
+ | ST_AsText(geom) / ST_AsWKT(geom) | 输出 WKT(ST_AsText 是 ST_AsWKT 的别名,两者内置) | VARCHAR |
94
+ | ST_CRS(geom) / ST_SetCRS(geom, crs) | 读取 / 设置几何的 CRS 标识(内置,DuckDB 1.5+) | VARCHAR / GEOMETRY |
87
95
 
88
96
  ```sql
89
97
  SELECT ST_AsText(ST_Point(116.39, 39.90)) AS pt,
@@ -91,7 +99,14 @@ SELECT ST_AsText(ST_Point(116.39, 39.90)) AS pt,
91
99
  ST_AsWKB('POINT(1 2)'::GEOMETRY)::BLOB AS wkb;
92
100
  ```
93
101
 
94
- 字符串可以直接带类型转换写成 'POINT(...)'::GEOMETRY,这是最短路径。DuckDB Spatial 的 GEOMETRY 不保存 SRID,因此没有 ST_SetSRID 这类函数。
102
+ 字符串可以直接带类型转换写成 'POINT(...)'::GEOMETRY,这是最短路径。CRS 在 DuckDB 里是**类型的一部分**而不是行内隐藏属性:`GEOMETRY('OGC:CRS84')`、`GEOMETRY('EPSG:4326')` 声明列的 CRS,用 ST_CRS / ST_SetCRS 读写,没有 PostGIS 那种 ST_SRID / ST_SetSRID 函数名。
103
+
104
+ ```sql
105
+ SELECT ST_CRS('POINT(1 2)'::GEOMETRY('OGC:CRS84')); -- OGC:CRS84
106
+ SELECT typeof(ST_SetCRS('POINT(1 2)'::GEOMETRY, 'OGC:CRS84')); -- GEOMETRY('OGC:CRS84')
107
+ ```
108
+
109
+ CRS 标识必须已在系统目录注册:内置只注册少数常见 CRS(如 OGC:CRS84、OGC:CRS83),加载 spatial 后才会注册 EPSG 全量 7000+ 套,可用 `SELECT * FROM duckdb_coordinate_systems();` 查看。带 CRS 的 GEOMETRY 列要求存储版本 v1.5.0 及以上(DuckDB 2.0 的默认存储版本已满足)。
95
110
 
96
111
  ### 空间关系谓词
97
112
 
@@ -226,7 +241,7 @@ SELECT * FROM 'data/roads.shp' LIMIT 5;
226
241
  import duckdb
227
242
 
228
243
  con = duckdb.connect("analysis.duckdb")
229
- con.execute("INSTALL spatial; LOAD spatial;")
244
+ con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
230
245
 
231
246
  # 1) 读入并落到持久表(避免每次查询重复解析 Shapefile)
232
247
  con.execute("CREATE OR REPLACE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');")
@@ -282,7 +297,7 @@ print(con.execute("SELECT * FROM road_length_by_district LIMIT 10").fetchall())
282
297
  import duckdb, geopandas as gpd
283
298
 
284
299
  con = duckdb.connect()
285
- con.execute("INSTALL spatial; LOAD spatial;")
300
+ con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
286
301
 
287
302
  # 查询结果直接转 DataFrame
288
303
  rows = con.execute("SELECT name, ST_AsText(geom) FROM ST_Read('data/cities.shp')").fetchdf()
@@ -320,7 +335,7 @@ SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
320
335
  ## 性能优化
321
336
 
322
337
  1. **落表再查**:对同一文件重复 ST_Read 会反复走 GDAL 解析,先 CREATE TABLE AS 物化。GDAL 是单线程的,ST_Read 无法并行。
323
- 2. **没有空间索引,先做包围盒粗筛**:DuckDB Spatial 不提供 R-Tree 索引,join 前用 ST_Intersects_Extent 缩小候选集,再用 ST_Intersects 精确判断。
338
+ 2. **先做包围盒粗筛,再看要不要空间索引**:join 前用 ST_Intersects_Extent(或等价的 `&&` 运算符)缩小候选集,再用 ST_Intersects 精确判断 —— 这一步在任何版本都有效,而且 `&&` 在 2.0 里还能吃到 GEOMETRY 列的 row-group 统计信息。DuckDB 2.0 的索引文档写明「spatial 扩展可为空间列提供 R-tree」,`CREATE INDEX` 也支持可选的 index type;但具体能否建、建了是否被选中,取决于扩展版本与查询形态,落地前先 `EXPLAIN ANALYZE` 实测对比,别假设它一定生效。
324
339
  3. **优先用轻量类型**:能落成 POINT_2D / POLYGON_2D 的列走原生实现,必要时用 ST_Force2D 去掉 Z/M。
325
340
  4. **面积/长度单位要有依据**:经纬度下 ST_Area 的单位是平方度,应改用 ST_Area_Spheroid 或先投影。
326
341
  5. **投影一次即可**:ST_Transform 是 CPU 热点,放在建表阶段,不要写在 WHERE 里逐行算。
@@ -337,14 +352,19 @@ SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
337
352
  | ST_Transform 报 CRS 解析失败 | 源/目标 CRS 字符串拼错或 PROJ 未识别 | 用 'EPSG:4326' 这类标准写法;SELECT duckdb_proj_version() 确认 PROJ 可用 |
338
353
  | 读 GeoPackage 只拿到第一个图层 | 多图层文件未指定 layer | 用 ST_Read_Meta 先看 layers,再 ST_Read(..., layer := '...') |
339
354
  | Shapefile 中文属性乱码 | DBF 编码与默认 UTF-8 不一致 | 用 ST_ReadSHP(path, encoding := 'GBK'),或在 open_options 里给驱动指定编码 |
340
- | 空间 join 极慢 | 没有空间索引,也没做包围盒粗筛 | 先 ST_Intersects_Extent 粗筛,再 ST_Intersects 精筛 |
355
+ | 空间 join 极慢 | 没做包围盒粗筛,也没利用任何索引 | 先 ST_Intersects_Extent(`&&`)粗筛再 ST_Intersects 精筛;仍慢再试 `CREATE INDEX` 并 `EXPLAIN ANALYZE` 核对是否真的用上 |
341
356
  | 写出的 Parquet 没有 CRS | ST_AsWKB 只写几何,不写 CRS 元数据 | 落盘后用 GeoPandas/GDAL 补写 crs,或用 ogr2ogr 转出 |
342
357
  | ST_ReadOSM 只返回 node/way 原始表 | 该函数不做几何装配 | 需要成品几何时改用 ST_Read 的 OSM 驱动 |
358
+ | Unknown coordinate system / unrecognized coordinate system | CRS 标识未注册:EPSG 全集由 spatial 扩展注册,只装了 DuckDB 没 LOAD spatial 时只剩少数内置 CRS | 先 LOAD spatial 再写 `GEOMETRY('EPSG:4326')`;仍失败则 `SELECT * FROM duckdb_coordinate_systems()` 核对标识,必要时 `SET ignore_unknown_crs = true` 显式丢弃未知 CRS |
359
+ | GEOMETRY columns with coordinate reference system identifiers are not supported in storage versions prior v1.5.0 | 带 CRS 的 GEOMETRY 列要求存储版本 v1.5.0+,旧库文件读不了 | 用 `ATTACH 'file.db' (STORAGE_VERSION 'v1.5.0')` 重建库,或先用 EXPORT DATABASE / IMPORT DATABASE 迁移存储格式 |
360
+ | pip install duckdb 装到 1.x、没有 2.0 的新行为 | DuckDB 2.0 要求 Python 3.11+,3.10 上 pip 只会解析到 1.x | 升级 Python 到 3.11+ 后重装;`python -c "import duckdb; print(duckdb.__version__)"` 确认 |
343
361
 
344
362
  ## AI 使用建议
345
363
 
346
364
  - **先验扩展再写 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_%'; 探测实际可用函数。
365
+ - **版本敏感**:2.0.0 与旧版函数集合有差异(ST_Area_Spheroid、ST_CoverageUnion_Agg 属较新函数;GEOMETRY 类型自 1.5 起内置,ST_CRS / ST_SetCRS 也随之内置)。写示例前用 SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'ST_%'; 探测实际可用函数。
366
+ - **2.0 迁移要先看存储格式**:DuckDB 2.0 默认写 storage version 69,旧版本(如 1.5.x)读不了;跨版本共享库文件前先用 `duckdb my.db -storage-version v1.5.6` 或 `config={"storage_compatibility_version": "v1.5.0"}` 指定存储版本,迁移方法见官方 Migrating to DuckDB 2.0。
367
+ - **CRS 是类型的一部分**:`GEOMETRY('EPSG:4326')` 与无 CRS 的 GEOMETRY 是不同的类型,多数二元空间函数要求两侧 CRS 一致;跨 CRS 先 ST_Transform,不要只靠 SET 全局开关去改轴序。
348
368
  - **大文件不要整读进内存**:优先用 ST_Read 的 spatial_filter_box / layer 参数与 Parquet 列裁剪;反复查询时先落表。
349
369
  - **验证产物**:写完 Parquet/MVT 后回读核对 count、ST_IsValid、ST_GeometryType 分布,以及坐标范围是否落在预期 CRS 内。
350
370
  - **写操作确认**:COPY ... TO、CREATE OR REPLACE TABLE、DROP TABLE 会覆盖文件或表;执行前确认目标路径已被授权覆盖。
@@ -360,4 +380,7 @@ SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
360
380
  ## 参考资源
361
381
  - 扩展仓库:<https://github.com/duckdb/duckdb-spatial>
362
382
  - 函数总表:<https://duckdb.org/docs/stable/core_extensions/spatial/functions>
383
+ - GEOMETRY 数据类型:<https://duckdb.org/docs/stable/sql/data_types/geometry>
384
+ - 内置几何函数:<https://duckdb.org/docs/stable/sql/functions/geometry>
385
+ - DuckDB 2.0 迁移指南:<https://duckdb.org/docs/stable/operations_manual/migration>
363
386
  - DuckDB 文档:<https://duckdb.org/docs/stable/>
@@ -103,12 +103,12 @@ gdal <command> <subcommand> [options] <inputs>
103
103
 
104
104
  ```bash
105
105
  # 矢量重投影 + 格式转换(等价 ogr2ogr -t_srs ... -f GPKG)
106
- gdal vector reproject --output-crs EPSG:3857 -o out.gpkg in.shp
106
+ gdal vector reproject --output-crs EPSG:3857 in.shp out.gpkg --overwrite
107
107
 
108
108
  # 栅格镶嵌(等价 gdal_merge.py / gdalwarp 多输入)
109
- gdal raster mosaic -o mosaic.tif tile1.tif tile2.tif tile3.tif
109
+ gdal raster mosaic tile1.tif tile2.tif tile3.tif mosaic.tif --overwrite
110
110
 
111
- # 数据集体检(3.13+)
111
+ # 数据集体检(3.13+,有错时退出码为 1)
112
112
  gdal dataset check data.gpkg
113
113
  ```
114
114
 
@@ -162,8 +162,8 @@ ogr2ogr -t_srs EPSG:3857 output.shp input.shp
162
162
  # 属性过滤
163
163
  ogr2ogr output.shp input.shp -where "area > 1000"
164
164
 
165
- # 选择特定字段
166
- ogr2ogr output.shp input.shp -select "id,name,geometry"
165
+ # 选择特定字段(几何默认保留;列表里写 geometry 只在几何被登记为字段名时有效)
166
+ ogr2ogr output.shp input.shp -select "id,name"
167
167
  ```
168
168
 
169
169
  ---
@@ -210,7 +210,7 @@ COG 是带内部金字塔和分块的 GeoTIFF,便于 HTTP Range 按需读取
210
210
  gdal_translate -of COG -co COMPRESS=DEFLATE -co OVERVIEWS=AUTO input.tif output_cog.tif
211
211
 
212
212
  # 3.11+ 新式 CLI 等价写法
213
- gdal raster convert --of COG -o output_cog.tif input.tif
213
+ gdal raster convert --of COG -co COMPRESS=DEFLATE input.tif output_cog.tif --overwrite
214
214
 
215
215
  # 校验:分块、金字塔、是否被识别为 COG
216
216
  gdalinfo -json output_cog.tif | grep -E 'COMPRESSION|LAYOUT|BLOCK'
@@ -27,8 +27,8 @@ metadata:
27
27
 
28
28
  GDAL 是地理空间数据处理的事实标准库,由 OSGeo 基金会维护。它提供:
29
29
 
30
- - **200+ 栅格驱动**:GeoTIFF、NetCDF、HDF5、COG、JPEG2000 等
31
- - **100+ 矢量驱动**:Shapefile、GeoJSON、GeoPackage、PostGIS、FlatGeobuf 等
30
+ - **上百个栅格驱动**:GeoTIFF、NetCDF、HDF5、COG、JPEG2000 等(完整清单见 [Raster drivers](https://gdal.org/en/stable/drivers/raster/index.html))
31
+ - **近百个矢量驱动**:Shapefile、GeoJSON、GeoPackage、PostGIS、FlatGeobuf 等(完整清单见 [Vector drivers](https://gdal.org/en/stable/drivers/vector/index.html))
32
32
  - **坐标参考系统**:基于 PROJ 的坐标变换与投影转换
33
33
  - **栅格分析**:重采样、镶嵌、裁剪、波段运算、DEM 分析等
34
34
  - **矢量操作**:空间过滤、属性查询、要素创建与编辑等
@@ -344,6 +344,7 @@ python -c "import json;d=json.load(open('beijing.geolibre.json'));print(len(d.ge
344
344
  ## 相关技能
345
345
 
346
346
  - **duckdb-spatial** — SQL 工作区背后的空间分析引擎:[../duckdb-spatial/SKILL.md](../duckdb-spatial/SKILL.md)
347
+ - **maplibre-gl-js** — GeoLibre 默认的矢量瓦片渲染引擎:[../maplibre-gl-js/SKILL.md](../maplibre-gl-js/SKILL.md)
347
348
  - **openlayers** — 自建 Web 地图前端时的核心库:[../openlayers/SKILL.md](../openlayers/SKILL.md)
348
349
  - **cesiumjs** — GeoLibre 的 3D 球渲染引擎之一:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
349
350
  - **qgis-process** — 桌面 GIS 的另一种无头批处理路径:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
@@ -129,8 +129,8 @@ python manage.py runserver 0.0.0.0:8000
129
129
  ### 验证
130
130
 
131
131
  ```bash
132
- # 版本
133
- curl -s http://localhost/version.txt
132
+ # 版本:容器内读 Django 应用版本(Docker 部署最可靠)
133
+ docker compose exec django python -c "import geonode; print(geonode.get_version())"
134
134
 
135
135
  # API 是否可用(公开资源无需认证)
136
136
  curl -s "http://localhost/api/v2/resources?page_size=1" | head -c 300
@@ -318,7 +318,7 @@ print(requests.get(wms, params={
318
318
 
319
319
  ## AI 使用建议
320
320
 
321
- - **先确认版本与入口**:`curl -s http://localhost/version.txt` 确认 5.1.1;Docker 部署优先用 `docker compose exec` 而不是宿主机的 `manage.py`,避免环境错位。
321
+ - **先确认版本与入口**:Docker 部署用 `docker compose exec django python -c "import geonode; print(geonode.get_version())"` 确认 5.1.1;优先用 `docker compose exec` 而不是宿主机的 `manage.py`,避免环境错位。
322
322
  - **API 用 `/api/v2/`**:旧 Tastypie 的 `/api/*` 仍在,但新代码一律用 `/api/v2/resources` 与 `/api/v2/uploads/upload`;两者返回结构不同,不要混用。
323
323
  - **认证信息不要进日志**:用环境变量传 `Authorization`,示例里出现的 `<base64>` 必须替换,不要把真实凭据写进脚本或报告。
324
324
  - **验证产物**:上传后回读资源详情,核对 `subtype`、`alternate`、`links[]` 与 `download_url`,再对 WMS 发一次 `GetMap`;只看 201 响应不构成"发布成功"。
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: geopandas
3
- description: "Use when doing vector spatial analysis in Python — gpd.read_file/to_file via pyogrio (GPKG, Shapefile, GeoParquet), sjoin/sjoin_nearest, overlay, clip, dissolve, to_crs vs set_crs, gdf.plot choropleth; also for CRSError from a missing PROJ data dir, area/distance computed in degrees, or GeoDataFrame geometry-column conflicts. GeoPandas 1.2.0 extends pandas DataFrames with geometry columns."
3
+ description: "Use when doing vector spatial analysis in Python — gpd.read_file/to_file via pyogrio (GPKG, Shapefile, GeoParquet 2.0), sjoin/sjoin_nearest, overlay, clip, dissolve, make_grid, to_crs vs set_crs, gdf.plot choropleth; also for CRSError from a missing PROJ data dir, area/distance computed in degrees, or GeoDataFrame geometry-column conflicts. GeoPandas 1.2.0 extends pandas DataFrames with geometry columns."
4
4
  license: MIT
5
5
  metadata:
6
6
  category: gis
@@ -13,7 +13,7 @@ metadata:
13
13
  >
14
14
  > **官网:** <https://geopandas.org>
15
15
  >
16
- > **最新版本:** 1.2.0(截至 2026-11,PyPI)
16
+ > **最新版本:** 1.2.0(截至 2026-11,[PyPI](https://pypi.org/project/geopandas/) / [Release notes](https://geopandas.org/en/stable/docs/changelog.html))
17
17
  >
18
18
  > **许可证:** BSD-3-Clause
19
19
 
@@ -34,7 +34,8 @@ pip install geopandas
34
34
  # 可选依赖(绘图/交互地图/分类/Parquet 等)
35
35
  pip install "geopandas[all]"
36
36
 
37
- # 验证
37
+ # 验证(版本 + 默认 IO 引擎)
38
+ python -c "import geopandas as gpd; print(gpd.__version__, gpd.options.io_engine)"
38
39
  python -c "import geopandas as gpd; gpd.show_versions()"
39
40
  ```
40
41
 
@@ -44,11 +45,14 @@ python -c "import geopandas as gpd; gpd.show_versions()"
44
45
 
45
46
  | 核心依赖 | 最低版本 | 用途 |
46
47
  |----------|---------|------|
47
- | `pandas` | >= 2.2.0 | DataFrame 基类 |
48
+ | `pandas` | >= 2.2.0 | DataFrame 基类(1.2) |
48
49
  | `shapely` | >= 2.1.0 | 几何对象与运算 (GEOS) |
49
50
  | `pyproj` | >= 3.7.0 | CRS 处理与坐标变换 |
50
- | `pyogrio` | >= 0.8 | 默认文件 IO 引擎 (GDAL/OGR) |
51
+ | `pyogrio` | >= 0.8 | 默认文件 IO 引擎 (GDAL/OGR);`read_file_info` 与 `fid_as_index` 也由它提供 |
51
52
  | `numpy` | >= 2 | 数组运算 |
53
+ | `packaging` | — | 版本解析 |
54
+
55
+ 以上为 1.2.0 `pyproject.toml` 的实测下限。
52
56
 
53
57
  | 可选依赖 | 用途 |
54
58
  |----------|------|
@@ -60,6 +64,7 @@ python -c "import geopandas as gpd; gpd.show_versions()"
60
64
  | `geopy` | 地理编码 |
61
65
  | `SQLAlchemy` >= 2.0 + `GeoAlchemy2` | PostGIS 读写 |
62
66
  | `xyzservices` | 瓦片底图服务 |
67
+ | `contextily` | `plot(tiles=...)` 叠加在线底图(1.2 新增用法) |
63
68
 
64
69
  ## 全局配置
65
70
 
@@ -80,9 +85,14 @@ gpd.options.io_engine # None|"pyogrio"|"fiona"
80
85
  ```python
81
86
  gpd.read_file(filename, bbox=None, mask=None, columns=None, rows=None, engine=None, **kwargs)
82
87
  gdf.to_file(filename, driver=None, schema=None, index=None, **kwargs)
83
- gpd.list_layers(filename) # → DataFrame (layer_name, geometry_type)
88
+ gpd.list_layers(filename) # → DataFrame (layer_name, geometry_type)
89
+ gpd.read_file_info(filename, layer=None) # → dict(1.2 新增,pyogrio.read_info 的别名)
84
90
  ```
85
91
 
92
+ - `engine="pyogrio"`(默认,装了就用)或 `"fiona"`;可用 `gpd.options.io_engine` 全局指定
93
+ - `read_file(..., fid_as_index=True)`(pyogrio)把文件内的 feature id 用作索引 —— GeoPackage 的 fid 默认不在列里
94
+ - `read_file(..., use_arrow=True)`(pyogrio + pyarrow)走 Arrow 通道,官方称读速可提升 2–4 倍
95
+
86
96
  **支持的文件格式(扩展名 → 驱动):**
87
97
 
88
98
  | 扩展名 | 驱动 |
@@ -110,7 +120,9 @@ gdf.to_parquet(path, compression="snappy", geometry_encoding="WKB",
110
120
  gdf.to_feather(path, compression=None, schema_version=None, **kwargs)
111
121
  ```
112
122
 
113
- GeoParquet 规范版本:`"1.0.0"`, `"1.1.0"` 等。几何编码:`"WKB"`(默认)、`"geoarrow"`。
123
+ GeoParquet 规范版本:`schema_version` 可取 `"0.1.0"`、`"0.4.0"`、`"1.0.0"`、`"1.1.0"`、`"2.0.0"`,不传时默认写最新的稳定版 1.1.0。几何编码:`"WKB"`(默认)、`"geoarrow"`(GeoParquet 1.1 起,实验性)。
124
+
125
+ 1.2 的变化:`read_parquet` / `to_parquet` 支持(当时定义中的)GeoParquet 2.0 规范;`read_parquet` 可直接读 HTTP/HTTPS 上的文件(`storage_options` 透传给 urllib);`to_parquet` 写入的 `attrs` 会在 `read_parquet` 时读回;`write_covering_bbox=True` 写出的 `bbox` 列可让后续 `read_parquet(bbox=...)` 做过滤读取。
114
126
 
115
127
  ### Arrow (GeoArrow)
116
128
 
@@ -175,7 +187,7 @@ gpd.overlay(df1, df2, how="intersection", keep_geom_type=None, make_valid=True)
175
187
  gpd.clip(gdf, mask, keep_geom_type=False, sort=False)
176
188
  ```
177
189
 
178
- - `mask`: GeoDataFrame、GeoSeries、(Multi)Polygon 或 `(minx, miny, maxx, maxy)` 元组
190
+ - `mask`: GeoDataFrame、GeoSeries、(Multi)Polygon 或 `(minx, miny, maxx, maxy)` 元组;传入四元素列表时走更快的矩形裁剪(`clip_by_rect()`),结果不保证拓扑有效,边角情形可能与多边形裁剪略有差异
179
191
 
180
192
  ### 地理编码
181
193
 
@@ -186,6 +198,25 @@ gpd.tools.reverse_geocode(points, provider=None, **kwargs) # → GeoDataFrame
186
198
 
187
199
  需要 `geopy`。默认 provider: `"photon"`。返回含 `geometry` 和 `address` 列的 GeoDataFrame。
188
200
 
201
+ ### 网格与聚合
202
+
203
+ ```python
204
+ # 1.2 新增:按输入范围生成正方形或蜂窝网格(返回 GeoSeries)
205
+ gpd.make_grid(input_geometry, cell_size=1000, grid_type="square",
206
+ feature_type="polygons", offset=None, intersect=True, flat_topped=False)
207
+ gs.make_grid(...) # GeoSeries 上的同名方法
208
+
209
+ # 1.2 起 GeoSeries 的二元集合运算新增 grid_size(精度栅格,顶点吸附到该格网)
210
+ gs_left.union(gs_right, grid_size=1e-6)
211
+ gs_left.intersection(gs_right, grid_size=1e-6)
212
+ gs_left.difference(gs_right, grid_size=1e-6)
213
+ gs_left.symmetric_difference(gs_right, grid_size=1e-6)
214
+ ```
215
+
216
+ - `grid_type`:`"square"` 或 `"hexagon"`
217
+ - `feature_type`:`"polygons"`(面)、`"centers"`(点)、`"corners"`(顶点)
218
+ - `intersect=True` 只保留与输入几何相交的网格单元;要整块外接矩形填满网格传 `False`
219
+
189
220
  ### 其他工具
190
221
 
191
222
  ```python
@@ -362,6 +393,9 @@ m = gdf.explore(column="population", cmap="viridis",
362
393
  | `buffer(resolution=...)` 出现弃用警告 | 1.2 起 `resolution` 被弃用,向 shapely 命名惯例对齐 | 改用 `quad_segs` 参数 |
363
394
  | `DriverError` 无法写入 | 驱动不支持或文件被占用 | 检查驱动名拼写、关闭已打开的文件 |
364
395
  | `align=True` 导致意外 NaN | 二元操作默认按索引对齐 | 传入 `align=False` 或重置索引 |
396
+ | `AttributeError: module 'geopandas' has no attribute 'make_grid'` / `read_file_info` | 装的是 1.2 之前的版本(`make_grid`、`read_file_info` 均为 1.2 新增) | `python -c "import geopandas; print(geopandas.__version__)"` 确认,升级到 1.2.0+ |
397
+ | `CRSError: Invalid projection` / PROJ 数据目录缺失 | pyproj 自带 PROJ data 未生效,或混用了 conda/pip 两套环境 | `pyproj.datadir.get_data_dir()` 查目录;重装 pyproj/pyogrio 或统一用 conda-forge 环境 |
398
+ | `to_parquet` 写了 `schema_version="2.0.0"` 但下游读不了 | GeoParquet 2.0 仍新,部分读者只认 1.0/1.1 | 不传 `schema_version` 用默认 1.1.0,或显式写 `"1.0.0"` 兼容老读者 |
365
399
 
366
400
  ## AI 使用建议
367
401
 
@@ -3,6 +3,7 @@
3
3
  ## Contents
4
4
 
5
5
  - 核心类 API
6
+ - 1.2 新增接口(make_grid、read_file_info、grid_size)
6
7
 
7
8
  GeoSeries and GeoDataFrame core API details split from SKILL.md.
8
9
 
@@ -223,3 +224,53 @@ sindex.is_empty # 是否为空
223
224
 
224
225
  ---
225
226
 
227
+ ---
228
+
229
+ ## 1.2 新增接口(make_grid、read_file_info、grid_size)
230
+
231
+ 以上内容以 GeoPandas 1.2.0 为基准。1.2 新增或变更的接口如下。
232
+
233
+ ### gpd.read_file_info()
234
+
235
+ ```python
236
+ gpd.read_file_info(filename, layer=None) # -> dict,1.2 新增
237
+ ```
238
+
239
+ 返回单个图层的元数据字典(pyogrio.read_info 的别名,需装 pyogrio)。与 `gpd.list_layers()` 的分工:`list_layers()` 列出所有图层(name/geometry_type),`read_file_info()` 给某一层的完整信息(CRS、字段、要素数等)。
240
+
241
+ ### gpd.make_grid()
242
+
243
+ ```python
244
+ gpd.make_grid(input_geometry, /, cell_size, grid_type="square",
245
+ feature_type="polygons", offset=None, intersect=True, flat_topped=False)
246
+ GeoSeries.make_grid(...) # 同名方法
247
+ ```
248
+
249
+ | 参数 | 取值 | 说明 |
250
+ |------|------|------|
251
+ | `cell_size` | float | 正方形边长;六边形时为对边距离(边长 = cell_size / sqrt(3)) |
252
+ | `grid_type` | `"square"` / `"hexagon"` | 平面网格,不是 H3/S2 那种球面网格 |
253
+ | `feature_type` | `"polygons"` / `"centers"` / `"corners"` | 返回面、中心点或顶点 |
254
+ | `offset` | (x, y) | 网格左下角,默认取输入范围左下角 |
255
+ | `intersect` | bool | True 只保留与输入几何相交的单元;False 返回覆盖外接矩形的完整网格 |
256
+ | `flat_topped` | bool | 六边形是否平顶(默认尖顶朝上) |
257
+
258
+ 返回 GeoSeries(1.2 新增)。
259
+
260
+ ### 集合运算的 grid_size
261
+
262
+ 1.2 起以下 GeoSeries 方法新增 `grid_size` 参数,用于固定精度栅格(顶点吸附到指定格网,可改善拓扑鲁棒性):
263
+
264
+ ```text
265
+ union(other, align=None, grid_size=None)
266
+ intersection(other, align=None, grid_size=None)
267
+ difference(other, align=None, grid_size=None)
268
+ symmetric_difference(other, align=None, grid_size=None)
269
+ union_all(method="unary", grid_size=None)
270
+ ```
271
+
272
+ `gpd.overlay()` 没有 `grid_size` 参数,需要固定精度时先对各 GeoSeries 做 `set_precision()` 或用上述方法。
273
+
274
+ ### GeoParquet 规范版本
275
+
276
+ `to_parquet(schema_version=...)` 支持 `"0.1.0"`、`"0.4.0"`、`"1.0.0"`、`"1.1.0"`、`"2.0.0"`;不传时默认写 1.1.0。1.2 起 GeoParquet 2.0 可读写。