@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
@@ -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/>
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: geometry-api-java
3
- description: "Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in Java — spatial operations, JSON/GeoJSON/WKT I/O, geodesic calculations. Esri Geometry API for Java."
3
+ description: "Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in Java — GeometryEngine, com.esri.geometry:esri-geometry-api:2.2.4, WKT/WKB/GeoJSON/Esri JSON I/O, geodesic distance; also when GeometryEngine has no intersects or WKB method and you need OperatorFactoryLocal, or when 2.3.1 coordinates fail to resolve on Maven Central. Esri Geometry API for Java."
4
4
  tags:
5
5
  - java
6
6
  - geometry
@@ -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. 相交判断(算子调用)
@@ -378,21 +378,13 @@ if (hit) {
378
378
 
379
379
  ## AI 使用建议
380
380
 
381
- ### 推荐工作流
382
-
383
- 1. **创建几何对象**:使用 `Point`、`Polyline`、`Polygon` 等构造函数创建几何
384
- 2. **设置空间参考**:通过 `SpatialReference.create(wkid)` 指定坐标系
385
- 3. **空间运算**:优先使用 `GeometryEngine` 静态方法(线程安全、API 简洁);批量处理使用 `OperatorFactoryLocal` + `GeometryCursor`
386
- 4. **格式转换**:使用 `GeometryEngine.geometryToGeoJson()` / `geometryFromWkt()` 等方法进行 WKT、GeoJSON、Esri JSON 互转;WKB 通过 `OperatorImportFromWkb` / `OperatorExportToWkb` 算子
387
- 5. **大地测量**:经纬度距离使用 `GeometryEngine.geodesicDistanceOnWGS84()`(返回米);椭球面积/长度算子未对外公开,需要时改用 JTS / GeoTools
388
-
389
- ### 关键注意事项
390
-
391
- - **坐标系一致**:进行空间运算前,确保所有几何对象使用相同的 `SpatialReference`
392
- - **简化几何**:导入外部数据后,使用 `GeometryEngine.simplify()` 确保拓扑正确
393
- - **大地测量 vs 平面**:经纬度距离用 `geodesicDistanceOnWGS84()`;椭球面积/长度算子未公开,建议改用 JTS/GeoTools
394
- - **性能优化**:批量操作使用 `OperatorFactoryLocal` + `GeometryCursor`,而非逐个调用 `GeometryEngine` 静态方法
395
- - **线程安全**:`GeometryEngine` 静态方法是线程安全的;`Operator` 实例非线程安全
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 判断。
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 或别处坐标。
383
+ - **离线与网络**:首次 `mvn` 会拉依赖,无网或私服缺包时报 `Could not resolve dependencies`;不要为绕过它去改 `settings.xml`、加未知仓库或降级版本,先向用户要可用镜像。
384
+ - **验证产物**:写最小 main(或 JUnit)断言三件事——`geometryFromWkt` → `geometryToWkt` 往返等价、`GeometryEngine.buffer(poly, sr, 2.0)` 后 `getEnvelope()` 向外扩张、`geometryToGeoJson` 能被 `geoJsonToGeometry` 重新读入;`mvn -q -DskipTests package` 只证明能编译,不代表几何正确。
385
+ - **编译期陷阱**:`GeometryEngine` 没有 `intersects` 和 WKB 方法,分别用 `OperatorIntersects.local().execute(a, b, sr, null)` 与 `OperatorImportFromWkb`/`OperatorExportToWkb`;面积/长度用 `geometry.calculateArea2D()` / `calculateLength2D()`,不要去找 `getArea()`。
386
+ - **坐标与线程**:参与运算的几何必须带同一 `SpatialReference`;`GeometryEngine` 静态方法可并发调用,`Operator` 实例非线程安全,批量时用 `OperatorFactoryLocal` + `GeometryCursor` 并每线程持有自己的算子。
387
+ - **安全与权限**:`mvn` 会写 `~/.m2` 与工作区 `target/`,属预期行为;执行 `mvn install`/`deploy`、改动共享 `settings.xml` 或写入系统目录前先征得用户同意。
396
388
 
397
389
  ## 相关技能
398
390
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: geometry-api-net
3
- description: "Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in .NET/C# — spatial operations, JSON/GeoJSON/WKT I/O, geodesic calculations. Esri Geometry API for .NET."
3
+ description: "Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in .NET/C# — GeometryEngine, NuGet OpenGIS.Esri.Geometry.Core 1.0.9, WKT/EWKT, WKB, GeoJSON and Esri JSON I/O, System.Text.Json converters, geodesic distance; also for unclosed polygon rings, Geometry base-class casts after overlay, or the retired Esri/geometry-api-net repo. Esri Geometry API for .NET."
4
4
  tags:
5
5
  - dotnet
6
6
  - geometry
@@ -19,19 +19,18 @@ tags:
19
19
  >
20
20
  > **NuGet:** `OpenGIS.Esri.Geometry.Core`(最新 1.0.9,截至 2026-10)
21
21
  >
22
- > **注意:** 原 Esri 仓库(github.com/Esri/geometry-api-net)已不再维护(404)。此分支由 znlgis 社区维护,已重命名为 OpenGIS.Esri.Geometry。
23
- >
24
22
  > **许可证:** LGPL-2.1
25
- >
26
- > 本文件旨在帮助 AI 快速理解并使用 geometry-api-net 库进行空间几何开发。
23
+ >
24
+ > **注意:** 原 Esri 仓库(github.com/Esri/geometry-api-net)已停止维护(404);此分支由 znlgis 社区维护,包名与命名空间已改为 `OpenGIS.Esri.Geometry`。
27
25
 
28
26
  ## 概述
29
27
 
30
- 这是一个 .NET Standard 2.0 的空间几何计算库,提供 6 种几何类型、28 个空间运算算子(含 DE-9IM 驱动的 9 个谓词、多边形布尔运算、缓冲/简化/MakeValid 与大地测量)和 4 种序列化格式(WKT/EWKT、WKB/EWKB、GeoJSON、Esri JSON),核心引擎已与 PostGIS/GEOS 交叉验证。
28
+ 这是一个 .NET Standard 2.0 的空间几何计算库,提供 6 种几何类型(Point、MultiPoint、Line、Polyline、Polygon、Envelope)、35 个算子类(`Operators` 命名空间 27 个几何算子 + `IO` 命名空间 8 个读写算子,含 8 个 DE-9IM 谓词:Contains/Crosses/Disjoint/Equals/Intersects/Overlaps/Touches/Within)和 4 种序列化格式(WKT/EWKT、WKB/EWKB、GeoJSON、Esri JSON)。
31
29
 
32
- - **核心包**: `OpenGIS.Esri.Geometry.Core`
33
- - **JSON 扩展包**: `OpenGIS.Esri.Geometry.Json`
34
- - **许可证**: LGPL-2.1-only
30
+ - **核心包**:`OpenGIS.Esri.Geometry.Core`(`GeometryEngine` 提供 39 个静态便捷方法)
31
+ - **JSON 扩展包**:`OpenGIS.Esri.Geometry.Json`(System.Text.Json 转换器)
32
+ - **许可证**:LGPL-2.1-only
33
+ - **能力边界**:不提供 `MakeValid`,`Simplify` 只做抽稀、不修复自相交环;需要几何修复请在上游(GEOS/PostGIS/JTS)完成后再导入。
35
34
 
36
35
  ## 快速开始
37
36
 
@@ -166,6 +165,50 @@ result.IsRightSide // bool, 是否在多路径几何的右侧
166
165
 
167
166
  ---
168
167
 
168
+ ## 典型工作流
169
+
170
+ 端到端:WKT 读入 → 有效性校验 → 叠加分析 → 输出 GeoJSON 与 Esri JSON。
171
+
172
+ ```csharp
173
+ using OpenGIS.Esri.Geometry.Core;
174
+ using OpenGIS.Esri.Geometry.Core.Geometries;
175
+ using OpenGIS.Esri.Geometry.Core.IO;
176
+
177
+ // 1. 从 WKT 读入输入几何(环由库自动闭合)
178
+ Geometry parcel = GeometryEngine.GeometryFromWkt(
179
+ "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))");
180
+ Geometry zone = GeometryEngine.GeometryFromWkt(
181
+ "POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))");
182
+
183
+ // 2. 校验:先确认几何本身可用,不要拿 0 容差去"修复"
184
+ if (!parcel.IsValid() || !zone.IsValid())
185
+ throw new InvalidOperationException("输入几何无效,请先修正数据");
186
+
187
+ // 3. 叠加:求交集(5×5 的方形重叠区)
188
+ Geometry overlapArea = GeometryEngine.Intersection(parcel, zone);
189
+ bool intersects = GeometryEngine.Intersects(parcel, zone); // true
190
+ double area = GeometryEngine.Area(overlapArea); // 约 25(内部容差带来 1e-6 级误差)
191
+
192
+ // 4. 输出两种格式
193
+ string geoJson = GeometryEngine.GeometryToGeoJson(overlapArea);
194
+ string esriJson = EsriJsonExportOperator.Instance.Execute(overlapArea);
195
+
196
+ // 5. 回读校验:序列化再反序列化,几何应一致
197
+ Geometry roundTrip = GeometryEngine.GeometryFromGeoJson(geoJson);
198
+ bool same = GeometryEngine.Equals(overlapArea, roundTrip);
199
+ ```
200
+
201
+ **输出与验收**:
202
+
203
+ - `overlapArea` 是 `(5,5)-(10,10)` 的矩形,`GeometryEngine.Area()` 实测约 `24.999998`(默认容差 `1e-10` 下的浮点结果,不要断言严格等于 25)。
204
+ - `geoJson` 形如 `{"type":"Polygon","coordinates":[[[10,5],...]]}`;`esriJson` 形如 `{"rings":[[[10,5],...]]}`。
205
+ - `same` 必须为 `true`;若为 `false`,先检查环是否闭合、坐标顺序是否一致。
206
+ - `GeometryEngine.Simplify(geometry, tolerance)` 的 `tolerance` 必须为正,传 `0.0` 会抛 `ArgumentException: Tolerance must be positive`;且 `Simplify` 只做抽稀,不保证把自相交环修成有效面,需修复无效数据请在上游处理。
207
+
208
+ > 注意:集合运算返回 `Geometry` 基类,需要面积/环等具体成员时按实际类型(`Polygon`/`Polyline`)转型后再用。
209
+
210
+ ---
211
+
169
212
  ## 常见开发场景
170
213
 
171
214
  ### 场景 1:判断点是否在多边形内
@@ -304,37 +347,31 @@ dotnet run --project samples/OpenGIS.Esri.Geometry.Samples
304
347
 
305
348
  ---
306
349
 
307
- ## AI 使用建议
308
-
309
- ### 推荐工作流
310
-
311
- 1. **创建几何对象**:使用 `Point`、`Polyline`、`Polygon` 等构造函数创建几何
312
- 2. **空间运算**:优先使用 `GeometryEngine` 静态方法(API 最简洁);需要精细控制时使用 `Operator.Instance` 单例模式
313
- 3. **格式转换**:使用 `GeometryEngine.GeometryToGeoJson()` / `GeometryFromWkt()` 等方法进行 WKT、WKB、GeoJSON、Esri JSON 互转
314
- 4. **大地测量**:对地理坐标的距离/面积计算,使用 `GeometryEngine.GeodesicDistance()` / `GeodesicArea()`
315
- 5. **序列化集成**:使用 `OpenGIS.Esri.Geometry.Json.Converters` 命名空间的 `System.Text.Json` 转换器
316
-
317
- ### 关键注意事项
318
-
319
- - **Polygon 环必须闭合**:首尾点必须相同
320
- - **返回类型需转换**:集合运算返回 `Geometry` 基类,需根据实际类型做类型转换
321
- - **大地测量基于 WGS84**:`GeodesicDistance` 使用 Vincenty 公式
322
- - **GeoJSON 导出规则**:单路径 Polyline 导出为 `LineString`,多路径导出为 `MultiLineString`
323
- - **Operator 使用 Lazy 单例**:所有 Operator 类通过 `Instance` 属性获取单例实例
324
-
325
350
  ## 常见问题
326
351
 
327
352
  | 问题 | 解决 |
328
353
  |------|------|
329
354
  | NuGet 安装后找不到命名空间 | 同时安装 `OpenGIS.Esri.Geometry.Core` 与(可选)`OpenGIS.Esri.Geometry.Json`;命名空间为 `OpenGIS.Esri.Geometry.Core.*` |
330
- | Polygon 面积 / 包含判断异常 | 环必须闭合(首尾点相同),可先用 `GeometryEngine.Simplify` 修复 |
331
- | 浮点坐标比较误差 | 内部容差 `GeometryConstants.DefaultTolerance`(1e-10),为内部常量、不可外部配置 |
355
+ | Polygon 面积 / 包含判断异常 | 环必须闭合(首尾点相同);注意 `IsValid()` 对自相交环较宽松,可能返回 true |
356
+ | `Simplify` 抛 `ArgumentException: Tolerance must be positive` | 容差必须为正,不能传 `0.0`;`Simplify` 只抽稀,不修复自相交 |
357
+ | 浮点坐标比较误差 | 内部容差 `GeometryConstants.DefaultTolerance`(1e-10),为内部常量、不可外部配置;面积等断言用近似比较 |
332
358
  | 集合运算返回值类型不符预期 | 返回 `Geometry` 基类,需按实际类型做类型转换后使用 |
333
359
  | 无法 `new` 算子实例 | 所有 Operator 类通过 `Instance` 属性获取 Lazy 单例 |
334
360
  | 修改 `GetRing()` / `GetPath()` 结果报错 | 返回 `IReadOnlyList<Point>` 只读视图,需要复制后修改 |
335
361
  | `GeodesicDistance` 结果异常 | 基于 WGS84(Vincenty 公式),输入必须是经纬度坐标;`GeodesicArea` 使用球面超量公式 |
336
362
  | GeoJSON 导出类型与预期不符 | 单路径 Polyline 导出为 `LineString`,多路径导出为 `MultiLineString`;Envelope 导出为 `Polygon` |
337
363
 
364
+ ## AI 使用建议
365
+
366
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/geometry-types.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
367
+ - **执行环境**:先 `dotnet --version`(库目标 `netstandard2.0`,可被 net6/net8/net9/net10 引用);Windows 上用 PowerShell 执行 `dotnet` 命令,`dotnet new console -o demo && cd demo` 建最小工程。
368
+ - **依赖坐标**:`dotnet add package OpenGIS.Esri.Geometry.Core --version 1.0.9`(NuGet 最新 1.0.9,2026-09-21),需要 `System.Text.Json` 转换器时再装 `OpenGIS.Esri.Geometry.Json`;还原失败报 `NU1101` 说明源或版本不可用,报告“依赖不可下载”,不要自己编版本号。
369
+ - **验证产物**:最小控制台程序断言三件事——`GeometryEngine.GeometryFromWkt` → `GeometryToWkt` 往返、`GeometryEngine.Contains(polygon, point)` 返回 true、`GeometryEngine.Buffer(point, 5.0).GetEnvelope()` 为 (XMin=5,YMin=15,XMax=15,YMax=25),再 `dotnet run` 看实际输出;`dotnet build` 成功不代表几何结果正确。
370
+ - **构建与测试**:`dotnet build` 编译、`dotnet test` 跑 xUnit、`dotnet run --project samples/OpenGIS.Esri.Geometry.Samples` 跑示例(需在仓库 checkout 内,且该路径存在);输出在 `bin/`、`obj/`,不要提交。
371
+ - **编译期陷阱**:`Polygon.AddRing` 必须闭合(首尾点相同)否则面积/包含判断异常;集合运算返回 `Geometry` 基类,要按 `Point`/`Polygon` 转型后再用;容差 `GeometryConstants.DefaultTolerance`(1e-10)是内部常量,无法外部调整。
372
+ - **大地测量前提**:`GeodesicDistance`/`GeodesicArea` 基于 WGS84(Vincenty),输入必须是经纬度;对投影坐标(如 EPSG:3857 米制)调用会得到无意义结果。
373
+ - **安全与权限**:`dotnet restore` 需访问 NuGet 源,离线时先确认本地缓存;修改全局 `NuGet.config`、安装 SDK 或写入系统目录前先征得用户同意,命令输出里不要回显私有源凭据。
374
+
338
375
  ## 相关技能
339
376
 
340
377
  - **nettopologysuite** — .NET JTS 移植(几何计算核心):[../nettopologysuite/SKILL.md](../nettopologysuite/SKILL.md)