@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: opengis-utils-for-net
3
- description: "Use when needing common GIS utility functions in .NET/C# — CRS utilities, geometry helpers, format converters, spatial validation. OpenGIS Utils for .NET: convenience toolkit for .NET GIS projects."
3
+ description: "Use when needing common GIS utilities in .NET/C# — OguLayerUtil ReadLayer/WriteLayer/ConvertFormat, GeometryUtil 50+ ops, CrsUtil CGCS2000 transforms, Shapefile/GeoJSON/FileGDB/GeoPackage/KML/PostGIS I/O; also for Unable to load DLL gdal / DllNotFoundException, GBK shapefile mojibake, or ArgumentException from Geojson2Wkt on a whole FeatureCollection. OpenGIS.Utils 1.1.2."
4
4
  tags:
5
5
  - dotnet
6
6
  - csharp
@@ -18,7 +18,7 @@ tags:
18
18
  >
19
19
  > **NuGet 包:** `OpenGIS.Utils`
20
20
  >
21
- > **最新版本:** 1.1.2(截至2026-10,NuGet)
21
+ > **最新版本:** 1.1.2(截至 2026-10,NuGet)
22
22
  >
23
23
  > **许可证:** LGPL-2.1-or-later
24
24
 
@@ -38,11 +38,31 @@ tags:
38
38
 
39
39
  ## 环境准备
40
40
 
41
+ ### 方式一:dotnet CLI
42
+
41
43
  ```bash
42
- dotnet add package OpenGIS.Utils
44
+ dotnet add package OpenGIS.Utils --version 1.1.2
45
+ ```
46
+
47
+ ### 方式二:手写 csproj 的 PackageReference
48
+
49
+ ```xml
50
+ <ItemGroup>
51
+ <PackageReference Include="OpenGIS.Utils" Version="1.1.2" />
52
+ </ItemGroup>
43
53
  ```
44
54
 
45
- ## Build & Test
55
+ ### 验证
56
+
57
+ ```bash
58
+ dotnet --version # 库为 netstandard2.0,.NET Core 2.0+ / .NET 5+ 均可引用
59
+ dotnet restore # 能解析 OpenGIS.Utils 1.1.2 即包可用
60
+ dotnet list package --include-transitive | findstr OpenGIS.Utils
61
+ ```
62
+
63
+ > GDAL 原生运行时由 `MaxRev.Gdal.Universal` 随包分发,无需手动 `GdalConfiguration.ConfigureGdal()`;`DllNotFoundException` 通常来自 RID 不匹配,见常见问题。
64
+
65
+ ## 构建与测试
46
66
 
47
67
  ```bash
48
68
  dotnet build OpenGIS.Utils.sln
@@ -51,7 +71,7 @@ dotnet test tests/OpenGIS.Utils.Tests/
51
71
 
52
72
  ---
53
73
 
54
- ## Project Structure
74
+ ## 项目结构
55
75
 
56
76
  ```text
57
77
  src/OpenGIS.Utils/
@@ -93,7 +113,7 @@ src/OpenGIS.Utils/
93
113
 
94
114
  ---
95
115
 
96
- ## Enums
116
+ ## 枚举
97
117
 
98
118
  ### GeometryType
99
119
 
@@ -131,7 +151,7 @@ TOO_FEW_POINTS, INVALID_COORDINATE, RING_NOT_CLOSED
131
151
 
132
152
  ---
133
153
 
134
- ## Core Model Classes
154
+ ## 核心模型类
135
155
 
136
156
  ### OguLayer
137
157
 
@@ -234,7 +254,7 @@ Methods: `ToWkt()` → `string`, `FromWkt(string wkt)` → `OguCoordinate` *(sta
234
254
 
235
255
  > OguLayerUtil、GeometryUtil、CrsUtil、ShpUtil、PostgisUtil、GtTxtUtil 等工具类与 GDAL 配置的完整 API 见 [reference/util-classes.md](reference/util-classes.md)
236
256
 
237
- ## Engine Architecture
257
+ ## 引擎架构
238
258
 
239
259
  ```csharp
240
260
  using OpenGIS.Utils.Engine;
@@ -278,7 +298,7 @@ public interface ILayerWriter
278
298
 
279
299
  ---
280
300
 
281
- ## General Utilities
301
+ ## 通用工具
282
302
 
283
303
  ### EncodingUtil
284
304
 
@@ -322,7 +342,7 @@ string NumUtil.FormatNumber(double value, int decimals)
322
342
 
323
343
  ---
324
344
 
325
- ## Exception Hierarchy
345
+ ## 异常层次
326
346
 
327
347
  ```text
328
348
  System.Exception
@@ -336,7 +356,7 @@ System.Exception
336
356
 
337
357
  ---
338
358
 
339
- ## Result Models
359
+ ## 结果模型
340
360
 
341
361
  ### TopologyValidationResult
342
362
 
@@ -367,27 +387,6 @@ Properties: `GdbPath` (`string?`), `LayerNames` (`List<string>`)
367
387
 
368
388
  > 常用代码模式完整示例见 [reference/code-patterns.md](reference/code-patterns.md)
369
389
 
370
- ## AI 使用建议
371
-
372
-
373
- ### 关键注意事项
374
-
375
- - **GDAL 自动初始化**:无需手动调用 `GdalConfiguration.ConfigureGdal()`
376
- - **GeoJSON 字符串可直接解析**:`Geojson2Wkt()` 和 `Geojson2Geometry()` 通过 GDAL 解析裸几何、`Feature` 或 `FeatureCollection`(取第一个要素的几何),无法解析时抛 `ArgumentException`;整文件请从文件加载
377
- - **几何以 WKT 存储**:`OguFeature.Wkt` 存储 WKT 字符串;多数 `GeometryUtil` 方法有 `*Wkt` 变体
378
- - **.NET 的 GDAL 实现**:`GEOTOOLS` 枚举值仅为兼容保留并重定向到 GDAL(Java 版本为双引擎)
379
- - **线程安全**:GDAL 初始化线程安全,但单个 GDAL 几何对象非线程安全
380
-
381
- ## 典型工作流
382
-
383
- 1. **读取数据**:使用 `OguLayerUtil.ReadLayer()` 统一入口读取各类矢量格式
384
- 2. **几何运算**:使用 `GeometryUtil.Wkt2Geometry()` 转换后操作,或直接用 `*Wkt` 后缀方法
385
- 3. **坐标转换**:使用 `CrsUtil.Transform()` 进行坐标系变换(CGCS2000 系列)
386
- 4. **写出结果**:使用 `OguLayerUtil.WriteLayer()` 写出为目标格式
387
- 5. **格式转换**:使用 `OguLayerUtil.ConvertFormat()` 一步完成
388
-
389
- ---
390
-
391
390
  ## 常见问题
392
391
 
393
392
  | 问题 | 解决 |
@@ -399,14 +398,7 @@ Properties: `GdbPath` (`string?`), `LayerNames` (`List<string>`)
399
398
  | `Geojson2Wkt`/`Geojson2Geometry` 抛 `ArgumentException` | 仅接受裸几何、`Feature` 或 `FeatureCollection` 字符串;空串或无法解析会抛错,整文件请走 `OguLayerUtil.ReadLayer` |
400
399
  | OGR 几何内存管理 | `OgrGeometry` 实现 `IDisposable`,用完及时 `Dispose()`;或用 `*Wkt` 便捷方法避免手动管理 |
401
400
 
402
- ## 相关技能
403
-
404
- - **nettopologysuite** — .NET 几何计算核心:[../nettopologysuite/SKILL.md](../nettopologysuite/SKILL.md)
405
- - **geometry-api-net** — Esri Geometry API for .NET:[../geometry-api-net/SKILL.md](../geometry-api-net/SKILL.md)
406
- - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
407
- - **gdal-api** — GDAL 编程 API:[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
408
-
409
- ## Important Notes
401
+ ## AI 编码约定
410
402
 
411
403
  1. **GDAL auto-initializes** — No manual `GdalConfiguration.ConfigureGdal()` call needed.
412
404
  2. **GeoJSON string parsing is supported** — `Geojson2Wkt()` / `Geojson2Geometry()` parse bare geometry, `Feature`, or `FeatureCollection` strings (first feature's geometry wins) via the GDAL GeoJSON driver and throw `ArgumentException` for unparseable input. For whole files use `GdalReader` or `OguLayerUtil.ReadLayer(DataFormatType.GEOJSON, path)`.
@@ -416,6 +408,80 @@ Properties: `GdbPath` (`string?`), `LayerNames` (`List<string>`)
416
408
  6. **Encoding support** — `EncodingUtil` detects UTF-8, UTF-16 LE/BE, GBK, GB2312. Register CodePages with `Encoding.RegisterProvider(CodePagesEncodingProvider.Instance)` if needed.
417
409
  7. **WKT convenience methods** — Most `GeometryUtil` methods have `*Wkt` variants that accept/return WKT strings directly, avoiding the need to manage `OgrGeometry` objects.
418
410
 
411
+ ---
412
+
413
+ ## 典型工作流
414
+
415
+ 以「Shapefile → 属性筛选 → 缓冲区 → 投影 → GeoPackage」为例:输入 `data/parcels.shp`(EPSG:4326),输出 `data/parcels_4528.gpkg`。
416
+
417
+ 1. **读取数据**:`OguLayerUtil.ReadLayer(DataFormatType.SHP, path)` 统一入口读取各类矢量格式
418
+ 2. **几何运算**:`GeometryUtil.Wkt2Geometry()` 转换后操作,或直接用 `*Wkt` 后缀方法
419
+ 3. **坐标转换**:`CrsUtil.Transform()` 只接受 WKT 或 `OgrGeometry`,整层变换需逐要素处理后改 `layer.Wkid`
420
+ 4. **写出结果**:`OguLayerUtil.WriteLayer()` 写出为目标格式
421
+ 5. **格式转换**:`OguLayerUtil.ConvertFormat()` 一步完成
422
+ 6. **回读验证**:重新读取产物,核对要素数与 `Wkid`
423
+
424
+ ```csharp
425
+ using OpenGIS.Utils.DataSource;
426
+ using OpenGIS.Utils.Engine.Enums;
427
+ using OpenGIS.Utils.Engine.Model.Layer;
428
+ using OpenGIS.Utils.Geometry;
429
+
430
+ // 1. 读:完整重载见 reference/code-patterns.md
431
+ OguLayer layer = OguLayerUtil.ReadLayer(DataFormatType.SHP, "data/parcels.shp");
432
+ Console.WriteLine($"{layer.Wkid} / {layer.GetFeatureCount()}");
433
+
434
+ // 2. 筛选 + 缓冲:几何以 WKT 字符串存放,OgrGeometry 需要 Dispose
435
+ var large = layer.Filter(f =>
436
+ {
437
+ using var g = GeometryUtil.Wkt2Geometry(f.Wkt!);
438
+ return GeometryUtil.Area(g) > 10000;
439
+ });
440
+
441
+ foreach (var f in large)
442
+ {
443
+ using var g = GeometryUtil.Wkt2Geometry(f.Wkt!);
444
+ using var buffered = GeometryUtil.Buffer(g, 50);
445
+ f.Wkt = GeometryUtil.Geometry2Wkt(buffered);
446
+ }
447
+
448
+ // 3. 投影到 CGCS2000 3 度带(EPSG:4528)。
449
+ // CrsUtil 只有 WKT / OgrGeometry 两个重载,没有整层变换,必须逐要素处理并改 Wkid
450
+ int sourceWkid = layer.Wkid ?? 4326;
451
+ foreach (var f in layer.Features)
452
+ f.Wkt = CrsUtil.Transform(f.Wkt!, sourceWkid, 4528);
453
+ layer.Wkid = 4528;
454
+
455
+ // 4. 写出 GeoPackage
456
+ OguLayerUtil.WriteLayer(DataFormatType.GEOPACKAGE, layer, "data/parcels_4528.gpkg");
457
+
458
+ // 6. 回读验证
459
+ OguLayer check = OguLayerUtil.ReadLayer(DataFormatType.GEOPACKAGE, "data/parcels_4528.gpkg");
460
+ Console.WriteLine($"{check.Wkid} / {check.GetFeatureCount()}");
461
+ ```
462
+
463
+ **验收**:打印的 WKID 应为 4528、要素数与筛选结果一致;再用 `ogrinfo -so data/parcels_4528.gpkg` 复核。`dotnet build` 成功不代表能跑——GDAL 原生库是运行期才加载的。
464
+
465
+ ---
466
+
467
+ ## AI 使用建议
468
+
469
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/code-patterns.md`、`reference/util-classes.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
470
+ - **执行环境**:先 `dotnet --version`;库目标 .NET Standard 2.0,可被 .NET Core 2.0+ / .NET 5+ / .NET Framework 4.6.1+ 引用,Windows 用 PowerShell;用 `dotnet new console -o demo && cd demo` 起最小工程。
471
+ - **依赖坐标**:`dotnet add package OpenGIS.Utils --version 1.1.2`(NuGet 最新 1.1.2),原生 GDAL 运行时随包分发(`MaxRev.Gdal.Universal`);用 `dotnet list package --include-transitive | Select-String OpenGIS.Utils` 核对解析出的版本,`NU1101`/`NU1102` 表示源或版本不可用,如实报告而不是改版本号重试。
472
+ - **平台与原生库**:运行时与 RID 绑定,`DllNotFoundException` 或 `Unable to load DLL 'gdal'` 多因 `-r win-x64`/`linux-x64` 与运行环境不一致;`dotnet publish -r win-x64` 后跑发布目录,不要只跑 `bin/Debug` 里的半成品。
473
+ - **验证产物**:最小程序 `OguLayerUtil.ReadLayer(DataFormatType.SHP, path)` 读入(完整重载见 `reference/code-patterns.md`)→ 打印 `layer.GetFeatureCount()` 与 `layer.Wkid`,再 `WriteLayer` 写出 GeoJSON 并重新读回,核对要素数与 CRS;`dotnet build` 成功只说明编译通过,GDAL 原生库是运行期才加载的。
474
+ - **常见误操**:`Geojson2Wkt()` 只接受裸几何 / `Feature` / `FeatureCollection` 字符串,传整文件内容会抛 `ArgumentException`,整文件走 `OguLayerUtil.ReadLayer`;`OgrGeometry` 是 `IDisposable`,用完 `Dispose()`;`GEOTOOLS` 枚举仅为兼容,在 .NET 版实际重定向到 GDAL。
475
+ - **构建与测试**:在仓库 checkout 内 `dotnet build OpenGIS.Utils.sln`、`dotnet test tests/OpenGIS.Utils.Tests/`,输出在 `bin/`、`obj/`(不要提交);只看某一条测试时加 `--filter FullyQualifiedName~关键字`。
476
+ - **安全与权限**:写入 Shapefile/GeoPackage 会覆盖同名文件,执行前确认目标路径;PostGIS 连接串与 GDAL 配置里的密码不要回显;`dotnet restore`、安装 SDK 或改 `NuGet.config` 前先征得用户同意。
477
+
478
+ ## 相关技能
479
+
480
+ - **nettopologysuite** — .NET 几何计算核心:[../nettopologysuite/SKILL.md](../nettopologysuite/SKILL.md)
481
+ - **geometry-api-net** — Esri Geometry API for .NET:[../geometry-api-net/SKILL.md](../geometry-api-net/SKILL.md)
482
+ - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
483
+ - **gdal-api** — GDAL 编程 API:[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
484
+
419
485
  ## 参考资源
420
486
 
421
487
  - **GitHub 仓库:** <https://github.com/znlgis/opengis-utils-for-net>
@@ -1,12 +1,12 @@
1
- # OpenGIS Utils for .NET Common Code Patterns
1
+ # OpenGIS Utils for .NET 常用代码模式
2
2
 
3
- Common code patterns and examples split from SKILL.md.
3
+ 从 SKILL.md 拆出的常用代码模式与示例,.NET 版本按 OpenGIS.Utils 1.1.2 编写。
4
4
 
5
5
  ---
6
6
 
7
- ## Common Code Patterns
7
+ ## 常用代码模式
8
8
 
9
- ### Create a Layer from Scratch
9
+ ### 从零构造图层
10
10
 
11
11
  ```csharp
12
12
  using OpenGIS.Utils.Engine.Model.Layer;
@@ -32,7 +32,7 @@ layer.AddFeature(feature);
32
32
  layer.Validate();
33
33
  ```
34
34
 
35
- ### Read → Process → Write
35
+ ### 读取 → 处理 → 写出
36
36
 
37
37
  ```csharp
38
38
  using OpenGIS.Utils.DataSource;
@@ -60,7 +60,7 @@ foreach (var feature in layer.Features)
60
60
  OguLayerUtil.WriteLayer(DataFormatType.GEOJSON, layer, "output.geojson");
61
61
  ```
62
62
 
63
- ### Coordinate Transformation
63
+ ### 坐标变换
64
64
 
65
65
  ```csharp
66
66
  using OpenGIS.Utils.Engine.Util;
@@ -73,7 +73,7 @@ int wkid = CrsUtil.GetProjectedWkid(zone); // Projected WKID
73
73
  string projected = CrsUtil.Transform(wktWgs84, 4326, wkid);
74
74
  ```
75
75
 
76
- ### Geometry Analysis
76
+ ### 几何分析
77
77
 
78
78
  ```csharp
79
79
  using OpenGIS.Utils.Geometry;
@@ -87,20 +87,20 @@ string center = GeometryUtil.CentroidWkt(polygon); // "POINT (5 5)"
87
87
  string buffer = GeometryUtil.BufferWkt(point, 1.0); // Buffered polygon WKT
88
88
  ```
89
89
 
90
- ### Format Conversion (One Line)
90
+ ### 格式转换(一行代码)
91
91
 
92
92
  ```csharp
93
93
  OguLayerUtil.ConvertFormat("input.shp", DataFormatType.SHP, "output.gpkg", DataFormatType.GEOPACKAGE);
94
94
  ```
95
95
 
96
- ### JSON Serialization
96
+ ### JSON 序列化
97
97
 
98
98
  ```csharp
99
99
  string json = layer.ToJson();
100
100
  OguLayer? restored = OguLayer.FromJson(json);
101
101
  ```
102
102
 
103
- ### Shapefile with Encoding
103
+ ### 带编码的 Shapefile
104
104
 
105
105
  ```csharp
106
106
  using OpenGIS.Utils.Engine.Util;
@@ -110,7 +110,7 @@ var layer = ShpUtil.ReadShapefile("data.shp", Encoding.GetEncoding("GBK"));
110
110
  ShpUtil.WriteShapefile(layer, "output.shp", Encoding.UTF8);
111
111
  ```
112
112
 
113
- ### Natural Sorting
113
+ ### 自然排序
114
114
 
115
115
  ```csharp
116
116
  using OpenGIS.Utils.Utils;
@@ -1,17 +1,17 @@
1
- # OpenGIS Utils for .NET Utility Classes Reference
1
+ # OpenGIS Utils for .NET 工具类参考
2
2
 
3
- OguLayerUtil, GeometryUtil, CrsUtil, ShpUtil, PostgisUtil, GtTxtUtil and GDAL configuration split from SKILL.md.
3
+ 从 SKILL.md 拆出的 OguLayerUtil、GeometryUtil、CrsUtil、ShpUtil、PostgisUtil、GtTxtUtil 与 GDAL 配置参考,按 OpenGIS.Utils 1.1.2 编写。
4
4
 
5
5
  ---
6
6
 
7
- ## Data I/O — OguLayerUtil (Recommended Entry Point)
7
+ ## 数据读写 — OguLayerUtil(推荐入口)
8
8
 
9
9
  ```csharp
10
10
  using OpenGIS.Utils.DataSource;
11
11
  using OpenGIS.Utils.Engine.Enums;
12
12
  ```
13
13
 
14
- ### Read
14
+ ### 读取
15
15
 
16
16
  ```csharp
17
17
  OguLayer layer = OguLayerUtil.ReadLayer(
@@ -28,7 +28,7 @@ OguLayer layer = OguLayerUtil.ReadLayer(
28
28
  OguLayer layer = await OguLayerUtil.ReadLayerAsync(DataFormatType.GEOJSON, "data.geojson");
29
29
  ```
30
30
 
31
- ### Write
31
+ ### 写出
32
32
 
33
33
  ```csharp
34
34
  OguLayerUtil.WriteLayer(
@@ -44,7 +44,7 @@ OguLayerUtil.WriteLayer(
44
44
  await OguLayerUtil.WriteLayerAsync(DataFormatType.SHP, layer, "output.shp");
45
45
  ```
46
46
 
47
- ### Format Conversion
47
+ ### 格式转换
48
48
 
49
49
  ```csharp
50
50
  OguLayerUtil.ConvertFormat(
@@ -59,13 +59,13 @@ await OguLayerUtil.ConvertFormatAsync(
59
59
  );
60
60
  ```
61
61
 
62
- ### Utilities
62
+ ### 工具
63
63
 
64
64
  ```csharp
65
65
  IList<string> names = OguLayerUtil.GetLayerNames(DataFormatType.FILEGDB, "data.gdb");
66
66
  ```
67
67
 
68
- ### Supported Format ↔ Driver
68
+ ### 支持的格式 ↔ 驱动
69
69
 
70
70
  | DataFormatType | Driver Name | Extension |
71
71
  |---|---|---|
@@ -80,7 +80,7 @@ IList<string> names = OguLayerUtil.GetLayerNames(DataFormatType.FILEGDB, "data.g
80
80
 
81
81
  ---
82
82
 
83
- ## Geometry Operations — GeometryUtil
83
+ ## 几何运算 — GeometryUtil
84
84
 
85
85
  ```csharp
86
86
  using OpenGIS.Utils.Geometry;
@@ -88,7 +88,7 @@ using OpenGIS.Utils.Geometry;
88
88
 
89
89
  All methods are `public static`.
90
90
 
91
- ### Format Conversion
91
+ ### 几何格式转换
92
92
 
93
93
  ```csharp
94
94
  OgrGeometry geom = GeometryUtil.Wkt2Geometry(string wkt);
@@ -99,7 +99,7 @@ string geojson = GeometryUtil.Geometry2Geojson(OgrGeometry geom);
99
99
 
100
100
  > **Note:** `Geojson2Wkt(string)` and `Geojson2Geometry(string)` parse GeoJSON strings (bare geometry, `Feature`, or `FeatureCollection` — the first feature's geometry is used) through the GDAL GeoJSON driver. Unparseable input, or input without a geometry, raises `ArgumentException`. For whole files use `GdalReader` or `OguLayerUtil.ReadLayer(DataFormatType.GEOJSON, path)`.
101
101
 
102
- ### Spatial Relationships (OgrGeometry)
102
+ ### 空间关系(OgrGeometry)
103
103
 
104
104
  ```csharp
105
105
  bool GeometryUtil.Intersects(OgrGeometry a, OgrGeometry b)
@@ -111,14 +111,14 @@ bool GeometryUtil.Overlaps(OgrGeometry a, OgrGeometry b)
111
111
  bool GeometryUtil.Disjoint(OgrGeometry a, OgrGeometry b)
112
112
  ```
113
113
 
114
- ### Spatial Relationships (WKT convenience)
114
+ ### 空间关系(WKT 便捷方法)
115
115
 
116
116
  ```csharp
117
117
  bool GeometryUtil.IntersectsWkt(string wktA, string wktB)
118
118
  bool GeometryUtil.ContainsWkt(string wktA, string wktB)
119
119
  ```
120
120
 
121
- ### Spatial Analysis (OgrGeometry)
121
+ ### 空间分析(OgrGeometry)
122
122
 
123
123
  ```csharp
124
124
  OgrGeometry GeometryUtil.Buffer(OgrGeometry geom, double distance)
@@ -129,7 +129,7 @@ OgrGeometry GeometryUtil.Difference(OgrGeometry a, OgrGeometry b)
129
129
  OgrGeometry GeometryUtil.SymDifference(OgrGeometry a, OgrGeometry b)
130
130
  ```
131
131
 
132
- ### Spatial Analysis (WKT convenience)
132
+ ### 空间分析(WKT 便捷方法)
133
133
 
134
134
  ```csharp
135
135
  string GeometryUtil.BufferWkt(string wkt, double distance)
@@ -137,7 +137,7 @@ string GeometryUtil.IntersectionWkt(string wktA, string wktB)
137
137
  string GeometryUtil.UnionWkt(IEnumerable<string> wktList)
138
138
  ```
139
139
 
140
- ### Geometry Properties
140
+ ### 几何属性
141
141
 
142
142
  ```csharp
143
143
  double GeometryUtil.Area(OgrGeometry geom)
@@ -150,7 +150,7 @@ GeometryType GeometryUtil.GetGeometryType(OgrGeometry geom)
150
150
  bool GeometryUtil.IsEmpty(OgrGeometry geom)
151
151
  ```
152
152
 
153
- ### Geometry Properties (WKT convenience)
153
+ ### 几何属性(WKT 便捷方法)
154
154
 
155
155
  ```csharp
156
156
  double GeometryUtil.AreaWkt(string wkt)
@@ -158,7 +158,7 @@ double GeometryUtil.LengthWkt(string wkt)
158
158
  string GeometryUtil.CentroidWkt(string wkt)
159
159
  ```
160
160
 
161
- ### Geometry Operations
161
+ ### 几何操作
162
162
 
163
163
  ```csharp
164
164
  OgrGeometry GeometryUtil.Boundary(OgrGeometry geom)
@@ -169,14 +169,14 @@ OgrGeometry GeometryUtil.Densify(OgrGeometry geom, double distanceTolerance)
169
169
  string GeometryUtil.SimplifyWkt(string wkt, double tolerance)
170
170
  ```
171
171
 
172
- ### Topology Validation
172
+ ### 拓扑校验
173
173
 
174
174
  ```csharp
175
175
  TopologyValidationResult GeometryUtil.IsValid(OgrGeometry geom)
176
176
  SimpleGeometryResult GeometryUtil.IsSimple(OgrGeometry geom)
177
177
  ```
178
178
 
179
- ### Equality & Distance
179
+ ### 相等与距离
180
180
 
181
181
  ```csharp
182
182
  bool GeometryUtil.EqualsExact(OgrGeometry a, OgrGeometry b)
@@ -188,7 +188,7 @@ bool GeometryUtil.IsWithinDistance(OgrGeometry a, OgrGeometry b, double maxDis
188
188
 
189
189
  ---
190
190
 
191
- ## Coordinate Reference Systems — CrsUtil
191
+ ## 坐标参考系 — CrsUtil
192
192
 
193
193
  ```csharp
194
194
  using OpenGIS.Utils.Engine.Util;
@@ -216,7 +216,7 @@ bool CrsUtil.IsProjectedCRS(int wkid) // Is projected CRS?
216
216
 
217
217
  ---
218
218
 
219
- ## Shapefile Utilities — ShpUtil
219
+ ## Shapefile 工具 — ShpUtil
220
220
 
221
221
  ```csharp
222
222
  using OpenGIS.Utils.Engine.Util;
@@ -233,7 +233,7 @@ void ShpUtil.RepairShapefile(string shpPath)
233
233
 
234
234
  ---
235
235
 
236
- ## PostGIS Utilities — PostgisUtil
236
+ ## PostGIS 工具 — PostgisUtil
237
237
 
238
238
  ```csharp
239
239
  using OpenGIS.Utils.Engine.Util;
@@ -248,7 +248,7 @@ void PostgisUtil.CreateSpatialIndex(string connectionString, string tableNam
248
248
 
249
249
  ---
250
250
 
251
- ## National Land Survey TXT Format — GtTxtUtil
251
+ ## 国土调查 TXT 格式 — GtTxtUtil
252
252
 
253
253
  ```csharp
254
254
  using OpenGIS.Utils.DataSource;
@@ -263,7 +263,7 @@ string GtTxtUtil.FormatTxtLine(OguCoordinate coordinate, int zoneNumber)
263
263
 
264
264
  ---
265
265
 
266
- ## GDAL Configuration
266
+ ## GDAL 配置
267
267
 
268
268
  ```csharp
269
269
  using OpenGIS.Utils.Configuration;
@@ -277,7 +277,7 @@ IList<string> GdalConfiguration.GetSupportedDrivers()
277
277
  bool GdalConfiguration.IsDriverAvailable(string driverName)
278
278
  ```
279
279
 
280
- ### LibrarySettings (Global Defaults)
280
+ ### LibrarySettings(全局默认值)
281
281
 
282
282
  | Property | Type | Default | Description |
283
283
  |---|---|---|---|
@@ -288,4 +288,3 @@ bool GdalConfiguration.IsDriverAvailable(string driverName)
288
288
  | `UseGdalExceptions` | `bool` | `true` | GDAL exception mode |
289
289
 
290
290
  ---
291
-
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: openlayers
3
- description: "Use when adding interactive 2D maps to web applications — WMS/WFS/WMTS layers, vector styling, map controls, popups. OpenLayers: the most full-featured open-source JavaScript web mapping library."
3
+ description: "Use when adding interactive 2D maps to web apps with npm ol 10.11.0 — Map/View, fromLonLat to EPSG:3857, WMS/WMTS/XYZ sources, MVT with featureClass, Draw/Modify/Snap interactions, or debugging blank layers (missing setStyle), offset centers and ol/... module-not-found errors."
4
4
  tags:
5
5
  - javascript
6
6
  - web
@@ -21,7 +21,7 @@ tags:
21
21
  >
22
22
  > **示例:** <https://openlayers.org/en/latest/examples/>
23
23
  >
24
- > **最新版本:** 10.11.0(截至2026-10,npm `ol`)
24
+ > **最新版本:** 10.11.0(截至 2026-10,npm `ol`)
25
25
  >
26
26
  > **许可证:** BSD-2-Clause
27
27
 
@@ -226,12 +226,70 @@ new VectorLayer({ source: clusterSource, style: clusterStyleFn });
226
226
 
227
227
  ## 典型工作流
228
228
 
229
- 1. **创建 Map**:`new Map({ target, layers, view })` → 设置投影和初始中心
229
+ 以「底图 + GeoJSON 行政区 + 绘制编辑」为例,输入 `public/data/districts.geojson`,输出可浏览、可勾绘的面图层页面。
230
+
231
+ 1. **创建 Map**:`new Map({ target, layers, view })` → `new View({ center: fromLonLat([116.39, 39.9]), zoom: 10 })`
230
232
  2. **添加底图**:`TileLayer` + `OSM`/`XYZ`/`TileWMS` Source
231
- 3. **加载矢量数据**:`VectorLayer` + `VectorSource` + `GeoJSON`/`MVT` Format
232
- 4. **应用样式**:使用 `Style` 函数按属性动态渲染
233
+ 3. **加载矢量数据**:`VectorLayer` + `VectorSource` + `GeoJSON` Format
234
+ 4. **应用样式**:`layer.setStyle(fn)` 按属性动态渲染(不设样式矢量图层不渲染)
233
235
  5. **添加交互**:`Draw`/`Modify`/`Select`/`Snap` Interaction
234
- 6. **性能优化**:`declutter` 避让标注、`renderMode: 'image'` 静态图层
236
+ 6. **导出结果**:`geojson.writeFeatures(source.getFeatures())` 落盘
237
+ 7. **性能优化**:`declutter` 避让标注、`renderMode: 'image'` 静态图层
238
+
239
+ ```js
240
+ import Map from 'ol/Map.js';
241
+ import View from 'ol/View.js';
242
+ import TileLayer from 'ol/layer/Tile.js';
243
+ import OSM from 'ol/source/OSM.js';
244
+ import VectorLayer from 'ol/layer/Vector.js';
245
+ import VectorSource from 'ol/source/Vector.js';
246
+ import GeoJSON from 'ol/format/GeoJSON.js';
247
+ import { fromLonLat } from 'ol/proj.js';
248
+ import { Style, Fill, Stroke, Text } from 'ol/style.js';
249
+ import Draw from 'ol/interaction/Draw.js';
250
+
251
+ // 显式 dataProjection / featureProjection,避免 4326 数据直接落在 3857 视图上偏移
252
+ const geojson = new GeoJSON({
253
+ dataProjection: 'EPSG:4326',
254
+ featureProjection: 'EPSG:3857'
255
+ });
256
+
257
+ const vectorLayer = new VectorLayer({
258
+ source: new VectorSource({
259
+ url: '/data/districts.geojson',
260
+ format: geojson
261
+ }),
262
+ style: (feature) => new Style({
263
+ fill: new Fill({ color: 'rgba(70,130,180,0.25)' }),
264
+ stroke: new Stroke({ color: '#4682b4', width: 1.5 }),
265
+ text: new Text({
266
+ text: feature.get('name'),
267
+ font: '12px sans-serif',
268
+ overflow: true
269
+ })
270
+ })
271
+ });
272
+
273
+ const map = new Map({
274
+ target: 'map',
275
+ layers: [new TileLayer({ source: new OSM() }), vectorLayer],
276
+ view: new View({ center: fromLonLat([116.39, 39.9]), zoom: 9 })
277
+ });
278
+
279
+ // 直接在同一个矢量图层上绘制;画完把全部要素序列化回 EPSG:4326
280
+ const drawSource = vectorLayer.getSource();
281
+ map.addInteraction(new Draw({ source: drawSource, type: 'Polygon' }));
282
+
283
+ drawSource.on('addfeature', () => {
284
+ const text = geojson.writeFeatures(drawSource.getFeatures(), {
285
+ dataProjection: 'EPSG:4326',
286
+ featureProjection: 'EPSG:3857'
287
+ });
288
+ console.log(text); // 可直接提交给后端保存
289
+ });
290
+ ```
291
+
292
+ **验证产物**:`npm run build` 后打开页面,底图与行政区面同时显示;再画一个多边形,控制台应输出对应 GeoJSON(坐标已转回 EPSG:4326)。
235
293
 
236
294
  ---
237
295
 
@@ -261,14 +319,13 @@ new VectorLayer({ source: clusterSource, style: clusterStyleFn });
261
319
 
262
320
  ## AI 使用建议
263
321
 
264
-
265
- ### 关键注意事项
266
-
267
- - **投影一致**:经纬度需 `fromLonLat()` 转为 EPSG:3857;自定义投影需注册 proj4
268
- - **WMS 参数**:`LAYERS` 参数需使用完整名称(如 `workspace:layer`),检查 CORS
269
- - **矢量瓦片字段**:MVT 格式需设置 `featureClass: Feature` 保留属性
270
- - **样式缓存**:使用函数式 Style 时,缓存 Style 实例避免重复创建
271
- - **批量添加**:使用 `addFeatures([])` 而非循环 `addFeature`,显著提升性能
322
+ - **执行环境**:`npm install`、`npm run build` 在终端中执行;Windows 下 `npm` 是 `npm.cmd`,长构建放后台运行并把输出落盘再读。
323
+ - **先探测版本**:`npm ls ol`(未装则 `npm view ol version`);本技能按 10.11.0 编写,只使用 `ol/Map.js`、`ol/layer/Tile.js` 等 ESM 子路径,旧版 `ol.source.*` 全量命名空间写法不要混用。
324
+ - **验证产物**:`npm run build` 后用 `npx serve dist`(或 `python -m http.server 5173 -d dist`)起静态服务,`curl.exe -I http://localhost:5173/` 与打包出的 `assets/*.js` 应为 200;AI 助手通常看不到浏览器画面,请用户看页面与控制台,环境支持读图时用截图核对。
325
+ - **投影**:经纬度必须 `fromLonLat()` 转 EPSG:3857,自定义投影先 `register(proj4)`;否则中心点偏移或图层不显示。
326
+ - **图层样式**:矢量图层不设样式默认不渲染,务必 `setStyle()`;MVT 源要用 `MVT({ featureClass: Feature })` 才能保留属性。
327
+ - **常见症状**:WMS 空白先查 CORS、`LAYERS` 全名与 `SRS`;`ol/...` 模块找不到说明打包器没按 ESM 解析;容器尺寸变化后调用 `map.updateSize()`。
328
+ - **安全与权限**:装包、起 dev server、对外暴露端口前先征得用户同意;内网 WMS 地址与凭据不要写进示例。
272
329
 
273
330
  ## 相关技能
274
331