@dsh-gis/dsh-opengis-skill 0.1.3 → 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.
- package/CHANGELOG.md +40 -0
- package/README.md +48 -22
- package/THIRD_PARTY_NOTICES.md +9 -0
- package/adaptations/brutile.md +8 -0
- package/adaptations/cesiumjs.md +8 -0
- package/adaptations/common.md +16 -0
- package/adaptations/deck-gl.md +8 -0
- package/adaptations/duckdb-spatial.md +8 -0
- package/adaptations/gdal-api.md +8 -0
- package/adaptations/gdal.md +8 -0
- package/adaptations/geolibre.md +8 -0
- package/adaptations/geometry-api-java.md +8 -0
- package/adaptations/geometry-api-net.md +8 -0
- package/adaptations/geonode.md +8 -0
- package/adaptations/geopandas.md +8 -0
- package/adaptations/geopipe-agent.md +8 -0
- package/adaptations/geoserver-cloud.md +8 -0
- package/adaptations/geoserver-rest-api.md +8 -0
- package/adaptations/geoserver.md +8 -0
- package/adaptations/geotools.md +8 -0
- package/adaptations/grass-gis.md +8 -0
- package/adaptations/jts.md +8 -0
- package/adaptations/kepler-gl.md +8 -0
- package/adaptations/leaflet.md +8 -0
- package/adaptations/mapbox-gl-js.md +8 -0
- package/adaptations/mapserver.md +8 -0
- package/adaptations/mapsui.md +8 -0
- package/adaptations/nettopologysuite.md +8 -0
- package/adaptations/opengis-all.md +8 -0
- package/adaptations/opengis-daf.md +8 -0
- package/adaptations/opengis-utils-for-java.md +8 -0
- package/adaptations/opengis-utils-for-net.md +8 -0
- package/adaptations/openlayers.md +8 -0
- package/adaptations/pdal.md +8 -0
- package/adaptations/postgis.md +8 -0
- package/adaptations/proj.md +8 -0
- package/adaptations/projnet4geoapi.md +8 -0
- package/adaptations/pyqgis.md +8 -0
- package/adaptations/qgis-process.md +8 -0
- package/adaptations/qgis-server.md +8 -0
- package/adaptations/shapely.md +8 -0
- package/adaptations/sharpmap.md +8 -0
- package/adaptations/spatialite.md +8 -0
- package/adaptations/whitebox-tools.md +8 -0
- package/assets/brutile/SKILL.md +289 -0
- package/assets/cesiumjs/SKILL.md +73 -23
- package/assets/deck-gl/SKILL.md +19 -20
- package/assets/duckdb-spatial/SKILL.md +370 -0
- package/assets/gdal/SKILL.md +50 -21
- package/assets/gdal-api/SKILL.md +6 -4
- package/assets/geolibre/SKILL.md +364 -0
- package/assets/geometry-api-java/SKILL.md +5 -6
- package/assets/geometry-api-net/SKILL.md +65 -21
- package/assets/geonode/SKILL.md +347 -0
- package/assets/geopandas/SKILL.md +17 -15
- package/assets/geopipe-agent/SKILL.md +25 -20
- package/assets/geoserver/SKILL.md +6 -4
- package/assets/geoserver-cloud/SKILL.md +14 -15
- package/assets/geoserver-rest-api/SKILL.md +13 -8
- package/assets/geotools/SKILL.md +7 -5
- package/assets/grass-gis/SKILL.md +19 -20
- package/assets/jts/SKILL.md +7 -4
- package/assets/kepler-gl/SKILL.md +313 -0
- package/assets/leaflet/SKILL.md +41 -19
- package/assets/mapbox-gl-js/SKILL.md +18 -19
- package/assets/mapserver/SKILL.md +17 -19
- package/assets/mapsui/SKILL.md +85 -48
- package/assets/nettopologysuite/SKILL.md +91 -20
- package/assets/opengis-all/SKILL.md +78 -270
- package/assets/opengis-all/reference/data-stages.md +262 -4
- package/assets/opengis-daf/SKILL.md +6 -5
- package/assets/opengis-utils-for-java/SKILL.md +52 -39
- package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
- package/assets/opengis-utils-for-net/SKILL.md +105 -39
- package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
- package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
- package/assets/openlayers/SKILL.md +66 -9
- package/assets/pdal/SKILL.md +21 -17
- package/assets/postgis/SKILL.md +61 -11
- package/assets/proj/SKILL.md +28 -30
- package/assets/projnet4geoapi/SKILL.md +299 -0
- package/assets/pyqgis/SKILL.md +28 -20
- package/assets/qgis-process/SKILL.md +71 -22
- package/assets/qgis-server/SKILL.md +20 -20
- package/assets/shapely/SKILL.md +132 -75
- package/assets/sharpmap/SKILL.md +93 -50
- package/assets/spatialite/SKILL.md +365 -0
- package/assets/whitebox-tools/SKILL.md +269 -0
- package/lib/adaptations.d.ts +47 -0
- package/lib/adaptations.js +268 -0
- package/lib/index.d.ts +1 -1
- package/lib/index.js +14 -2
- package/lib/skill-file.js +31 -7
- package/locale/en.json +1 -1
- package/locale/zh.json +1 -1
- package/package.json +12 -2
- package/upstream.json +56 -40
package/assets/shapely/SKILL.md
CHANGED
|
@@ -18,7 +18,7 @@ tags:
|
|
|
18
18
|
>
|
|
19
19
|
> **PyPI:** <https://pypi.org/project/shapely/>
|
|
20
20
|
>
|
|
21
|
-
>
|
|
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
|
|
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
|
-
##
|
|
58
|
+
## 几何类型
|
|
59
59
|
|
|
60
|
-
|
|
|
60
|
+
| 类型 | 类 | 说明 |
|
|
61
61
|
|------|-------|-------------|
|
|
62
|
-
| Point | `shapely.Point` |
|
|
63
|
-
| LineString | `shapely.LineString` |
|
|
64
|
-
| LinearRing | `shapely.LinearRing` |
|
|
65
|
-
| Polygon | `shapely.Polygon` |
|
|
66
|
-
| MultiPoint | `shapely.MultiPoint` |
|
|
67
|
-
| MultiLineString | `shapely.MultiLineString` |
|
|
68
|
-
| MultiPolygon | `shapely.MultiPolygon` |
|
|
69
|
-
| GeometryCollection | `shapely.GeometryCollection` |
|
|
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
|
|
71
|
+
**所有空间分析都忽略 Z 值** —— 运算只在 x-y 平面进行。
|
|
72
72
|
|
|
73
|
-
##
|
|
73
|
+
## 双 API 模式
|
|
74
74
|
|
|
75
|
-
Shapely
|
|
75
|
+
Shapely 提供两套 API:处理数组、追求性能时优先用**函数式 API**,只做单个几何的便捷操作时用**面向对象 API**。
|
|
76
76
|
|
|
77
|
-
###
|
|
77
|
+
### 函数式 API(向量化,NumPy ufunc)
|
|
78
78
|
|
|
79
|
-
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
##
|
|
115
|
+
## 几何对象创建
|
|
116
116
|
|
|
117
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
##
|
|
201
|
+
## 缺失值
|
|
202
202
|
|
|
203
|
-
`None`
|
|
204
|
-
-
|
|
205
|
-
-
|
|
206
|
-
-
|
|
203
|
+
`None` 表示缺失几何,各函数行为保持一致:
|
|
204
|
+
- 谓词返回 `False`
|
|
205
|
+
- 度量返回 `nan`
|
|
206
|
+
- 构造类操作返回 `None`
|
|
207
207
|
|
|
208
|
-
|
|
208
|
+
用 `shapely.is_missing(obj)` 判断,注意它与 `shapely.is_empty(geom)`(空几何)不同。
|
|
209
209
|
|
|
210
|
-
##
|
|
210
|
+
## 重要注意事项
|
|
211
211
|
|
|
212
|
-
1.
|
|
212
|
+
1. **分析中忽略 Z 值**:所有空间运算只在 x-y 平面进行,Z 值不同的几何仍可能相交或相等。
|
|
213
213
|
|
|
214
|
-
2. **`contains`
|
|
214
|
+
2. **`contains` 不含边界**:`contains(line, endpoint)` 为 `False`;需要把边界算在内时用 `covers()` 或 `intersects()`。
|
|
215
215
|
|
|
216
|
-
3. **`set_coordinates`
|
|
216
|
+
3. **`set_coordinates` 原地修改**:需保留原几何时,先 `.copy()`。
|
|
217
217
|
|
|
218
|
-
4. **`clip_by_rect`
|
|
218
|
+
4. **`clip_by_rect` 可能产出无效几何**:这个快速裁剪不保证拓扑有效。
|
|
219
219
|
|
|
220
|
-
5. **WKB
|
|
220
|
+
5. **WKB 丢失 LinearRing**:LinearRing 在 WKB 序列化时变成 LineString。
|
|
221
221
|
|
|
222
|
-
6. **`to_geojson`
|
|
222
|
+
6. **`to_geojson` 丢弃 Z**:第三维被静默丢弃,LinearRing 输出为 `null`。
|
|
223
223
|
|
|
224
|
-
7.
|
|
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`
|
|
226
|
+
8. **`set_precision` 改变顶点顺序**:返回几何处于"轻度规范化"形式,不要依赖其顶点顺序。
|
|
227
227
|
|
|
228
|
-
9. **NaN
|
|
228
|
+
9. **NaN 坐标**:默认允许用 NaN/Inf 构造几何;需要控制时在创建函数里传 `handle_nan='error'` 或 `handle_nan='skip'`。
|
|
229
229
|
|
|
230
|
-
10.
|
|
230
|
+
10. **预处理状态不保留**:任何产生新几何的运算之后,都要重新调用 `prepare()`。
|
|
231
231
|
|
|
232
|
-
11. **GEOS
|
|
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`
|
|
234
|
+
12. **`shapely.ops.transform` 已弃用**:2.2 起改用 `shapely.transform`(按坐标逐点)或 `shapely.transform_coordseq`(按坐标序列);`multithreading_enabled` 装饰器同样已弃用。
|
|
235
235
|
|
|
236
|
-
##
|
|
236
|
+
## 典型工作流
|
|
237
|
+
|
|
238
|
+
端到端:WKT 读入 → 有效性修复 → 裁剪/缓冲 → 写回 GeoJSON,全程用函数式 API。
|
|
237
239
|
|
|
238
|
-
### Point-in-polygon test for many points
|
|
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
|
+
### 大批量点落在面内判断
|
|
280
|
+
```python
|
|
281
|
+
import numpy as np
|
|
282
|
+
import shapely
|
|
240
283
|
from shapely import STRtree, points
|
|
241
284
|
|
|
242
|
-
|
|
243
|
-
|
|
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
|
-
###
|
|
294
|
+
### 批量合并大量多边形
|
|
249
295
|
```python
|
|
296
|
+
import shapely
|
|
297
|
+
|
|
250
298
|
result = shapely.union_all(polygon_array)
|
|
251
299
|
```
|
|
252
300
|
|
|
253
|
-
###
|
|
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,32 +313,23 @@ def project(coords):
|
|
|
262
313
|
projected = shapely.transform(geom, project)
|
|
263
314
|
```
|
|
264
315
|
|
|
265
|
-
###
|
|
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
|
-
###
|
|
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
|
-
## 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
333
|
## 常见问题
|
|
292
334
|
|
|
293
335
|
| 问题 | 解决 |
|
|
@@ -300,18 +342,24 @@ left_idx, right_idx = tree.query(left_geoms, predicate="intersects")
|
|
|
300
342
|
| STRtree 查询返回空数组 | 检查几何是否 `None`/`Empty`;确认查询几何与索引几何的 CRS 一致 |
|
|
301
343
|
| WKB 序列化丢失 LinearRing | WKB 规范不支持 LinearRing,会自动转为 LineString |
|
|
302
344
|
| `to_geojson` 丢失 Z 坐标 | GeoJSON 标准不支持 Z,改用 WKB 或自定义序列化 |
|
|
303
|
-
| `shapely.ops.transform` 弃用警告 | 2.2
|
|
345
|
+
| `shapely.ops.transform` 弃用警告 | 2.2 起弃用,改用 `shapely.transform` 或 `shapely.transform_coordseq` |
|
|
304
346
|
|
|
305
347
|
---
|
|
306
348
|
|
|
307
|
-
##
|
|
349
|
+
## AI 使用建议
|
|
308
350
|
|
|
309
|
-
-
|
|
310
|
-
-
|
|
311
|
-
-
|
|
312
|
-
-
|
|
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 到文件再分段读,别刷屏。
|
|
359
|
+
|
|
360
|
+
---
|
|
313
361
|
|
|
314
|
-
##
|
|
362
|
+
## 包结构
|
|
315
363
|
|
|
316
364
|
```text
|
|
317
365
|
shapely/
|
|
@@ -341,6 +389,15 @@ shapely/
|
|
|
341
389
|
|
|
342
390
|
---
|
|
343
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
|
+
|
|
344
401
|
## 参考资源
|
|
345
402
|
|
|
346
403
|
- **GitHub 仓库:** <https://github.com/shapely/shapely>
|
package/assets/sharpmap/SKILL.md
CHANGED
|
@@ -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
|
-
|
|
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 = (
|
|
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,43 +250,82 @@ 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,
|
|
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 底图
|
|
265
|
+
### 工作流 2:PostGIS 数据 + OSM 底图
|
|
266
|
+
|
|
267
|
+
输入 PostGIS 表 `poi(geom, id)`,输出带在线底图的 `map_with_osm.png`。
|
|
264
268
|
|
|
265
269
|
```csharp
|
|
266
|
-
|
|
267
|
-
|
|
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
|
-
|
|
275
|
-
using
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
287
|
+
map.ZoomToExtents();
|
|
288
|
+
using var img = map.GetMap();
|
|
289
|
+
img.Save("map_with_osm.png");
|
|
290
|
+
```
|
|
291
|
+
|
|
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 检查
|
|
279
297
|
```
|
|
280
298
|
|
|
281
|
-
|
|
299
|
+
**验证产物**:只有 `dotnet build` 成功不算完成——打开 `output.png`,能看到按人口分色的面、标注文字与底图瓦片才算渲染正确。
|
|
300
|
+
|
|
301
|
+
## 最佳实践与性能建议
|
|
302
|
+
|
|
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 使用建议
|
|
282
326
|
|
|
283
|
-
- **加载与引用**:用 `skill("sharpmap")` 加载(用户也可输入 `/sharpmap`);示例写入会话工作区的 .NET 工程,技能目录只读。
|
|
284
327
|
- **执行环境**:先 `dotnet --list-sdks`;核心包 `SharpMap` 是 netstandard2.0,可被 .NET 8+ 工程引用,但 WinForms 控件 `SharpMap.UI` 只有 .NET Framework 4.7.2,目标框架必须选 net472,不能套 net8.0。
|
|
285
|
-
- **验证产物**:`dotnet build` 后 `map.GetMap()` 取 `System.Drawing.Image` 再 `Save("output.png")
|
|
328
|
+
- **验证产物**:`dotnet build` 后 `map.GetMap()` 取 `System.Drawing.Image` 再 `Save("output.png")`,打开 PNG 看实际着色与标注;编译通过不代表渲染正确。
|
|
286
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 漏洞告警,需向用户说明而不是静默忽略。
|
|
287
330
|
- **坐标与 SRID**:`map.SRID` 与图层 SRID 必须一致;ProjNet 2.x 不再实现 GeoAPI 接口,坐标变换用 `ProjNet4GeoAPI` 1.4.1。
|
|
288
331
|
- **资源释放**:GDI+ 的 `Brush`/`Pen`/`Bitmap` 必须 `using` 或 `Dispose`,否则长时间运行内存持续上涨。
|