@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
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: gdal
3
- description: "Use when processing geospatial raster/vector data via GDAL/OGR CLI — ogr2ogr format conversion (Shapefile/GeoPackage/GeoJSON), gdalwarp reprojection, gdal_translate, gdal_calc.py NDVI, COG, mosaicking, DEM contours, gdalinfo -json checks — or diagnosing \"not recognized as a supported file format\"; also covers the 3.9+ unified gdal raster / gdal vector CLI."
3
+ description: "Use when processing geospatial raster/vector data via GDAL/OGR CLI — ogr2ogr format conversion (Shapefile/GeoPackage/GeoJSON), gdalwarp reprojection, gdal_translate, gdal_calc.py NDVI, COG, mosaicking, DEM contours, gdalinfo -json checks — or diagnosing \"not recognized as a supported file format\"; also covers the 3.11+ unified gdal raster / gdal vector CLI."
4
4
 
5
5
  tags:
6
6
  - gdal
@@ -37,7 +37,7 @@ GDAL 是地理空间数据处理的事实标准库。它提供了 **50+ 个命
37
37
 
38
38
  ### 前置条件
39
39
 
40
- GDAL 3.0+ 已预装在大多数 Linux 发行版的地理信息处理环境中。确保工具在 `PATH` 中:
40
+ 部分 Linux 发行版与 GIS 软件栈会预装 GDAL(QGIS、PostGIS 客户端等),先用下面的命令确认工具在 `PATH` 中:
41
41
 
42
42
  ```bash
43
43
  gdalinfo --version # 验证 GDAL 版本
@@ -73,8 +73,10 @@ conda install -c conda-forge gdal
73
73
 
74
74
  #### Docker
75
75
 
76
+ Docker Hub 上的 `osgeo/gdal` 已迁移(该镜像最后一次更新为 2023 年),现由 GHCR 发布:
77
+
76
78
  ```bash
77
- docker run -it osgeo/gdal:latest bash
79
+ docker run --rm -it ghcr.io/osgeo/gdal:latest bash
78
80
  ```
79
81
 
80
82
  ### Python 绑定(可选)
@@ -91,19 +93,31 @@ conda install -c conda-forge gdal
91
93
 
92
94
  ## 核心命令结构
93
95
 
94
- ### 新式 CLI (GDAL 3.9+)
96
+ ### 新式 CLI (GDAL 3.11+)
95
97
 
96
- GDAL 3.9 引入了统一的 CLI 接口(最新稳定版 **3.13.3**,2026-08 发布,见 [下载页](https://gdal.org/download.html)),并在后续版本持续完善,新增 `gdal vector concave-hull/convex-hull/dissolve/sort`、`gdal dataset check` 等子命令:
98
+ GDAL 3.11 引入了统一的 `gdal` 命令行入口(官方文档标注 "Added in version 3.11";最新稳定版 **3.13.3**,2026-08-18 发布,见 [下载页](https://gdal.org/download.html)),后续版本持续加入 `gdal vector concave-hull/convex-hull/dissolve/sort` 等子命令,`gdal dataset check` 自 3.13 起提供:
97
99
 
98
100
  ```bash
99
101
  gdal <command> <subcommand> [options] <inputs>
100
102
  ```
101
103
 
102
104
  主要命令:
103
- - `gdal info` — 获取数据信息(自动检测栅格或矢量)
104
- - `gdal vector` — 矢量操作入口
105
- - `gdal raster` — 栅格操作入口
106
- - `gdal dataset` — 数据集管理
105
+ - `gdal info` — 获取数据信息(自动检测栅格或矢量,等价 `gdal raster info` / `gdal vector info`)
106
+ - `gdal vector` — 矢量操作入口(`convert`、`reproject`、`clip`、`buffer`、`dissolve`、`make-valid`、`sql` 等)
107
+ - `gdal raster` — 栅格操作入口(`convert`、`reproject`、`mosaic`、`clip`、`calc`、`contour` 等)
108
+ - `gdal dataset` — 数据集管理(`check`、`copy`、`rename`、`delete`、`identify`)
109
+ - `gdal pipeline` — 把多个步骤串成一条命令
110
+
111
+ ```bash
112
+ # 矢量重投影 + 格式转换(等价 ogr2ogr -t_srs ... -f GPKG)
113
+ gdal vector reproject --output-crs EPSG:3857 -o out.gpkg in.shp
114
+
115
+ # 栅格镶嵌(等价 gdal_merge.py / gdalwarp 多输入)
116
+ gdal raster mosaic -o mosaic.tif tile1.tif tile2.tif tile3.tif
117
+
118
+ # 数据集体检(3.13+)
119
+ gdal dataset check data.gpkg
120
+ ```
107
121
 
108
122
  ### 传统 CLI(广泛使用)
109
123
 
@@ -194,6 +208,21 @@ gdal_translate -outsize 50% 50% input.tif output.tif
194
208
  gdal_translate -projwin -180 90 -170 80 input.tif output.tif
195
209
  ```
196
210
 
211
+ ### COG / 云优化 GeoTIFF
212
+
213
+ COG 是带内部金字塔和分块的 GeoTIFF,便于 HTTP Range 按需读取(S3、对象存储、静态服务器):
214
+
215
+ ```bash
216
+ # GeoTIFF → COG(压缩 + 金字塔一次生成)
217
+ gdal_translate -of COG -co COMPRESS=DEFLATE -co OVERVIEWS=AUTO input.tif output_cog.tif
218
+
219
+ # 3.11+ 新式 CLI 等价写法
220
+ gdal raster convert --of COG -o output_cog.tif input.tif
221
+
222
+ # 校验:分块、金字塔、是否被识别为 COG
223
+ gdalinfo -json output_cog.tif | grep -E 'COMPRESSION|LAYOUT|BLOCK'
224
+ ```
225
+
197
226
  ### gdalwarp — 栅格重投影和镶嵌
198
227
 
199
228
  ```bash
@@ -415,18 +444,6 @@ gdaltindex -recursive -of GPKG \
415
444
 
416
445
  ---
417
446
 
418
- ## DeepSeek Harness 使用建议
419
-
420
- - **加载与引用**:用 `skill("gdal")` 加载(用户也可输入 `/gdal`);`reference/raster-tools.md`、`reference/vector-tools.md`、`reference/data-formats.md` 按需 `read`,路径相对加载结果中的 Base directory;技能目录只读,产物写到会话工作区。
421
- - **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`;仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行)。正文的 `apt-get`、`sudo`、`export VAR=` 是 Bash 写法:Windows 改为 `$env:GDAL_NUM_THREADS = "ALL_CPUS"`,无 `sudo`/`apt` 时改用 conda-forge 或 `docker run --rm -v "${PWD}:/data" -w /data osgeo/gdal:latest ...`。
422
- - **先探测版本**:`gdalinfo --version`、`ogrinfo --version`;本技能按 GDAL 3.13.3 编写,低于 3.9 没有 `gdal <command>` 新式 CLI(`gdal vector`/`gdal raster`),须退回 `ogr2ogr`/`gdalwarp`,且 `gdal_calc.py` 等脚本工具还需要 Python 绑定。
423
- - **验证产物**:栅格用 `gdalinfo -json out.tif` 核对 `driverShortName`、`size`、`coordinateSystem.wkt`、`bands[].noDataValue`;矢量用 `ogrinfo -so out.shp layer`(或 `ogrinfo -json out.gpkg`)核对 `Feature Count`、`Geometry`、字段列表;不要只凭退出码报告成功。
424
- - **先看错误再改参数**:`ERROR 4: ... not recognized as a supported file format` 先查路径与 `gdalinfo --formats`;`--debug on` 或 `CPL_DEBUG=ON` 看驱动细节;输出很长时重定向到文件再分段 `read`,不要一次打印全文。
425
- - **批处理与中间产物**:批量循环建议用 Python 生成命令,中间结果用 `gdalbuildvrt` 写 `.vrt` 而不是反复 `gdalwarp`;耗时命令放后台作业,避免一次重投影全部数据。
426
- - **安全与权限**:`gdal_edit.py`、`ogr2ogr` 写已有目标、`-overwrite`/`-append` 会就地改写或覆盖数据,先备份或换输出名;安装 GDAL、改 `GDAL_DATA`/`PROJ_LIB`、访问 `/vsis3/`(需 `AWS_SECRET_ACCESS_KEY`)前先征得用户同意,回答里不要回显密钥。
427
-
428
- ---
429
-
430
447
  ## 常见问题
431
448
 
432
449
  | 问题 | 解决 |
@@ -442,6 +459,18 @@ gdaltindex -recursive -of GPKG \
442
459
 
443
460
  ---
444
461
 
462
+ ## AI 使用建议
463
+
464
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/data-formats.md`、`reference/raster-tools.md`、`reference/vector-tools.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
465
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell)。正文的 `apt-get`、`sudo`、`export VAR=` 是 Bash 写法:Windows 改为 `$env:GDAL_NUM_THREADS = "ALL_CPUS"`,无 `sudo`/`apt` 时改用 conda-forge 或 `docker run --rm -v "${PWD}:/data" -w /data ghcr.io/osgeo/gdal:latest ...`。
466
+ - **先探测版本**:`gdalinfo --version`、`ogrinfo --version`;本技能按 GDAL 3.13.3 编写,低于 3.11 没有 `gdal <command>` 新式 CLI(`gdal vector`/`gdal raster`),须退回 `ogr2ogr`/`gdalwarp`;`gdal dataset check` 需 3.13+,且 `gdal_calc.py` 等脚本工具还需要 Python 绑定。
467
+ - **验证产物**:栅格用 `gdalinfo -json out.tif` 核对 `driverShortName`、`size`、`coordinateSystem.wkt`、`bands[].noDataValue`;矢量用 `ogrinfo -so out.shp layer`(或 `ogrinfo -json out.gpkg`)核对 `Feature Count`、`Geometry`、字段列表;不要只凭退出码报告成功。
468
+ - **先看错误再改参数**:`ERROR 4: ... not recognized as a supported file format` 先查路径与 `gdalinfo --formats`;`--debug on` 或 `CPL_DEBUG=ON` 看驱动细节;输出很长时重定向到文件再分段读取,不要一次打印全文。
469
+ - **批处理与中间产物**:批量循环建议用 Python 生成命令,中间结果用 `gdalbuildvrt` 写 `.vrt` 而不是反复 `gdalwarp`;耗时命令放后台运行,避免一次重投影全部数据。
470
+ - **安全与权限**:`gdal_edit.py`、`ogr2ogr` 写已有目标、`-overwrite`/`-append` 会就地改写或覆盖数据,先备份或换输出名;安装 GDAL、改 `GDAL_DATA`/`PROJ_LIB`、访问 `/vsis3/`(需 `AWS_SECRET_ACCESS_KEY`)前先征得用户同意,回答里不要回显密钥。
471
+
472
+ ---
473
+
445
474
  ## 相关技能
446
475
 
447
476
  - **gdal-api** — GDAL 编程 API(C/C++/Python/.NET):[../gdal-api/SKILL.md](../gdal-api/SKILL.md)
@@ -174,7 +174,8 @@ if (transform->Transform(1, &x, &y)) {
174
174
  // x, y 已变换为 EPSG:3857 坐标
175
175
  }
176
176
 
177
- OCTDestroyCoordinateTransformation(transform);
177
+ // C++ 用 DestroyCT 归还;OCTDestroyCoordinateTransformation 是 C API(接收 OGRCoordinateTransformationH)
178
+ OGRCoordinateTransformation::DestroyCT(transform);
178
179
  ```
179
180
 
180
181
  ### Python
@@ -305,6 +306,7 @@ src_ds = None # 释放数据源
305
306
  | 通用 | 大栅格内存溢出 | 用 `RasterIO` 指定窗口分块读写,避免一次性读入整个影像 |
306
307
  | 通用 | 报错信息不明确 | C++ 用 `CPLGetLastErrorMsg()`,Python 用 `gdal.GetLastErrorMsg()` 获取详细错误 |
307
308
  | C++ | WKT 等 C 字符串泄漏 | 用 `CPLFree()` 释放(如 `exportToWkt` 返回值);几何用 `OGRGeometryFactory::destroyGeometry()` |
309
+ | C++ | 坐标变换释放方式混用 | C++ 用 `OGRCoordinateTransformation::DestroyCT()`;`OCTDestroyCoordinateTransformation()` 只接收 C API 的 `OGRCoordinateTransformationH` |
308
310
  | C++ | 编译 / 链接失败 | 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL)` 配置编译参数 |
309
311
  | Python | 出错却不抛异常 | 脚本开头调用 `gdal.UseExceptions()` 启用异常模式 |
310
312
  | Python | 如何高效读写像素 | `band.ReadAsArray()` / `band.WriteArray(array)` 直接与 NumPy 数组互转 |
@@ -315,10 +317,10 @@ src_ds = None # 释放数据源
315
317
 
316
318
  ---
317
319
 
318
- ## DeepSeek Harness 使用建议
320
+ ## AI 使用建议
319
321
 
320
- - **加载与引用**:用 `skill("gdal-api")` 加载(用户也可输入 `/gdal-api`);`reference/raster-api.md`(栅格读写的完整 API)、`reference/vector-api.md`(OGR 图层与 GeoPackage)按需 `read`,路径相对 Base directory;技能目录只读,示例代码与产物写到会话工作区。
321
- - **执行环境**:编译与运行交给 dsh 的 shell 工具(Windows 用 `pwsh`;仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行)。C++ 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL REQUIRED)`;Python 用装好绑定的解释器;Java 的 `gdalalljni`、.NET 的 MaxRev 运行时包必须与平台、架构匹配。
322
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/raster-api.md`、`reference/vector-api.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
323
+ - **执行环境**:编译与运行在终端 / shell 中执行(Windows 用 PowerShell)。C++ 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL REQUIRED)`;Python 用装好绑定的解释器;Java 的 `gdalalljni`、.NET 的 MaxRev 运行时包必须与平台、架构匹配。
322
324
  - **先探测版本**:`ogrinfo --version`、`python -c "from osgeo import gdal; print(gdal.VersionInfo())"`(返回 `3130300` 这类数字)、`mvn -v`、`dotnet --version`;本技能按 GDAL 3.13.3、Java 绑定 3.13.0 编写,低版本缺少新驱动与部分 SWIG 方法,回答里要说明差异。
323
325
  - **验证产物**:写完后重新打开核对——`python -c "from osgeo import gdal; ds=gdal.Open('out.tif'); print(ds.GetDriver().ShortName, ds.RasterCount, ds.GetSpatialRef().GetAuthorityCode(None))"`;矢量用 `ogrinfo -al -so out.gpkg` 看要素数与字段;Python 一律先 `gdal.UseExceptions()`,否则错误被静默吞掉。
324
326
  - **语言选择**:数据处理脚本优先 Python(`ReadAsArray()` 直通 NumPy);生产服务与嵌入式优先 C++;Java 注意用 `java.util.Vector<String>` 传选项;.NET 用 `OSGeo.GDAL`/`OSGeo.OGR` 命名空间,或 MaxRev 封装 + 对应平台运行时包。
@@ -0,0 +1,364 @@
1
+ ---
2
+ name: geolibre
3
+ description: "Use when scripting or self-hosting the GeoLibre GIS app — geolibre Python anywidget (Map/add_geojson/add_cog/save_project), geolibre-mcp stdio server for AI agents, ghcr.io/opengeos/geolibre Docker image, DuckDB-WASM SQL workspace, ?data= and ?url= deep links; also for a blank window on Linux WebKitGTK, sidecar path not allowed from GEOLIBRE_CONVERSION_ROOTS, and Jupyter relay not connected. GeoLibre 3.5.1."
4
+ tags:
5
+ - geolibre
6
+ - gis
7
+ - python
8
+ - jupyter
9
+ - mcp
10
+ - duckdb
11
+ - docker
12
+ - webgis
13
+ - tauri
14
+ - geospatial
15
+ ---
16
+
17
+ > **项目地址:** <https://github.com/opengeos/GeoLibre>
18
+ >
19
+ > **官方文档:** <https://geolibre.app/getting-started/>
20
+ >
21
+ > **在线版:** <https://web.geolibre.app>
22
+ >
23
+ > **PyPI:** geolibre 3.5.1(要求 Python >= 3.11,截至 2026-10);conda-forge 渠道为 3.5.0
24
+ >
25
+ > **许可证:** MIT
26
+
27
+ ## 概述
28
+
29
+ GeoLibre 是一个云原生 GIS 应用,同一份代码可运行在浏览器、桌面(Tauri v2)、移动端与 Jupyter Notebook 里。它把地图渲染、矢量/栅格/点云浏览、SQL 分析与上千个地理处理工具装进一个前端应用,数据默认留在本机。
30
+
31
+ 对脚本与自动化最相关的四个入口:
32
+
33
+ - **Python 包**:geolibre.Map(anywidget)把整个应用嵌进 Notebook,并暴露 leafmap 风格的 API
34
+ - **MCP 服务器**:geolibre-mcp 以无头方式读写 .geolibre.json 工程,供 AI 客户端调用
35
+ - **Docker 镜像**:ghcr.io/opengeos/geolibre:latest 自托管 Web 版,可选 sidecar 与 Basic Auth
36
+ - **SQL 工作区**:DuckDB-WASM 加 spatial 扩展,把地图上的每个矢量图层当成 SQL 表
37
+
38
+ 技术栈为 Tauri v2 + React + TypeScript + MapLibre GL JS + DuckDB-WASM Spatial + deck.gl;渲染引擎可在 MapLibre、Mapbox、CesiumJS、ArcGIS 之间切换。地理处理工具(地形、水文、点云、遥感、矢量分析)通过 WebAssembly 在浏览器里执行,不需要服务端。
39
+
40
+ ## 环境准备
41
+
42
+ ### 路径一:零安装(浏览器)
43
+
44
+ 访问 <https://web.geolibre.app>。网页版可读浏览器能选择的数据、URL 服务、COG 与远程 GeoParquet,但没有本地文件对话框,也不能读本地 MBTiles/栅格。
45
+
46
+ ### 路径二:桌面应用
47
+
48
+ | 平台 | 命令 / 入口 |
49
+ |------|-------------|
50
+ | Windows(Store,推荐) | <https://apps.microsoft.com/detail/9nwt67rv531x> |
51
+ | Windows(winget,未签名构建) | `winget install OpenGeos.GeoLibre` |
52
+ | macOS(Homebrew Cask) | `brew install --cask geolibre` |
53
+ | Arch / Manjaro | `yay -S geolibre-bin` |
54
+ | Fedora / RHEL(COPR) | `sudo dnf copr enable giswqs/geolibre && sudo dnf install geolibre` |
55
+ | Flatpak | `flatpak install flatpark app.geolibre.GeoLibre` |
56
+ | Debian / Ubuntu | `sudo apt install ./GeoLibre.Desktop_<version>_amd64.deb` |
57
+
58
+ 验证:启动后 **Help → About** 核对版本为 3.5.1,**Help → Diagnostics** 应无红色错误项。
59
+
60
+ ### 路径三:Python 包(Notebook / 脚本)
61
+
62
+ ```bash
63
+ pip install geolibre==3.5.1
64
+
65
+ # 或 conda-forge
66
+ conda install -c conda-forge geolibre
67
+
68
+ # 可选 extras
69
+ pip install "geolibre[dash]" # DashMap 组件
70
+ pip install "geolibre[mcp]" # geolibre-mcp 控制台脚本
71
+ ```
72
+
73
+ ```python
74
+ from geolibre import Map
75
+ print(Map.__module__) # 能 import 即为安装成功
76
+ ```
77
+
78
+ ### 路径四:Docker 自托管
79
+
80
+ ```bash
81
+ docker pull ghcr.io/opengeos/geolibre:latest
82
+ docker run --rm -p 8080:80 ghcr.io/opengeos/geolibre:latest
83
+ # 打开 http://localhost:8080
84
+ ```
85
+
86
+ 需要 sidecar(转换、栅格、PostGIS 等本地工具)时挂载数据目录并限制可访问路径:
87
+
88
+ ```bash
89
+ docker run --rm -p 8080:80 \
90
+ -v "$PWD/data:/data" \
91
+ -e GEOLIBRE_CONVERSION_ROOTS=/data \
92
+ ghcr.io/opengeos/geolibre:latest
93
+ ```
94
+
95
+ 加共享密码(应用与 /sidecar 都启用 HTTP Basic Auth,/healthz 除外):
96
+
97
+ ```bash
98
+ docker run --rm -p 8080:80 \
99
+ -e GEOLIBRE_AUTH_USER=admin \
100
+ -e GEOLIBRE_AUTH_PASSWORD='change-me' \
101
+ ghcr.io/opengeos/geolibre:latest
102
+ ```
103
+
104
+ ### 路径五:源码运行
105
+
106
+ ```bash
107
+ git clone https://github.com/opengeos/GeoLibre.git
108
+ cd GeoLibre
109
+ npm install # 需要 Node 22+
110
+ npm run dev # 浏览器开发服务器 http://localhost:5173
111
+ npm run tauri:dev # 桌面应用(需要 Rust 工具链)
112
+ npm run build # Web 生产构建
113
+ ```
114
+
115
+ ## 核心接口
116
+
117
+ ### Python:geolibre.Map
118
+
119
+ | 方法 | 说明 |
120
+ |------|------|
121
+ | Map(center=(lng, lat), zoom=4) | 创建内嵌应用;参数决定初始视图 |
122
+ | add_geojson(data, name=, **style) | 加矢量图层,接受 URL、dict、GeoDataFrame、JSON 字符串 |
123
+ | add_tile_layer(url, name=, attribution=) | XYZ 栅格瓦片 |
124
+ | add_cog(url, name=, colormap=) | 云优化 GeoTIFF |
125
+ | add_basemap(name) | 切换底图(如 "dark") |
126
+ | set_center(lng, lat, zoom=) | 移动相机 |
127
+ | save_project(path) / load_project(path) | 读写 .geolibre.json 工程 |
128
+ | to_project() | 取当前工程状态(dict),用于回读 UI 侧编辑 |
129
+
130
+ ```python
131
+ from geolibre import Map
132
+
133
+ m = Map(center=(-100, 40), zoom=4)
134
+ m.add_geojson("https://example.com/data.geojson", name="Data")
135
+ m.add_tile_layer(
136
+ "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
137
+ name="OpenStreetMap",
138
+ attribution="(c) OpenStreetMap contributors",
139
+ )
140
+ m.add_cog("https://example.com/dem.tif", name="DEM", colormap="terrain")
141
+ m.add_basemap("dark")
142
+ m.set_center(-120, 47, zoom=8)
143
+ m.save_project("my-map.geolibre.json")
144
+ m # 最后一行放在单元格末尾才会渲染
145
+ ```
146
+
147
+ 工程状态双向同步:Python 加的图层会出现在 UI,UI 里平移/缩放后再 to_project() 能读回新的 mapView.center。
148
+
149
+ ```python
150
+ m2 = Map()
151
+ m2.load_project("my-map.geolibre.json")
152
+ print(m2.to_project()["mapView"]["center"])
153
+ ```
154
+
155
+ ### Python:Google Earth Engine 图层
156
+
157
+ ```bash
158
+ pip install earthengine-api
159
+ ```
160
+
161
+ ```python
162
+ import ee
163
+ ee.Authenticate() # 每台机器一次
164
+ ee.Initialize(project="your-gcp-project")
165
+
166
+ from geolibre import Map
167
+ m = Map()
168
+ m.add_ee_layer(ee.Image("USGS/SRTMGL1_003"), {"min": 0, "max": 3000}, name="SRTM")
169
+ m
170
+ ```
171
+
172
+ ### MCP 服务器:geolibre-mcp
173
+
174
+ 无头写工程:不需要浏览器、不需要运行中的应用,产出与桌面/网页版能加载的工程同构。
175
+
176
+ ```bash
177
+ pip install "geolibre[mcp]"
178
+ geolibre-mcp --root ~/maps
179
+ ```
180
+
181
+ | 参数 / 变量 | 说明 |
182
+ |-------------|------|
183
+ | --root | 可重复,声明工作区根目录 |
184
+ | GEOLIBRE_MCP_ROOTS | 环境变量版,冒号分隔(Windows 用分号) |
185
+ | --transport | stdio(默认,客户端 spawn 用)、streamable-http、sse |
186
+
187
+ 客户端配置(Claude Desktop 等):
188
+
189
+ ```json
190
+ {
191
+ "mcpServers": {
192
+ "geolibre": {
193
+ "command": "geolibre-mcp",
194
+ "args": ["--root", "C:/Users/you/maps"]
195
+ }
196
+ }
197
+ }
198
+ ```
199
+
200
+ 支持 MCP 的客户端(Claude Code、Cursor、Cline、OpenCode 等)都把上段 JSON 写进各自的 MCP 配置即可;以 Claude Code 为例的一行注册:
201
+
202
+ ```bash
203
+ claude mcp add geolibre -- geolibre-mcp --root ~/maps
204
+ ```
205
+
206
+ 常用工具分组:
207
+
208
+ | 分组 | 工具 |
209
+ |------|------|
210
+ | 工程生命周期 | create_project、describe_project、list_catalog |
211
+ | 加图层 | add_geojson_layer、add_vector_layer、add_raster_layer、add_tile_layer、add_ogc_layer、add_3d_tiles_layer |
212
+ | 编辑 | update_layer、remove_layer、style_layer、set_layer_metadata、set_layer_filter |
213
+ | 取景与装饰 | set_view、set_basemap、add_legend、add_colorbar、add_swipe |
214
+ | 导出 | export_html(独立页面)、show_map(支持 MCP Apps 的客户端内联预览) |
215
+ | 实时地图 | live_status、live_fly_to、live_add_geojson、live_run_algorithm |
216
+
217
+ list_catalog 应该是第一个调用的工具:底图、色带、图例预设、插件 id 都以它为准,猜错名字不会报错,只会静默不生效。
218
+
219
+ 工作区安全模型(决定为什么有些路径写不进去):
220
+
221
+ | 闸门 | 规则 |
222
+ |------|------|
223
+ | 路径解析 | 每次调用的路径都按允许根解析,根之外与"根内指向根外的符号链接"一律拒绝 |
224
+ | 扩展名 | 只写 .json(工程)或 .html(导出) |
225
+ | 覆盖 | 不带 overwrite 不覆盖已存在文件 |
226
+ | 大小 | 内联 GeoJSON 不超过 50 MB,工程文件读取不超过 256 MB |
227
+
228
+ 给它一个专门放地图的目录,不要给家目录。
229
+
230
+ ### SQL 工作区(DuckDB-WASM)
231
+
232
+ **Processing → SQL Workspace** 打开,面板停靠在地图下方。地图上每个矢量图层同时是一张 SQL 表:
233
+
234
+ - 表名规则:小写、非字母数字压成下划线、数字开头加 t_ 前缀、保留字加前缀、重名追加 _2
235
+ - 几何列名:DuckDB 与 PostGIS 引擎为 geom,Sedona 为 geometry
236
+ - 支持三种引擎:DuckDB(默认,可直读远程文件)、PostGIS(PGlite)、Apache Sedona(CereusDB,单层上限 5 万要素)
237
+
238
+ ```sql
239
+ -- 两个图层直接 JOIN:城市点落在哪个国家
240
+ SELECT c.NAME AS country, p.name AS city, p.geom
241
+ FROM cities p
242
+ JOIN countries c
243
+ ON ST_Intersects(c.geom, p.geom)
244
+ WHERE c.CONTINENT = 'Africa';
245
+ ```
246
+
247
+ 结果区可 **Add as layer**(物化)或 **Add as query layer**(活查询,仅 DuckDB)。
248
+
249
+ ### Web 版 URL 参数(分享与嵌入)
250
+
251
+ | 参数 | 作用 |
252
+ |------|------|
253
+ | url= | 打开一个公开 .geolibre 工程 |
254
+ | data= | 直接打开托管数据,可重复(GeoJSON、GeoParquet、PMTiles、COG、LiDAR 等) |
255
+ | style= | 给 data= 应用样式 JSON |
256
+ | layout=compact | 图标化工具栏,适合窄嵌入 |
257
+ | layout=viewer | 只读查看器预设 |
258
+ | panels=none / maponly | 隐藏面板 / 完全去掉工具栏与状态栏 |
259
+
260
+ ```text
261
+ https://web.geolibre.app/?data=https://example.org/places.geojson&layout=compact&panels=none
262
+ ```
263
+
264
+ ### 关键环境变量
265
+
266
+ | 变量 | 作用 |
267
+ |------|------|
268
+ | GEOLIBRE_CONVERSION_ROOTS | sidecar 允许读写的目录白名单(Docker 镜像内默认 /data) |
269
+ | GEOLIBRE_DISABLE_SIDECAR=1 | 纯静态 Web 行为,不起 sidecar |
270
+ | GEOLIBRE_AUTH_USER / GEOLIBRE_AUTH_PASSWORD | nginx 层 HTTP Basic Auth |
271
+ | GEOLIBRE_CAPABILITIES | 逗号分隔的能力白名单(或 none),用于只读门户/展厅 |
272
+ | GEOLIBRE_EMBED_ORIGINS | 允许通过 iframe/postMessage 驱动应用的来源 |
273
+ | GEOLIBRE_STORE_BUILD / GEOLIBRE_MAS_BUILD | 商店构建开关(移除自动更新 / sidecar 能力) |
274
+
275
+ ## 典型工作流:MCP 生成工程 → 桌面打开 → 导出独立 HTML
276
+
277
+ 目标:不打开应用,用 AI 客户端生成一张城市地图,人工在桌面版微调后导出为可分发的单页。
278
+
279
+ **步骤 1:装 MCP 并准备目录**
280
+
281
+ ```bash
282
+ pip install "geolibre[mcp]"
283
+ mkdir -p ~/maps
284
+ claude mcp add geolibre -- geolibre-mcp --root ~/maps
285
+ ```
286
+
287
+ **步骤 2:让客户端依次调用工具(工具序列)**
288
+
289
+ ```text
290
+ list_catalog() # 先查有哪些底图/色带/插件 id
291
+ create_project(name="beijing", center=[116.39, 39.90], zoom=10)
292
+ add_geojson_layer(url="https://example.org/poi.geojson", name="POI")
293
+ style_layer(layer="POI", fillColor="#f97316", circleRadius=6)
294
+ set_view(center=[116.39, 39.90], zoom=11) # 精确取景用 center+zoom,不要用 bbox
295
+ ```
296
+
297
+ 产出一个 .geolibre.json(工作区内,扩展名只能是 .json 或 .html)。
298
+
299
+ **步骤 3:桌面版打开并微调**
300
+
301
+ 双击工程文件(桌面安装包已注册文件关联),调整样式、加图例(add_legend / set_map_legend),必要时用 **Project → Save** 写回。
302
+
303
+ **步骤 4:导出可分发的 HTML**
304
+
305
+ ```text
306
+ export_html(path="beijing.html", app_url="https://web.geolibre.app")
307
+ ```
308
+
309
+ export_html 会剥掉凭据;指向本地文件的图层在别人机器上不会加载,要分享就用托管 URL。app_url 是信任边界——工程内容会被 POST 到那个来源,只填你本来就信任的地址。
310
+
311
+ **步骤 5:验证**
312
+
313
+ ```bash
314
+ python -c "import json;d=json.load(open('beijing.geolibre.json'));print(len(d.get('layers',[])),'layers')"
315
+ ```
316
+
317
+ 再在浏览器打开 beijing.html,确认底图与图层能渲染、点击要素有弹窗。
318
+
319
+ ## 最佳实践
320
+
321
+ 1. **生成用 MCP 或 Python 包,审阅用 GUI**:无头路径可重复、可测试,GUI 微调难以复现。
322
+ 2. **工程文件走版本控制**:.geolibre.json 是纯 JSON,diff 友好;大 GeoJSON 放外部 URL 而不是内联。
323
+ 3. **sidecar 路径走白名单目录**:自托管时把数据挂到 GEOLIBRE_CONVERSION_ROOTS 声明的目录下。
324
+ 4. **只读门户用能力策略**:GEOLIBRE_CAPABILITIES 受限或 none,配 layout=viewer,避免把编辑能力暴露出去。
325
+ 5. **嵌入要声明来源**:iframe 驱动需要 GEOLIBRE_EMBED_ORIGINS 白名单,否则命令会被丢弃。
326
+ 6. **实时工具有前提**:桌面版每次启动后要先打开一次 **Processing → Jupyter Notebook** 启动中继;网页版与 JupyterLite 没有中继。
327
+
328
+ ## 常见问题
329
+
330
+ | 问题 | 原因 | 解决方案 |
331
+ |------|------|---------|
332
+ | Linux 桌面版窗口空白或地图闪烁 | WebKitGTK 的 DMA-BUF 渲染器与驱动不兼容 | 用传统渲染器启动:WEBKIT_DISABLE_DMABUF_RENDERER=1 geolibre-desktop;若被自动降到传统渲染器后很慢,改回 0 再试 |
333
+ | 无 AVX 的老 CPU 上窗口永不绘制 | JavaScriptCore 的 WebAssembly JIT 触发 SIGILL | 成对设置 JSC_useWasmOSR=false 与 JSC_useBBQTierUpChecks=false |
334
+ | MCP 返回路径不允许或工具直接拒绝 | 路径不在 --root 或 GEOLIBRE_MCP_ROOTS 内,或是指向根外的符号链接 | 把工程目录加进 --root,或把文件移到根内;不要给家目录 |
335
+ | geolibre-mcp 不在客户端 PATH 里 | 装在 virtualenv 中,客户端 spawn 时用系统 PATH | 配置里改用解释器:command 指向 venv 的 python,args 用 -m geolibre.mcp --root ... |
336
+ | live_ 工具报没连接或超时 | 桌面版中继没启动,或大 FeatureCollection 超过约 5 秒 | 先打开一次 Processing → Jupyter Notebook;超时不代表失败,用 live_list_layers 回查而不是重发 |
337
+ | add_geojson / list_layers 返回 None 或抛 GeoLibreNotConnectedError | 没有窗口在监听,或读回在网页版不可用 | 确认至少一个桌面窗口连到同一 Jupyter 服务器;同步读回只在桌面版可用 |
338
+ | SQL 工作区里 ST_Intersects 报函数不存在 | 引擎未加载空间扩展,或图层未按几何列注册 | 检查 Queryable layers 里的表名与几何列名(DuckDB/PostGIS 是 geom,Sedona 是 geometry) |
339
+ | 自托管转换报路径不允许 | 触到 GEOLIBRE_CONVERSION_ROOTS 白名单 | 输出到白名单目录内,或调整该变量 |
340
+ | 网页版打开本地文件后刷新就没了 | 浏览器安全模型不给持久文件路径 | 用桌面版做本地文件工作,或用 data= 指向托管 URL |
341
+ | 沙盒(Mac App Store)版加载松散 Shapefile 丢属性 | 沙盒授权只覆盖显式选择的文件 | 一次选中所有分片(.shp/.dbf/.prj)或用压缩包 |
342
+
343
+ ## AI 使用建议
344
+
345
+ - **先确认版本与入口**:pip show geolibre 看版本,geolibre-mcp --help 看参数;桌面版看 Help → About。教程可能对应 3.4,遇到差异以 3.5.1 的实际行为为准。
346
+ - **装包前确认 Python 版本**:PyPI 的 geolibre 3.5.1 要求 Python >= 3.11;低版本解释器会直接安装失败,不要误判为网络问题。
347
+ - **MCP 路径要显式**:Windows 上 JSON 里写正向斜杠(C:/Users/you/maps),反斜杠需成对转义,容易出错。
348
+ - **验证产物**:写完工程先 json.load 检查图层数与 mapView,再用浏览器打开导出的 HTML 看渲染;不要只看工具返回的成功。
349
+ - **写操作确认**:export_html、save_project 与 MCP 的覆盖写会改写磁盘文件;覆盖前确认目标,或先写新文件名。
350
+
351
+ ## 相关技能
352
+
353
+ - **duckdb-spatial** — SQL 工作区背后的空间分析引擎:[../duckdb-spatial/SKILL.md](../duckdb-spatial/SKILL.md)
354
+ - **openlayers** — 自建 Web 地图前端时的核心库:[../openlayers/SKILL.md](../openlayers/SKILL.md)
355
+ - **cesiumjs** — GeoLibre 的 3D 球渲染引擎之一:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
356
+ - **qgis-process** — 桌面 GIS 的另一种无头批处理路径:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
357
+ - **opengis-all** — 全流程 GIS 索引:[../opengis-all/SKILL.md](../opengis-all/SKILL.md)
358
+
359
+ ## 参考资源
360
+ - 官方文档:<https://geolibre.app/getting-started/>
361
+ - 下载页:<https://geolibre.app/downloads/>
362
+ - Python 包文档:<https://geolibre.app/python/>
363
+ - 功能列表:<https://geolibre.app/features/>
364
+ - 渲染引擎对比:<https://geolibre.app/user-guide/rendering-engines/>
@@ -124,8 +124,8 @@ MapGeometry mapGeom = new MapGeometry(pt, srWGS84);
124
124
  ```java
125
125
  SpatialReference sr = SpatialReference.create(4326);
126
126
 
127
- // 缓冲区
128
- Geometry buffered = GeometryEngine.buffer(point, sr, 100.0);
127
+ // 缓冲区(返回 Polygon)
128
+ Polygon buffered = GeometryEngine.buffer(point, sr, 100.0);
129
129
 
130
130
  // 交集
131
131
  Geometry inter = GeometryEngine.intersect(polygon1, polygon2, sr);
@@ -334,7 +334,7 @@ Geometry polygon = GeometryEngine.geometryFromWkt(
334
334
 
335
335
  SpatialReference sr = SpatialReference.create(4326);
336
336
 
337
- // 2. 缓冲区分析
337
+ // 2. 缓冲区分析(GeometryEngine.buffer 返回 Polygon)
338
338
  Polygon buffered = GeometryEngine.buffer(polygon, sr, 2.0);
339
339
 
340
340
  // 3. 相交判断(算子调用)
@@ -376,10 +376,9 @@ if (hit) {
376
376
 
377
377
  ---
378
378
 
379
- ## DeepSeek Harness 使用建议
379
+ ## AI 使用建议
380
380
 
381
- - **加载与引用**:用 `skill("geometry-api-java")` 加载(用户也可输入 `/geometry-api-java`);本技能没有 `reference/` 子目录,示例都在正文;技能目录只读,Maven 工程建在会话工作区。
382
- - **执行环境**:先 `mvn -v` 与 `java -version` 确认工具链(JDK 8+ 即可编译,建议 17/21 运行),Windows 上用 `pwsh` 执行;`%JAVA_HOME%`/`JAVA_HOME` 与 `mvn` 实际使用的 JDK 可能不同,报 `Unsupported class file major version` 时按 `mvn -v` 显示的 JDK 判断。
381
+ - **执行环境**:先 `mvn -v` 与 `java -version` 确认工具链(JDK 8+ 即可编译,建议 17/21 运行),Windows 上用 PowerShell 执行;`%JAVA_HOME%`/`JAVA_HOME` 与 `mvn` 实际使用的 JDK 可能不同,报 `Unsupported class file major version` 时按 `mvn -v` 显示的 JDK 判断。
383
382
  - **依赖坐标**:`com.esri.geometry:esri-geometry-api:2.2.4` 是 Maven Central 最新(2020-09 发布);上游 2.3.1(2026-10-09)未发布到 Central。先 `mvn dependency:get -Dartifact=com.esri.geometry:esri-geometry-api:2.2.4` 确认可解析,解析失败时报告“依赖不可下载”,不要自行改成 2.3.1 或别处坐标。
384
383
  - **离线与网络**:首次 `mvn` 会拉依赖,无网或私服缺包时报 `Could not resolve dependencies`;不要为绕过它去改 `settings.xml`、加未知仓库或降级版本,先向用户要可用镜像。
385
384
  - **验证产物**:写最小 main(或 JUnit)断言三件事——`geometryFromWkt` → `geometryToWkt` 往返等价、`GeometryEngine.buffer(poly, sr, 2.0)` 后 `getEnvelope()` 向外扩张、`geometryToGeoJson` 能被 `geoJsonToGeometry` 重新读入;`mvn -q -DskipTests package` 只证明能编译,不代表几何正确。