@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.
Files changed (97) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +48 -22
  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 +73 -23
  47. package/assets/deck-gl/SKILL.md +19 -20
  48. package/assets/duckdb-spatial/SKILL.md +370 -0
  49. package/assets/gdal/SKILL.md +50 -21
  50. package/assets/gdal-api/SKILL.md +6 -4
  51. package/assets/geolibre/SKILL.md +364 -0
  52. package/assets/geometry-api-java/SKILL.md +5 -6
  53. package/assets/geometry-api-net/SKILL.md +65 -21
  54. package/assets/geonode/SKILL.md +347 -0
  55. package/assets/geopandas/SKILL.md +17 -15
  56. package/assets/geopipe-agent/SKILL.md +25 -20
  57. package/assets/geoserver/SKILL.md +6 -4
  58. package/assets/geoserver-cloud/SKILL.md +14 -15
  59. package/assets/geoserver-rest-api/SKILL.md +13 -8
  60. package/assets/geotools/SKILL.md +7 -5
  61. package/assets/grass-gis/SKILL.md +19 -20
  62. package/assets/jts/SKILL.md +7 -4
  63. package/assets/kepler-gl/SKILL.md +313 -0
  64. package/assets/leaflet/SKILL.md +41 -19
  65. package/assets/mapbox-gl-js/SKILL.md +18 -19
  66. package/assets/mapserver/SKILL.md +17 -19
  67. package/assets/mapsui/SKILL.md +85 -48
  68. package/assets/nettopologysuite/SKILL.md +91 -20
  69. package/assets/opengis-all/SKILL.md +78 -270
  70. package/assets/opengis-all/reference/data-stages.md +262 -4
  71. package/assets/opengis-daf/SKILL.md +6 -5
  72. package/assets/opengis-utils-for-java/SKILL.md +52 -39
  73. package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
  74. package/assets/opengis-utils-for-net/SKILL.md +105 -39
  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 +66 -9
  78. package/assets/pdal/SKILL.md +21 -17
  79. package/assets/postgis/SKILL.md +61 -11
  80. package/assets/proj/SKILL.md +28 -30
  81. package/assets/projnet4geoapi/SKILL.md +299 -0
  82. package/assets/pyqgis/SKILL.md +28 -20
  83. package/assets/qgis-process/SKILL.md +71 -22
  84. package/assets/qgis-server/SKILL.md +20 -20
  85. package/assets/shapely/SKILL.md +132 -75
  86. package/assets/sharpmap/SKILL.md +93 -50
  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
@@ -17,11 +17,13 @@ tags:
17
17
 
18
18
  > **项目地址:** <https://github.com/znlgis/opengis-daf>
19
19
  >
20
+ > **版本:** 仓库主线(截至 2026-10,无 Release tag、无 NuGet 包;以 `global.json` 的 .NET SDK 10.0.301 为准)
21
+ >
20
22
  > **许可证:** MIT License
21
23
  >
22
24
  > **文档:** <https://github.com/znlgis/opengis-daf/tree/main/docs>(快速入门、方案配置指南、算子参考、CLI 参考)
23
25
  >
24
- > **底层依赖:** GDAL/OGR 3.x、NetTopologySuite 2.6、Npgsql 10、Serilog 4.4
26
+ > **底层依赖:** GDAL/OGR 3.x、NetTopologySuite 2.6.0、Npgsql 10.0.3、Serilog 4.4.0(实测各 `*.csproj`)
25
27
 
26
28
  ## 概述
27
29
 
@@ -193,7 +195,7 @@ dotnet demo/plugin/OpenGisDAF.PluginHostDemo/bin/Release/net10.0/OpenGisDAF.Plug
193
195
 
194
196
  ---
195
197
 
196
- ## 常见工作流
198
+ ## 典型工作流
197
199
 
198
200
  ### 先质检、后分析(推荐)
199
201
 
@@ -237,10 +239,9 @@ dotnet demo/plugin/OpenGisDAF.PluginHostDemo/bin/Release/net10.0/OpenGisDAF.Plug
237
239
 
238
240
  ---
239
241
 
240
- ## DeepSeek Harness 使用建议
242
+ ## AI 使用建议
241
243
 
242
- - **加载与引用**:用 `skill("opengis-daf")` 加载(用户也可输入 `/opengis-daf`);本技能没有 `reference/` 子目录,方案文档在上游仓库 `docs/`;技能目录只读,方案 JSON 与输出写到会话工作区。
243
- - **执行环境**:先 `dotnet --version`,必须是 **10.0**(仓库 `global.json` 锁定),Windows 用 `pwsh`;克隆必须 `git clone --recurse-submodules`,漏了子模块 `opengis-utils-for-net` 会在编译期报 GDAL 绑定类型缺失。
244
+ - **执行环境**:先 `dotnet --version`,必须是 **10.0**(仓库 `global.json` 锁定),Windows 用 PowerShell;克隆必须 `git clone --recurse-submodules`,漏了子模块 `opengis-utils-for-net` 会在编译期报 GDAL 绑定类型缺失。
244
245
  - **源码构建(无 NuGet 包)**:`dotnet build` 或 `./build.sh`,再 `dotnet run --project src/OpenGisDAF.Cli -- help` 确认 CLI 可用;这是自有项目,不要写 `dotnet add package OpenGisDAF`。
245
246
  - **测试两步走**:`dotnet build OpenGisDAF.slnx -c Release` 后 `dotnet test OpenGisDAF.slnx -c Release --no-build`——同一条 `dotnet test` 在 xunit.v3 工具链下会报“运行了零个测试”并以退出码 5 失败。
246
247
  - **验证产物**:先 `daf validate --plan plans/my.json`(只校验 21 条规则)再 `daf run --plan plans/my.json`;退出码 `0` 才是成功(失败或跳过都返回 1),随后重开输出 GeoJSON 核对 `crs` 与要素数,并查看 `{plan}.qc-report.json` 的 `totalChecked/failed/passRate`(仅 `qcMode: true` 才生成)。
@@ -17,7 +17,7 @@ tags:
17
17
  >
18
18
  > **官方文档:** <https://github.com/znlgis/opengis-utils-for-java#readme>
19
19
  >
20
- > **Maven 坐标:** `com.znlgis.ogu4j:ogu4j:1.0.0`(截至2026-10 尚未发布到 Maven Central,需从源码 `mvn install` 安装到本地仓库)
20
+ > **Maven 坐标:** `com.znlgis.ogu4j:ogu4j:1.0.0`(截至 2026-10 尚未发布到 Maven Central,需从源码 `mvn install` 安装到本地仓库)
21
21
  >
22
22
  > **许可证:** LGPL-2.1-or-later
23
23
 
@@ -133,7 +133,7 @@ com.znlgis.ogu4j
133
133
 
134
134
  > 常见任务快速参考(Quick Reference: Common Tasks)完整内容见 [reference/common-tasks.md](reference/common-tasks.md)
135
135
 
136
- ## Data Format Support Matrix
136
+ ## 数据格式支持矩阵
137
137
 
138
138
  | Format | DataFormatType | GeoTools | GDAL | Read | Write | Notes |
139
139
  |--------|---------------|----------|------|------|-------|-------|
@@ -147,9 +147,9 @@ com.znlgis.ogu4j
147
147
 
148
148
  ---
149
149
 
150
- ## Data Model Reference
150
+ ## 数据模型参考
151
151
 
152
- ### OguLayer (Core)
152
+ ### OguLayer(核心)
153
153
 
154
154
  | Property | Type | Description |
155
155
  |----------|------|-------------|
@@ -211,7 +211,7 @@ com.znlgis.ogu4j
211
211
 
212
212
  **Constructors:** `OguCoordinate(x, y)`, `OguCoordinate(x, y, z)`
213
213
 
214
- ### DbConnBaseModel (PostGIS connection)
214
+ ### DbConnBaseModel(PostGIS 连接)
215
215
 
216
216
  | Property | Type | Description |
217
217
  |----------|------|-------------|
@@ -225,7 +225,7 @@ com.znlgis.ogu4j
225
225
 
226
226
  ---
227
227
 
228
- ## Enumerations Quick Reference
228
+ ## 枚举速查
229
229
 
230
230
  ### GeometryType
231
231
 
@@ -251,7 +251,7 @@ com.znlgis.ogu4j
251
251
 
252
252
  ---
253
253
 
254
- ## Exception Hierarchy
254
+ ## 异常层次
255
255
 
256
256
  ```text
257
257
  Exception
@@ -267,7 +267,7 @@ RuntimeException
267
267
 
268
268
  ---
269
269
 
270
- ## Architecture & Design Patterns
270
+ ## 架构与设计模式
271
271
 
272
272
  - **Factory Pattern:** `GisEngineFactory` creates engine instances; use `GisEngineType.AUTO` for automatic selection (prefers GDAL if available)
273
273
  - **Strategy Pattern:** `LayerReader` / `LayerWriter` interfaces define pluggable format-specific I/O strategies
@@ -277,18 +277,20 @@ RuntimeException
277
277
 
278
278
  ---
279
279
 
280
- ## DeepSeek Harness 使用建议
280
+ ## 常见问题
281
281
 
282
- - **加载与引用**:用 `skill("opengis-utils-for-java")` 加载(用户也可输入 `/opengis-utils-for-java`);`reference/common-tasks.md` 按需 `read`,路径相对加载结果中的 Base directory;技能目录只读,验证工程建在会话工作区。
283
- - **执行环境**:先 `java -version` 与 `mvn -version`(需 JDK 17+、Maven 3.8+),Windows 用 `pwsh`;`mvn -v` 里显示的 JDK 才是 Maven 实际使用的,与 shell 的 `java` 不一致时改 `JAVA_HOME` 再重试。
284
- - **源码安装(本库未发布到 Central)**:`git clone https://github.com/znlgis/opengis-utils-for-java.git` 后 `mvn install -DskipTests`,产物落在 `~/.m2/repository/com/znlgis/ogu4j/ogu4j/1.0.0/`;用 `mvn dependency:tree -Dincludes=com.znlgis.ogu4j` 确认坐标可解析。不要在 `pom.xml` 里直接写 `ogu4j:1.0.0` 后指望从 Central 下载。
285
- - **仓库与网络**:GeoTools 依赖不在 Central,`pom.xml` 必须带 `https://repo.osgeo.org/repository/release/`,否则 `Could not resolve dependencies for org.geotools:*`;离线或私服缺包时如实报告依赖不可下载,不要自行换版本或加未知仓库。
286
- - **原生 GDAL 匹配**:GDAL 引擎绑定 `org.gdal:gdal` 3.13.0,本机需装 GDAL 3.13.x 且 `java.library.path` 能找到 `gdal_jni`(Windows 上 `java -XshowSettings:properties -version 2>&1 | Select-String library.path`);报 `UnsatisfiedLinkError: no gdal_jni in java.library.path` 说明原生库缺失或版本不符,此时改用 `GisEngineType.GEOTOOLS`。
287
- - **验证产物**:写最小 main 读一个 Shapefile/GeoJSON → `OguLayerUtil.readLayer(DataFormatType.SHP, path, null, null, null, GisEngineType.AUTO)`,打印 `layer.getWkid()`、`layer.getFeatureCount()`,再 `writeLayer` 成 GeoJSON 并重新读回比对要素数与 CRS;`mvn -q -DskipTests package` 只说明能编译。
288
- - **常见误操**:`AUTO` 在本机有原生 GDAL 时会优先走 GDAL,想复现纯 Java 结果必须显式传 `GisEngineType.GEOTOOLS`;`OguFeature.geometry` 是 WKT 字符串,做运算前先 `GeometryUtil.wkt2Geometry()`;`DataStore` 与 OGR `DataSource` 要在 `finally` 里释放,否则文件被占用后 `writeLayer` 覆盖失败。
289
- - **安全与权限**:PostGIS 连接串(`PG: host=... password=...`)里的密码不要回显到输出;`mvn install` 会写 `~/.m2`、示例代码会写 `/data` 等绝对路径,覆盖已有数据前先确认路径并征得用户同意。
282
+ | 问题 | 解决 |
283
+ |------|------|
284
+ | `mvn install` 依赖解析失败 | 配置 osgeo 仓库(GeoTools 依赖不在 Maven Central);确认 Maven 3.8+ 与 JDK 17+ |
285
+ | 找不到 `com.znlgis.ogu4j:ogu4j` 依赖 | 该库尚未发布到 Maven Central,先在本仓库执行 `mvn install` 安装到本地仓库 |
286
+ | 运行时报 GDAL 相关 `UnsatisfiedLinkError` | 本地缺少与 `org.gdal:gdal` 3.13.0 匹配的原生 GDAL;安装 GDAL 3.13.x,或改用 `GisEngineType.GEOTOOLS` |
287
+ | FileGDB 读写失败 | FileGDB 仅 GDAL 引擎支持:安装原生 GDAL 并使用 `GisEngineType.GDAL` 或 `AUTO` |
288
+ | Shapefile 字段名被截断 | DBF 规范限制 10 字符,使用 `ShpUtil.formatFieldName()` 自动截断 |
289
+ | PostGIS 连接失败 | 检查连接串格式(`PG: host=... port=... dbname=... user=... password=... active_schema=...`)与 schema 名称 |
290
290
 
291
- ## Important Notes for AI Developers
291
+ ---
292
+
293
+ ## AI 编码约定
292
294
 
293
295
  1. **Always use `OguLayerUtil` as the primary entry point** for reading/writing GIS data. It handles engine selection and format routing.
294
296
 
@@ -330,28 +332,9 @@ RuntimeException
330
332
 
331
333
  ---
332
334
 
333
- ## 常见问题
335
+ ## 典型工作流
334
336
 
335
- | 问题 | 解决 |
336
- |------|------|
337
- | `mvn install` 依赖解析失败 | 配置 osgeo 仓库(GeoTools 依赖不在 Maven Central);确认 Maven 3.8+ 与 JDK 17+ |
338
- | 找不到 `com.znlgis.ogu4j:ogu4j` 依赖 | 该库尚未发布到 Maven Central,先在本仓库执行 `mvn install` 安装到本地仓库 |
339
- | 运行时报 GDAL 相关 `UnsatisfiedLinkError` | 本地缺少与 `org.gdal:gdal` 3.13.0 匹配的原生 GDAL;安装 GDAL 3.13.x,或改用 `GisEngineType.GEOTOOLS` |
340
- | FileGDB 读写失败 | FileGDB 仅 GDAL 引擎支持:安装原生 GDAL 并使用 `GisEngineType.GDAL` 或 `AUTO` |
341
- | Shapefile 字段名被截断 | DBF 规范限制 10 字符,使用 `ShpUtil.formatFieldName()` 自动截断 |
342
- | PostGIS 连接失败 | 检查连接串格式(`PG: host=... port=... dbname=... user=... password=... active_schema=...`)与 schema 名称 |
343
-
344
- ---
345
-
346
- ## 相关技能
347
-
348
- - **geotools** — Java GIS 工具库:[../geotools/SKILL.md](../geotools/SKILL.md)
349
- - **jts** — JTS Topology Suite:[../jts/SKILL.md](../jts/SKILL.md)
350
- - **geometry-api-java** — Esri Geometry API:[../geometry-api-java/SKILL.md](../geometry-api-java/SKILL.md)
351
- - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
352
- - **gdal-api** — GDAL 编程 API:[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
353
-
354
- ## 典型工作流示例
337
+ 以「Shapefile → 面积筛选 → 缓冲 → 投影 → GeoJSON」为例:输入 `/data/parcels.shp`(EPSG:4326),输出 `/data/output.geojson`(EPSG:4528)。
355
338
 
356
339
  ```java
357
340
  import com.znlgis.ogu4j.datasource.OguLayerUtil;
@@ -388,8 +371,38 @@ OguLayerUtil.writeLayer(
388
371
  DataFormatType.GEOJSON, projected,
389
372
  "/data/output.geojson", null, null, GisEngineType.AUTO
390
373
  );
374
+
375
+ // Step 6: 回读验证——要素数与 CRS 必须与预期一致,否则说明引擎或投影没生效
376
+ OguLayer check = OguLayerUtil.readLayer(
377
+ DataFormatType.GEOJSON, "/data/output.geojson",
378
+ null, null, null, GisEngineType.AUTO
379
+ );
380
+ System.out.println(check.getWkid() + " / " + check.getFeatureCount());
391
381
  ```
392
382
 
383
+ **验收**:`mvn -q -DskipTests package` 只说明能编译;实际运行上面的 main,打印的 WKID 应为 4528、要素数等于筛选后数量,`output.geojson` 用 `ogrinfo -so` 复查一遍。
384
+
385
+ ---
386
+
387
+ ## AI 使用建议
388
+
389
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/common-tasks.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
390
+ - **执行环境**:先 `java -version` 与 `mvn -version`(需 JDK 17+、Maven 3.8+),Windows 用 PowerShell;`mvn -v` 里显示的 JDK 才是 Maven 实际使用的,与 shell 的 `java` 不一致时改 `JAVA_HOME` 再重试。
391
+ - **源码安装(本库未发布到 Central)**:`git clone https://github.com/znlgis/opengis-utils-for-java.git` 后 `mvn install -DskipTests`,产物落在 `~/.m2/repository/com/znlgis/ogu4j/ogu4j/1.0.0/`;用 `mvn dependency:tree -Dincludes=com.znlgis.ogu4j` 确认坐标可解析。不要在 `pom.xml` 里直接写 `ogu4j:1.0.0` 后指望从 Central 下载。
392
+ - **仓库与网络**:GeoTools 依赖不在 Central,`pom.xml` 必须带 `https://repo.osgeo.org/repository/release/`,否则 `Could not resolve dependencies for org.geotools:*`;离线或私服缺包时如实报告依赖不可下载,不要自行换版本或加未知仓库。
393
+ - **原生 GDAL 匹配**:GDAL 引擎绑定 `org.gdal:gdal` 3.13.0,本机需装 GDAL 3.13.x 且 `java.library.path` 能找到 `gdal_jni`(Windows 上 `java -XshowSettings:properties -version 2>&1 | Select-String library.path`);报 `UnsatisfiedLinkError: no gdal_jni in java.library.path` 说明原生库缺失或版本不符,此时改用 `GisEngineType.GEOTOOLS`。
394
+ - **验证产物**:写最小 main 读一个 Shapefile/GeoJSON → `OguLayerUtil.readLayer(DataFormatType.SHP, path, null, null, null, GisEngineType.AUTO)`,打印 `layer.getWkid()`、`layer.getFeatureCount()`,再 `writeLayer` 成 GeoJSON 并重新读回比对要素数与 CRS;`mvn -q -DskipTests package` 只说明能编译。
395
+ - **常见误操**:`AUTO` 在本机有原生 GDAL 时会优先走 GDAL,想复现纯 Java 结果必须显式传 `GisEngineType.GEOTOOLS`;`OguFeature.geometry` 是 WKT 字符串,做运算前先 `GeometryUtil.wkt2Geometry()`;`DataStore` 与 OGR `DataSource` 要在 `finally` 里释放,否则文件被占用后 `writeLayer` 覆盖失败。
396
+ - **安全与权限**:PostGIS 连接串(`PG: host=... password=...`)里的密码不要回显到输出;`mvn install` 会写 `~/.m2`、示例代码会写 `/data` 等绝对路径,覆盖已有数据前先确认路径并征得用户同意。
397
+
398
+ ## 相关技能
399
+
400
+ - **geotools** — Java GIS 工具库:[../geotools/SKILL.md](../geotools/SKILL.md)
401
+ - **jts** — JTS Topology Suite:[../jts/SKILL.md](../jts/SKILL.md)
402
+ - **geometry-api-java** — Esri Geometry API:[../geometry-api-java/SKILL.md](../geometry-api-java/SKILL.md)
403
+ - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
404
+ - **gdal-api** — GDAL 编程 API:[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
405
+
393
406
  ## 参考资源
394
407
 
395
408
  - **GitHub 仓库:** <https://github.com/znlgis/opengis-utils-for-java>
@@ -1,12 +1,12 @@
1
- # OpenGIS Utils for Java Common Tasks Reference
1
+ # OpenGIS Utils for Java 常用任务参考
2
2
 
3
- Common task quick reference split from SKILL.md.
3
+ 从 SKILL.md 拆出的常用任务速查,Java 版本按 OGU4J 1.0.0 编写。
4
4
 
5
5
  ---
6
6
 
7
- ## Quick Reference: Common Tasks
7
+ ## 常用任务速查
8
8
 
9
- ### 1. Read a GIS Layer (Shapefile / GeoJSON / PostGIS / FileGDB / TXT)
9
+ ### 1. 读取图层(Shapefile / GeoJSON / PostGIS / FileGDB / TXT)
10
10
 
11
11
  ```java
12
12
  import com.znlgis.ogu4j.datasource.OguLayerUtil;
@@ -48,7 +48,7 @@ import com.znlgis.ogu4j.datasource.GtTxtUtil;
48
48
  OguLayer layer = GtTxtUtil.loadTxt("/path/to/file.txt", null); // null = auto-detect fields
49
49
  ```
50
50
 
51
- ### 2. Write a GIS Layer
51
+ ### 2. 写出图层
52
52
 
53
53
  ```java
54
54
  import com.znlgis.ogu4j.datasource.OguLayerUtil;
@@ -93,7 +93,7 @@ metadata.setMeasureUnit("米");
93
93
  GtTxtUtil.saveTxt(layer, "/path/to/output.txt", metadata, null, 39);
94
94
  ```
95
95
 
96
- ### 3. Format Conversion (One-Step)
96
+ ### 3. 格式转换(一步完成)
97
97
 
98
98
  ```java
99
99
  // SHP → GeoJSON
@@ -105,7 +105,7 @@ OguLayer layer = OguLayerUtil.readLayer(DataFormatType.GEOJSON, geojsonPath, nul
105
105
  OguLayerUtil.writeLayer(DataFormatType.POSTGIS, layer, connStr, "tableName", null, GisEngineType.AUTO);
106
106
  ```
107
107
 
108
- ### 4. Work with the Layer Model
108
+ ### 4. 使用图层模型
109
109
 
110
110
  ```java
111
111
  import com.znlgis.ogu4j.engine.model.layer.*;
@@ -157,7 +157,7 @@ int featureCount = layer.getFeatureCount();
157
157
  int fieldCount = layer.getFieldCount();
158
158
  ```
159
159
 
160
- ### 5. Geometry Operations (GeometryUtil)
160
+ ### 5. 几何运算(GeometryUtil)
161
161
 
162
162
  ```java
163
163
  import com.znlgis.ogu4j.geometry.GeometryUtil;
@@ -241,7 +241,7 @@ boolean norm = GeometryUtil.equalsNorm(geomA, geomB);
241
241
  boolean topo = GeometryUtil.equalsTopo(geomA, geomB);
242
242
  ```
243
243
 
244
- ### 6. WKT-Based Geometry Operations (ESRI Geometry API)
244
+ ### 6. 基于 WKT 的几何运算(ESRI Geometry API)
245
245
 
246
246
  These methods work directly with WKT strings, without creating JTS Geometry objects. Useful when geometry data is in WKT format. Method names end with `Wkt`.
247
247
 
@@ -280,7 +280,7 @@ boolean simple = GeometryUtil.isSimpleWkt(wkt, 4490);
280
280
  String simplified = GeometryUtil.simplifyWkt(wkt, 4490);
281
281
  ```
282
282
 
283
- ### 7. Coordinate Reference System (CrsUtil)
283
+ ### 7. 坐标参考系(CrsUtil)
284
284
 
285
285
  ```java
286
286
  import com.znlgis.ogu4j.engine.util.CrsUtil;
@@ -317,7 +317,7 @@ Map<Integer, CoordinateReferenceSystem> crsList = CrsUtil.getSupportedCRSList();
317
317
  Map.Entry<Integer, CoordinateReferenceSystem> entry = CrsUtil.getSupportedCRS(4490);
318
318
  ```
319
319
 
320
- ### 8. Engine API (Advanced Usage)
320
+ ### 8. 引擎 API(高级用法)
321
321
 
322
322
  ```java
323
323
  import com.znlgis.ogu4j.engine.*;
@@ -343,7 +343,7 @@ OguLayer layer = reader.read(path, layerName, attrFilter, spatialFilterWkt);
343
343
  writer.write(layer, path, layerName, options);
344
344
  ```
345
345
 
346
- ### 9. Utility Classes
346
+ ### 9. 工具类
347
347
 
348
348
  ```java
349
349
  // ZIP operations
@@ -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
43
45
  ```
44
46
 
45
- ## Build & Test
47
+ ### 方式二:手写 csproj 的 PackageReference
48
+
49
+ ```xml
50
+ <ItemGroup>
51
+ <PackageReference Include="OpenGIS.Utils" Version="1.1.2" />
52
+ </ItemGroup>
53
+ ```
54
+
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
- ## DeepSeek Harness 使用建议
371
-
372
- - **加载与引用**:用 `skill("opengis-utils-for-net")` 加载(用户也可输入 `/opengis-utils-for-net`);`reference/code-patterns.md`、`reference/util-classes.md` 按需 `read`,路径相对加载结果中的 Base directory;技能目录只读,验证工程建在会话工作区。
373
- - **执行环境**:先 `dotnet --version`;库目标 .NET Standard 2.0,可被 .NET Core 2.0+ / .NET 5+ / .NET Framework 4.6.1+ 引用,Windows 用 `pwsh`;用 `dotnet new console -o demo && cd demo` 起最小工程。
374
- - **依赖坐标**:`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` 表示源或版本不可用,如实报告而不是改版本号重试。
375
- - **平台与原生库**:运行时与 RID 绑定,`DllNotFoundException` 或 `Unable to load DLL 'gdal'` 多因 `-r win-x64`/`linux-x64` 与运行环境不一致;`dotnet publish -r win-x64` 后跑发布目录,不要只跑 `bin/Debug` 里的半成品。
376
- - **验证产物**:最小程序 `OguLayerUtil.ReadLayer(DataFormatType.SHP, path)` 读入(完整重载见 `reference/code-patterns.md`)→ 打印 `layer.GetFeatureCount()` 与 `layer.Wkid`,再 `WriteLayer` 写出 GeoJSON 并重新读回,核对要素数与 CRS;`dotnet build` 成功只说明编译通过,GDAL 原生库是运行期才加载的。
377
- - **常见误操**:`Geojson2Wkt()` 只接受裸几何 / `Feature` / `FeatureCollection` 字符串,传整文件内容会抛 `ArgumentException`,整文件走 `OguLayerUtil.ReadLayer`;`OgrGeometry` 是 `IDisposable`,用完 `Dispose()`;`GEOTOOLS` 枚举仅为兼容,在 .NET 版实际重定向到 GDAL。
378
- - **构建与测试**:在仓库 checkout 内 `dotnet build OpenGIS.Utils.sln`、`dotnet test tests/OpenGIS.Utils.Tests/`,输出在 `bin/`、`obj/`(不要提交);只看某一条测试时加 `--filter FullyQualifiedName~关键字`。
379
- - **安全与权限**:写入 Shapefile/GeoPackage 会覆盖同名文件,执行前确认目标路径;PostGIS 连接串与 GDAL 配置里的密码不要回显;`dotnet restore`、安装 SDK 或改 `NuGet.config` 前先征得用户同意。
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;