@dsh-gis/dsh-opengis-skill 0.1.3 → 0.3.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 (117) hide show
  1. package/CHANGELOG.md +95 -0
  2. package/README.md +68 -28
  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 +19 -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 +9 -0
  30. package/adaptations/opengis-daf.md +9 -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 +283 -0
  46. package/assets/cesiumjs/SKILL.md +81 -35
  47. package/assets/deck-gl/SKILL.md +26 -34
  48. package/assets/duckdb-spatial/SKILL.md +363 -0
  49. package/assets/gdal/SKILL.md +55 -33
  50. package/assets/gdal/reference/raster-tools.md +14 -0
  51. package/assets/gdal/reference/vector-tools.md +5 -0
  52. package/assets/gdal-api/SKILL.md +12 -18
  53. package/assets/gdal-api/reference/raster-api.md +7 -0
  54. package/assets/gdal-api/reference/vector-api.md +9 -0
  55. package/assets/geolibre/SKILL.md +357 -0
  56. package/assets/geometry-api-java/SKILL.md +10 -16
  57. package/assets/geometry-api-net/SKILL.md +70 -32
  58. package/assets/geometry-api-net/reference/geometry-types.md +5 -0
  59. package/assets/geonode/SKILL.md +340 -0
  60. package/assets/geopandas/SKILL.md +21 -24
  61. package/assets/geopandas/reference/core-api.md +4 -0
  62. package/assets/geopipe-agent/SKILL.md +29 -31
  63. package/assets/geopipe-agent/reference/steps-reference.md +12 -0
  64. package/assets/geopipe-agent/reference/workflows.md +8 -0
  65. package/assets/geoserver/SKILL.md +10 -15
  66. package/assets/geoserver-cloud/SKILL.md +25 -33
  67. package/assets/geoserver-rest-api/SKILL.md +17 -19
  68. package/assets/geoserver-rest-api/reference/endpoints.md +16 -0
  69. package/assets/geotools/SKILL.md +12 -17
  70. package/assets/geotools/reference/raster-rendering.md +5 -0
  71. package/assets/geotools/reference/vector-io.md +7 -0
  72. package/assets/grass-gis/SKILL.md +26 -33
  73. package/assets/jts/SKILL.md +12 -16
  74. package/assets/jts/reference/geometry-operations.md +13 -0
  75. package/assets/kepler-gl/SKILL.md +306 -0
  76. package/assets/leaflet/SKILL.md +58 -40
  77. package/assets/mapbox-gl-js/SKILL.md +26 -33
  78. package/assets/mapserver/SKILL.md +21 -29
  79. package/assets/mapsui/SKILL.md +109 -63
  80. package/assets/nettopologysuite/SKILL.md +96 -31
  81. package/assets/opengis-all/SKILL.md +91 -289
  82. package/assets/opengis-all/reference/data-stages.md +269 -4
  83. package/assets/opengis-all/reference/workflow-cheatsheets.md +7 -0
  84. package/assets/opengis-daf/SKILL.md +10 -17
  85. package/assets/opengis-utils-for-java/SKILL.md +58 -49
  86. package/assets/opengis-utils-for-java/reference/common-tasks.md +16 -12
  87. package/assets/opengis-utils-for-net/SKILL.md +109 -48
  88. package/assets/opengis-utils-for-net/reference/code-patterns.md +15 -11
  89. package/assets/opengis-utils-for-net/reference/util-classes.md +35 -26
  90. package/assets/openlayers/SKILL.md +81 -28
  91. package/assets/pdal/SKILL.md +25 -27
  92. package/assets/postgis/SKILL.md +80 -35
  93. package/assets/proj/SKILL.md +32 -41
  94. package/assets/projnet4geoapi/SKILL.md +293 -0
  95. package/assets/pyqgis/SKILL.md +33 -30
  96. package/assets/pyqgis/reference/processing-rendering.md +6 -0
  97. package/assets/pyqgis/reference/vector-raster-layers.md +6 -0
  98. package/assets/qgis-process/SKILL.md +75 -33
  99. package/assets/qgis-process/reference/algorithm-cheatsheet.md +6 -0
  100. package/assets/qgis-server/SKILL.md +25 -31
  101. package/assets/shapely/SKILL.md +136 -84
  102. package/assets/shapely/reference/operations-reference.md +12 -0
  103. package/assets/sharpmap/SKILL.md +97 -60
  104. package/assets/spatialite/SKILL.md +358 -0
  105. package/assets/whitebox-tools/SKILL.md +262 -0
  106. package/lib/adaptations.d.ts +53 -0
  107. package/lib/adaptations.js +343 -0
  108. package/lib/catalog.d.ts +7 -1
  109. package/lib/catalog.js +9 -1
  110. package/lib/index.d.ts +10 -1
  111. package/lib/index.js +34 -3
  112. package/lib/skill-file.d.ts +12 -0
  113. package/lib/skill-file.js +133 -18
  114. package/locale/en.json +1 -1
  115. package/locale/zh.json +1 -1
  116. package/package.json +12 -2
  117. package/upstream.json +73 -57
@@ -1,6 +1,13 @@
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
+ ## Contents
4
+
5
+ - 阶段一:数据获取与信息查询
6
+ - 阶段二:数据处理与转换
7
+ - 阶段三:空间分析
8
+ - 阶段四:发布 GIS 地图服务(GeoServer REST API)
9
+
10
+ Stage 1 (data acquisition/query), stage 2 (processing/conversion), stage 3 (spatial analysis) and stage 4 (GeoServer publishing) split from SKILL.md.
4
11
 
5
12
  ---
6
13
 
@@ -435,6 +442,267 @@ gdal_edit.py -mo DATUM=WGS84 -mo SOURCE=USGS input.tif
435
442
 
436
443
  ---
437
444
 
445
+ ## 阶段三:空间分析
446
+
447
+ ### 3.1 缓冲区分析
448
+
449
+ ```bash
450
+ # qgis_process
451
+ qgis_process run native:buffer -- \
452
+ INPUT=points.shp DISTANCE=1000 SEGMENTS=16 OUTPUT=buffered.gpkg
453
+ ```
454
+
455
+ ```python
456
+ # PyQGIS (processing)
457
+ result = processing.run("native:buffer", {
458
+ 'INPUT': '/data/roads.shp',
459
+ 'DISTANCE': 50,
460
+ 'SEGMENTS': 10,
461
+ 'DISSOLVE': False,
462
+ 'OUTPUT': '/data/roads_buffer.shp'
463
+ })
464
+ ```
465
+
466
+ ```python
467
+ # PyQGIS (几何操作)
468
+ buffered = geom.buffer(100, 16)
469
+ ```
470
+
471
+ ```python
472
+ # GDAL Python API (OGR 几何)
473
+ from osgeo import ogr
474
+ pt = ogr.Geometry(ogr.wkbPoint)
475
+ pt.SetPoint_2D(0, 116.4, 39.9)
476
+ buffer = pt.Buffer(1.0)
477
+ ```
478
+
479
+ ### 3.2 叠加分析(交集/联合/差集)
480
+
481
+ ```bash
482
+ # qgis_process — 交集
483
+ qgis_process run native:intersection -- \
484
+ INPUT=layer1.shp OVERLAY=layer2.shp OUTPUT=intersection.shp
485
+
486
+ # qgis_process — 联合
487
+ qgis_process run native:union -- \
488
+ INPUT=layer1.shp OVERLAY=layer2.shp OUTPUT=union.shp
489
+
490
+ # qgis_process — 差集
491
+ qgis_process run native:difference -- \
492
+ INPUT=layer1.shp OVERLAY=layer2.shp OUTPUT=difference.shp
493
+ ```
494
+
495
+ ```python
496
+ # PyQGIS
497
+ result = processing.run("native:intersection", {
498
+ 'INPUT': layer1, 'OVERLAY': layer2, 'OUTPUT': 'memory:intersected'
499
+ })
500
+ ```
501
+
502
+ ```python
503
+ # PyQGIS 几何级别操作
504
+ intersection = geom1.intersection(geom2)
505
+ union = geom1.combine(geom2)
506
+ difference = geom1.difference(geom2)
507
+ sym_diff = geom1.symDifference(geom2)
508
+ ```
509
+
510
+ ```python
511
+ # GDAL OGR 几何级别操作
512
+ inter = polygon.Intersection(pt)
513
+ united = polygon.Union(pt)
514
+ diff = polygon.Difference(pt)
515
+ ```
516
+
517
+ ### 3.3 融合(Dissolve)
518
+
519
+ ```bash
520
+ # qgis_process
521
+ qgis_process run native:dissolve -- \
522
+ INPUT=polygons.shp FIELD=type OUTPUT=dissolved.gpkg
523
+ ```
524
+
525
+ ```python
526
+ # PyQGIS
527
+ result = processing.run("native:dissolve", {
528
+ 'INPUT': '/data/polygons.shp',
529
+ 'FIELD': ['type'],
530
+ 'OUTPUT': '/data/dissolved.gpkg'
531
+ })
532
+ ```
533
+
534
+ ### 3.4 空间连接
535
+
536
+ ```bash
537
+ # qgis_process — 按位置连接属性
538
+ qgis_process run native:joinattributesbylocation -- \
539
+ INPUT=points.shp JOIN=polygons.shp PREDICATE=0 OUTPUT=joined.shp
540
+ ```
541
+
542
+ ```python
543
+ # PyQGIS
544
+ result = processing.run("native:joinattributesbylocation", {
545
+ 'INPUT': points_layer,
546
+ 'JOIN': polygons_layer,
547
+ 'PREDICATE': [0], # 0=相交
548
+ 'METHOD': 0, # 0=一对一
549
+ 'OUTPUT': 'memory:joined'
550
+ })
551
+ ```
552
+
553
+ ### 3.5 栅格计算(波段运算)
554
+
555
+ ```bash
556
+ # NDVI 计算
557
+ gdal_calc.py -A nir.tif -B red.tif \
558
+ --calc="(A-B)/(A+B)" --outfile=ndvi.tif
559
+
560
+ # 栅格掩膜
561
+ gdal_calc.py -A input.tif --calc="A*(A>100)" \
562
+ --outfile=masked.tif --NoDataValue=0
563
+
564
+ # 两个栅格平均
565
+ gdal_calc.py -A input1.tif -B input2.tif \
566
+ --calc="(A+B)/2" --outfile=mean.tif
567
+ ```
568
+
569
+ ### 3.6 DEM 分析
570
+
571
+ ```bash
572
+ # 等值线提取
573
+ gdal_contour -a elevation dem.tif contours.shp -i 10
574
+
575
+ # qgis_process — 坡度分析
576
+ qgis_process run gdal:slope -- INPUT=dem.tif OUTPUT=slope.tif
577
+
578
+ # qgis_process — 坡向分析
579
+ qgis_process run gdal:aspect -- INPUT=dem.tif OUTPUT=aspect.tif
580
+
581
+ # qgis_process — 山体阴影
582
+ qgis_process run gdal:hillshade -- INPUT=dem.tif OUTPUT=hillshade.tif
583
+ ```
584
+
585
+ ```python
586
+ # PyQGIS — 坡度分析
587
+ result = processing.run("gdal:slope", {
588
+ 'INPUT': '/data/dem.tif',
589
+ 'OUTPUT': '/data/slope.tif'
590
+ })
591
+ ```
592
+
593
+ ### 3.7 散点插值(创建 DEM)
594
+
595
+ ```bash
596
+ # 反距离加权(IDW)插值
597
+ gdal_grid -a invdist:power=2:smoothing=0 \
598
+ -zfield Z input_points.shp output_dem.tif
599
+
600
+ # 指定输出范围和分辨率
601
+ gdal_grid -outsize 512 512 -tr 10 10 \
602
+ -a average input_points.shp output_dem.tif
603
+ ```
604
+
605
+ ### 3.8 栅格矢量互转
606
+
607
+ ```bash
608
+ # 栅格转矢量(多边形化)
609
+ gdal_polygonize.py input.tif output.shp
610
+
611
+ # qgis_process
612
+ qgis_process run gdal:polygonize -- INPUT=input.tif OUTPUT=output.shp
613
+
614
+ # 矢量转栅格
615
+ qgis_process run gdal:rasterize -- \
616
+ INPUT=input.shp FIELD=value OUTPUT=output.tif
617
+ ```
618
+
619
+ ### 3.9 空间查询与过滤
620
+
621
+ ```bash
622
+ # ogr2ogr — 属性过滤
623
+ ogr2ogr output.shp input.shp -where "population > 1000000"
624
+
625
+ # ogr2ogr — 空间过滤
626
+ ogr2ogr output.shp input.shp -spat 116.0 39.5 117.0 40.5
627
+
628
+ # qgis_process — 按属性提取
629
+ qgis_process run native:extractbyattribute -- \
630
+ INPUT=input.shp FIELD=type OPERATOR=0 VALUE=road OUTPUT=roads.shp
631
+
632
+ # qgis_process — 按位置提取
633
+ qgis_process run native:extractbylocation -- \
634
+ INPUT=points.shp INTERSECT=boundary.shp PREDICATE=0 OUTPUT=extracted.shp
635
+ ```
636
+
637
+ ```python
638
+ # PyQGIS — 要素查询
639
+ from qgis.core import QgsFeatureRequest, QgsRectangle
640
+
641
+ # 属性过滤
642
+ request = QgsFeatureRequest().setFilterExpression('"population" > 10000')
643
+ for feature in layer.getFeatures(request):
644
+ print(feature["name"])
645
+
646
+ # 空间范围过滤
647
+ rect = QgsRectangle(116.0, 39.0, 117.0, 40.0)
648
+ request = QgsFeatureRequest().setFilterRect(rect)
649
+ for feature in layer.getFeatures(request):
650
+ print(feature.id())
651
+ ```
652
+
653
+ ```python
654
+ # GDAL Python API — 空间过滤 + 属性过滤
655
+ from osgeo import ogr
656
+
657
+ ds = ogr.Open("input.shp")
658
+ layer = ds.GetLayer(0)
659
+ layer.SetSpatialFilterRect(116.0, 39.5, 117.0, 40.5)
660
+ layer.SetAttributeFilter("POPULATION > 1000000")
661
+
662
+ for feature in layer:
663
+ print(feature.GetField("NAME"))
664
+ ds = None
665
+ ```
666
+
667
+ ### 3.10 地图渲染与导出
668
+
669
+ ```python
670
+ # PyQGIS — 渲染为 PNG
671
+ from qgis.core import QgsMapSettings, QgsMapRendererSequentialJob
672
+ from qgis.PyQt.QtCore import QSize
673
+
674
+ settings = QgsMapSettings()
675
+ settings.setLayers([layer])
676
+ settings.setDestinationCrs(layer.crs())
677
+ settings.setExtent(layer.extent())
678
+ settings.setOutputSize(QSize(1920, 1080))
679
+
680
+ job = QgsMapRendererSequentialJob(settings)
681
+ job.start()
682
+ job.waitForFinished()
683
+ job.renderedImage().save("/data/map_output.png")
684
+ ```
685
+
686
+ ```python
687
+ # PyQGIS — 导出 PDF
688
+ from qgis.core import QgsProject, QgsPrintLayout, QgsLayoutItemMap, QgsLayoutExporter
689
+
690
+ project = QgsProject.instance()
691
+ layout = QgsPrintLayout(project)
692
+ layout.initializeDefaults()
693
+
694
+ map_item = QgsLayoutItemMap(layout)
695
+ map_item.setRect(20, 20, 200, 150)
696
+ map_item.setExtent(layer.extent())
697
+ map_item.setLayers([layer])
698
+ layout.addLayoutItem(map_item)
699
+
700
+ exporter = QgsLayoutExporter(layout)
701
+ exporter.exportToPdf("/data/output.pdf", QgsLayoutExporter.PdfExportSettings())
702
+ ```
703
+
704
+ ---
705
+
438
706
  ## 阶段四:发布 GIS 地图服务(GeoServer REST API)
439
707
 
440
708
  **基础 URL:** `http://{host}:{port}/geoserver/rest`
@@ -603,6 +871,3 @@ curl -u admin:geoserver -XPOST \
603
871
  | 清空图层缓存 | POST | `/gwc/rest/seed/{layer}.json` |
604
872
  | 查看缓存任务 | GET | `/gwc/rest/seed/{layer}.json` |
605
873
  | 批量截断 | POST | `/gwc/rest/masstruncate` |
606
-
607
- ---
608
-
@@ -1,5 +1,12 @@
1
1
  # OpenGIS Workflow Examples and Cheatsheets
2
2
 
3
+ ## Contents
4
+
5
+ - 端到端工作流示例
6
+ - 常用内置算法速查(qgis_process / PyQGIS)
7
+ - GDAL 命令行工具速查
8
+ - 数据格式支持
9
+
3
10
  End-to-end workflow examples, built-in algorithm cheatsheet, GDAL CLI cheatsheet, data formats and env vars split from SKILL.md.
4
11
 
5
12
  ---
@@ -1,27 +1,21 @@
1
1
  ---
2
2
  name: opengis-daf
3
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
-
5
- tags:
6
- - gis
7
- - csharp
8
- - dotnet
9
- - spatial-analysis
10
- - data-quality
11
- - geojson
12
- - shapefile
13
- - postgis
14
- - vector
15
- - pipeline
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "gis, csharp, dotnet, spatial-analysis, data-quality, geojson, shapefile, postgis, vector, pipeline"
16
8
  ---
17
9
 
18
10
  > **项目地址:** <https://github.com/znlgis/opengis-daf>
19
11
  >
12
+ > **最新版本:** 仓库 `main` 主线(截至 2026-11,[无 Release tag](https://github.com/znlgis/opengis-daf/releases)、无 NuGet 包;以 `global.json` 的 .NET SDK 10.0.301 为准)
13
+ >
20
14
  > **许可证:** MIT License
21
15
  >
22
16
  > **文档:** <https://github.com/znlgis/opengis-daf/tree/main/docs>(快速入门、方案配置指南、算子参考、CLI 参考)
23
17
  >
24
- > **底层依赖:** GDAL/OGR 3.x、NetTopologySuite 2.6、Npgsql 10、Serilog 4.4
18
+ > **底层依赖:** GDAL/OGR 3.x、NetTopologySuite 2.6.0、Npgsql 10.0.3、Serilog 4.4.0(实测各 `*.csproj`)
25
19
 
26
20
  ## 概述
27
21
 
@@ -193,7 +187,7 @@ dotnet demo/plugin/OpenGisDAF.PluginHostDemo/bin/Release/net10.0/OpenGisDAF.Plug
193
187
 
194
188
  ---
195
189
 
196
- ## 常见工作流
190
+ ## 典型工作流
197
191
 
198
192
  ### 先质检、后分析(推荐)
199
193
 
@@ -237,10 +231,9 @@ dotnet demo/plugin/OpenGisDAF.PluginHostDemo/bin/Release/net10.0/OpenGisDAF.Plug
237
231
 
238
232
  ---
239
233
 
240
- ## DeepSeek Harness 使用建议
234
+ ## AI 使用建议
241
235
 
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 绑定类型缺失。
236
+ - **执行环境**:先 `dotnet --version`,必须是 **10.0**(仓库 `global.json` 锁定),Windows 用 PowerShell;克隆必须 `git clone --recurse-submodules`,漏了子模块 `opengis-utils-for-net` 会在编译期报 GDAL 绑定类型缺失。
244
237
  - **源码构建(无 NuGet 包)**:`dotnet build` 或 `./build.sh`,再 `dotnet run --project src/OpenGisDAF.Cli -- help` 确认 CLI 可用;这是自有项目,不要写 `dotnet add package OpenGisDAF`。
245
238
  - **测试两步走**:`dotnet build OpenGisDAF.slnx -c Release` 后 `dotnet test OpenGisDAF.slnx -c Release --no-build`——同一条 `dotnet test` 在 xunit.v3 工具链下会报“运行了零个测试”并以退出码 5 失败。
246
239
  - **验证产物**:先 `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` 才生成)。
@@ -1,23 +1,19 @@
1
1
  ---
2
2
  name: opengis-utils-for-java
3
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
- tags:
5
- - java
6
- - gis
7
- - geotools
8
- - jts
9
- - gdal
10
- - geometry
11
- - vector
12
- - crs
13
- - cgcs2000
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "java, gis, geotools, jts, gdal, geometry, vector, crs, cgcs2000"
14
8
  ---
15
9
 
16
10
  > **项目地址:** <https://github.com/znlgis/opengis-utils-for-java>
17
11
  >
18
12
  > **官方文档:** <https://github.com/znlgis/opengis-utils-for-java#readme>
19
13
  >
20
- > **Maven 坐标:** `com.znlgis.ogu4j:ogu4j:1.0.0`(截至2026-10 尚未发布到 Maven Central,需从源码 `mvn install` 安装到本地仓库)
14
+ > **最新版本:** 1.0.0(截至 2026-11,[仓库 `main` 分支 `pom.xml`](https://github.com/znlgis/opengis-utils-for-java/blob/main/pom.xml),无 Git tag;**尚未发布到 Maven Central**,需从源码 `mvn install` 安装到本地仓库)
15
+ >
16
+ > **Maven 坐标:** `com.znlgis.ogu4j:ogu4j`
21
17
  >
22
18
  > **许可证:** LGPL-2.1-or-later
23
19
 
@@ -133,7 +129,7 @@ com.znlgis.ogu4j
133
129
 
134
130
  > 常见任务快速参考(Quick Reference: Common Tasks)完整内容见 [reference/common-tasks.md](reference/common-tasks.md)
135
131
 
136
- ## Data Format Support Matrix
132
+ ## 数据格式支持矩阵
137
133
 
138
134
  | Format | DataFormatType | GeoTools | GDAL | Read | Write | Notes |
139
135
  |--------|---------------|----------|------|------|-------|-------|
@@ -147,9 +143,9 @@ com.znlgis.ogu4j
147
143
 
148
144
  ---
149
145
 
150
- ## Data Model Reference
146
+ ## 数据模型参考
151
147
 
152
- ### OguLayer (Core)
148
+ ### OguLayer(核心)
153
149
 
154
150
  | Property | Type | Description |
155
151
  |----------|------|-------------|
@@ -211,7 +207,7 @@ com.znlgis.ogu4j
211
207
 
212
208
  **Constructors:** `OguCoordinate(x, y)`, `OguCoordinate(x, y, z)`
213
209
 
214
- ### DbConnBaseModel (PostGIS connection)
210
+ ### DbConnBaseModel(PostGIS 连接)
215
211
 
216
212
  | Property | Type | Description |
217
213
  |----------|------|-------------|
@@ -225,7 +221,7 @@ com.znlgis.ogu4j
225
221
 
226
222
  ---
227
223
 
228
- ## Enumerations Quick Reference
224
+ ## 枚举速查
229
225
 
230
226
  ### GeometryType
231
227
 
@@ -251,7 +247,7 @@ com.znlgis.ogu4j
251
247
 
252
248
  ---
253
249
 
254
- ## Exception Hierarchy
250
+ ## 异常层次
255
251
 
256
252
  ```text
257
253
  Exception
@@ -267,7 +263,7 @@ RuntimeException
267
263
 
268
264
  ---
269
265
 
270
- ## Architecture & Design Patterns
266
+ ## 架构与设计模式
271
267
 
272
268
  - **Factory Pattern:** `GisEngineFactory` creates engine instances; use `GisEngineType.AUTO` for automatic selection (prefers GDAL if available)
273
269
  - **Strategy Pattern:** `LayerReader` / `LayerWriter` interfaces define pluggable format-specific I/O strategies
@@ -277,18 +273,20 @@ RuntimeException
277
273
 
278
274
  ---
279
275
 
280
- ## DeepSeek Harness 使用建议
276
+ ## 常见问题
281
277
 
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` 等绝对路径,覆盖已有数据前先确认路径并征得用户同意。
278
+ | 问题 | 解决 |
279
+ |------|------|
280
+ | `mvn install` 依赖解析失败 | 配置 osgeo 仓库(GeoTools 依赖不在 Maven Central);确认 Maven 3.8+ 与 JDK 17+ |
281
+ | 找不到 `com.znlgis.ogu4j:ogu4j` 依赖 | 该库尚未发布到 Maven Central,先在本仓库执行 `mvn install` 安装到本地仓库 |
282
+ | 运行时报 GDAL 相关 `UnsatisfiedLinkError` | 本地缺少与 `org.gdal:gdal` 3.13.0 匹配的原生 GDAL;安装 GDAL 3.13.x,或改用 `GisEngineType.GEOTOOLS` |
283
+ | FileGDB 读写失败 | FileGDB 仅 GDAL 引擎支持:安装原生 GDAL 并使用 `GisEngineType.GDAL` 或 `AUTO` |
284
+ | Shapefile 字段名被截断 | DBF 规范限制 10 字符,使用 `ShpUtil.formatFieldName()` 自动截断 |
285
+ | PostGIS 连接失败 | 检查连接串格式(`PG: host=... port=... dbname=... user=... password=... active_schema=...`)与 schema 名称 |
286
+
287
+ ---
290
288
 
291
- ## Important Notes for AI Developers
289
+ ## AI 编码约定
292
290
 
293
291
  1. **Always use `OguLayerUtil` as the primary entry point** for reading/writing GIS data. It handles engine selection and format routing.
294
292
 
@@ -330,28 +328,9 @@ RuntimeException
330
328
 
331
329
  ---
332
330
 
333
- ## 常见问题
334
-
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)
331
+ ## 典型工作流
353
332
 
354
- ## 典型工作流示例
333
+ 以「Shapefile → 面积筛选 → 缓冲 → 投影 → GeoJSON」为例:输入 `/data/parcels.shp`(EPSG:4326),输出 `/data/output.geojson`(EPSG:4528)。
355
334
 
356
335
  ```java
357
336
  import com.znlgis.ogu4j.datasource.OguLayerUtil;
@@ -388,8 +367,38 @@ OguLayerUtil.writeLayer(
388
367
  DataFormatType.GEOJSON, projected,
389
368
  "/data/output.geojson", null, null, GisEngineType.AUTO
390
369
  );
370
+
371
+ // Step 6: 回读验证——要素数与 CRS 必须与预期一致,否则说明引擎或投影没生效
372
+ OguLayer check = OguLayerUtil.readLayer(
373
+ DataFormatType.GEOJSON, "/data/output.geojson",
374
+ null, null, null, GisEngineType.AUTO
375
+ );
376
+ System.out.println(check.getWkid() + " / " + check.getFeatureCount());
391
377
  ```
392
378
 
379
+ **验收**:`mvn -q -DskipTests package` 只说明能编译;实际运行上面的 main,打印的 WKID 应为 4528、要素数等于筛选后数量,`output.geojson` 用 `ogrinfo -so` 复查一遍。
380
+
381
+ ---
382
+
383
+ ## AI 使用建议
384
+
385
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/common-tasks.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
386
+ - **执行环境**:先 `java -version` 与 `mvn -version`(需 JDK 17+、Maven 3.8+),Windows 用 PowerShell;`mvn -v` 里显示的 JDK 才是 Maven 实际使用的,与 shell 的 `java` 不一致时改 `JAVA_HOME` 再重试。
387
+ - **源码安装(本库未发布到 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 下载。
388
+ - **仓库与网络**:GeoTools 依赖不在 Central,`pom.xml` 必须带 `https://repo.osgeo.org/repository/release/`,否则 `Could not resolve dependencies for org.geotools:*`;离线或私服缺包时如实报告依赖不可下载,不要自行换版本或加未知仓库。
389
+ - **原生 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`。
390
+ - **验证产物**:写最小 main 读一个 Shapefile/GeoJSON → `OguLayerUtil.readLayer(DataFormatType.SHP, path, null, null, null, GisEngineType.AUTO)`,打印 `layer.getWkid()`、`layer.getFeatureCount()`,再 `writeLayer` 成 GeoJSON 并重新读回比对要素数与 CRS;`mvn -q -DskipTests package` 只说明能编译。
391
+ - **常见误操**:`AUTO` 在本机有原生 GDAL 时会优先走 GDAL,想复现纯 Java 结果必须显式传 `GisEngineType.GEOTOOLS`;`OguFeature.geometry` 是 WKT 字符串,做运算前先 `GeometryUtil.wkt2Geometry()`;`DataStore` 与 OGR `DataSource` 要在 `finally` 里释放,否则文件被占用后 `writeLayer` 覆盖失败。
392
+ - **安全与权限**:PostGIS 连接串(`PG: host=... password=...`)里的密码不要回显到输出;`mvn install` 会写 `~/.m2`、示例代码会写 `/data` 等绝对路径,覆盖已有数据前先确认路径并征得用户同意。
393
+
394
+ ## 相关技能
395
+
396
+ - **geotools** — Java GIS 工具库:[../geotools/SKILL.md](../geotools/SKILL.md)
397
+ - **jts** — JTS Topology Suite:[../jts/SKILL.md](../jts/SKILL.md)
398
+ - **geometry-api-java** — Esri Geometry API:[../geometry-api-java/SKILL.md](../geometry-api-java/SKILL.md)
399
+ - **gdal** — 命令行数据处理:[../gdal/SKILL.md](../gdal/SKILL.md)
400
+ - **gdal-api** — GDAL 编程 API:[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
401
+
393
402
  ## 参考资源
394
403
 
395
404
  - **GitHub 仓库:** <https://github.com/znlgis/opengis-utils-for-java>
@@ -1,12 +1,16 @@
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
+ ## Contents
4
+
5
+ - 常用任务速查
6
+
7
+ 从 SKILL.md 拆出的常用任务速查,Java 版本按 OGU4J 1.0.0 编写。
4
8
 
5
9
  ---
6
10
 
7
- ## Quick Reference: Common Tasks
11
+ ## 常用任务速查
8
12
 
9
- ### 1. Read a GIS Layer (Shapefile / GeoJSON / PostGIS / FileGDB / TXT)
13
+ ### 1. 读取图层(Shapefile / GeoJSON / PostGIS / FileGDB / TXT)
10
14
 
11
15
  ```java
12
16
  import com.znlgis.ogu4j.datasource.OguLayerUtil;
@@ -48,7 +52,7 @@ import com.znlgis.ogu4j.datasource.GtTxtUtil;
48
52
  OguLayer layer = GtTxtUtil.loadTxt("/path/to/file.txt", null); // null = auto-detect fields
49
53
  ```
50
54
 
51
- ### 2. Write a GIS Layer
55
+ ### 2. 写出图层
52
56
 
53
57
  ```java
54
58
  import com.znlgis.ogu4j.datasource.OguLayerUtil;
@@ -93,7 +97,7 @@ metadata.setMeasureUnit("米");
93
97
  GtTxtUtil.saveTxt(layer, "/path/to/output.txt", metadata, null, 39);
94
98
  ```
95
99
 
96
- ### 3. Format Conversion (One-Step)
100
+ ### 3. 格式转换(一步完成)
97
101
 
98
102
  ```java
99
103
  // SHP → GeoJSON
@@ -105,7 +109,7 @@ OguLayer layer = OguLayerUtil.readLayer(DataFormatType.GEOJSON, geojsonPath, nul
105
109
  OguLayerUtil.writeLayer(DataFormatType.POSTGIS, layer, connStr, "tableName", null, GisEngineType.AUTO);
106
110
  ```
107
111
 
108
- ### 4. Work with the Layer Model
112
+ ### 4. 使用图层模型
109
113
 
110
114
  ```java
111
115
  import com.znlgis.ogu4j.engine.model.layer.*;
@@ -157,7 +161,7 @@ int featureCount = layer.getFeatureCount();
157
161
  int fieldCount = layer.getFieldCount();
158
162
  ```
159
163
 
160
- ### 5. Geometry Operations (GeometryUtil)
164
+ ### 5. 几何运算(GeometryUtil)
161
165
 
162
166
  ```java
163
167
  import com.znlgis.ogu4j.geometry.GeometryUtil;
@@ -241,7 +245,7 @@ boolean norm = GeometryUtil.equalsNorm(geomA, geomB);
241
245
  boolean topo = GeometryUtil.equalsTopo(geomA, geomB);
242
246
  ```
243
247
 
244
- ### 6. WKT-Based Geometry Operations (ESRI Geometry API)
248
+ ### 6. 基于 WKT 的几何运算(ESRI Geometry API)
245
249
 
246
250
  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
251
 
@@ -280,7 +284,7 @@ boolean simple = GeometryUtil.isSimpleWkt(wkt, 4490);
280
284
  String simplified = GeometryUtil.simplifyWkt(wkt, 4490);
281
285
  ```
282
286
 
283
- ### 7. Coordinate Reference System (CrsUtil)
287
+ ### 7. 坐标参考系(CrsUtil)
284
288
 
285
289
  ```java
286
290
  import com.znlgis.ogu4j.engine.util.CrsUtil;
@@ -317,7 +321,7 @@ Map<Integer, CoordinateReferenceSystem> crsList = CrsUtil.getSupportedCRSList();
317
321
  Map.Entry<Integer, CoordinateReferenceSystem> entry = CrsUtil.getSupportedCRS(4490);
318
322
  ```
319
323
 
320
- ### 8. Engine API (Advanced Usage)
324
+ ### 8. 引擎 API(高级用法)
321
325
 
322
326
  ```java
323
327
  import com.znlgis.ogu4j.engine.*;
@@ -343,7 +347,7 @@ OguLayer layer = reader.read(path, layerName, attrFilter, spatialFilterWkt);
343
347
  writer.write(layer, path, layerName, options);
344
348
  ```
345
349
 
346
- ### 9. Utility Classes
350
+ ### 9. 工具类
347
351
 
348
352
  ```java
349
353
  // ZIP operations