@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
@@ -1,23 +1,17 @@
1
1
  ---
2
2
  name: qgis-server
3
3
  description: "Use when publishing QGIS projects (.qgs/.qgz) as OGC web services — WMS GetMap/GetPrint, WFS and WFS-T, WMTS, OGC API Features via qgis_mapserv.fcgi with Apache mod_fcgid, Nginx, or Docker, plus QGIS_SERVER_* tuning (MAX_THREADS, PARALLEL_RENDERING, LOG_STDERR); covers \"Service unknown or unsupported\" and MAP/GetCapabilities checks. QGIS 4.2.3 and LTR 3.44.15."
4
- tags:
5
- - qgis
6
- - server
7
- - wms
8
- - wfs
9
- - wmts
10
- - ogc
11
- - fcgi
12
- - map
13
- - web
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "qgis, server, wms, wfs, wmts, ogc, fcgi, map, web"
14
8
  ---
15
9
 
16
10
  > **项目地址:** <https://github.com/qgis/QGIS>
17
11
  >
18
- > **官方文档:** <https://docs.qgis.org/latest/en/docs/server_manual/>
12
+ > **官方文档:** <https://docs.qgis.org/4.2/en/docs/server_manual/>(4.2 文档挂在 `/testing/` 路径下;`/latest/` 重定向到 3.44 LTR 手册,查 LTR 行为时用 <https://docs.qgis.org/3.44/en/docs/server_manual/>)
19
13
  >
20
- > **最新版本:** 4.2.3(截至 2026-10);LTR 3.44.15
14
+ > **最新版本:** 4.2.3(官网 Latest Release);LTR 3.44.15(截至 2026-11,实测 `qgis/qgis` 镜像 tag 与 <https://qgis.org/download/>)
21
15
  >
22
16
  > **许可证:** GPL-2.0
23
17
 
@@ -119,7 +113,9 @@ WMS 的 `LAYERS` 支持按短名或图层 ID 选择,多个图层用逗号分
119
113
 
120
114
  WMTS 的 `TILEMATRIXSET` 定义金字塔所用 CRS(形如 `EPSG:XXXX`),`TILEMATRIX`/`TILEROW`/`TILECOL` 定位具体瓦片;`FORMAT` 仅支持 `jpg`/`jpeg`/`image/jpeg`/`image/png`,其余值回退为 PNG。`GetFeatureInfo` 的 `INFOFORMAT` 默认 `text/plain`,用 `I`/`J` 指定像素坐标。
121
115
 
122
- OGC API - Features(WFS3)是面向 REST 的 JSON 接口,按项目发布,端点位于服务根路径下(如 `/wfs3/collections`、`/wfs3/collections/{id}/items`),支持 `limit`、`bbox`、`datetime` 等查询参数。该服务是否可用取决于项目 `OWS Server` 页的发布设置。
116
+ OGC API - Features(OAPIF,旧称 WFS3)是面向 REST 的 JSON/HTML 接口,按项目发布,服务根为 `/wfs3`(如 `/wfs3/collections`、`/wfs3/collections/{id}/items`),`/wfs3/api` 提供自描述文档,支持 `limit`、`bbox`、`datetime` 等查询参数。该服务是否可用取决于项目 `OWS Server` 页的发布设置。
117
+
118
+ > 官方注意:OAPIF 遵循 OpenAPI 规范,不接受额外查询参数,因此**不建议**在 URL 里暴露 `MAP`;改用 `QGIS_PROJECT_FILE` 环境变量或 Web 服务器重写规则指定项目(实测 QGIS 3.44/4.2 Server 手册 "OGC API Features" 一节)。
123
119
 
124
120
  ### 在项目中启用服务
125
121
 
@@ -185,7 +181,7 @@ location /qgis {
185
181
 
186
182
  1. **版本对齐**:QGIS Server 与生成项目的 QGIS Desktop 尽量使用相同主版本;跨大版本打开旧项目可能因图层/表达式不兼容而报错。生产环境优先 LTR。
187
183
  2. **优先 `.qgz`**:`.qgz` 是压缩的单文件项目,便于分发并避免路径遗漏;配合 `QGIS_PROJECT_FILE` 固定默认项目。
188
- 3. **日志走 stderr**:使用 `QGIS_SERVER_LOG_STDERR` 交给系统日志收集,`QGIS_SERVER_LOG_FILE` 已废弃并计划在 QGIS 5.0 移除。
184
+ 3. **日志走 stderr**:使用 `QGIS_SERVER_LOG_STDERR` 交给系统日志收集,`QGIS_SERVER_LOG_FILE` 已废弃。
189
185
  4. **并行渲染与线程**:高并发栅格出图时设置 `QGIS_SERVER_PARALLEL_RENDERING=true`,并用 `QGIS_SERVER_MAX_THREADS` 控制 CPU 占用。
190
186
  5. **项目缓存**:多项目场景调大 `QGIS_SERVER_PROJECT_CACHE_SIZE`,减少重复加载开销。
191
187
  6. **容错**:允许部分图层缺失时设 `QGIS_SERVER_IGNORE_BAD_LAYERS=true`,避免整份项目不可用。
@@ -205,19 +201,18 @@ location /qgis {
205
201
  | `GetPrint` 报错或输出空白 | Linux 无 X 环境,需安装并启动 `Xvfb`,在 Web 服务器配置 `DISPLAY=:99` |
206
202
  | WFS `Transaction` 提交失败 | 需通过 POST 提交(删除可用 `OPERATION`),且数据源必须可写、图层勾选相应发布权限 |
207
203
  | 高并发下响应缓慢 | 开启 `QGIS_SERVER_PARALLEL_RENDERING`、调大 `QGIS_SERVER_MAX_THREADS` 与项目缓存 |
204
+ | 直接执行 `qgis_mapserv.fcgi` 无输出 | 正常:FCGI 需由 Web 服务器以 FastCGI 协议调用;用 `curl` 带 `SERVICE=WMS&REQUEST=GetCapabilities` 验证 |
208
205
 
209
206
  ---
210
207
 
211
- ## 参考资源
208
+ ## AI 使用建议
212
209
 
213
- - QGIS Server 手册:<https://docs.qgis.org/latest/en/docs/server_manual/>
214
- - 配置与环境变量:<https://docs.qgis.org/latest/en/docs/server_manual/config.html>
215
- - WMS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wms.html>
216
- - WFS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wfs.html>
217
- - WMTS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wmts.html>
218
- - 容器化部署:<https://docs.qgis.org/latest/en/docs/server_manual/containerized_deployment.html>
219
-
220
- ---
210
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell),Windows 上 `curl` 要写 `curl.exe`;Apache/Nginx 片段属于目标服务器配置,本机会话改不了远端,需在主机上执行或用容器验证。
211
+ - **先探测版本**:用同一安装的 `qgis --version` / `qgis_process --version`(或 `dpkg -l qgis-server`、容器镜像 tag)确认服务端版本;Debian/Ubuntu 的服务入口是 `/usr/lib/cgi-bin/qgis_mapserv.fcgi`,直接执行返回 `ServiceExceptionReport` 即安装可用。本技能覆盖 4.2.3(最新)与 3.44.15(LTR),生成项目的 QGIS Desktop 与服务端大版本应一致。
212
+ - **验证服务**:先 `curl "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities"` 存盘后核对 `<Service>` 与 `<Layer>` 清单,再测 `GetMap` 出图(导出的 PNG 要实际打开看是否空白)、`GetFeature`、`GetTile`。
213
+ - **常见报错**:`Service unknown or unsupported` 是缺 `SERVICE`/`MAP` 参数而非服务故障;`GetMap` 空白先查 `MAP` 路径可读性与项目 `OWS Server` 页的 `published` 勾选,再查 CRS/`BBOX`。
214
+ - **日志与生效**:`QGIS_SERVER_LOG_STDERR=1` 交给 journald 或容器日志;`QGIS_SERVER_LOG_FILE` 已废弃,不要再用;`QGIS_SERVER_*` 改动要重启 FCGI 进程(或容器)才生效。
215
+ - **安全与权限**:启动容器、开放端口、改 Web 服务器配置前先征得用户同意;`GetPrint` 在无 X 的 Linux 上需 `Xvfb`;项目文件可能含数据库凭证,命令与回答里不要回显密码。
221
216
 
222
217
  ## 相关技能
223
218
 
@@ -228,12 +223,11 @@ location /qgis {
228
223
 
229
224
  ---
230
225
 
231
- ## DeepSeek Harness 使用建议
226
+ ## 参考资源
232
227
 
233
- - **加载与引用**:用 `skill("qgis-server")` 加载(用户也可输入 `/qgis-server`);本技能没有 reference 子目录,服务能力以 `GetCapabilities` 实测为准;技能目录只读,配置片段与导出的能力文档写到会话工作区。
234
- - **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`;仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行),Windows 上 `curl` 要写 `curl.exe`;Apache/Nginx 片段属于目标服务器配置,本机会话改不了远端,需在主机上执行或用容器验证。
235
- - **先探测版本**:用同一安装的 `qgis --version` / `qgis_process --version`(或 `dpkg -l qgis-server`、容器镜像 tag)确认服务端版本;Debian/Ubuntu 的服务入口是 `/usr/lib/cgi-bin/qgis_mapserv.fcgi`,直接执行返回 `ServiceExceptionReport` 即安装可用。本技能覆盖 4.2.3(最新)与 3.44.15(LTR),生成项目的 QGIS Desktop 与服务端大版本应一致。
236
- - **验证服务**:先 `curl "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities"` 存盘后核对 `<Service>` 与 `<Layer>` 清单,再测 `GetMap` 出图(PNG 可 `read_image` 看是否空白)、`GetFeature`、`GetTile`。
237
- - **常见报错**:`Service unknown or unsupported` 是缺 `SERVICE`/`MAP` 参数而非服务故障;`GetMap` 空白先查 `MAP` 路径可读性与项目 `OWS Server` 页的 `published` 勾选,再查 CRS/`BBOX`。
238
- - **日志与生效**:`QGIS_SERVER_LOG_STDERR=1` 交给 journald 或容器日志;`QGIS_SERVER_LOG_FILE` 已废弃,不要再用;`QGIS_SERVER_*` 改动要重启 FCGI 进程(或容器)才生效。
239
- - **安全与权限**:启动容器、开放端口、改 Web 服务器配置前先征得用户同意;`GetPrint` 在无 X 的 Linux 上需 `Xvfb`;项目文件可能含数据库凭证,命令与回答里不要回显密码。
228
+ - QGIS Server 手册:<https://docs.qgis.org/latest/en/docs/server_manual/>
229
+ - 配置与环境变量:<https://docs.qgis.org/latest/en/docs/server_manual/config.html>
230
+ - WMS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wms.html>
231
+ - WFS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wfs.html>
232
+ - WMTS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wmts.html>
233
+ - 容器化部署:<https://docs.qgis.org/latest/en/docs/server_manual/containerized_deployment.html>
@@ -1,15 +1,10 @@
1
1
  ---
2
2
  name: shapely
3
3
  description: "Use when doing computational geometry in Python — shapely.intersection/union/buffer/convex_hull/simplify, STRtree queries, from_wkt/to_wkt/to_geojson, make_valid, GEOS-gated ops (coverage_clean, split); also for TopologyException on self-intersecting polygons or OOP vs function buffer quad_segs mismatch. Shapely 2.2.0 binds GEOS."
4
- tags:
5
- - python
6
- - geometry
7
- - geos
8
- - wkt
9
- - wkb
10
- - geojson
11
- - spatial
12
- - numpy
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "python, geometry, geos, wkt, wkb, geojson, spatial, numpy"
13
8
  ---
14
9
 
15
10
  > **项目地址:** <https://github.com/shapely/shapely>
@@ -18,7 +13,7 @@ tags:
18
13
  >
19
14
  > **PyPI:** <https://pypi.org/project/shapely/>
20
15
  >
21
- > **最新版本:** 2.2.0(截至2026-10,PyPI)
16
+ > **最新版本:** 2.2.0(截至 2026-11,[PyPI](https://pypi.org/project/shapely/);[GitHub Release](https://github.com/shapely/shapely/releases))
22
17
  >
23
18
  > **许可证:** BSD-3-Clause
24
19
 
@@ -35,7 +30,7 @@ Shapely 是 Python 计算几何的核心库,基于 GEOS(Geometry Engine - Op
35
30
  - **格式读写**:WKT、WKB、GeoJSON
36
31
  - **双重 API**:函数式(向量化,支持 NumPy 广播)+ OOP(标量便捷)
37
32
 
38
- **环境要求:** Python 3.11+(Shapely 2.2 起;2.1 为 3.10+),NumPy >= 1.26,GEOS >= 3.10。PyPI 二进制 wheel 内含 GEOS 3.14.1。
33
+ **环境要求:** Python 3.11+(Shapely 2.2 起;2.1 为 3.10+),NumPy >= 1.26,GEOS >= 3.10。PyPI 二进制 wheel 内含 GEOS 3.14。
39
34
 
40
35
  ---
41
36
 
@@ -55,28 +50,28 @@ python -c "import shapely; print(shapely.__version__, shapely.geos_version)"
55
50
 
56
51
  ---
57
52
 
58
- ## Geometry Types
53
+ ## 几何类型
59
54
 
60
- | Type | Class | Description |
55
+ | 类型 | 类 | 说明 |
61
56
  |------|-------|-------------|
62
- | Point | `shapely.Point` | Single coordinate (x, y [, z [, m]]) |
63
- | LineString | `shapely.LineString` | Ordered sequence of 2+ points |
64
- | LinearRing | `shapely.LinearRing` | Closed, simple LineString |
65
- | Polygon | `shapely.Polygon` | Exterior ring + optional holes |
66
- | MultiPoint | `shapely.MultiPoint` | Collection of Points |
67
- | MultiLineString | `shapely.MultiLineString` | Collection of LineStrings |
68
- | MultiPolygon | `shapely.MultiPolygon` | Collection of Polygons |
69
- | GeometryCollection | `shapely.GeometryCollection` | Heterogeneous collection |
57
+ | Point | `shapely.Point` | 单个坐标 (x, y [, z [, m]]) |
58
+ | LineString | `shapely.LineString` | 由 2 个以上点组成的有序序列 |
59
+ | LinearRing | `shapely.LinearRing` | 闭合的简单 LineString |
60
+ | Polygon | `shapely.Polygon` | 外环 + 可选内环(洞) |
61
+ | MultiPoint | `shapely.MultiPoint` | 点集合 |
62
+ | MultiLineString | `shapely.MultiLineString` | 线集合 |
63
+ | MultiPolygon | `shapely.MultiPolygon` | 面集合 |
64
+ | GeometryCollection | `shapely.GeometryCollection` | 异构几何集合 |
70
65
 
71
- Z coordinates are **ignored for all spatial analysis** — operations are performed in the x-y plane only.
66
+ **所有空间分析都忽略 Z 值** —— 运算只在 x-y 平面进行。
72
67
 
73
- ## Dual API Pattern
68
+ ## 双 API 模式
74
69
 
75
- Shapely provides two APIs. Prefer the **function-based API** for arrays and performance; use the **OOP API** for scalar convenience.
70
+ Shapely 提供两套 API:处理数组、追求性能时优先用**函数式 API**,只做单个几何的便捷操作时用**面向对象 API**。
76
71
 
77
- ### Function-based (vectorized, NumPy ufunc)
72
+ ### 函数式 API(向量化,NumPy ufunc)
78
73
 
79
- All functions release the GIL during GEOS execution, support NumPy broadcasting, and handle arrays natively.
74
+ 这些函数在 GEOS 运算期间释放 GIL,支持 NumPy 广播,并原生处理数组。
80
75
 
81
76
  ```python
82
77
  import shapely
@@ -89,7 +84,7 @@ shapely.buffer(geoms, 1.0) # array of polygons
89
84
  shapely.distance(geoms, other) # array of distances
90
85
  ```
91
86
 
92
- ### OOP (method-based, scalar)
87
+ ### 面向对象 API(方法式,标量)
93
88
 
94
89
  ```python
95
90
  from shapely import Point, Polygon
@@ -103,7 +98,7 @@ poly.contains(p)
103
98
  poly.intersection(other)
104
99
  ```
105
100
 
106
- ### Operator overloading
101
+ ### 运算符重载
107
102
 
108
103
  ```python
109
104
  geom1 & geom2 # intersection
@@ -112,9 +107,9 @@ geom1 - geom2 # difference
112
107
  geom1 ^ geom2 # symmetric_difference
113
108
  ```
114
109
 
115
- ## Geometry Creation
110
+ ## 几何对象创建
116
111
 
117
- ### From coordinates (OOP)
112
+ ### 从坐标创建(面向对象)
118
113
 
119
114
  ```python
120
115
  from shapely import Point, LineString, LinearRing, Polygon
@@ -132,7 +127,7 @@ MultiPolygon([poly1, poly2])
132
127
  GeometryCollection([point, line, poly])
133
128
  ```
134
129
 
135
- ### From coordinates (vectorized)
130
+ ### 从坐标创建(向量化)
136
131
 
137
132
  ```python
138
133
  import shapely
@@ -149,7 +144,7 @@ shapely.multipolygons(...)
149
144
  shapely.geometrycollections(...)
150
145
  ```
151
146
 
152
- ### From serialization formats
147
+ ### 从序列化格式创建
153
148
 
154
149
  ```python
155
150
  # WKT
@@ -169,7 +164,7 @@ shapely.from_ragged_array(geometry_type, coords, offsets)
169
164
  shapely.to_ragged_array(geometries)
170
165
  ```
171
166
 
172
- ### From/to GeoJSON-like dict (`__geo_interface__`)
167
+ ### 与 GeoJSON 字典互转(`__geo_interface__`)
173
168
 
174
169
  ```python
175
170
  from shapely.geometry import shape, mapping
@@ -180,7 +175,7 @@ d = mapping(geom) # {"type": "Point", "coordinates": (0.0, 0.0)}
180
175
 
181
176
  > 构造操作、空间谓词、集合运算、测量、空间索引、仿射与坐标变换及线性参考的完整 API 见 [reference/operations-reference.md](reference/operations-reference.md)
182
177
 
183
- ## Validation
178
+ ## 有效性校验
184
179
 
185
180
  ```python
186
181
  shapely.is_valid(geom)
@@ -188,9 +183,9 @@ shapely.is_valid_reason(geom)
188
183
  shapely.make_valid(geom, method="linework") # or "structure"
189
184
  ```
190
185
 
191
- ## Prepared Geometry
186
+ ## 预处理几何(Prepared Geometry)
192
187
 
193
- Caches spatial index for repeated predicate tests against the same geometry.
188
+ 为同一几何的重复谓词判断缓存空间索引。
194
189
 
195
190
  ```python
196
191
  shapely.prepare(geom) # in-place, returns True if newly prepared
@@ -198,61 +193,112 @@ shapely.destroy_prepared(geom) # free cache
198
193
  shapely.is_prepared(geom)
199
194
  ```
200
195
 
201
- ## Missing Values
196
+ ## 缺失值
202
197
 
203
- `None` represents missing geometries. Consistent behavior:
204
- - Predicates return `False`
205
- - Measurements return `nan`
206
- - Constructive operations return `None`
198
+ `None` 表示缺失几何,各函数行为保持一致:
199
+ - 谓词返回 `False`
200
+ - 度量返回 `nan`
201
+ - 构造类操作返回 `None`
207
202
 
208
- Use `shapely.is_missing(obj)` to check, distinct from `shapely.is_empty(geom)`.
203
+ 用 `shapely.is_missing(obj)` 判断,注意它与 `shapely.is_empty(geom)`(空几何)不同。
209
204
 
210
- ## Important Caveats
205
+ ## 重要注意事项
211
206
 
212
- 1. **Z ignored in analysis**: All spatial operations work in x-y plane only. Geometries with different z values may still intersect or be equal.
207
+ 1. **分析中忽略 Z 值**:所有空间运算只在 x-y 平面进行,Z 值不同的几何仍可能相交或相等。
213
208
 
214
- 2. **`contains` excludes boundary**: `contains(line, endpoint)` is `False`. Use `covers()` or `intersects()` if you need boundary inclusion.
209
+ 2. **`contains` 不含边界**:`contains(line, endpoint)` 为 `False`;需要把边界算在内时用 `covers()` 或 `intersects()`。
215
210
 
216
- 3. **`set_coordinates` modifies in-place**: Copy geometry first with `.copy()` if originals must be preserved.
211
+ 3. **`set_coordinates` 原地修改**:需保留原几何时,先 `.copy()`。
217
212
 
218
- 4. **`clip_by_rect` may produce invalid output**: The fast clip is not guaranteed to yield valid topology.
213
+ 4. **`clip_by_rect` 可能产出无效几何**:这个快速裁剪不保证拓扑有效。
219
214
 
220
- 5. **WKB drops LinearRing**: LinearRings become LineStrings during WKB serialization.
215
+ 5. **WKB 丢失 LinearRing**:LinearRing 在 WKB 序列化时变成 LineString。
221
216
 
222
- 6. **`to_geojson` drops Z**: Third dimension is silently discarded; LinearRing outputs as `null`.
217
+ 6. **`to_geojson` 丢弃 Z**:第三维被静默丢弃,LinearRing 输出为 `null`。
223
218
 
224
- 7. **OOP vs function `buffer` defaults differ**: `Point(0,0).buffer(1)` uses `quad_segs=16`; `shapely.buffer(Point(0,0), 1)` uses `quad_segs=8`.
219
+ 7. **面向对象与函数式 `buffer` 默认值不同**:`Point(0,0).buffer(1)` 用 `quad_segs=16`,`shapely.buffer(Point(0,0), 1)` 用 `quad_segs=8`。
225
220
 
226
- 8. **`set_precision` changes vertex order**: Returned geometry is in "mild canonical form" — vertex order should not be relied upon.
221
+ 8. **`set_precision` 改变顶点顺序**:返回几何处于"轻度规范化"形式,不要依赖其顶点顺序。
227
222
 
228
- 9. **NaN coordinates**: Creating geometries with NaN/Inf is allowed by default. Use `handle_nan='error'` or `handle_nan='skip'` in creation functions to control this.
223
+ 9. **NaN 坐标**:默认允许用 NaN/Inf 构造几何;需要控制时在创建函数里传 `handle_nan='error'` 或 `handle_nan='skip'`。
229
224
 
230
- 10. **Prepared state not preserved**: After any operation producing a new geometry, `prepare()` must be called again.
225
+ 10. **预处理状态不保留**:任何产生新几何的运算之后,都要重新调用 `prepare()`。
231
226
 
232
- 11. **GEOS version gates**: `concave_hull`, `constrained_delaunay_triangles`, `remove_repeated_points` require GEOS >= 3.11. `coverage_simplify`, `has_m`, `get_m` require GEOS >= 3.12. `coverage_clean` requires GEOS >= 3.14; top-level `split` requires GEOS >= 3.15 (older GEOS falls back to `shapely.ops.split`).
227
+ 11. **GEOS 版本门槛**:`concave_hull`、`constrained_delaunay_triangles`、`remove_repeated_points` 需 GEOS >= 3.11;`coverage_simplify`、`has_m`、`get_m` 需 GEOS >= 3.12;`coverage_clean` 需 GEOS >= 3.14;顶层 `split` 需 GEOS >= 3.15(低版本自动回退到 `shapely.ops.split`)。
233
228
 
234
- 12. **`shapely.ops.transform` deprecated**: since 2.2 use `shapely.transform` (per-coordinate) or `shapely.transform_coordseq` (per-coordinate sequence) instead. The `multithreading_enabled` decorator is also deprecated.
229
+ 12. **`shapely.ops.transform` 已弃用**:2.2 起改用 `shapely.transform`(按坐标逐点)或 `shapely.transform_coordseq`(按坐标序列);`multithreading_enabled` 装饰器同样已弃用。
235
230
 
236
- ## 典型工作流与常用模式(Common Patterns)
231
+ ## 典型工作流
232
+
233
+ 端到端:WKT 读入 → 有效性修复 → 裁剪/缓冲 → 写回 GeoJSON,全程用函数式 API。
237
234
 
238
- ### Point-in-polygon test for many points
239
235
  ```python
236
+ import json
237
+ import numpy as np
238
+ import shapely
239
+
240
+ # 1. 读入输入几何(WKT 或 WKB)
241
+ parcels = shapely.from_wkt([
242
+ "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))",
243
+ "POLYGON ((20 20, 30 30, 30 20, 20 30, 20 20))", # 自相交的"蝴蝶结",无效
244
+ ])
245
+ clip_poly = shapely.from_wkt("POLYGON ((5 5, 25 5, 25 25, 5 25, 5 5))")
246
+
247
+ # 2. 先查有效性,无效的再修复(不要盲目 buffer(0))
248
+ print(shapely.is_valid(parcels)) # [True False]
249
+ print(shapely.is_valid_reason(parcels[1])) # Self-intersection[25 25]
250
+ parcels = np.where(shapely.is_valid(parcels), parcels,
251
+ shapely.make_valid(parcels)) # 无效的那个变成 MultiPolygon
252
+
253
+ # 3. 空间运算:裁剪 + 缓冲区
254
+ clipped = shapely.intersection(parcels, clip_poly)
255
+ buffered = shapely.buffer(clipped, 1.0, quad_segs=8) # 显式指定 quad_segs
256
+
257
+ # 4. 度量(示例坐标无投影,面积即平面面积)
258
+ print(shapely.area(clipped)) # 每个几何的面积数组
259
+
260
+ # 5. 写出 GeoJSON(FeatureCollection)
261
+ features = [
262
+ {"type": "Feature", "properties": {"id": int(i)},
263
+ "geometry": json.loads(shapely.to_geojson(g))}
264
+ for i, g in enumerate(buffered) if not shapely.is_empty(g)
265
+ ]
266
+ with open("clipped.geojson", "w", encoding="utf-8") as fh:
267
+ json.dump({"type": "FeatureCollection", "features": features}, fh)
268
+ ```
269
+
270
+ **输出与验收**:`clipped.geojson` 中每个 Feature 都能被 `shapely.from_geojson()` 重新读入;`shapely.is_valid()` 全为 `True`;面积量级应与输入量级同阶(若用经纬度坐标,先投影再算,见下)。
271
+
272
+ ## 常用模式
273
+
274
+ ### 大批量点落在面内判断
275
+ ```python
276
+ import numpy as np
277
+ import shapely
240
278
  from shapely import STRtree, points
241
279
 
242
- pts = points(np.random.rand(10000, 2))
243
- tree = STRtree(pts)
280
+ rng = np.random.default_rng(0)
281
+ pts = points(rng.random((10000, 2)))
282
+ polygon = shapely.box(0.2, 0.2, 0.6, 0.6) # 待查询的面
283
+
284
+ tree = STRtree(pts) # 索引点集
244
285
  idx = tree.query(polygon, predicate="intersects")
245
- inside_points = pts[idx]
286
+ inside_points = pts[idx] # 落面内的点
246
287
  ```
247
288
 
248
- ### Batch union of many polygons
289
+ ### 批量合并大量多边形
249
290
  ```python
291
+ import shapely
292
+
250
293
  result = shapely.union_all(polygon_array)
251
294
  ```
252
295
 
253
- ### Coordinate projection (e.g., with pyproj)
296
+ ### 坐标投影(配合 pyproj)
254
297
  ```python
298
+ import numpy as np
299
+ import shapely
255
300
  from pyproj import Transformer
301
+
256
302
  transformer = Transformer.from_crs("EPSG:4326", "EPSG:3857", always_xy=True)
257
303
 
258
304
  def project(coords):
@@ -262,32 +308,23 @@ def project(coords):
262
308
  projected = shapely.transform(geom, project)
263
309
  ```
264
310
 
265
- ### Extract all coordinates from mixed geometries
311
+ ### 从混合几何中提取全部坐标
266
312
  ```python
313
+ import shapely
314
+
267
315
  coords = shapely.get_coordinates(geom_array, include_z=False)
268
316
  # coords shape: (N, 2)
269
317
  ```
270
318
 
271
- ### Spatial join pattern
319
+ ### 空间连接模式
272
320
  ```python
321
+ from shapely import STRtree
322
+
273
323
  tree = STRtree(right_geoms)
274
324
  left_idx, right_idx = tree.query(left_geoms, predicate="intersects")
275
325
  # left_idx[i] and right_idx[i] are paired matches
276
326
  ```
277
327
 
278
- ## DeepSeek Harness 使用建议
279
-
280
- - **加载与引用**:用 `skill("shapely")` 加载(用户也可输入 `/shapely`);`reference/operations-reference.md` 按需 `read`,路径相对加载结果中的 Base directory;技能目录只读,验证脚本与产物写到会话工作区。
281
- - **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`,仅暴露 `run_code` 的会话在 `tools.pwsh` 里跑);`python` 不一定是 QGIS/GDAL 自带环境,先 `python -c "import sys; print(sys.executable, sys.version)"`。
282
- - **先探测版本**:`python -c "import shapely; print(shapely.__version__, shapely.geos_version)"`;本技能按 2.2.0 编写,PyPI wheel 内含 GEOS 3.14.1。GEOS 低版本请按第 11 条降级(如 `coverage_clean` 需 3.14、`shapely.split` 需 3.15)。
283
- - **验证产物(必做)**:`print(shapely.is_valid(g), shapely.is_valid_reason(g))` 报无效原因;面积/长度做量级断言;序列化回读 `shapely.from_wkt(shapely.to_wkt(g, rounding_precision=-1)).equals(g)`,改过几何后再核对一次 `geom_type` 与 `get_num_geometries()`。
284
- - **报错先查有效性**:`TopologyException: side location conflict` 基本都是输入几何自相交,先 `shapely.make_valid(g)`(可指定 `method="structure"`)再算,不要直接加 `buffer(0)`。
285
- - **性能与内存**:批量操作走向量化函数(`shapely.union_all`、`shapely.buffer(geoms, r)`),别逐条 OOP 循环;十万级以上几何先 `STRtree(geoms)` 过滤,再对小集合做精确谓词。
286
- - **典型误操**:`set_coordinates()`/`shapely.prepare()` 都是原地修改,先 `.copy()`;`shapely.buffer` 默认 `quad_segs=8` 与 `Point.buffer()` 的 16 不同,比较结果前显式传参。
287
- - **安全**:`pip install shapely` 前先征得用户同意;输出 WKT/坐标前确认数据是否敏感(精确坐标可反推位置),大几何 dump 到文件再分段读,别刷屏。
288
-
289
- ---
290
-
291
328
  ## 常见问题
292
329
 
293
330
  | 问题 | 解决 |
@@ -300,18 +337,24 @@ left_idx, right_idx = tree.query(left_geoms, predicate="intersects")
300
337
  | STRtree 查询返回空数组 | 检查几何是否 `None`/`Empty`;确认查询几何与索引几何的 CRS 一致 |
301
338
  | WKB 序列化丢失 LinearRing | WKB 规范不支持 LinearRing,会自动转为 LineString |
302
339
  | `to_geojson` 丢失 Z 坐标 | GeoJSON 标准不支持 Z,改用 WKB 或自定义序列化 |
303
- | `shapely.ops.transform` 弃用警告 | 2.2 起弃用 | 改用 `shapely.transform` 或 `shapely.transform_coordseq` |
340
+ | `shapely.ops.transform` 弃用警告 | 2.2 起弃用,改用 `shapely.transform` 或 `shapely.transform_coordseq` |
304
341
 
305
342
  ---
306
343
 
307
- ## 相关技能
344
+ ## AI 使用建议
308
345
 
309
- - **geopandas** — 基于 Shapely 的矢量数据分析库:[../geopandas/SKILL.md](../geopandas/SKILL.md)
310
- - **pyqgis** — QGIS Python 绑定(也使用 GEOS/QgsGeometry):[../pyqgis/SKILL.md](../pyqgis/SKILL.md)
311
- - **jts** — Java 几何计算(Shapely 的 GEOS 底层是 JTS 的 C++ 移植):[../jts/SKILL.md](../jts/SKILL.md)
312
- - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
346
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/operations-reference.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
347
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell);`python` 不一定是 QGIS/GDAL 自带环境,先 `python -c "import sys; print(sys.executable, sys.version)"`。
348
+ - **先探测版本**:`python -c "import shapely; print(shapely.__version__, shapely.geos_version)"`;本技能按 2.2.0 编写,PyPI wheel 内含 GEOS 3.14。GEOS 低版本请按第 11 条降级(如 `coverage_clean` 需 3.14、`shapely.split` 需 3.15)。
349
+ - **验证产物(必做)**:`print(shapely.is_valid(g), shapely.is_valid_reason(g))` 报无效原因;面积/长度做量级断言;序列化回读 `shapely.from_wkt(shapely.to_wkt(g, rounding_precision=-1)).equals(g)`,改过几何后再核对一次 `geom_type` 与 `get_num_geometries()`。
350
+ - **报错先查有效性**:`TopologyException: side location conflict` 基本都是输入几何自相交,先 `shapely.make_valid(g)`(可指定 `method="structure"`)再算,不要直接加 `buffer(0)`。
351
+ - **性能与内存**:批量操作走向量化函数(`shapely.union_all`、`shapely.buffer(geoms, r)`),别逐条 OOP 循环;十万级以上几何先 `STRtree(geoms)` 过滤,再对小集合做精确谓词。
352
+ - **典型误操**:`set_coordinates()`/`shapely.prepare()` 都是原地修改,先 `.copy()`;`shapely.buffer` 默认 `quad_segs=8` 与 `Point.buffer()` 的 16 不同,比较结果前显式传参。
353
+ - **安全**:`pip install shapely` 前先征得用户同意;输出 WKT/坐标前确认数据是否敏感(精确坐标可反推位置),大几何 dump 到文件再分段读,别刷屏。
354
+
355
+ ---
313
356
 
314
- ## Package Structure
357
+ ## 包结构
315
358
 
316
359
  ```text
317
360
  shapely/
@@ -341,6 +384,15 @@ shapely/
341
384
 
342
385
  ---
343
386
 
387
+ ## 相关技能
388
+
389
+ - **geopandas** — 基于 Shapely 的矢量数据分析库:[../geopandas/SKILL.md](../geopandas/SKILL.md)
390
+ - **pyqgis** — QGIS Python 绑定(也使用 GEOS/QgsGeometry):[../pyqgis/SKILL.md](../pyqgis/SKILL.md)
391
+ - **jts** — Java 几何计算(Shapely 的 GEOS 底层是 JTS 的 C++ 移植):[../jts/SKILL.md](../jts/SKILL.md)
392
+ - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
393
+
394
+ ---
395
+
344
396
  ## 参考资源
345
397
 
346
398
  - **GitHub 仓库:** <https://github.com/shapely/shapely>
@@ -1,5 +1,17 @@
1
1
  # Shapely Operations API Reference
2
2
 
3
+ ## Contents
4
+
5
+ - Constructive Operations
6
+ - Spatial Predicates
7
+ - Set-Theoretic Operations
8
+ - Measurements
9
+ - STRtree Spatial Index
10
+ - Geometry Accessors
11
+ - Affine Transforms
12
+ - Coordinate Transforms
13
+ - Linear Referencing
14
+
3
15
  Constructive operations, predicates, set operations, measurements, indexing and coordinate operations split from SKILL.md.
4
16
 
5
17
  ---