@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
@@ -0,0 +1,372 @@
1
+ ---
2
+ name: geos
3
+ description: "Use when working with the GEOS C/C++ geometry engine that powers PostGIS, QGIS, Shapely and GDAL — GEOSGeomFromWKT/GEOSIntersection/GEOSBuffer/GEOSMakeValid C API, geos::geom C++ API, OverlayNG robustness, GEOSPrepare and GEOSSTRtree, or debugging TopologyException and self-intersection."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "c, cpp, geometry, topology, overlay, postgis, shapely, gis"
8
+ ---
9
+
10
+ > **项目地址:** <https://github.com/libgeos/geos>
11
+ >
12
+ > **官方文档:** <https://libgeos.org/>
13
+ >
14
+ > **最新版本:** 3.15.0(2026-09-01 发布,截至 2026-11,[Release 3.15.0](https://github.com/libgeos/geos/releases/tag/3.15.0) / [下载与构建页](https://libgeos.org/usage/download/))
15
+ >
16
+ > **C API 文档:** <https://libgeos.org/usage/c_api/> | **C++ API 文档:** <https://libgeos.org/usage/cpp_api/>
17
+ >
18
+ > **许可证:** LGPL-2.1(C 库链接后按 LGPL 动态链接条款使用)
19
+
20
+ ## 概述
21
+
22
+ GEOS(Geometry Engine, Open Source)是用 C++ 实现的二维矢量几何运算库,主体移植自 Java 的 JTS Topology Suite。它是开源空间数据栈的「几何内核」:PostGIS 的 ST_Intersection/ST_Buffer、QGIS 的叠加分析、Python Shapely、GDAL/OGR 的矢量叠加后端、R 的 sf 包,底层都在调用 GEOS。
23
+
24
+ 核心能力:
25
+
26
+ - **几何模型**:Point / LineString / LinearRing / Polygon / Multi* / GeometryCollection,支持 XY、XYZ、XYM、XYZM
27
+ - **空间关系**:Intersects、Contains、Within、Touches、Crosses、Overlaps、Covers、Relate(DE-9IM)
28
+ - **集合与叠加运算**:Intersection、Union、Difference、SymDifference、UnaryUnion、Buffer、Clip、Split
29
+ - **构造与修复**:MakeValid、Normalize、Snap、Node、Polygonize、Densify、Simplify
30
+ - **索引与加速**:STRtree(批量窗口查询、最近邻)、PreparedGeometry(重复谓词加速)
31
+ - **序列化**:WKT、WKB、GeoJSON 读写器
32
+
33
+ **与相邻技术的分工**:JTS 是同一套算法的 Java 实现(GEOS 的语义上游);Shapely 是 GEOS 的 Python 绑定;PostGIS 把 GEOS 编译进数据库后端;GDAL/OGR 用 GEOS 做矢量叠加,但数据格式读写由 GDAL 负责。需要跨语言一致结果时以 GEOS 版本为准——不同 GEOS 版本的叠加结果可能有细微差异。
34
+
35
+ **API 选型结论先行**:一般应用用 **C API**(`geos_c.h`,ABI 稳定、可跨小版本换库);要嵌入 C++ 工程并接受重新编译时用 **C++ API**(`geos/geom/*.h`,无 ABI 稳定承诺)。下文示例默认 C API,C++ 差异单独标注。
36
+
37
+ ---
38
+
39
+ ## 环境准备与安装
40
+
41
+ ### 通过包管理器
42
+
43
+ ```bash
44
+ # Ubuntu / Debian(需要更新版本时可加 ppa:ubuntugis/ppa)
45
+ sudo apt-get install geos libgeos-dev
46
+
47
+ # RHEL / Amazon Linux(EPEL 提供)
48
+ sudo yum install -y epel-release geos geos-devel
49
+
50
+ # macOS
51
+ brew install geos
52
+ ```
53
+
54
+ ```bash
55
+ # 自检:确认版本与头文件/库可见
56
+ geos-config --version
57
+ pkg-config --modversion geos
58
+ ```
59
+
60
+ ### 从源码构建(官方 CMake 流程)
61
+
62
+ ```bash
63
+ tar xvfj geos-3.15.0.tar.bz2
64
+ cd geos-3.15.0
65
+ mkdir _build && cd _build
66
+
67
+ cmake \
68
+ -DCMAKE_BUILD_TYPE=Release \
69
+ -DCMAKE_INSTALL_PREFIX=/usr/local \
70
+ ..
71
+ make -j4
72
+ ctest # 可选但建议:跑一遍单元测试
73
+ sudo make install
74
+ ```
75
+
76
+ **构建要求**:CMake ≥ 3.15、支持 C++14 的编译器(常规测试 GCC / Clang / MSVC)、可选 Doxygen 生成 API 文档。常用开关:`BUILD_SHARED_LIBS=ON`(默认开)、`BUILD_TESTING=ON`(默认开)、`BUILD_DOCUMENTATION=OFF`(默认关)、`CMAKE_BUILD_TYPE` 取 `Release` / `RelWithDebInfo` / `Debug` / `ASAN`。
77
+
78
+ 链接时 C API 用 `-lgeos_c`,C++ API 用 `-lgeos`。用 pkg-config 更省事:
79
+
80
+ ```bash
81
+ cc myapp.c -o myapp $(pkg-config --cflags --libs geos)
82
+ ```
83
+
84
+ Windows 下建议用 vcpkg 或 conda-forge 安装,并让 `geos_c.dll` 与可执行文件同目录或加入 `PATH`。
85
+
86
+ ---
87
+
88
+ ## C API 基础骨架
89
+
90
+ C API 只有一个头文件 `<geos_c.h>`,使用前必须注册消息回调并初始化全局状态,退出时清理。
91
+
92
+ ```c
93
+ #include <stdio.h>
94
+ #include <stdarg.h>
95
+ #include <geos_c.h>
96
+
97
+ static void geos_msg_handler(const char *fmt, ...) {
98
+ va_list ap;
99
+ va_start(ap, fmt);
100
+ vfprintf(stderr, fmt, ap);
101
+ va_end(ap);
102
+ }
103
+
104
+ int main(void) {
105
+ initGEOS(geos_msg_handler, geos_msg_handler);
106
+
107
+ GEOSWKTReader *reader = GEOSWKTReader_create();
108
+ GEOSGeometry *geom = GEOSWKTReader_read(reader, "POINT(1 1)");
109
+
110
+ GEOSWKTWriter *writer = GEOSWKTWriter_create();
111
+ char *wkt = GEOSWKTWriter_write(writer, geom);
112
+ printf("%s\n", wkt);
113
+
114
+ GEOSFree(wkt); /* GEOS 分配的字符串必须用 GEOSFree 释放 */
115
+ GEOSGeom_destroy(geom);
116
+ GEOSWKTWriter_destroy(writer);
117
+ GEOSWKTReader_destroy(reader);
118
+
119
+ finishGEOS();
120
+ return 0;
121
+ }
122
+ ```
123
+
124
+ 编译:`cc hello.c -o hello -lgeos_c`。
125
+
126
+ ### 可重入与多线程版本
127
+
128
+ 所有 C 函数都有 `_r` 后缀的可重入变体,多一个 `GEOSContextHandle_t` 参数。每个线程各自 `GEOS_init_r()` 建上下文、自己 `GEOS_finish_r()`,**不要跨线程共享 context handle**。
129
+
130
+ ```c
131
+ GEOSContextHandle_t ctx = GEOS_init_r();
132
+ GEOSContext_setNoticeHandler_r(ctx, geos_msg_handler);
133
+ GEOSContext_setErrorHandler_r(ctx, geos_msg_handler);
134
+
135
+ GEOSWKTReader *reader = GEOSWKTReader_create_r(ctx);
136
+ GEOSGeometry *g = GEOSWKTReader_read_r(ctx, reader, "POINT(1 1)");
137
+ GEOSWKTWriter *writer = GEOSWKTWriter_create_r(ctx);
138
+ char *wkt = GEOSWKTWriter_write_r(ctx, writer, g);
139
+
140
+ GEOSFree_r(ctx, wkt);
141
+ GEOSGeom_destroy_r(ctx, g);
142
+ GEOSWKTWriter_destroy_r(ctx, writer);
143
+ GEOSWKTReader_destroy_r(ctx, reader);
144
+ GEOS_finish_r(ctx);
145
+ ```
146
+
147
+ ---
148
+
149
+ ## 核心 API
150
+
151
+ ### 几何构造
152
+
153
+ | 用途 | C 函数 |
154
+ |---|---|
155
+ | 点 | `GEOSGeom_createPointFromXY(x, y)`、`GEOSGeom_createPoint(seq)` |
156
+ | 线串 / 环 | `GEOSGeom_createLineString(seq)`、`GEOSGeom_createLinearRing(seq)` |
157
+ | 面 | `GEOSGeom_createPolygon(shell, holes, nholes)` |
158
+ | 集合 | `GEOSGeom_createCollection(type, geoms, n)` |
159
+ | 坐标序列 | `GEOSCoordSeq_create(n, dims)`、`GEOSCoordSeq_copyFromBuffer(buf, n, hasZ, hasM)` |
160
+ | 文本 → 几何 | `GEOSWKTReader_read`、`GEOSWKBReader_read`、`GEOSGeoJSONReader_readGeometry` |
161
+
162
+ ```c
163
+ /* 用坐标数组造一条 3 点的线,再转 WKT */
164
+ double coords[] = {0, 0, 10, 10, 20, 0};
165
+ GEOSCoordSequence *seq = GEOSCoordSeq_copyFromBuffer(coords, 3, 0, 0);
166
+ GEOSGeometry *line = GEOSGeom_createLineString(seq); /* 所有权转移给 geometry */
167
+ ```
168
+
169
+ **所有权规则**:`GEOSGeom_create*()` 接收坐标序列后由其负责释放,**不要再手动 `GEOSCoordSeq_destroy`**;几何对象一律 `GEOSGeom_destroy()`,GEOS 返回的字符串一律 `GEOSFree()`。
170
+
171
+ ### 叠加与缓冲
172
+
173
+ ```c
174
+ GEOSGeometry *a = GEOSWKTReader_read(r, "POLYGON((0 0,10 0,10 10,0 10,0 0))");
175
+ GEOSGeometry *b = GEOSWKTReader_read(r, "POLYGON((5 5,15 5,15 15,5 15,5 5))");
176
+
177
+ GEOSGeometry *inter = GEOSIntersection(a, b); /* 相交 */
178
+ GEOSGeometry *uni = GEOSUnion(a, b); /* 合并 */
179
+ GEOSGeometry *diff = GEOSDifference(a, b); /* 差集 */
180
+ GEOSGeometry *sym = GEOSSymDifference(a, b); /* 对称差 */
181
+ GEOSGeometry *buf = GEOSBuffer(a, 2.0, 8); /* 半径 2,每四分之一圆 8 段 */
182
+ GEOSGeometry *hull = GEOSConvexHull(a);
183
+ ```
184
+
185
+ `GEOSBuffer` 默认圆头圆角;方头 / 斜接需用 `GEOSBufferWithStyle`(参数:quadSegs、endCapStyle、joinStyle、mitreLimit)。
186
+
187
+ ### 空间谓词与 DE-9IM
188
+
189
+ ```c
190
+ char hit = GEOSIntersects(a, b); /* 1 真 / 2 假 / 0 异常 */
191
+ char inside = GEOSContains(a, b);
192
+ char covered = GEOSCovers(a, b);
193
+ char rel = GEOSRelatePattern(a, b, "T*F**FFF*");
194
+ char *matrix = GEOSRelate(a, b); /* 9 字符 DE-9IM 矩阵 */
195
+ GEOSFree(matrix);
196
+ ```
197
+
198
+ 谓词返回 `char`:`1` 真、`2` 假、`0` 出错(查错误回调)。**不要当布尔直接取反**。
199
+
200
+ ### PreparedGeometry:重复谓词加速
201
+
202
+ 同一个大面被几万个点反复 `Intersects` / `Contains` 时,预处理能带来数量级提升。
203
+
204
+ ```c
205
+ const GEOSPreparedGeometry *prep = GEOSPrepare(polygon); /* 只读,不接管 polygon 所有权 */
206
+ for (size_t i = 0; i < n; i++) {
207
+ if (GEOSPreparedIntersects(prep, pts[i]) == 1) {
208
+ /* 命中 */
209
+ }
210
+ }
211
+ GEOSPreparedGeom_destroy(prep);
212
+ /* polygon 与 pts 仍需自行 destroy */
213
+ ```
214
+
215
+ ### STRtree:窗口查询与最近邻
216
+
217
+ ```c
218
+ typedef struct { GEOSGeometry *geom; size_t id; } item;
219
+
220
+ GEOSSTRtree *tree = GEOSSTRtree_create(10); /* 参数是节点分支数,10 是常用值 */
221
+ for (size_t i = 0; i < n; i++) {
222
+ GEOSSTRtree_insert(tree, items[i]->geom, items[i]); /* 只存指针,不接管所有权 */
223
+ }
224
+
225
+ GEOSGeometry *queryEnv = GEOSWKTReader_read(r, "POLYGON((20 20,22 20,22 22,20 22,20 20))");
226
+ GEOSSTRtree_query(tree, queryEnv, queryCallback, &count); /* 回调逐个给候选 */
227
+ ```
228
+
229
+ 最近邻用 `GEOSSTRtree_nearest_generic(tree, item, geom, distanceCallback, userdata)`,距离回调里调用 `GEOSDistance` 判定真实距离。用完 `GEOSSTRtree_destroy(tree)`,并自行释放所有 item 几何。
230
+
231
+ ### 有效性修复与精度
232
+
233
+ ```c
234
+ GEOSGeometry *fixed = GEOSMakeValid(invalid); /* 自相交、环重叠等无效面修复 */
235
+ char ok = GEOSisValid(invalid); /* 1 有效 / 2 无效 / 0 出错 */
236
+ char *reason = GEOSisValidReason(invalid); /* 无效原因文本 */
237
+ GEOSGeometry *snapped = GEOSSnap(a, b, 1e-6); /* 容差吸附,治理近重合顶点 */
238
+ ```
239
+
240
+ **OverlayNG**:自 GEOS 3.9 起默认叠加引擎已是 OverlayNG(鲁棒、失败率显著低于旧引擎),无需额外开关。遇到 `TopologyException` 优先做有效性修复或加容差(`GEOSSnap` / 先量化坐标),而不是反复重算。3.15 的破坏性变化之一:叠加遇到连续子段时输出 `LineString` 而非 `MultiLineString`,下游不要假设返回类型。
241
+
242
+ ### 内存与错误处理要点
243
+
244
+ | 规则 | 说明 |
245
+ |---|---|
246
+ | 成对释放 | `GEOSGeom_destroy` / `GEOSWKTReader_destroy` / `GEOSSTRtree_destroy` / `GEOSFree` 各管各的对象 |
247
+ | 字符串专用 | `GEOSWKTWriter_write`、`GEOSRelate` 返回的 `char*` 必须 `GEOSFree`,不能用 `free()` |
248
+ | 序列所有权 | `GEOSGeom_createLineString/Polygon` 成功后不得再 destroy 该坐标序列 |
249
+ | 空结果 | 无交返回 `POLYGON EMPTY` 一类空几何,不是 `NULL`;`NULL` 只表示出错 |
250
+ | 出错排查 | `GEOS_getLastError()`(可重入版 `GEOS_getLastError_r(ctx)`)配合错误回调看原文 |
251
+
252
+ ---
253
+
254
+ ## 典型工作流
255
+
256
+ ### 工作流一:WKT → 缓冲 → 相交 → 输出 WKT(C API)
257
+
258
+ 输入两块相交的 WKT 多边形;输出缓冲后的相交面积与 WKT。
259
+
260
+ ```c
261
+ initGEOS(geos_msg_handler, geos_msg_handler);
262
+ GEOSWKTReader *r = GEOSWKTReader_create();
263
+ GEOSGeometry *a = GEOSWKTReader_read(r, "POLYGON((0 0,10 0,10 10,0 10,0 0))");
264
+ GEOSGeometry *b = GEOSWKTReader_read(r, "POLYGON((5 5,15 5,15 15,5 15,5 5))");
265
+
266
+ GEOSGeometry *inter = GEOSIntersection(a, b);
267
+ GEOSGeometry *buf = GEOSBuffer(inter, 0.5, 8);
268
+
269
+ double area = 0.0;
270
+ GEOSArea(buf, &area); /* 校验:应大于 0 */
271
+ printf("area = %.3f\n", area);
272
+
273
+ GEOSWKTWriter *w = GEOSWKTWriter_create();
274
+ GEOSWKTWriter_setTrim(w, 1); /* 3.12 起默认已 trim,此行仅显式声明 */
275
+ char *out = GEOSWKTWriter_write(w, buf);
276
+ printf("%s\n", out);
277
+
278
+ GEOSFree(out);
279
+ GEOSGeom_destroy(buf); GEOSGeom_destroy(inter);
280
+ GEOSGeom_destroy(a); GEOSGeom_destroy(b);
281
+ GEOSWKTWriter_destroy(w); GEOSWKTReader_destroy(r);
282
+ finishGEOS();
283
+ ```
284
+
285
+ **校验产物**:`area` 为正、输出 WKT 能被 `GEOSWKTReader_read` 读回且 `GEOSisValid` 为 1。
286
+
287
+ ### 工作流二:C++ API 嵌入(geos::geom)
288
+
289
+ ```cpp
290
+ #include <iostream>
291
+ #include <memory>
292
+ #include <geos/geom/GeometryFactory.h>
293
+ #include <geos/geom/Geometry.h>
294
+ #include <geos/io/WKTReader.h>
295
+ #include <geos/io/WKTWriter.h>
296
+
297
+ using namespace geos::geom;
298
+ using namespace geos::io;
299
+
300
+ int main() {
301
+ GeometryFactory::Ptr factory = GeometryFactory::create();
302
+ WKTReader reader(*factory);
303
+
304
+ std::unique_ptr<Geometry> a(reader.read("POLYGON((0 0,10 0,10 10,0 10,0 0))"));
305
+ std::unique_ptr<Geometry> b(reader.read("POLYGON((5 5,15 5,15 15,5 15,5 5))"));
306
+ std::unique_ptr<Geometry> inter = a->intersection(b.get());
307
+
308
+ WKTWriter writer;
309
+ writer.setTrim(true); /* 3.12 之前才必须显式设置 */
310
+ std::cout << writer.write(inter.get()) << std::endl;
311
+ return 0;
312
+ }
313
+ ```
314
+
315
+ 编译:`g++ -std=c++14 demo.cpp -o demo -lgeos`。C++ 侧注意:`GeometryFactory::create()` 返回 `Ptr`(`std::unique_ptr`);`WKTReader` 必须绑定 factory 以共享 PrecisionModel;**C++ ABI 不跨版本稳定**,升级 GEOS 后必须重新编译。
316
+
317
+ ### 工作流三:几何清洗流水线(服务端批处理)
318
+
319
+ 1. `GEOSWKBReader_read` 读入源数据(比 WKT 更小更快)
320
+ 2. `GEOSisValid` 检查,无效则 `GEOSMakeValid` 修复
321
+ 3. `GEOSNormalize` 统一顶点顺序与环方向,便于结果比对
322
+ 4. `GEOSUnaryUnion` 合并同层要素,`GEOSBuffer(geom, 0, 8)` 消除自相交残渣
323
+ 5. `GEOSWKBWriter_write` 写回,并记录修复前后 `GEOSisValid` 结果
324
+
325
+ **校验产物**:抽样统计修复前后 `GEOSisValid == 1` 的比例,以及 `GEOSArea` 总量变化不超过阈值(避免修复把几何吃掉)。
326
+
327
+ ---
328
+
329
+ ## 常见问题
330
+
331
+ | 问题 | 原因 | 处置 |
332
+ |---|---|---|
333
+ | `TopologyException: side location conflict` / `Self-intersection` | 输入几何无效(自相交、环重叠、重复点) | 先 `GEOSisValid` + `GEOSMakeValid` 修复;仍失败加 `GEOSSnap` 容差 |
334
+ | 段错误(Segmentation fault) | 忘记 `initGEOS`、跨线程共用 context、或对已 destroy 的几何再操作 | 补初始化 / 用 `_r` 每线程独立 context;用 ASAN 构建定位 |
335
+ | 返回字符串释放后崩溃 | 用 `free()` 释放 GEOS 分配的字符串 | 改用 `GEOSFree()`(Windows 上尤为关键) |
336
+ | 退出时报内存泄漏 | 坐标序列被重复释放,或 item 几何未销毁 | 确认 `GEOSGeom_create*` 后不再 destroy 序列;STRtree 只存指针,item 自己释放 |
337
+ | 链接报 `undefined reference to GEOSIntersection` | 只链接了 `-lgeos`(C++ 库) | C API 要链接 `-lgeos_c`,用 `pkg-config --libs geos` 最稳 |
338
+ | 谓词判断结果反了 | C API 谓词返回 `char`:1 真 / 2 假 / 0 异常 | 用 `== 1` 判真,不要直接当布尔取反 |
339
+ | 升级后叠加结果类型变了 | 3.15 起连续子段叠加输出 `LineString` 而非 `MultiLineString` | 按 `GEOSGeomTypeId` 分支处理,不要硬转型 |
340
+ | 空结果被当成错误 | 无交返回 `POLYGON EMPTY`,不是 `NULL` | 用 `GEOSisEmpty` 判断而非判空指针 |
341
+
342
+ ---
343
+
344
+ ## AI 使用建议
345
+
346
+ - **执行环境**:C 示例用 `cc demo.c -o demo $(pkg-config --cflags --libs geos)` 编译;C++ 示例用 `g++ -std=c++14 demo.cpp -lgeos`。Windows 优先 vcpkg / conda-forge,运行时确保 `geos_c.dll` 在搜索路径。
347
+ - **先探测版本**:`geos-config --version` 或 `pkg-config --modversion geos`;版本差异集中在叠加引擎、空几何语义与 M 值保留,报告结论时带上版本号。
348
+ - **验证产物**:不要只看「程序没崩」——用 `GEOSisValid`、`GEOSArea`、`GEOSGetNumGeometries` 三方断言;WKT/WKB 往返后再比一次面积与顶点数。
349
+ - **易错操作**:混用 `GEOSGeom_destroy` 与 `GEOSFree`、忘记 `initGEOS`、多线程共享 context、对 `char*` 调 `free()`——这四类占了绝大多数崩溃与泄漏。
350
+ - **性能验证**:重复谓词先用 `GEOSPrepare`,批量窗口查询先建 `GEOSSTRtree`,再用 `std::chrono` / `clock_gettime` 计时对比,用数据证明优化有效。
351
+ - **安全与权限**:`make install` 会写系统目录(默认 `/usr/local`),执行前先征得用户同意;生产升级前先备份,并在副本上跑一遍几何回归。
352
+
353
+ ## 相关技能
354
+
355
+ - **jts** — GEOS 的 Java 上游实现(算法语义同源):[../jts/SKILL.md](../jts/SKILL.md)
356
+ - **shapely** — GEOS 的 Python 绑定,本技能是其底层内核:[../shapely/SKILL.md](../shapely/SKILL.md)
357
+ - **postgis** — 把 GEOS 编进数据库后端提供 ST_* 函数:[../postgis/SKILL.md](../postgis/SKILL.md)
358
+ - **gdal** — OGR 矢量处理,叠加运算调用 GEOS:[../gdal/SKILL.md](../gdal/SKILL.md)
359
+ - **nettopologysuite** — JTS 的 .NET 移植(同族算法):[../nettopologysuite/SKILL.md](../nettopologysuite/SKILL.md)
360
+
361
+ ## 参考资源
362
+
363
+ - **GitHub 仓库:** <https://github.com/libgeos/geos>
364
+ - **官网:** <https://libgeos.org/>
365
+ - **C API 编程指南:** <https://libgeos.org/usage/c_api/>
366
+ - **C++ API 编程指南:** <https://libgeos.org/usage/cpp_api/>
367
+ - **下载与构建:** <https://libgeos.org/usage/download/>
368
+ - **安装包说明:** <https://libgeos.org/usage/install/>
369
+ - **C API 参考(Doxygen):** <https://libgeos.org/usage/doxygen/>
370
+ - **常见问题:** <https://libgeos.org/usage/faq/>
371
+ - **旧版本下载:** <https://download.osgeo.org/geos/>
372
+ - **绑定列表(Shapely / sf / PostGIS 等):** <https://libgeos.org/usage/bindings/>
@@ -199,7 +199,7 @@ curl -u admin:geoserver -XPOST \
199
199
  | WFS-T 403 | Data 规则允许 `w` 权限 |
200
200
  | 跨域 | 配置 CORS 过滤器 |
201
201
  | 改了 SLD 但预览不变 | 图层被 GeoWebCache 缓存:Tile Caching 里 Truncate 该图层,或给 GetMap 加 `&tiled=false` |
202
- | 忘记管理员密码 | 数据目录 `security/users.properties` 里恢复,改完重启;GeoServer 3.x 默认改由 security 配置文件管理 |
202
+ | 忘记管理员密码 | 默认 XML 用户/组服务的用户在数据目录 `security/usergroup/<name>/users.xml`(默认服务名 `default`);改完重启,或用 Docker 的 `GEOSERVER_ADMIN_PASSWORD` 重置 |
203
203
  | 启动报 `UnsupportedClassVersionError` | JVM 版本低于 17:换成 JDK 17 或 21 再启动 3.0.x 分发包 |
204
204
 
205
205
  ---
@@ -191,8 +191,6 @@ docker run -e SPRING_PROFILES_ACTIVE=datadir \
191
191
 
192
192
  ---
193
193
 
194
- ---
195
-
196
194
  ## 典型工作流
197
195
 
198
196
  ### 工作流 1:从零部署高可用 GeoServer Cloud
@@ -13,13 +13,15 @@ metadata:
13
13
  >
14
14
  > **手册入口:** <https://grass.osgeo.org/grass-stable/manuals/>
15
15
  >
16
- > **最新版本:** 8.5.0(截至 2026-11,GitHub Releases;8.4 系列最新补丁 8.4.2)
16
+ > **最新版本:** 8.5.0(截至 2026-11,[GitHub Releases](https://github.com/OSGeo/grass/releases/tag/8.5.0);8.4 系列最新补丁 8.4.2)
17
17
  >
18
- > **许可证:** GPL-2.0
18
+ > **运行要求:** 8.5 起要求 GDAL 3.7+、PROJ 9.0+、Python 3.10+、C++17(conda-forge 包已自带这些依赖)
19
+ >
20
+ > **许可证:** GPL-2.0-or-later
19
21
 
20
22
  ## 概述
21
23
 
22
- GRASS GIS(Geographic Resources Analysis and Support System)是 OSGeo 创始项目之一,提供栅格、拓扑矢量、三维栅格、影像与时序数据的分析能力。它以模块化命令体系为核心:每个功能是一个独立命令(模块),既可交互使用,也可通过 `grass --exec` 在无头会话中执行。计算区域(computational region)与地图数据范围分离管理,是理解其行为的关键概念。Python 生态(`grass.script`、PyGRASS、`grass.jupyter`)使其适合脚本化与自动化。
24
+ GRASS(Geographic Resources Analysis Support System,8.5 起官方品牌名从 "GRASS GIS" 简化为 "GRASS")是 OSGeo 创始项目之一,提供栅格、拓扑矢量、三维栅格、影像与时序数据的分析能力。它以模块化命令体系为核心:每个功能是一个独立命令(模块),既可交互使用,也可通过 `grass --exec` 在无头会话中执行。计算区域(computational region)与地图数据范围分离管理,是理解其行为的关键概念。Python 生态(`grass.script`、PyGRASS、`grass.jupyter`)使其适合脚本化与自动化。
23
25
 
24
26
  核心特点:
25
27
 
@@ -27,7 +29,8 @@ GRASS GIS(Geographic Resources Analysis and Support System)是 OSGeo 创始
27
29
  - **计算区域独立管理**:栅格模块在 `g.region` 定义的窗口上运算,与地图本身范围解耦。
28
30
  - **无头执行**:`grass --exec` / `--tmp-project` / `--tmp-mapset` 支持服务器与 CI 场景。
29
31
  - **时空框架**:`t.*` 模块管理 strds / str3ds / stvds 时空数据集。
30
- - **Python 接口**:`grass.script`(命令封装)、`grass.script.array`(NumPy 读写栅格)、`grass.tools`(8.5+ 面向对象工具调用)、`grass.jupyter`(笔记本集成)。
32
+ - **Python 接口**:`grass.script`(命令封装)、`grass.script.array`(NumPy 读写栅格)、`grass.tools`(8.5 新增的面向对象工具调用)、`grass.jupyter`(笔记本集成)。
33
+ - **8.5 亮点**:`grass.tools` 新 Python API;`g.list`、`g.region`、`r.info`、`r.univar`、`r.stats`、`r.report`、`v.info`、`v.what`、`v.db.connect` 等几十个模块支持 JSON 输出;`r.mapcalc`、`r.texture`、`r.horizon` 支持 `nprocs` 并行;同一地图集可存多份掩膜(`r.mask.status` 查看);新增 `r.smooth.edgepreserve`。
31
34
 
32
35
  ## 环境准备
33
36
 
@@ -225,7 +228,7 @@ elev_ft.write(mapname="elev_ft", overwrite=True)
225
228
  elev3d = garray.array3d(mapname="elev3d")
226
229
  ```
227
230
 
228
- 8.5+ 提供面向对象的工具调用接口 `grass.tools`(模块名中的点替换为下划线,支持 numpy 输入输出);8.4.x 及更早版本没有该模块,只能用 `grass.script`:
231
+ 8.5 新增面向对象的工具调用接口 `grass.tools`(模块名中的点替换为下划线,支持 NumPy 输入输出,官方说明 8.5 中仍是实验性、预计 8.6 稳定);8.4.x 及更早版本没有该模块,只能用 `grass.script`:
229
232
 
230
233
  ```python
231
234
  from grass.tools import Tools
@@ -236,7 +239,28 @@ tools.r_random_surface(output="surface", seed=42)
236
239
  print(tools.g_region(flags="p", format="json")["cells"])
237
240
  ```
238
241
 
239
- `grass.jupyter` 提供 Jupyter 集成(`init`、`Map`、`Map3D`、`InteractiveMap`、`SeriesMap`、`TimeSeriesMap` 等)。
242
+ `grass.jupyter` 提供 Jupyter 集成(`init`、`Map`、`Map3D`、`InteractiveMap`、`SeriesMap`、`TimeSeriesMap` 等)。8.5 起 `InteractiveMap` 增加查询按钮与简单几何绘制,`Map3D` 增加 `save()`,`SeriesMap` / `TimeSeriesMap` 支持并行。
243
+
244
+ 8.5 的 8 个模块支持 JSON 输出,脚本里优先用 `format="json"` 拿结构化结果,不要解析人类可读文本:
245
+
246
+ ```bash
247
+ # 8.5 新增 JSON 输出的代表模块
248
+ g.list type=raster format=json
249
+ g.region -p format=json
250
+ r.univar map=elevation format=json
251
+ r.stats input=elevation format=json
252
+ v.info map=roads format=json
253
+ ```
254
+
255
+ 8.5 起一个地图集可存多份掩膜,`r.mask.status` 报告当前掩膜状态;Python 里用 `grass.script` 的 `RegionManager` / `MaskManager` 上下文管理器做作用域内的区域/掩膜切换:
256
+
257
+ ```python
258
+ import grass.script as gs
259
+
260
+ with gs.RegionManager(raster="elevation"), gs.MaskManager(mask_name="mask"):
261
+ gs.parse_command("r.univar", map="elevation", format="json")
262
+ # 退出上下文后区域与掩膜自动还原
263
+ ```
240
264
 
241
265
  ### 与 QGIS 集成
242
266
 
@@ -284,7 +308,7 @@ grass $HOME/grassdata/ndvi_project/PERMANENT --exec sh -c '
284
308
  2. **无头场景用 `--exec` 单行执行**:避免交互式会话依赖;CI 优先使用 `--tmp-project` 保持幂等。
285
309
  3. **临时项目内先导出结果**:`--tmp-project` / `--tmp-mapset` 结束时目录被删除。
286
310
  4. **覆盖已有地图加 `--overwrite`**:否则模块报地图已存在并退出非零。
287
- 5. **Python 中结构化解析**:用 `gs.parse_command(..., format="json")` 或 `flags="g"` 获取 dict,不要手工解析人类可读输出。
311
+ 5. **Python 中结构化解析**:用 `gs.parse_command(..., format="json")` 或 `flags="g"` 获取 dict,不要手工解析人类可读输出;8.5 起 `g.list`、`g.region`、`r.info`、`r.univar`、`r.stats`、`r.report`、`v.info`、`v.what`、`v.db.connect` 等几十个模块都支持 `format="json"`。
288
312
  6. **Python 会话内改动区域用 `gs.use_temp_region()`**:临时区域随会话结束自动还原。
289
313
  7. **导入优先用 `r.import` / `v.import`**:自动重投影到项目 CRS,避免 CRS 不一致导致的分析错误。
290
314
  8. **`--exec` 脚本加 shebang**:缺失 shebang 会报 `Exec format error`。
@@ -292,6 +292,7 @@ React 侧的等价流程是:`processGeojson` / `processCsvData` 解析 → `di
292
292
  ## 相关技能
293
293
 
294
294
  - **deck-gl** — Kepler.gl 的渲染底座,自定义图层与拾取需直接操作 deck.gl:[../deck-gl/SKILL.md](../deck-gl/SKILL.md)
295
+ - **maplibre-gl-js** — Kepler.gl 默认底图所用的开源渲染库(免 token):[../maplibre-gl-js/SKILL.md](../maplibre-gl-js/SKILL.md)
295
296
  - **mapbox-gl-js** — 使用 Mapbox 官方样式与 token 时的对应技能:[../mapbox-gl-js/SKILL.md](../mapbox-gl-js/SKILL.md)
296
297
  - **openlayers** — 传统 2D WebGIS 方案,适合与 Kepler.gl 做能力对比:[../openlayers/SKILL.md](../openlayers/SKILL.md)
297
298
  - **geopandas** — Python 侧数据预处理与投影转换:[../geopandas/SKILL.md](../geopandas/SKILL.md)
@@ -15,7 +15,7 @@ metadata:
15
15
  >
16
16
  > **示例:** <https://leafletjs.com/examples.html>
17
17
  >
18
- > **最新版本:** 1.9.4(截至 2026-11,[npm `leaflet`](https://www.npmjs.com/package/leaflet) 与 [GitHub Release](https://github.com/Leaflet/Leaflet/releases) 一致;1.9.4 发布于 2023-05,仍是当前稳定版)
18
+ > **最新版本:** 1.9.4(截至 2026-11,[npm `leaflet`](https://www.npmjs.com/package/leaflet) dist-tag `latest` 与 [GitHub Release](https://github.com/Leaflet/Leaflet/releases) 一致;1.9.4 发布于 2023-05,仍是**当前稳定版**。2.0 尚在 beta 阶段(`v2.0.0-beta.3`,2026-11-10),未发布稳定版,生产环境沿用 1.x)
19
19
  >
20
20
  > **许可证:** BSD-2-Clause
21
21
 
@@ -349,7 +349,7 @@ export default function MapView() {
349
349
  ## AI 使用建议
350
350
 
351
351
  - **执行环境**:`npm install`、`npm run build` 在终端中执行;纯静态页面可用 `python -m http.server 5173` 起服务(`python` 不存在时用 `py -3`)。
352
- - **先探测版本**:`npm ls leaflet`(未装则 `npm view leaflet version`);本技能按 1.9.4 编写,CDN 的 `integrity` SRI 哈希只对应 1.9.4,换版本必须同步换哈希。
352
+ - **先探测版本**:`npm ls leaflet`(未装则 `npm view leaflet version`);本技能按 1.9.4 编写,CDN 的 `integrity` SRI 哈希只对应 1.9.4,换版本必须同步换哈希。Leaflet 2.0 目前只有 beta(`2.0.0-beta.3`),API 与插件兼容性仍在变动,回答里默认给 1.9.4 方案。
353
353
  - **验证产物**:构建后 `curl.exe -I http://localhost:5173/assets/<入口>.js` 确认 200;联网时还可 `curl.exe -I https://unpkg.com/leaflet@1.9.4/dist/leaflet.js` 核对 CDN 版本;AI 助手通常看不到浏览器画面,把 URL 和“应看到瓦片与标记”交给用户,环境支持读图时用截图核对。
354
354
  - **图标与坐标**:npm + 打包器下默认 marker 图标会 404,需显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`;坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`。
355
355
  - **生命周期**:SPA 卸载必须 `map.remove()` 并解绑自定义事件;容器隐藏或尺寸变化后 `map.invalidateSize()`。
@@ -412,6 +412,7 @@ map.on('load', () => {
412
412
 
413
413
  ## 相关技能
414
414
 
415
+ - **maplibre-gl-js** — 本库 v1 的开源分支,免 token、BSD-3-Clause,API 高度兼容:[../maplibre-gl-js/SKILL.md](../maplibre-gl-js/SKILL.md)
415
416
  - **leaflet** — 轻量 2D 瓦片地图,无需 token,适合简单场景:[../leaflet/SKILL.md](../leaflet/SKILL.md)
416
417
  - **openlayers** — 功能全面的开源 2D WebGIS 库(投影、MVT、高级交互):[../openlayers/SKILL.md](../openlayers/SKILL.md)
417
418
  - **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)