@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
  # OpenGIS Data Pipeline Stages Reference
2
2
 
3
- Stage 1 (data acquisition/query), stage 2 (processing/conversion) and stage 4 (GeoServer publishing) split from SKILL.md.
3
+ Stage 1 (data acquisition/query), stage 2 (processing/conversion), stage 3 (spatial analysis) and stage 4 (GeoServer publishing) split from SKILL.md.
4
4
 
5
5
  ---
6
6
 
@@ -435,6 +435,267 @@ gdal_edit.py -mo DATUM=WGS84 -mo SOURCE=USGS input.tif
435
435
 
436
436
  ---
437
437
 
438
+ ## 阶段三:空间分析
439
+
440
+ ### 3.1 缓冲区分析
441
+
442
+ ```bash
443
+ # qgis_process
444
+ qgis_process run native:buffer -- \
445
+ INPUT=points.shp DISTANCE=1000 SEGMENTS=16 OUTPUT=buffered.gpkg
446
+ ```
447
+
448
+ ```python
449
+ # PyQGIS (processing)
450
+ result = processing.run("native:buffer", {
451
+ 'INPUT': '/data/roads.shp',
452
+ 'DISTANCE': 50,
453
+ 'SEGMENTS': 10,
454
+ 'DISSOLVE': False,
455
+ 'OUTPUT': '/data/roads_buffer.shp'
456
+ })
457
+ ```
458
+
459
+ ```python
460
+ # PyQGIS (几何操作)
461
+ buffered = geom.buffer(100, 16)
462
+ ```
463
+
464
+ ```python
465
+ # GDAL Python API (OGR 几何)
466
+ from osgeo import ogr
467
+ pt = ogr.Geometry(ogr.wkbPoint)
468
+ pt.SetPoint_2D(0, 116.4, 39.9)
469
+ buffer = pt.Buffer(1.0)
470
+ ```
471
+
472
+ ### 3.2 叠加分析(交集/联合/差集)
473
+
474
+ ```bash
475
+ # qgis_process — 交集
476
+ qgis_process run native:intersection -- \
477
+ INPUT=layer1.shp OVERLAY=layer2.shp OUTPUT=intersection.shp
478
+
479
+ # qgis_process — 联合
480
+ qgis_process run native:union -- \
481
+ INPUT=layer1.shp OVERLAY=layer2.shp OUTPUT=union.shp
482
+
483
+ # qgis_process — 差集
484
+ qgis_process run native:difference -- \
485
+ INPUT=layer1.shp OVERLAY=layer2.shp OUTPUT=difference.shp
486
+ ```
487
+
488
+ ```python
489
+ # PyQGIS
490
+ result = processing.run("native:intersection", {
491
+ 'INPUT': layer1, 'OVERLAY': layer2, 'OUTPUT': 'memory:intersected'
492
+ })
493
+ ```
494
+
495
+ ```python
496
+ # PyQGIS 几何级别操作
497
+ intersection = geom1.intersection(geom2)
498
+ union = geom1.combine(geom2)
499
+ difference = geom1.difference(geom2)
500
+ sym_diff = geom1.symDifference(geom2)
501
+ ```
502
+
503
+ ```python
504
+ # GDAL OGR 几何级别操作
505
+ inter = polygon.Intersection(pt)
506
+ united = polygon.Union(pt)
507
+ diff = polygon.Difference(pt)
508
+ ```
509
+
510
+ ### 3.3 融合(Dissolve)
511
+
512
+ ```bash
513
+ # qgis_process
514
+ qgis_process run native:dissolve -- \
515
+ INPUT=polygons.shp FIELD=type OUTPUT=dissolved.gpkg
516
+ ```
517
+
518
+ ```python
519
+ # PyQGIS
520
+ result = processing.run("native:dissolve", {
521
+ 'INPUT': '/data/polygons.shp',
522
+ 'FIELD': ['type'],
523
+ 'OUTPUT': '/data/dissolved.gpkg'
524
+ })
525
+ ```
526
+
527
+ ### 3.4 空间连接
528
+
529
+ ```bash
530
+ # qgis_process — 按位置连接属性
531
+ qgis_process run native:joinattributesbylocation -- \
532
+ INPUT=points.shp JOIN=polygons.shp PREDICATE=0 OUTPUT=joined.shp
533
+ ```
534
+
535
+ ```python
536
+ # PyQGIS
537
+ result = processing.run("native:joinattributesbylocation", {
538
+ 'INPUT': points_layer,
539
+ 'JOIN': polygons_layer,
540
+ 'PREDICATE': [0], # 0=相交
541
+ 'METHOD': 0, # 0=一对一
542
+ 'OUTPUT': 'memory:joined'
543
+ })
544
+ ```
545
+
546
+ ### 3.5 栅格计算(波段运算)
547
+
548
+ ```bash
549
+ # NDVI 计算
550
+ gdal_calc.py -A nir.tif -B red.tif \
551
+ --calc="(A-B)/(A+B)" --outfile=ndvi.tif
552
+
553
+ # 栅格掩膜
554
+ gdal_calc.py -A input.tif --calc="A*(A>100)" \
555
+ --outfile=masked.tif --NoDataValue=0
556
+
557
+ # 两个栅格平均
558
+ gdal_calc.py -A input1.tif -B input2.tif \
559
+ --calc="(A+B)/2" --outfile=mean.tif
560
+ ```
561
+
562
+ ### 3.6 DEM 分析
563
+
564
+ ```bash
565
+ # 等值线提取
566
+ gdal_contour -a elevation dem.tif contours.shp -i 10
567
+
568
+ # qgis_process — 坡度分析
569
+ qgis_process run gdal:slope -- INPUT=dem.tif OUTPUT=slope.tif
570
+
571
+ # qgis_process — 坡向分析
572
+ qgis_process run gdal:aspect -- INPUT=dem.tif OUTPUT=aspect.tif
573
+
574
+ # qgis_process — 山体阴影
575
+ qgis_process run gdal:hillshade -- INPUT=dem.tif OUTPUT=hillshade.tif
576
+ ```
577
+
578
+ ```python
579
+ # PyQGIS — 坡度分析
580
+ result = processing.run("gdal:slope", {
581
+ 'INPUT': '/data/dem.tif',
582
+ 'OUTPUT': '/data/slope.tif'
583
+ })
584
+ ```
585
+
586
+ ### 3.7 散点插值(创建 DEM)
587
+
588
+ ```bash
589
+ # 反距离加权(IDW)插值
590
+ gdal_grid -a invdist:power=2:smoothing=0 \
591
+ -zfield Z input_points.shp output_dem.tif
592
+
593
+ # 指定输出范围和分辨率
594
+ gdal_grid -outsize 512 512 -tr 10 10 \
595
+ -a average input_points.shp output_dem.tif
596
+ ```
597
+
598
+ ### 3.8 栅格矢量互转
599
+
600
+ ```bash
601
+ # 栅格转矢量(多边形化)
602
+ gdal_polygonize.py input.tif output.shp
603
+
604
+ # qgis_process
605
+ qgis_process run gdal:polygonize -- INPUT=input.tif OUTPUT=output.shp
606
+
607
+ # 矢量转栅格
608
+ qgis_process run gdal:rasterize -- \
609
+ INPUT=input.shp FIELD=value OUTPUT=output.tif
610
+ ```
611
+
612
+ ### 3.9 空间查询与过滤
613
+
614
+ ```bash
615
+ # ogr2ogr — 属性过滤
616
+ ogr2ogr output.shp input.shp -where "population > 1000000"
617
+
618
+ # ogr2ogr — 空间过滤
619
+ ogr2ogr output.shp input.shp -spat 116.0 39.5 117.0 40.5
620
+
621
+ # qgis_process — 按属性提取
622
+ qgis_process run native:extractbyattribute -- \
623
+ INPUT=input.shp FIELD=type OPERATOR=0 VALUE=road OUTPUT=roads.shp
624
+
625
+ # qgis_process — 按位置提取
626
+ qgis_process run native:extractbylocation -- \
627
+ INPUT=points.shp INTERSECT=boundary.shp PREDICATE=0 OUTPUT=extracted.shp
628
+ ```
629
+
630
+ ```python
631
+ # PyQGIS — 要素查询
632
+ from qgis.core import QgsFeatureRequest, QgsRectangle
633
+
634
+ # 属性过滤
635
+ request = QgsFeatureRequest().setFilterExpression('"population" > 10000')
636
+ for feature in layer.getFeatures(request):
637
+ print(feature["name"])
638
+
639
+ # 空间范围过滤
640
+ rect = QgsRectangle(116.0, 39.0, 117.0, 40.0)
641
+ request = QgsFeatureRequest().setFilterRect(rect)
642
+ for feature in layer.getFeatures(request):
643
+ print(feature.id())
644
+ ```
645
+
646
+ ```python
647
+ # GDAL Python API — 空间过滤 + 属性过滤
648
+ from osgeo import ogr
649
+
650
+ ds = ogr.Open("input.shp")
651
+ layer = ds.GetLayer(0)
652
+ layer.SetSpatialFilterRect(116.0, 39.5, 117.0, 40.5)
653
+ layer.SetAttributeFilter("POPULATION > 1000000")
654
+
655
+ for feature in layer:
656
+ print(feature.GetField("NAME"))
657
+ ds = None
658
+ ```
659
+
660
+ ### 3.10 地图渲染与导出
661
+
662
+ ```python
663
+ # PyQGIS — 渲染为 PNG
664
+ from qgis.core import QgsMapSettings, QgsMapRendererSequentialJob
665
+ from qgis.PyQt.QtCore import QSize
666
+
667
+ settings = QgsMapSettings()
668
+ settings.setLayers([layer])
669
+ settings.setDestinationCrs(layer.crs())
670
+ settings.setExtent(layer.extent())
671
+ settings.setOutputSize(QSize(1920, 1080))
672
+
673
+ job = QgsMapRendererSequentialJob(settings)
674
+ job.start()
675
+ job.waitForFinished()
676
+ job.renderedImage().save("/data/map_output.png")
677
+ ```
678
+
679
+ ```python
680
+ # PyQGIS — 导出 PDF
681
+ from qgis.core import QgsProject, QgsPrintLayout, QgsLayoutItemMap, QgsLayoutExporter
682
+
683
+ project = QgsProject.instance()
684
+ layout = QgsPrintLayout(project)
685
+ layout.initializeDefaults()
686
+
687
+ map_item = QgsLayoutItemMap(layout)
688
+ map_item.setRect(20, 20, 200, 150)
689
+ map_item.setExtent(layer.extent())
690
+ map_item.setLayers([layer])
691
+ layout.addLayoutItem(map_item)
692
+
693
+ exporter = QgsLayoutExporter(layout)
694
+ exporter.exportToPdf("/data/output.pdf", QgsLayoutExporter.PdfExportSettings())
695
+ ```
696
+
697
+ ---
698
+
438
699
  ## 阶段四:发布 GIS 地图服务(GeoServer REST API)
439
700
 
440
701
  **基础 URL:** `http://{host}:{port}/geoserver/rest`
@@ -603,6 +864,3 @@ curl -u admin:geoserver -XPOST \
603
864
  | 清空图层缓存 | POST | `/gwc/rest/seed/{layer}.json` |
604
865
  | 查看缓存任务 | GET | `/gwc/rest/seed/{layer}.json` |
605
866
  | 批量截断 | POST | `/gwc/rest/masstruncate` |
606
-
607
- ---
608
-
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: opengis-daf
3
- description: "Use when building plan-driven GIS data analysis or data quality-check pipelines with OpenGisDAF (.NET 10 / C# 14): define buffer, clip, intersect/containment checks, coordinate transform, field calculator, attribute/geometry QC rules purely in JSON plans, run the daf CLI, chain operators via DAG upstream bindings, output to GeoJSON/Shapefile/PostGIS, or extend with plugin operators loaded via AssemblyLoadContext."
3
+ description: "Use when building JSON-plan GIS analysis or QC pipelines with OpenGisDAF (.NET 10 / C# 14) — daf validate/run, operators buffer/clip/intersect_check/containment_check/coordinate_transform, DAG upstream bindings, GeoJSON/Shapefile/PostGIS sinks, qcMode QC reports, AssemblyLoadContext plugins; also for \"zero tests ran\" exit code 5, missing --recurse-submodules GDAL build errors, or PostGIS Layer already exists. Plan-driven ETL."
4
4
 
5
5
  tags:
6
6
  - gis
@@ -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
 
@@ -239,17 +241,13 @@ dotnet demo/plugin/OpenGisDAF.PluginHostDemo/bin/Release/net10.0/OpenGisDAF.Plug
239
241
 
240
242
  ## AI 使用建议
241
243
 
242
- ### 推荐工作流
243
-
244
- 1. **先读文档与 Demo**:优先阅读 `docs/quickstart.md`、`docs/plan-config-guide.md`、`docs/operator-reference.md`、`docs/cli-reference.md`,并对照 `demo/`(`demo/run-demo.ps1` / `run-demo.sh`)理解方案结构
245
- 2. **先校验、再质检、后分析**:先用 `daf validate --plan <path>` 校验 21 条规则,再用 `qcMode: true` 的质检方案生成 `{plan}.qc-report.json` 修复数据,最后跑分析方案
246
- 3. **串联用 upstream**:多步流程用 `InputBinding.type: "upstream"` 引用上游 item 输出,由 DAG 自动拓扑排序调度
247
-
248
- ### 关键注意事项
249
-
250
- - **核心概念**:方案(AnalysisPlan)由 `items[]`(每项一次算子调用)与 `inputs`/`parameters`/`output` 组成,算子通过 `upstream` 绑定串成 DAG
251
- - **常见错误**:插件目录勿复制 `OpenGisDAF.Core.dll`(Type 不同源会被静默跳过);`buffer` 单位与数据坐标系一致(度数坐标系需先 `coordinate_transform` 转米制投影);PostGIS 目标表已存在会报错,绝不静默覆盖
252
- - **退出码**:`0` 成功、`1` 任何失败或跳过,便于 CI 判断
244
+ - **执行环境**:先 `dotnet --version`,必须是 **10.0**(仓库 `global.json` 锁定),Windows 用 PowerShell;克隆必须 `git clone --recurse-submodules`,漏了子模块 `opengis-utils-for-net` 会在编译期报 GDAL 绑定类型缺失。
245
+ - **源码构建(无 NuGet 包)**:`dotnet build` 或 `./build.sh`,再 `dotnet run --project src/OpenGisDAF.Cli -- help` 确认 CLI 可用;这是自有项目,不要写 `dotnet add package OpenGisDAF`。
246
+ - **测试两步走**:`dotnet build OpenGisDAF.slnx -c Release` 后 `dotnet test OpenGisDAF.slnx -c Release --no-build`——同一条 `dotnet test` 在 xunit.v3 工具链下会报“运行了零个测试”并以退出码 5 失败。
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` 才生成)。
248
+ - **典型误操**:`buffer` 的 `distance` 单位随数据坐标系(EPSG:4326 下 800 就是 800 度),先 `coordinate_transform` 转米制;`daf operator import` 只对当前进程有效,要让插件参与 `daf run` 必须用同进程宿主(`demo/plugin/OpenGisDAF.PluginHostDemo`)。
249
+ - **插件坑**:插件工程引用 `OpenGisDAF.Core` 时必须 `Private="false" ExcludeAssets="runtime"`,把 `OpenGisDAF.Core.dll` 复制进插件目录会让 `IOperator` 类型不同源,算子被静默跳过。
250
+ - **安全与权限**:PostGIS 输出的 `encryptedPassword` 只接受当前用户上下文生成的密文(DPAPI / AES-256-GCM),明文或跨用户密文会失败;`daf plan` 写入 `%APPDATA%\opengis-daf\plans`,覆盖已有方案或输出文件前先确认路径。
253
251
 
254
252
  ---
255
253
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: opengis-utils-for-java
3
- description: "Use when needing common GIS utility functions in Java — CRS utilities, geometry helpers, format converters, spatial validation. OpenGIS Utils for Java: convenience toolkit for Java GIS projects."
3
+ description: "Use when needing common GIS utilities in Java — OguLayerUtil layer read/write, GeometryUtil 60+ ops, CrsUtil CGCS2000 (EPSG:4490, 4502-4554), Shapefile/GeoJSON/FileGDB/PostGIS/land TXT I/O, topology validation; also for GDAL UnsatisfiedLinkError on gdal_jni, missing osgeo repo on GeoTools, or resolving com.znlgis.ogu4j:ogu4j:1.0.0 that is not on Maven Central. OGU4J."
4
4
  tags:
5
5
  - java
6
6
  - gis
@@ -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,26 +277,20 @@ RuntimeException
277
277
 
278
278
  ---
279
279
 
280
- ## AI 使用建议
281
-
282
- ### 推荐工作流
283
-
284
- 1. **选择引擎**:`GisEngineType.AUTO` 自动选择最优引擎(GDAL 优先)
285
- 2. **读取数据**:使用 `OguLayerUtil.readLayer()` 统一入口读取各类矢量格式
286
- 3. **空间分析**:JTS Geometry 对象用 `GeometryUtil`(60+ 方法),WKT 字符串用 `*Wkt` 后缀方法
287
- 4. **坐标转换**:使用 `CrsUtil.transform()` 进行 CGCS2000 系列坐标系变换
288
- 5. **写出结果**:使用 `OguLayerUtil.writeLayer()` 写出为目标格式
280
+ ## 常见问题
289
281
 
290
- ### 关键注意事项
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 名称 |
291
290
 
292
- - **始终使用 `OguLayerUtil` 作为主入口**:自动处理引擎选择和格式路由
293
- - **几何以 WKT 存储**:`OguFeature.geometry` 存储 WKT 字符串;空间运算时转为 JTS Geometry
294
- - **引擎选择**:`GEOTOOLS`(纯 Java,无原生依赖)vs `GDAL`(需本地库,支持 FileGDB)
295
- - **CGCS2000 坐标系**:EPSG:4490 为默认地理 CRS,投影 CRS 范围 EPSG:4502-4554
296
- - **Shapefile 字段名限 10 字符**:使用 `ShpUtil.formatFieldName()` 自动截断
297
- - **资源释放**:`DataStore` 和 OGR `DataSource` 必须在 finally 块中释放
291
+ ---
298
292
 
299
- ## Important Notes for AI Developers
293
+ ## AI 编码约定
300
294
 
301
295
  1. **Always use `OguLayerUtil` as the primary entry point** for reading/writing GIS data. It handles engine selection and format routing.
302
296
 
@@ -338,28 +332,9 @@ RuntimeException
338
332
 
339
333
  ---
340
334
 
341
- ## 常见问题
342
-
343
- | 问题 | 解决 |
344
- |------|------|
345
- | `mvn install` 依赖解析失败 | 配置 osgeo 仓库(GeoTools 依赖不在 Maven Central);确认 Maven 3.8+ 与 JDK 17+ |
346
- | 找不到 `com.znlgis.ogu4j:ogu4j` 依赖 | 该库尚未发布到 Maven Central,先在本仓库执行 `mvn install` 安装到本地仓库 |
347
- | 运行时报 GDAL 相关 `UnsatisfiedLinkError` | 本地缺少与 `org.gdal:gdal` 3.13.0 匹配的原生 GDAL;安装 GDAL 3.13.x,或改用 `GisEngineType.GEOTOOLS` |
348
- | FileGDB 读写失败 | FileGDB 仅 GDAL 引擎支持:安装原生 GDAL 并使用 `GisEngineType.GDAL` 或 `AUTO` |
349
- | Shapefile 字段名被截断 | DBF 规范限制 10 字符,使用 `ShpUtil.formatFieldName()` 自动截断 |
350
- | PostGIS 连接失败 | 检查连接串格式(`PG: host=... port=... dbname=... user=... password=... active_schema=...`)与 schema 名称 |
351
-
352
- ---
353
-
354
- ## 相关技能
335
+ ## 典型工作流
355
336
 
356
- - **geotools** — Java GIS 工具库:[../geotools/SKILL.md](../geotools/SKILL.md)
357
- - **jts** — JTS Topology Suite:[../jts/SKILL.md](../jts/SKILL.md)
358
- - **geometry-api-java** — Esri Geometry API:[../geometry-api-java/SKILL.md](../geometry-api-java/SKILL.md)
359
- - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
360
- - **gdal-api** — GDAL 编程 API:[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
361
-
362
- ## 典型工作流示例
337
+ 以「Shapefile → 面积筛选 → 缓冲 → 投影 → GeoJSON」为例:输入 `/data/parcels.shp`(EPSG:4326),输出 `/data/output.geojson`(EPSG:4528)。
363
338
 
364
339
  ```java
365
340
  import com.znlgis.ogu4j.datasource.OguLayerUtil;
@@ -396,8 +371,38 @@ OguLayerUtil.writeLayer(
396
371
  DataFormatType.GEOJSON, projected,
397
372
  "/data/output.geojson", null, null, GisEngineType.AUTO
398
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());
399
381
  ```
400
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
+
401
406
  ## 参考资源
402
407
 
403
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