@dsh-gis/dsh-opengis-skill 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +79 -43
  3. package/THIRD_PARTY_NOTICES.md +9 -0
  4. package/adaptations/brutile.md +8 -0
  5. package/adaptations/cesiumjs.md +8 -0
  6. package/adaptations/common.md +16 -0
  7. package/adaptations/deck-gl.md +8 -0
  8. package/adaptations/duckdb-spatial.md +8 -0
  9. package/adaptations/gdal-api.md +8 -0
  10. package/adaptations/gdal.md +8 -0
  11. package/adaptations/geolibre.md +8 -0
  12. package/adaptations/geometry-api-java.md +8 -0
  13. package/adaptations/geometry-api-net.md +8 -0
  14. package/adaptations/geonode.md +8 -0
  15. package/adaptations/geopandas.md +8 -0
  16. package/adaptations/geopipe-agent.md +8 -0
  17. package/adaptations/geoserver-cloud.md +8 -0
  18. package/adaptations/geoserver-rest-api.md +8 -0
  19. package/adaptations/geoserver.md +8 -0
  20. package/adaptations/geotools.md +8 -0
  21. package/adaptations/grass-gis.md +8 -0
  22. package/adaptations/jts.md +8 -0
  23. package/adaptations/kepler-gl.md +8 -0
  24. package/adaptations/leaflet.md +8 -0
  25. package/adaptations/mapbox-gl-js.md +8 -0
  26. package/adaptations/mapserver.md +8 -0
  27. package/adaptations/mapsui.md +8 -0
  28. package/adaptations/nettopologysuite.md +8 -0
  29. package/adaptations/opengis-all.md +8 -0
  30. package/adaptations/opengis-daf.md +8 -0
  31. package/adaptations/opengis-utils-for-java.md +8 -0
  32. package/adaptations/opengis-utils-for-net.md +8 -0
  33. package/adaptations/openlayers.md +8 -0
  34. package/adaptations/pdal.md +8 -0
  35. package/adaptations/postgis.md +8 -0
  36. package/adaptations/proj.md +8 -0
  37. package/adaptations/projnet4geoapi.md +8 -0
  38. package/adaptations/pyqgis.md +8 -0
  39. package/adaptations/qgis-process.md +8 -0
  40. package/adaptations/qgis-server.md +8 -0
  41. package/adaptations/shapely.md +8 -0
  42. package/adaptations/sharpmap.md +8 -0
  43. package/adaptations/spatialite.md +8 -0
  44. package/adaptations/whitebox-tools.md +8 -0
  45. package/assets/brutile/SKILL.md +289 -0
  46. package/assets/cesiumjs/SKILL.md +78 -29
  47. package/assets/deck-gl/SKILL.md +20 -20
  48. package/assets/duckdb-spatial/SKILL.md +370 -0
  49. package/assets/gdal/SKILL.md +50 -55
  50. package/assets/gdal-api/SKILL.md +12 -29
  51. package/assets/geolibre/SKILL.md +364 -0
  52. package/assets/geometry-api-java/SKILL.md +11 -19
  53. package/assets/geometry-api-net/SKILL.md +66 -29
  54. package/assets/geonode/SKILL.md +347 -0
  55. package/assets/geopandas/SKILL.md +22 -28
  56. package/assets/geopipe-agent/SKILL.md +25 -30
  57. package/assets/geoserver/SKILL.md +21 -24
  58. package/assets/geoserver-cloud/SKILL.md +23 -34
  59. package/assets/geoserver-rest-api/SKILL.md +18 -23
  60. package/assets/geotools/SKILL.md +13 -21
  61. package/assets/grass-gis/SKILL.md +19 -20
  62. package/assets/jts/SKILL.md +12 -17
  63. package/assets/kepler-gl/SKILL.md +313 -0
  64. package/assets/leaflet/SKILL.md +42 -17
  65. package/assets/mapbox-gl-js/SKILL.md +19 -18
  66. package/assets/mapserver/SKILL.md +18 -18
  67. package/assets/mapsui/SKILL.md +87 -58
  68. package/assets/nettopologysuite/SKILL.md +96 -27
  69. package/assets/opengis-all/SKILL.md +80 -292
  70. package/assets/opengis-all/reference/data-stages.md +262 -4
  71. package/assets/opengis-daf/SKILL.md +12 -14
  72. package/assets/opengis-utils-for-java/SKILL.md +52 -47
  73. package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
  74. package/assets/opengis-utils-for-net/SKILL.md +106 -40
  75. package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
  76. package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
  77. package/assets/openlayers/SKILL.md +71 -14
  78. package/assets/pdal/SKILL.md +21 -15
  79. package/assets/postgis/SKILL.md +66 -18
  80. package/assets/proj/SKILL.md +29 -42
  81. package/assets/projnet4geoapi/SKILL.md +299 -0
  82. package/assets/pyqgis/SKILL.md +28 -54
  83. package/assets/qgis-process/SKILL.md +67 -39
  84. package/assets/qgis-server/SKILL.md +21 -32
  85. package/assets/shapely/SKILL.md +133 -84
  86. package/assets/sharpmap/SKILL.md +96 -61
  87. package/assets/spatialite/SKILL.md +365 -0
  88. package/assets/whitebox-tools/SKILL.md +269 -0
  89. package/lib/adaptations.d.ts +47 -0
  90. package/lib/adaptations.js +268 -0
  91. package/lib/index.d.ts +1 -1
  92. package/lib/index.js +14 -2
  93. package/lib/skill-file.js +31 -7
  94. package/locale/en.json +1 -1
  95. package/locale/zh.json +1 -1
  96. package/package.json +12 -2
  97. package/upstream.json +56 -40
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: shapely
3
- description: "Use when performing computational geometry in Python — intersection, union, buffer, convex hull, simplification. Shapely: Python bindings for GEOS, the C++ geometry engine that powers PostGIS."
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
4
  tags:
5
5
  - python
6
6
  - geometry
@@ -18,7 +18,7 @@ tags:
18
18
  >
19
19
  > **PyPI:** <https://pypi.org/project/shapely/>
20
20
  >
21
- > **最新版本:** 2.2.0(截至2026-10,PyPI)
21
+ > **包管理器:** `shapely`(最新 2.2.0,截至 2026-10,PyPI)
22
22
  >
23
23
  > **许可证:** BSD-3-Clause
24
24
 
@@ -35,7 +35,7 @@ Shapely 是 Python 计算几何的核心库,基于 GEOS(Geometry Engine - Op
35
35
  - **格式读写**:WKT、WKB、GeoJSON
36
36
  - **双重 API**:函数式(向量化,支持 NumPy 广播)+ OOP(标量便捷)
37
37
 
38
- **环境要求:** Python 3.11+(Shapely 2.2 起;2.1 为 3.10+),NumPy >= 1.26,GEOS >= 3.10。PyPI 二进制 wheel 内含 GEOS 3.14.1。
38
+ **环境要求:** Python 3.11+(Shapely 2.2 起;2.1 为 3.10+),NumPy >= 1.26,GEOS >= 3.10。PyPI 二进制 wheel 内含 GEOS 3.14。
39
39
 
40
40
  ---
41
41
 
@@ -55,28 +55,28 @@ python -c "import shapely; print(shapely.__version__, shapely.geos_version)"
55
55
 
56
56
  ---
57
57
 
58
- ## Geometry Types
58
+ ## 几何类型
59
59
 
60
- | Type | Class | Description |
60
+ | 类型 | 类 | 说明 |
61
61
  |------|-------|-------------|
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 |
62
+ | Point | `shapely.Point` | 单个坐标 (x, y [, z [, m]]) |
63
+ | LineString | `shapely.LineString` | 由 2 个以上点组成的有序序列 |
64
+ | LinearRing | `shapely.LinearRing` | 闭合的简单 LineString |
65
+ | Polygon | `shapely.Polygon` | 外环 + 可选内环(洞) |
66
+ | MultiPoint | `shapely.MultiPoint` | 点集合 |
67
+ | MultiLineString | `shapely.MultiLineString` | 线集合 |
68
+ | MultiPolygon | `shapely.MultiPolygon` | 面集合 |
69
+ | GeometryCollection | `shapely.GeometryCollection` | 异构几何集合 |
70
70
 
71
- Z coordinates are **ignored for all spatial analysis** — operations are performed in the x-y plane only.
71
+ **所有空间分析都忽略 Z 值** —— 运算只在 x-y 平面进行。
72
72
 
73
- ## Dual API Pattern
73
+ ## 双 API 模式
74
74
 
75
- Shapely provides two APIs. Prefer the **function-based API** for arrays and performance; use the **OOP API** for scalar convenience.
75
+ Shapely 提供两套 API:处理数组、追求性能时优先用**函数式 API**,只做单个几何的便捷操作时用**面向对象 API**。
76
76
 
77
- ### Function-based (vectorized, NumPy ufunc)
77
+ ### 函数式 API(向量化,NumPy ufunc)
78
78
 
79
- All functions release the GIL during GEOS execution, support NumPy broadcasting, and handle arrays natively.
79
+ 这些函数在 GEOS 运算期间释放 GIL,支持 NumPy 广播,并原生处理数组。
80
80
 
81
81
  ```python
82
82
  import shapely
@@ -89,7 +89,7 @@ shapely.buffer(geoms, 1.0) # array of polygons
89
89
  shapely.distance(geoms, other) # array of distances
90
90
  ```
91
91
 
92
- ### OOP (method-based, scalar)
92
+ ### 面向对象 API(方法式,标量)
93
93
 
94
94
  ```python
95
95
  from shapely import Point, Polygon
@@ -103,7 +103,7 @@ poly.contains(p)
103
103
  poly.intersection(other)
104
104
  ```
105
105
 
106
- ### Operator overloading
106
+ ### 运算符重载
107
107
 
108
108
  ```python
109
109
  geom1 & geom2 # intersection
@@ -112,9 +112,9 @@ geom1 - geom2 # difference
112
112
  geom1 ^ geom2 # symmetric_difference
113
113
  ```
114
114
 
115
- ## Geometry Creation
115
+ ## 几何对象创建
116
116
 
117
- ### From coordinates (OOP)
117
+ ### 从坐标创建(面向对象)
118
118
 
119
119
  ```python
120
120
  from shapely import Point, LineString, LinearRing, Polygon
@@ -132,7 +132,7 @@ MultiPolygon([poly1, poly2])
132
132
  GeometryCollection([point, line, poly])
133
133
  ```
134
134
 
135
- ### From coordinates (vectorized)
135
+ ### 从坐标创建(向量化)
136
136
 
137
137
  ```python
138
138
  import shapely
@@ -149,7 +149,7 @@ shapely.multipolygons(...)
149
149
  shapely.geometrycollections(...)
150
150
  ```
151
151
 
152
- ### From serialization formats
152
+ ### 从序列化格式创建
153
153
 
154
154
  ```python
155
155
  # WKT
@@ -169,7 +169,7 @@ shapely.from_ragged_array(geometry_type, coords, offsets)
169
169
  shapely.to_ragged_array(geometries)
170
170
  ```
171
171
 
172
- ### From/to GeoJSON-like dict (`__geo_interface__`)
172
+ ### 与 GeoJSON 字典互转(`__geo_interface__`)
173
173
 
174
174
  ```python
175
175
  from shapely.geometry import shape, mapping
@@ -180,7 +180,7 @@ d = mapping(geom) # {"type": "Point", "coordinates": (0.0, 0.0)}
180
180
 
181
181
  > 构造操作、空间谓词、集合运算、测量、空间索引、仿射与坐标变换及线性参考的完整 API 见 [reference/operations-reference.md](reference/operations-reference.md)
182
182
 
183
- ## Validation
183
+ ## 有效性校验
184
184
 
185
185
  ```python
186
186
  shapely.is_valid(geom)
@@ -188,9 +188,9 @@ shapely.is_valid_reason(geom)
188
188
  shapely.make_valid(geom, method="linework") # or "structure"
189
189
  ```
190
190
 
191
- ## Prepared Geometry
191
+ ## 预处理几何(Prepared Geometry)
192
192
 
193
- Caches spatial index for repeated predicate tests against the same geometry.
193
+ 为同一几何的重复谓词判断缓存空间索引。
194
194
 
195
195
  ```python
196
196
  shapely.prepare(geom) # in-place, returns True if newly prepared
@@ -198,61 +198,112 @@ shapely.destroy_prepared(geom) # free cache
198
198
  shapely.is_prepared(geom)
199
199
  ```
200
200
 
201
- ## Missing Values
201
+ ## 缺失值
202
202
 
203
- `None` represents missing geometries. Consistent behavior:
204
- - Predicates return `False`
205
- - Measurements return `nan`
206
- - Constructive operations return `None`
203
+ `None` 表示缺失几何,各函数行为保持一致:
204
+ - 谓词返回 `False`
205
+ - 度量返回 `nan`
206
+ - 构造类操作返回 `None`
207
207
 
208
- Use `shapely.is_missing(obj)` to check, distinct from `shapely.is_empty(geom)`.
208
+ 用 `shapely.is_missing(obj)` 判断,注意它与 `shapely.is_empty(geom)`(空几何)不同。
209
209
 
210
- ## Important Caveats
210
+ ## 重要注意事项
211
211
 
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.
212
+ 1. **分析中忽略 Z 值**:所有空间运算只在 x-y 平面进行,Z 值不同的几何仍可能相交或相等。
213
213
 
214
- 2. **`contains` excludes boundary**: `contains(line, endpoint)` is `False`. Use `covers()` or `intersects()` if you need boundary inclusion.
214
+ 2. **`contains` 不含边界**:`contains(line, endpoint)` 为 `False`;需要把边界算在内时用 `covers()` 或 `intersects()`。
215
215
 
216
- 3. **`set_coordinates` modifies in-place**: Copy geometry first with `.copy()` if originals must be preserved.
216
+ 3. **`set_coordinates` 原地修改**:需保留原几何时,先 `.copy()`。
217
217
 
218
- 4. **`clip_by_rect` may produce invalid output**: The fast clip is not guaranteed to yield valid topology.
218
+ 4. **`clip_by_rect` 可能产出无效几何**:这个快速裁剪不保证拓扑有效。
219
219
 
220
- 5. **WKB drops LinearRing**: LinearRings become LineStrings during WKB serialization.
220
+ 5. **WKB 丢失 LinearRing**:LinearRing 在 WKB 序列化时变成 LineString。
221
221
 
222
- 6. **`to_geojson` drops Z**: Third dimension is silently discarded; LinearRing outputs as `null`.
222
+ 6. **`to_geojson` 丢弃 Z**:第三维被静默丢弃,LinearRing 输出为 `null`。
223
223
 
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`.
224
+ 7. **面向对象与函数式 `buffer` 默认值不同**:`Point(0,0).buffer(1)` 用 `quad_segs=16`,`shapely.buffer(Point(0,0), 1)` 用 `quad_segs=8`。
225
225
 
226
- 8. **`set_precision` changes vertex order**: Returned geometry is in "mild canonical form" — vertex order should not be relied upon.
226
+ 8. **`set_precision` 改变顶点顺序**:返回几何处于"轻度规范化"形式,不要依赖其顶点顺序。
227
227
 
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.
228
+ 9. **NaN 坐标**:默认允许用 NaN/Inf 构造几何;需要控制时在创建函数里传 `handle_nan='error'` 或 `handle_nan='skip'`。
229
229
 
230
- 10. **Prepared state not preserved**: After any operation producing a new geometry, `prepare()` must be called again.
230
+ 10. **预处理状态不保留**:任何产生新几何的运算之后,都要重新调用 `prepare()`。
231
231
 
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`).
232
+ 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
233
 
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.
234
+ 12. **`shapely.ops.transform` 已弃用**:2.2 起改用 `shapely.transform`(按坐标逐点)或 `shapely.transform_coordseq`(按坐标序列);`multithreading_enabled` 装饰器同样已弃用。
235
235
 
236
- ## 典型工作流与常用模式(Common Patterns)
236
+ ## 典型工作流
237
237
 
238
- ### Point-in-polygon test for many points
238
+ 端到端:WKT 读入 → 有效性修复 → 裁剪/缓冲 → 写回 GeoJSON,全程用函数式 API。
239
+
240
+ ```python
241
+ import json
242
+ import numpy as np
243
+ import shapely
244
+
245
+ # 1. 读入输入几何(WKT 或 WKB)
246
+ parcels = shapely.from_wkt([
247
+ "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))",
248
+ "POLYGON ((20 20, 30 30, 30 20, 20 30, 20 20))", # 自相交的"蝴蝶结",无效
249
+ ])
250
+ clip_poly = shapely.from_wkt("POLYGON ((5 5, 25 5, 25 25, 5 25, 5 5))")
251
+
252
+ # 2. 先查有效性,无效的再修复(不要盲目 buffer(0))
253
+ print(shapely.is_valid(parcels)) # [True False]
254
+ print(shapely.is_valid_reason(parcels[1])) # Self-intersection[25 25]
255
+ parcels = np.where(shapely.is_valid(parcels), parcels,
256
+ shapely.make_valid(parcels)) # 无效的那个变成 MultiPolygon
257
+
258
+ # 3. 空间运算:裁剪 + 缓冲区
259
+ clipped = shapely.intersection(parcels, clip_poly)
260
+ buffered = shapely.buffer(clipped, 1.0, quad_segs=8) # 显式指定 quad_segs
261
+
262
+ # 4. 度量(示例坐标无投影,面积即平面面积)
263
+ print(shapely.area(clipped)) # 每个几何的面积数组
264
+
265
+ # 5. 写出 GeoJSON(FeatureCollection)
266
+ features = [
267
+ {"type": "Feature", "properties": {"id": int(i)},
268
+ "geometry": json.loads(shapely.to_geojson(g))}
269
+ for i, g in enumerate(buffered) if not shapely.is_empty(g)
270
+ ]
271
+ with open("clipped.geojson", "w", encoding="utf-8") as fh:
272
+ json.dump({"type": "FeatureCollection", "features": features}, fh)
273
+ ```
274
+
275
+ **输出与验收**:`clipped.geojson` 中每个 Feature 都能被 `shapely.from_geojson()` 重新读入;`shapely.is_valid()` 全为 `True`;面积量级应与输入量级同阶(若用经纬度坐标,先投影再算,见下)。
276
+
277
+ ## 常用模式
278
+
279
+ ### 大批量点落在面内判断
239
280
  ```python
281
+ import numpy as np
282
+ import shapely
240
283
  from shapely import STRtree, points
241
284
 
242
- pts = points(np.random.rand(10000, 2))
243
- tree = STRtree(pts)
285
+ rng = np.random.default_rng(0)
286
+ pts = points(rng.random((10000, 2)))
287
+ polygon = shapely.box(0.2, 0.2, 0.6, 0.6) # 待查询的面
288
+
289
+ tree = STRtree(pts) # 索引点集
244
290
  idx = tree.query(polygon, predicate="intersects")
245
- inside_points = pts[idx]
291
+ inside_points = pts[idx] # 落面内的点
246
292
  ```
247
293
 
248
- ### Batch union of many polygons
294
+ ### 批量合并大量多边形
249
295
  ```python
296
+ import shapely
297
+
250
298
  result = shapely.union_all(polygon_array)
251
299
  ```
252
300
 
253
- ### Coordinate projection (e.g., with pyproj)
301
+ ### 坐标投影(配合 pyproj)
254
302
  ```python
303
+ import numpy as np
304
+ import shapely
255
305
  from pyproj import Transformer
306
+
256
307
  transformer = Transformer.from_crs("EPSG:4326", "EPSG:3857", always_xy=True)
257
308
 
258
309
  def project(coords):
@@ -262,40 +313,23 @@ def project(coords):
262
313
  projected = shapely.transform(geom, project)
263
314
  ```
264
315
 
265
- ### Extract all coordinates from mixed geometries
316
+ ### 从混合几何中提取全部坐标
266
317
  ```python
318
+ import shapely
319
+
267
320
  coords = shapely.get_coordinates(geom_array, include_z=False)
268
321
  # coords shape: (N, 2)
269
322
  ```
270
323
 
271
- ### Spatial join pattern
324
+ ### 空间连接模式
272
325
  ```python
326
+ from shapely import STRtree
327
+
273
328
  tree = STRtree(right_geoms)
274
329
  left_idx, right_idx = tree.query(left_geoms, predicate="intersects")
275
330
  # left_idx[i] and right_idx[i] are paired matches
276
331
  ```
277
332
 
278
- ## AI 使用建议
279
-
280
- ### 推荐工作流
281
-
282
- 1. **创建几何**:使用 `shapely.points()` / `shapely.linestrings()` / `shapely.polygons()` 向量化创建,或 `Point()` / `LineString()` / `Polygon()` OOP 方式
283
- 2. **空间运算**:使用向量化函数(`shapely.intersection()` / `shapely.buffer()`)批量处理,比逐个 OOP 调用快 10-100 倍
284
- 3. **空间谓词**:使用 `shapely.contains()` / `shapely.intersects()` 等函数式 API,返回 bool 数组
285
- 4. **空间索引**:`STRtree` 查询 + `predicate="intersects"` 加速批量空间关系判断
286
- 5. **序列化**:`shapely.from_wkt()` / `shapely.to_geojson()` 等进行格式互转
287
-
288
- ### 关键注意事项
289
-
290
- - **Z 坐标在分析中被忽略**:所有空间运算仅在 x-y 平面进行
291
- - **`contains` 不包含边界**:如需边界判断使用 `covers()` 或 `intersects()`
292
- - **向量化函数 vs OOP 方法**:函数式 API(`shapely.area(geoms)`)释放 GIL,支持 NumPy 广播,性能远优于 OOP(`geom.area`)
293
- - **`set_precision` 改变顶点顺序**:返回的几何为"温和规范形式",不应依赖顶点顺序
294
- - **Prepared 状态不持久**:任何操作产生新几何后需重新 `prepare()`
295
- - **WKB 会丢弃 LinearRing**:WKB 序列化时 LinearRing 变为 LineString
296
-
297
- ---
298
-
299
333
  ## 常见问题
300
334
 
301
335
  | 问题 | 解决 |
@@ -308,18 +342,24 @@ left_idx, right_idx = tree.query(left_geoms, predicate="intersects")
308
342
  | STRtree 查询返回空数组 | 检查几何是否 `None`/`Empty`;确认查询几何与索引几何的 CRS 一致 |
309
343
  | WKB 序列化丢失 LinearRing | WKB 规范不支持 LinearRing,会自动转为 LineString |
310
344
  | `to_geojson` 丢失 Z 坐标 | GeoJSON 标准不支持 Z,改用 WKB 或自定义序列化 |
311
- | `shapely.ops.transform` 弃用警告 | 2.2 起弃用 | 改用 `shapely.transform` 或 `shapely.transform_coordseq` |
345
+ | `shapely.ops.transform` 弃用警告 | 2.2 起弃用,改用 `shapely.transform` 或 `shapely.transform_coordseq` |
312
346
 
313
347
  ---
314
348
 
315
- ## 相关技能
349
+ ## AI 使用建议
316
350
 
317
- - **geopandas** — 基于 Shapely 的矢量数据分析库:[../geopandas/SKILL.md](../geopandas/SKILL.md)
318
- - **pyqgis** — QGIS Python 绑定(也使用 GEOS/QgsGeometry):[../pyqgis/SKILL.md](../pyqgis/SKILL.md)
319
- - **jts** — Java 几何计算(Shapely 的 GEOS 底层是 JTS 的 C++ 移植):[../jts/SKILL.md](../jts/SKILL.md)
320
- - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
351
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/operations-reference.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
352
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell);`python` 不一定是 QGIS/GDAL 自带环境,先 `python -c "import sys; print(sys.executable, sys.version)"`。
353
+ - **先探测版本**:`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)。
354
+ - **验证产物(必做)**:`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()`。
355
+ - **报错先查有效性**:`TopologyException: side location conflict` 基本都是输入几何自相交,先 `shapely.make_valid(g)`(可指定 `method="structure"`)再算,不要直接加 `buffer(0)`。
356
+ - **性能与内存**:批量操作走向量化函数(`shapely.union_all`、`shapely.buffer(geoms, r)`),别逐条 OOP 循环;十万级以上几何先 `STRtree(geoms)` 过滤,再对小集合做精确谓词。
357
+ - **典型误操**:`set_coordinates()`/`shapely.prepare()` 都是原地修改,先 `.copy()`;`shapely.buffer` 默认 `quad_segs=8` 与 `Point.buffer()` 的 16 不同,比较结果前显式传参。
358
+ - **安全**:`pip install shapely` 前先征得用户同意;输出 WKT/坐标前确认数据是否敏感(精确坐标可反推位置),大几何 dump 到文件再分段读,别刷屏。
321
359
 
322
- ## Package Structure
360
+ ---
361
+
362
+ ## 包结构
323
363
 
324
364
  ```text
325
365
  shapely/
@@ -349,6 +389,15 @@ shapely/
349
389
 
350
390
  ---
351
391
 
392
+ ## 相关技能
393
+
394
+ - **geopandas** — 基于 Shapely 的矢量数据分析库:[../geopandas/SKILL.md](../geopandas/SKILL.md)
395
+ - **pyqgis** — QGIS Python 绑定(也使用 GEOS/QgsGeometry):[../pyqgis/SKILL.md](../pyqgis/SKILL.md)
396
+ - **jts** — Java 几何计算(Shapely 的 GEOS 底层是 JTS 的 C++ 移植):[../jts/SKILL.md](../jts/SKILL.md)
397
+ - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
398
+
399
+ ---
400
+
352
401
  ## 参考资源
353
402
 
354
403
  - **GitHub 仓库:** <https://github.com/shapely/shapely>
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sharpmap
3
- description: "Use when rendering 2D maps in legacy .NET WinForms or ASP.NET WebForms applications. SharpMap: an older .NET 2D mapping library. For new projects, prefer Mapsui."
3
+ description: "Use when rendering 2D maps in legacy .NET Framework 4.7.2 WinForms or ASP.NET WebForms apps with SharpMap 1.2.0 — Map.GetMap() to PNG, ShapeFile/PostGIS providers, VectorLayer with CustomTheme, TileAsyncLayer via BruTile, ProjNet4GeoAPI transforms, or debugging blank output and GDI+ handle leaks. New projects should use Mapsui."
4
4
  tags:
5
5
  - dotnet
6
6
  - csharp
@@ -19,7 +19,7 @@ tags:
19
19
  >
20
20
  > **NuGet:** `SharpMap`、`SharpMap.UI`、`SharpMap.Extensions`、`SharpMap.Web`、`SharpMap.Layers.BruTile`
21
21
  >
22
- > **最新版本:** 1.2.0(截至2026-10,NuGet;发布于 2021-03,仓库未归档但维护低频)
22
+ > **最新版本:** 1.2.0(截至 2026-10,NuGet;发布于 2021-03,仓库未归档但维护低频)
23
23
  >
24
24
  > **许可证:** LGPL-2.1-or-later
25
25
 
@@ -41,6 +41,8 @@ SharpMap 提供:
41
41
 
42
42
  ## 安装
43
43
 
44
+ ### 方式一:dotnet CLI
45
+
44
46
  ```bash
45
47
  dotnet add package SharpMap # 核心(netstandard2.0)
46
48
  dotnet add package SharpMap.UI # WinForms MapBox 控件(.NET Framework 4.7.2)
@@ -50,6 +52,33 @@ dotnet add package SharpMap.Web # ASP.NET WMS 服务
50
52
  dotnet add package ProjNet4GeoAPI # 坐标变换(实现 GeoAPI 接口;ProjNet 2.x 与 SharpMap 1.2 类型不兼容)
51
53
  ```
52
54
 
55
+ ### 方式二:手写 csproj 的 PackageReference
56
+
57
+ ```xml
58
+ <Project Sdk="Microsoft.NET.Sdk">
59
+ <PropertyGroup>
60
+ <OutputType>WinExe</OutputType>
61
+ <TargetFramework>net472</TargetFramework> <!-- SharpMap.UI 只有 .NET Framework 4.7.2 -->
62
+ </PropertyGroup>
63
+ <ItemGroup>
64
+ <PackageReference Include="SharpMap" Version="1.2.0" />
65
+ <PackageReference Include="SharpMap.UI" Version="1.2.0" />
66
+ <PackageReference Include="SharpMap.Layers.BruTile" Version="1.2.0" />
67
+ </ItemGroup>
68
+ </Project>
69
+ ```
70
+
71
+ ### 验证
72
+
73
+ ```bash
74
+ dotnet --version # 确认 SDK 可用
75
+ dotnet restore # 能还原 SharpMap 1.2.0 即包解析成功
76
+ dotnet build # 编译通过仅代表能构建,渲染结果仍需出图检查
77
+ ```
78
+
79
+ > `dotnet restore` 通常伴随 NU1902/NU1903/NU1904 漏洞告警(SharpMap 1.2.0 发布于 2021-03,传递依赖较旧),这是已知状态,不要当成安装失败。
80
+
81
+
53
82
  ---
54
83
 
55
84
  ## 核心 API:核心对象
@@ -183,34 +212,12 @@ mapBox1.MouseDown += (s, e) => {
183
212
 
184
213
  ---
185
214
 
186
- ## 性能建议
187
-
188
- 1. 预建空间索引(Shapefile `.qix`、PostGIS GiST)
189
- 2. `TileAsyncLayer` 用于在线底图
190
- 3. 避免主线程加载大数据
191
- 4. `LabelLayer` 启用优先级与碰撞检测
192
- 5. 复用 `Brush/Pen/VectorStyle`
193
-
194
- ---
195
-
196
- ## 常见问题
197
-
198
- | 问题 | 解决 |
199
- |------|------|
200
- | 无图 | 检查 SRID、`ZoomToExtents` |
201
- | 文字模糊 | 设置高 DPI Aware、`MapBox.MapTransform` |
202
- | GDI+ 内存泄漏 | 释放 `Brush/Pen/Bitmap` |
203
- | Shapefile 中文乱码 | `new ShapeFile(path, true, false, Encoding.UTF8)` |
204
- | 找不到 `SharpMap.UI.WinForms` 包 | 该包名在 NuGet 上不存在,WinForms 控件在 `SharpMap.UI` 包中 |
205
- | `CoordinateTransformation` 赋值编译错误 | ProjNet 2.x 不再实现 GeoAPI 接口,改用 `ProjNet4GeoAPI` 1.4.1 |
206
- | 找不到 `TileAsyncLayer` | 瓦片图层不在核心包中,需安装 `SharpMap.Layers.BruTile` |
207
-
208
- ---
209
-
210
215
  ## 典型工作流
211
216
 
212
217
  ### 工作流 1:Shapefile 渲染 + 主题样式 + 输出图片
213
218
 
219
+ 输入 `data/countries.shp`(含 `NAME`、`POP_EST` 字段),输出 `output.png`。
220
+
214
221
  ```csharp
215
222
  using SharpMap;
216
223
  using SharpMap.Layers;
@@ -219,12 +226,9 @@ using SharpMap.Styles;
219
226
  using SharpMap.Rendering.Thematics;
220
227
  using System.Drawing;
221
228
 
222
- // 创建地图
223
- var map = new Map(new Size(1024, 768));
224
- map.SRID = 4326;
229
+ var map = new Map(new Size(1024, 768)) { SRID = 4326 };
225
230
 
226
- // 添加 Shapefile 图层
227
- var prov = new ShapeFile("countries.shp", true);
231
+ var prov = new ShapeFile("data/countries.shp", true);
228
232
  var layer = new VectorLayer("Countries", prov)
229
233
  {
230
234
  Style = new VectorStyle
@@ -235,10 +239,10 @@ var layer = new VectorLayer("Countries", prov)
235
239
  }
236
240
  };
237
241
 
238
- // 按人口设置主题样式
242
+ // 按人口分档着色(DataRowView 索引器返回 object,需显式转换)
239
243
  layer.Theme = new CustomTheme(row =>
240
244
  {
241
- var pop = (int)row["POP_EST"];
245
+ var pop = Convert.ToInt64(row["POP_EST"]);
242
246
  return new VectorStyle
243
247
  {
244
248
  Fill = new SolidBrush(pop > 100_000_000 ? Color.Red : Color.LightBlue)
@@ -246,55 +250,86 @@ layer.Theme = new CustomTheme(row =>
246
250
  });
247
251
  map.Layers.Add(layer);
248
252
 
249
- // 添加行政标注
250
- var labels = new LabelLayer("Labels")
253
+ map.Layers.Add(new LabelLayer("Labels")
251
254
  {
252
- DataSource = prov, LabelColumn = "NAME",
255
+ DataSource = prov,
256
+ LabelColumn = "NAME",
253
257
  Style = new LabelStyle { Font = new Font("Arial", 10) }
254
- };
255
- map.Layers.Add(labels);
258
+ });
256
259
 
257
- // 渲染
258
260
  map.ZoomToExtents();
259
- using var img = map.GetMap();
261
+ using var img = map.GetMap(); // System.Drawing.Image
260
262
  img.Save("output.png");
261
263
  ```
262
264
 
263
- ### 工作流 2:PostGIS 数据 + OSM 底图 + WMS 发布
265
+ ### 工作流 2:PostGIS 数据 + OSM 底图
266
+
267
+ 输入 PostGIS 表 `poi(geom, id)`,输出带在线底图的 `map_with_osm.png`。
264
268
 
265
269
  ```csharp
266
- // PostGIS 数据
267
- var pgConn = "Host=localhost;Database=gisdb;User Id=postgres;Password=pg";
270
+ using BruTile.Predefined;
271
+
272
+ // 1) OSM 底图:瓦片图层来自 SharpMap.Layers.BruTile 包
273
+ var tileSrc = KnownTileSources.Create(KnownTileSource.OpenStreetMap);
274
+ map.Layers.Add(new TileAsyncLayer(tileSrc, "OSM"));
275
+
276
+ // 2) 底图是 Web Mercator,地图 SRID 必须同步,否则矢量层整体偏移
277
+ map.SRID = 3857;
278
+
279
+ // 3) PostGIS 矢量层:连接串后依次为表名、几何列、主键列
280
+ var pgConn = "Host=localhost;Database=gisdb;User Id=postgres;Password=***";
268
281
  var poiProvider = new PostGIS(pgConn, "poi", "geom", "id");
269
282
  map.Layers.Add(new VectorLayer("POI", poiProvider)
270
283
  {
271
284
  Style = new VectorStyle { Fill = Brushes.OrangeRed }
272
285
  });
273
286
 
274
- // OSM 底图
275
- using BruTile.Predefined;
276
- var tileSrc = KnownTileSources.Create(KnownTileSource.OpenStreetMap);
277
- map.Layers.Add(new TileAsyncLayer(tileSrc, "OSM"));
278
- map.SRID = 3857;
287
+ map.ZoomToExtents();
288
+ using var img = map.GetMap();
289
+ img.Save("map_with_osm.png");
279
290
  ```
280
291
 
281
- ## AI 使用建议
292
+ ```bash
293
+ dotnet --version # 需 .NET Framework 4.7.2 工程或 net472 目标框架
294
+ dotnet add package SharpMap --version 1.2.0
295
+ dotnet add package SharpMap.UI --version 1.2.0
296
+ dotnet build # 通过后打开输出的 PNG 检查
297
+ ```
282
298
 
283
- ### 推荐工作流
299
+ **验证产物**:只有 `dotnet build` 成功不算完成——打开 `output.png`,能看到按人口分色的面、标注文字与底图瓦片才算渲染正确。
284
300
 
285
- 1. **创建 Map**:`new Map(new Size(width, height))` → 设置 SRID
286
- 2. **添加数据源**:`ShapeFile(path)` / `PostGIS(conn, table, geomCol, idCol)` 等方式连接数据
287
- 3. **创建图层**:`VectorLayer(name, provider)` 并设置 `Style`;按需添加 `LabelLayer`
288
- 4. **添加底图**:`TileAsyncLayer` + `BruTile` 加载 OSM 在线底图
289
- 5. **渲染输出**:`map.GetMap()` 获取 `Image` 对象 → 保存为 PNG 或通过 ASP.NET WMS 发布
301
+ ## 最佳实践与性能建议
290
302
 
291
- ### 关键注意事项
303
+ 1. 预建空间索引(Shapefile `.qix`、PostGIS GiST)
304
+ 2. `TileAsyncLayer` 用于在线底图
305
+ 3. 避免主线程加载大数据
306
+ 4. `LabelLayer` 启用优先级与碰撞检测
307
+ 5. 复用 `Brush/Pen/VectorStyle`
308
+
309
+ ---
310
+
311
+ ## 常见问题
312
+
313
+ | 问题 | 解决 |
314
+ |------|------|
315
+ | 无图 | 检查 SRID、`ZoomToExtents` |
316
+ | 文字模糊 | 设置高 DPI Aware、`MapBox.MapTransform` |
317
+ | GDI+ 内存泄漏 | 释放 `Brush/Pen/Bitmap` |
318
+ | Shapefile 中文乱码 | DBF 无编码声明时 SharpMap 默认按 UTF-8 解码:`var shp = new ShapeFile("roads.shp"); shp.Encoding = System.Text.Encoding.GetEncoding("GBK");`(构造函数没有 Encoding 重载) |
319
+ | 找不到 `SharpMap.UI.WinForms` 包 | 该包名在 NuGet 上不存在,WinForms 控件在 `SharpMap.UI` 包中 |
320
+ | `CoordinateTransformation` 赋值编译错误 | ProjNet 2.x 不再实现 GeoAPI 接口,改用 `ProjNet4GeoAPI` 1.4.1 |
321
+ | 找不到 `TileAsyncLayer` | 瓦片图层不在核心包中,需安装 `SharpMap.Layers.BruTile` |
322
+
323
+ ---
324
+
325
+ ## AI 使用建议
292
326
 
293
- - **新项目建议 Mapsui**:SharpMap 主要面向 .NET Framework,新项目推荐使用 Mapsui(更活跃、跨平台更好)
294
- - **SRID 一致性**:图层与地图 SRID 必须一致,必要时通过 `CoordinateTransformation` 转换
295
- - **空间索引**:Shapefile 需预建 `.qix` 索引,PostGIS 用 GiST 索引加速查询
296
- - **资源释放**:GDI+ `Brush`/`Pen`/`Bitmap` 需及时释放避免内存泄漏
297
- - **Shapefile 编码**:中文数据需指定 `Encoding.UTF8` 或 `Encoding.GetEncoding("GBK")`
327
+ - **执行环境**:先 `dotnet --list-sdks`;核心包 `SharpMap` 是 netstandard2.0,可被 .NET 8+ 工程引用,但 WinForms 控件 `SharpMap.UI` 只有 .NET Framework 4.7.2,目标框架必须选 net472,不能套 net8.0。
328
+ - **验证产物**:`dotnet build` 后 `map.GetMap()` 取 `System.Drawing.Image` 再 `Save("output.png")`,打开 PNG 看实际着色与标注;编译通过不代表渲染正确。
329
+ - **依赖风险**:SharpMap 1.2.0(2021-03)的传递依赖含 `NetTopologySuite.Core` 1.15.3、`System.Drawing.Common` 4.6.0、`System.Data.SqlClient` 4.7.0,`dotnet restore` 会报 NU1902/NU1903/NU1904 漏洞告警,需向用户说明而不是静默忽略。
330
+ - **坐标与 SRID**:`map.SRID` 与图层 SRID 必须一致;ProjNet 2.x 不再实现 GeoAPI 接口,坐标变换用 `ProjNet4GeoAPI` 1.4.1。
331
+ - **资源释放**:GDI+ 的 `Brush`/`Pen`/`Bitmap` 必须 `using` 或 `Dispose`,否则长时间运行内存持续上涨。
332
+ - **安全与权限**:新建工程、装包、连接 PostGIS 前先征得用户同意;连接串里的密码不要写进代码或回答。
298
333
 
299
334
  ## 相关技能
300
335