@dsh-gis/dsh-opengis-skill 0.3.0 → 0.5.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 (86) hide show
  1. package/CHANGELOG.md +89 -1
  2. package/README.md +78 -21
  3. package/adaptations/brutile.md +19 -6
  4. package/adaptations/cesiumjs.md +14 -5
  5. package/adaptations/common.md +49 -16
  6. package/adaptations/deck-gl.md +19 -6
  7. package/adaptations/duckdb-spatial.md +20 -6
  8. package/adaptations/gdal-api.md +24 -6
  9. package/adaptations/gdal.md +22 -6
  10. package/adaptations/geolibre.md +20 -6
  11. package/adaptations/geometry-api-java.md +14 -6
  12. package/adaptations/geometry-api-net.md +17 -6
  13. package/adaptations/geonode.md +17 -6
  14. package/adaptations/geopandas.md +21 -6
  15. package/adaptations/geopipe-agent.md +21 -6
  16. package/adaptations/geos.md +23 -0
  17. package/adaptations/geoserver-cloud.md +17 -6
  18. package/adaptations/geoserver-rest-api.md +17 -6
  19. package/adaptations/geoserver.md +18 -6
  20. package/adaptations/geotools.md +19 -6
  21. package/adaptations/grass-gis.md +24 -6
  22. package/adaptations/jts.md +18 -6
  23. package/adaptations/kepler-gl.md +18 -5
  24. package/adaptations/leaflet.md +25 -6
  25. package/adaptations/mapbox-gl-js.md +23 -6
  26. package/adaptations/maplibre-gl-js.md +20 -0
  27. package/adaptations/maplibre-native.md +19 -0
  28. package/adaptations/mapserver.md +22 -6
  29. package/adaptations/mapsui.md +22 -6
  30. package/adaptations/nettopologysuite.md +19 -6
  31. package/adaptations/opendronemap.md +21 -0
  32. package/adaptations/opengis-all.md +16 -5
  33. package/adaptations/opengis-daf.md +16 -5
  34. package/adaptations/opengis-utils-for-java.md +20 -6
  35. package/adaptations/opengis-utils-for-net.md +23 -6
  36. package/adaptations/openlayers.md +20 -6
  37. package/adaptations/pdal.md +26 -6
  38. package/adaptations/postgis.md +20 -6
  39. package/adaptations/proj.md +20 -6
  40. package/adaptations/projnet4geoapi.md +21 -6
  41. package/adaptations/pyqgis.md +18 -6
  42. package/adaptations/qgis-process.md +21 -6
  43. package/adaptations/qgis-server.md +18 -6
  44. package/adaptations/shapely.md +22 -6
  45. package/adaptations/sharpmap.md +19 -6
  46. package/adaptations/spatialite.md +23 -6
  47. package/adaptations/stac-cog-titiler.md +23 -0
  48. package/adaptations/whitebox-tools.md +19 -6
  49. package/assets/deck-gl/SKILL.md +1 -0
  50. package/assets/duckdb-spatial/SKILL.md +36 -13
  51. package/assets/gdal/SKILL.md +6 -6
  52. package/assets/gdal-api/SKILL.md +2 -2
  53. package/assets/geolibre/SKILL.md +1 -0
  54. package/assets/geonode/SKILL.md +3 -3
  55. package/assets/geopandas/SKILL.md +42 -8
  56. package/assets/geopandas/reference/core-api.md +51 -0
  57. package/assets/geos/SKILL.md +372 -0
  58. package/assets/geoserver/SKILL.md +1 -1
  59. package/assets/geoserver-cloud/SKILL.md +0 -2
  60. package/assets/grass-gis/SKILL.md +31 -7
  61. package/assets/kepler-gl/SKILL.md +1 -0
  62. package/assets/leaflet/SKILL.md +2 -2
  63. package/assets/mapbox-gl-js/SKILL.md +1 -0
  64. package/assets/maplibre-gl-js/SKILL.md +478 -0
  65. package/assets/maplibre-native/SKILL.md +383 -0
  66. package/assets/mapserver/SKILL.md +7 -5
  67. package/assets/mapsui/SKILL.md +4 -2
  68. package/assets/opendronemap/SKILL.md +309 -0
  69. package/assets/opengis-all/SKILL.md +1 -0
  70. package/assets/pdal/SKILL.md +9 -1
  71. package/assets/projnet4geoapi/SKILL.md +1 -1
  72. package/assets/shapely/SKILL.md +24 -4
  73. package/assets/shapely/reference/operations-reference.md +30 -0
  74. package/assets/spatialite/SKILL.md +8 -2
  75. package/assets/stac-cog-titiler/SKILL.md +420 -0
  76. package/assets/whitebox-tools/SKILL.md +20 -4
  77. package/lib/adaptations.d.ts +22 -1
  78. package/lib/adaptations.js +166 -20
  79. package/lib/index.d.ts +13 -9
  80. package/lib/index.js +58 -12
  81. package/lib/taxonomy.d.ts +41 -0
  82. package/lib/taxonomy.js +332 -0
  83. package/locale/en.json +1 -1
  84. package/locale/zh.json +1 -1
  85. package/package.json +10 -4
  86. package/upstream.json +36 -26
@@ -0,0 +1,309 @@
1
+ ---
2
+ name: opendronemap
3
+ description: "Use when turning drone/aerial imagery into orthophotos, DSM/DTM, point clouds or 3D Tiles with OpenDroneMap — odm CLI via docker run --project-path, --dsm --dtm --orthophoto-resolution --pc-quality --3d-tiles, WebODM 4.0.0 compose, /api/token-auth/ and /api/projects/{id}/tasks, pyodm Node('localhost',3000); also for 'odm_orthophoto.tif' outputs and out-of-memory failures."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "photogrammetry, drone, orthophoto, point-cloud, dsm, dtm, 3d-tiles, webodm, docker, gis"
8
+ ---
9
+
10
+ > **项目地址:** <https://github.com/OpenDroneMap/ODM>(CLI/引擎)、<https://github.com/OpenDroneMap/WebODM>(Web 平台)
11
+ >
12
+ > **官方文档:** <https://docs.opendronemap.org/>(ODM)· <https://docs.webodm.org/>(WebODM)
13
+ >
14
+ > **最新版本:** ODM **3.6.2**(2026-08-12,[GitHub Releases](https://github.com/OpenDroneMap/ODM/releases);镜像 `opendronemap/odm:3.6.2`,2026-08-13 推送);WebODM **4.0.0**(2026-11-05,[GitHub Releases](https://github.com/OpenDroneMap/WebODM/releases);镜像 `webodm/webodm_webapp:4.0.0`,2026-11-04 推送);NodeODM **3.6.2**(镜像 `opendronemap/nodeodm:3.6.2`)(截至 2026-11)
15
+ >
16
+ > **运行环境:** Docker(Linux 推荐,Windows 原生安装包亦可);WebODM 4.0.0 栈为 Python 3.14、PostgreSQL 18、Valkey 9.1、Ubuntu 24.04
17
+ >
18
+ > **许可证:** AGPL-3.0(ODM 与 WebODM)
19
+ >
20
+ > **配套客户端:** PyODM 1.5.13(PyPI `pyodm`,通过 NodeODM REST API 提交任务)
21
+
22
+ ## 概述
23
+
24
+ OpenDroneMap(ODM)是一套完全开源的无人机航空摄影测量流水线:给一个装满照片的目录,它输出带地理坐标的正射影像、数字表面模型、点云与纹理三维模型。它把 SfM 空三(OpenSfM)、稠密匹配(OpenMVS)、网格重建、纹理映射与地理配准串成一条可复现的命令行流水线,是商业航测软件(Pix4D、Metashape)之外成本最低的替代路线。
25
+
26
+ 生态由四个组件构成,选择取决于你要「一次性出图」还是「长期运营一个出图平台」:
27
+
28
+ - **ODM(引擎/CLI)** — 真正干活的部分,一个 Docker 镜像 + 一组命令行参数,产物落在项目目录
29
+ - **NodeODM** — 把 ODM 包成 REST 任务队列服务(默认 3000 端口),可多机分布式
30
+ - **WebODM** — Django 前端:项目管理、任务队列、2D/3D 查看器、量测与 GCP 界面,底层通过 NodeODM 调度
31
+ - **PyODM** — Python 客户端,直接对 NodeODM API 编程,适合把航测接进已有系统
32
+
33
+ **与相邻技术的差异:** GDAL/PDAL 处理的是「已经有坐标的数据」,ODM 解决的是「只有照片,如何得到有坐标的数据」——它内部确实会调用 GDAL/PROJ 做地理配准与 GeoTIFF 写出,但入口是影像而非矢量/点云。
34
+
35
+ ## 环境准备
36
+
37
+ ### 方式一:Docker 跑 ODM CLI(推荐,最省事)
38
+
39
+ 无需安装任何摄影测量依赖,镜像内已含 OpenSfM、OpenMVS、Entwine、PDAL、GDAL 等全部组件。目录约定是硬性的:项目目录下必须有一个名为 `images` 的子目录,否则流水线找不到输入。
40
+
41
+ ```bash
42
+ # 目录结构:/datasets/<项目名>/images/*.jpg
43
+ docker run -ti --rm \
44
+ -v /home/user/datasets:/datasets \
45
+ opendronemap/odm \
46
+ --project-path /datasets my_project
47
+ ```
48
+
49
+ ```powershell
50
+ # Windows PowerShell(路径用正斜杠,避免反斜杠被当转义)
51
+ docker run -ti --rm -v c:/Users/user/datasets:/datasets opendronemap/odm --project-path /datasets my_project
52
+ ```
53
+
54
+ 固定版本比追 latest 更可靠:把 `opendronemap/odm` 换成 `opendronemap/odm:3.6.2`。需要 GPU 加速 SIFT 特征提取时用 `opendronemap/odm:gpu`(或 `opendronemap/odm:3.6.2-gpu`)并加 `--gpus all`。
55
+
56
+ ### 方式二:WebODM 平台(需要界面/多人协作时)
57
+
58
+ WebODM 4.0.0 官方仓库自带 `webodm.sh` 管理脚本,它会拉取 `webodm/webodm_webapp:4.0.0`、`webodm/webodm_db:18` 与 Valkey broker:
59
+
60
+ ```bash
61
+ git clone https://github.com/OpenDroneMap/WebODM.git
62
+ cd WebODM
63
+
64
+ ./webodm.sh start # 默认 http://localhost:8000
65
+ ./webodm.sh --port 8000 --hostname localhost start
66
+ ./webodm.sh --gpu start # Linux:挂 GPU 处理节点
67
+ ```
68
+
69
+ ```bash
70
+ ./webodm.sh stop # 停止容器
71
+ ./webodm.sh down # 停止并删除容器(数据卷保留)
72
+ ./webodm.sh liveupdate # 不停止服务地升级到最新发布
73
+ ```
74
+
75
+ 首次启动会创建管理员账号 `admin`(密码在控制台输出,或首次登录时设置)。`.env` 里的 `WO_PORT`(默认 8000)、`WO_HOST`、`WO_MEDIA_DIR`、`WO_DB_DIR` 决定端口与数据落盘位置,改完重启生效。
76
+
77
+ ### 方式三:原生安装与 Python 客户端
78
+
79
+ - **Windows**:从 ODM Releases 下载 setup 安装包,打开 ODM Console 后执行 `run C:\path\to\project --dsm`,无需 Docker
80
+ - **PyODM 客户端**:`pip install -U pyodm`,用于对 NodeODM 编程提交任务
81
+
82
+ ```bash
83
+ # 起一个本地 NodeODM 处理节点(默认 3000 端口)
84
+ docker run -ti -p 3000:3000 opendronemap/nodeodm:3.6.2
85
+ ```
86
+
87
+ ### 验证
88
+
89
+ ```bash
90
+ docker run --rm opendronemap/odm:3.6.2 --version # 打印 ODM 版本
91
+ curl -s http://localhost:3000/info # NodeODM 节点信息(version、queueCount、maxImages)
92
+ curl -s http://localhost:8000/api/ # WebODM API 根(返回带 version 的 JSON)
93
+ ```
94
+
95
+ ## 核心命令
96
+
97
+ ### ODM CLI 常用参数
98
+
99
+ ```bash
100
+ docker run -ti --rm -v /datasets:/datasets opendronemap/odm:3.6.2 \
101
+ --project-path /datasets my_project \
102
+ --dsm \
103
+ --orthophoto-resolution 2 \
104
+ --pc-quality high
105
+ ```
106
+
107
+ | 参数 | 默认值 | 作用 |
108
+ |------|--------|------|
109
+ | `--project-path <path>` | 必填 | 项目父目录;每个子目录是一个数据集,内含 `images/` |
110
+ | `--dsm` / `--dtm` | 关闭 | 生成数字表面模型 / 数字地形模型(不传就**没有** DEM 产物) |
111
+ | `--orthophoto-resolution <float>` | 5 | 正射影像地面分辨率(cm/px),值越小越精细也越慢 |
112
+ | `--dem-resolution <float>` | 5 | DSM/DTM 分辨率(cm/px) |
113
+ | `--pc-quality <ultra|high|medium|low|lowest>` | medium | 点云质量,直接决定稠密匹配耗时 |
114
+ | `--feature-quality <...>` | high | 特征提取质量(SIFT) |
115
+ | `--fast-orthophoto` | 关闭 | 跳过稠密重建与三维模型,只出 2D 正射(航拍平地区域首选) |
116
+ | `--skip-3dmodel` | 关闭 | 保留点云与正射,但跳过纹理三维模型 |
117
+ | `--3d-tiles` | 关闭 | 额外输出 OGC 3D Tiles(`3d_tiles/`,供 Cesium 等加载) |
118
+ | `--cog` | 关闭 | 输出 Cloud-Optimized GeoTIFF 而非普通 GeoTIFF |
119
+ | `--auto-boundary` | 关闭 | 用相机航迹自动裁掉重建范围外的噪声 |
120
+ | `--gcp <path>` | 无 | 控制点文件,用于提升绝对精度 |
121
+ | `--geo <path>` | 无 | 手动指定影像地理定位(无 EXIF/GPS 时) |
122
+ | `--mesh-size <int>` | 200000 | 三维网格面数上限,越大越精细 |
123
+ | `--max-concurrency <int>` | CPU 核数 | 并行任务数,内存不足时调小 |
124
+ | `--rerun <stage>` | 无 | 只重跑指定阶段并停止(改参数重算时省时间) |
125
+ | `--copy-to <path>` | 无 | 处理完成后把结果目录复制到此路径 |
126
+
127
+ ### 常用预设组合
128
+
129
+ ```bash
130
+ # 1) 快速正射(应急出图、只做 2D)
131
+ docker run -ti --rm -v /datasets:/datasets opendronemap/odm:3.6.2 \
132
+ --project-path /datasets my_project --fast-orthophoto --orthophoto-resolution 3
133
+
134
+ # 2) 标准测绘产物:正射 + DSM + DTM
135
+ docker run -ti --rm -v /datasets:/datasets opendronemap/odm:3.6.2 \
136
+ --project-path /datasets my_project --dsm --dtm --cog --auto-boundary
137
+
138
+ # 3) 带三维与 3D Tiles(数字孪生/Web 发布)
139
+ docker run -ti --rm -v /datasets:/datasets opendronemap/odm:3.6.2 \
140
+ --project-path /datasets my_project --dsm --3d-tiles --pc-quality high
141
+
142
+ # 4) 带控制点的高精度成果
143
+ docker run -ti --rm -v /datasets:/datasets opendronemap/odm:3.6.2 \
144
+ --project-path /datasets my_project --gcp /datasets/my_project/gcp_list.txt --dsm --dtm
145
+ ```
146
+
147
+ ### 产物目录
148
+
149
+ ODM 把每个阶段的结果留在项目目录下,交付时按需取用:
150
+
151
+ ```text
152
+ my_project/
153
+ ├── images/ # 输入照片
154
+ ├── opensfm/ # 空三:相机位姿与连接点
155
+ ├── odm_georeferencing/
156
+ │ └── odm_georeferenced_model.laz # 带坐标的点云(--pc-las 可出 .las)
157
+ ├── odm_dem/
158
+ │ ├── dsm.tif # 仅 --dsm 时生成
159
+ │ └── dtm.tif # 仅 --dtm 时生成
160
+ ├── odm_orthophoto/
161
+ │ ├── odm_orthophoto.tif # 正射影像 GeoTIFF
162
+ │ └── odm_orthophoto.original.tif # 未裁切版本
163
+ ├── odm_texturing/
164
+ │ ├── odm_textured_model.obj # 纹理模型(局部坐标)
165
+ │ └── odm_textured_model_geo.obj # 带地理坐标的纹理模型
166
+ ├── odm_report/ # 质量报告(PDF/HTML)
167
+ ├── 3d_tiles/ # 仅 --3d-tiles 时生成
168
+ ├── orthophoto_tiles/ dsm_tiles/ dtm_tiles/ # --tiles 时生成的瓦片
169
+ └── entwine_pointcloud/ # Entwine 点云索引(供 Potree 浏览)
170
+ ```
171
+
172
+ > 交付前先确认 `odm_report/` 里的重叠度与重投影误差:重叠度不足或空三失败时,后面的正射与 DSM 即使生成也不可信。
173
+
174
+ ### WebODM REST API
175
+
176
+ WebODM 的 API 与 ODM 引擎解耦,可用任意 HTTP 客户端驱动。认证走 JWT:
177
+
178
+ ```bash
179
+ # 1) 换 token(返回 {"token": "..."})
180
+ TOKEN=$(curl -s -X POST http://localhost:8000/api/token-auth/ \
181
+ -H "Content-Type: application/json" \
182
+ -d '{"username":"admin","password":"<password>"}' | python -c "import json,sys;print(json.load(sys.stdin)['token'])")
183
+
184
+ # 2) 建项目 → 建任务(上传影像 zip 或逐张 multipart)
185
+ curl -s -X POST http://localhost:8000/api/projects/ \
186
+ -H "Authorization: JWT $TOKEN" -H "Content-Type: application/json" \
187
+ -d '{"name":"my_project"}'
188
+
189
+ curl -s -X POST http://localhost:8000/api/projects/1/tasks/ \
190
+ -H "Authorization: JWT $TOKEN" \
191
+ -F "images=@images.zip" \
192
+ -F "options={\"dsm\": true, \"orthophoto-resolution\": 2}"
193
+
194
+ # 3) 查任务状态(status: 10 排队 / 20 运行 / 30 失败 / 40 完成 / 50 取消)
195
+ curl -s http://localhost:8000/api/projects/1/tasks/1/ -H "Authorization: JWT $TOKEN"
196
+ ```
197
+
198
+ 成果通过固定路径取用:`/api/projects/{pid}/tasks/{tid}/orthophoto/tiles.json`(瓦片元数据)、`.../orthophoto/tiles/{z}/{x}/{y}.png`(瓦片)、`.../download/{asset}`(原始成果下载)、`.../assets/...`(单项资产)。把 `orthophoto` 换成 `dsm`、`dtm` 即可取高程瓦片,可直接喂给 Leaflet / OpenLayers / Cesium。
199
+
200
+ ### PyODM:直接对 NodeODM 编程
201
+
202
+ ```python
203
+ from pyodm import Node
204
+
205
+ node = Node("localhost", 3000)
206
+ task = node.create_task(
207
+ ["images/1.jpg", "images/2.jpg"],
208
+ {"dsm": True, "orthophoto-resolution": 2},
209
+ name="demo",
210
+ )
211
+ task.wait_for_completion() # 阻塞直到完成或失败
212
+ assets = task.download_assets("results")
213
+ print(assets) # 含 odm_orthophoto、odm_dem 等目录
214
+ ```
215
+
216
+ ## 典型工作流
217
+
218
+ ### 工作流一:一段视频 / 一批照片 → 正射 + DSM 交付
219
+
220
+ **输入**:一次航飞的 JPG(带 GPS EXIF),或一段航拍视频抽帧后的图片序列。
221
+
222
+ 1. **检查输入**:照片带 GPS 且覆盖率足够(航向重叠 ≥ 70%、旁向 ≥ 60%),删掉糊片与地面随手拍,否则空三会失败
223
+ 2. **组织目录**:`/datasets/my_project/images/*.jpg`
224
+ 3. **先跑快速版确认数据可用**:加 `--fast-orthophoto --orthophoto-resolution 5`,十几分钟就能看出空三是否成立
225
+ 4. **再跑正式版**:`--dsm --dtm --cog --auto-boundary --pc-quality high`
226
+ 5. **验收**:`odm_report/` 看重叠度与重投影误差,用 `gdalinfo` 核对正射影像的 CRS 与分辨率
227
+
228
+ ```bash
229
+ # 第 5 步验收
230
+ gdalinfo -json /datasets/my_project/odm_orthophoto/odm_orthophoto.tif \
231
+ | python -c "import json,sys;d=json.load(sys.stdin);print(d['size'], d['coordinateSystem']['wkt'][:60], d['geoTransform'])"
232
+ gdalinfo -stats /datasets/my_project/odm_dem/dsm.tif | grep -E 'Minimum|Maximum'
233
+ ```
234
+
235
+ ### 工作流二:成果入库并发布为 OGC 服务
236
+
237
+ ODM 的 GeoTIFF 与点云要真正「可用」,还需接进既有 GIS 栈:
238
+
239
+ 1. **正射影像 → COG**(已是 `--cog` 时可跳过):`gdal_translate -of COG odm_orthophoto.tif ortho_cog.tif`
240
+ 2. **DSM/DTM → PostGIS 栅格**:`raster2pgsql -s <SRID> -I -C -M -t 256x256 dsm.tif public.dsm | psql -d gisdb`
241
+ 3. **点云 → PDAL 清洗/重投影**:`pdal translate odm_georeferenced_model.laz clean.laz outlier` 再去分类与抽稀
242
+ 4. **三维成果 → 3D Tiles 上云**:用 `--3d-tiles` 的 `3d_tiles/` 直接由 CesiumJS 加载
243
+
244
+ ```bash
245
+ gdalinfo -json odm_dem/dsm.tif | python -c "import json,sys;print(json.load(sys.stdin)['coordinateSystem']['wkt'][:120])"
246
+ # 用上面的 SRID(或 EPSG 码)替换下面的 <SRID>
247
+ raster2pgsql -s <SRID> -I -C -M -t 256x256 odm_dem/dsm.tif public.dsm_gen | psql -d gisdb
248
+ ```
249
+
250
+ ### 工作流三:WebODM 平台化批量作业
251
+
252
+ **场景**:一个团队要反复出图,需要项目管理、权限与在线查看器。
253
+
254
+ 1. `./webodm.sh start` 起平台,登录后先在「Processing Nodes」确认自带 ODM 节点在线
255
+ 2. 建项目 → 上传影像 zip → 选质量预设(Default / High Resolution / Fast Orthophoto)→ 提交
256
+ 3. 任务详情页看日志与进度;失败时读 `Task Output` 里的最后一段 Traceback
257
+ 4. 出图后在 2D 查看器量距/量面,3D 查看器看纹理模型;成果用 `Download` 打包全部资产
258
+ 5. 批量脚本化时改用 API(见上文 REST 小节)或 PyODM,不要靠点界面
259
+
260
+ ### 工作流四:只重算某一阶段
261
+
262
+ 改了某个参数不想从头跑(SfM 可能花掉一半时间)时,用 `--rerun` 指定阶段:
263
+
264
+ ```bash
265
+ docker run -ti --rm -v /datasets:/datasets opendronemap/odm:3.6.2 \
266
+ --project-path /datasets my_project --rerun odm_meshing --mesh-size 400000
267
+ ```
268
+
269
+ ## 常见问题
270
+
271
+ | 报错 / 现象 | 原因 | 处置 |
272
+ |------|------|------|
273
+ | `No images found in .../images` | 项目目录下没有 `images/` 子目录,或照片放在 `--project-path` 直下 | 严格按 `<project-path>/<dataset>/images/` 组织;`--project-path` 传父目录、末尾再跟数据集名 |
274
+ | 空三阶段失败、`Not enough images` / 大量未注册影像 | 重叠度不足、影像过糊、曝光差异过大,或照片缺少时间戳 | 提高航向/旁向重叠度重飞;删糊片;必要时加 `--matcher-type bruteforce` 或 `--feature-quality ultra` |
275
+ | 容器被 OOM killer 杀掉(退出码 137) | `--pc-quality ultra` 叠加高分辨率影像超出可用内存 | 降 `--pc-quality`、调小 `--max-concurrency`、加 `--split` 分块,或换更大内存机器 |
276
+ | 产物坐标在几千公里外 / 与底图对不上 | 影像 EXIF 的 GPS 有系统偏移,或缺 GCP | 用 `--gcp` 提供控制点;检查 EXIF 是否真的是 WGS84;`--gps-accuracy` 可放宽对 GPS 的信任 |
277
+ | 正射影像是空白 / 被裁成一条 | `--auto-boundary` 在影像不足时收缩过度,或空三只注册了少数影像 | 先去掉 `--auto-boundary` 看完整范围,再决定是否加回 |
278
+ | 没有 `dsm.tif` / `dtm.tif` | 没传 `--dsm` / `--dtm`,默认不生成 DEM | 明确加 `--dsm`、`--dtm`;只做 2D 的 `--fast-orthophoto` 也不产 DEM |
279
+ | `3d_tiles/` 目录不存在 | 没传 `--3d-tiles`,或该阶段被 `--rerun`/`--end-with` 提前截断 | 加 `--3d-tiles` 并确认 `--end-with` 未停在 `odm_postprocess` 之前 |
280
+ | Windows 下 `-v c:\data:/datasets` 挂载失败 | 反斜杠被 shell 转义,或 Docker Desktop 未共享该盘 | 用 `c:/data:/datasets` 正斜杠;在 Docker Desktop 里共享对应盘符 |
281
+ | WebODM 上传后任务一直排队 | 没有可用的 Processing Node,或节点已被占用 | 在 Processing Nodes 页面确认节点是绿色在线;`docker logs` 看 nodeodm 容器 |
282
+ | WebODM 接口返回 401 | 用了 Basic Auth 而非 JWT,或 token 过期 | 先 `POST /api/token-auth/` 取 token,请求头写 `Authorization: JWT <token>`,过期用 `/api/token-auth/refresh/` 换新 |
283
+
284
+ ## AI 使用建议
285
+
286
+ - **先判断产物需求**:只要正射就用 `--fast-orthophoto`(快数倍);要 DEM 必须显式加 `--dsm`/`--dtm`;要 Web 三维再加 `--3d-tiles`。不要默认把所有开关都打开——三维与超高质点云是主要耗时来源。
287
+ - **先探环境再动手**:`docker --version`、`docker run --rm opendronemap/odm:3.6.2 --version`;宿主机内存与磁盘要先确认(中间文件常达原图数倍),磁盘不足会在纹理阶段失败得很难看。
288
+ - **先快速跑通再上正式参数**:用 3–5 张照片或 `--fast-orthophoto` 跑一次端到端,确认挂载路径与目录结构正确,再换成正式参数,避免跑几小时后才发现 `images/` 放错位置。
289
+ - **验证产物而不是只看退出码**:`odm_orthophoto/odm_orthophoto.tif` 用 `gdalinfo` 核对 CRS/尺寸;`odm_dem/*.tif` 用 `-stats` 看高程范围是否合理;点云用 PDAL `info` 看点数与 SRS;`odm_report/` 的重投影误差是质量判据。
290
+ - **失败信号优先级**:容器退出码 137 是 OOM(先降 `--pc-quality`);空三失败几乎都是数据问题(重叠度、糊片、GPS),改参数救不回来;WebODM 任务卡住先查 Processing Node 而不是重装平台。
291
+ - **版本与可复现**:把镜像标签写死为 `opendronemap/odm:3.6.2` / `webodm/webodm_webapp:4.0.0`,不要只用 `latest`;不同 ODM 版本的默认参数与产物目录结构会变,复现旧项目时记录版本号。
292
+ - **安全与权限**:WebODM 的 `admin` 凭据、`WO_SECRET_KEY`、JWT token 不要写进脚本或回显到报告;`./webodm.sh down`、删项目、`--rerun` 覆盖已有产物均不可逆,执行前向用户确认;无人机影像可能涉及测绘资质与隐私,外传前确认合规。
293
+
294
+ ## 相关技能
295
+
296
+ - **pdal** — 点云清洗、分类与重投影,处理 ODM 输出的 `.laz`:[../pdal/SKILL.md](../pdal/SKILL.md)
297
+ - **gdal** — 正射影像/DSM 的 COG 转换、裁剪与栅格入库:[../gdal/SKILL.md](../gdal/SKILL.md)
298
+ - **cesiumjs** — 加载 `--3d-tiles` 产出的 OGC 3D Tiles 做 Web 三维发布:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
299
+ - **postgis** — DSM/DTM 与矢量成果入库、空间查询与瓦片服务:[../postgis/SKILL.md](../postgis/SKILL.md)
300
+
301
+ ## 参考资源
302
+
303
+ - **ODM 官方文档:** <https://docs.opendronemap.org/> | [全部参数](https://docs.opendronemap.org/arguments/) | [产出说明](https://docs.opendronemap.org/outputs/) | [安装](https://docs.opendronemap.org/installation/)
304
+ - **WebODM 文档:** <https://docs.webodm.org/> | [API Quickstart](https://docs.webodm.org/api/quickstart/) | [认证](https://docs.webodm.org/api/authentication/)
305
+ - **PyODM 文档:** <https://pyodm.readthedocs.io/>
306
+ - **源码:** [ODM](https://github.com/OpenDroneMap/ODM) | [WebODM](https://github.com/OpenDroneMap/WebODM) | [NodeODM](https://github.com/OpenDroneMap/NodeODM) | [pyodm](https://github.com/OpenDroneMap/pyodm)
307
+ - **GCP 与控制点:** <https://docs.opendronemap.org/gcp/>
308
+ - **镜像:** [opendronemap/odm](https://hub.docker.com/r/opendronemap/odm) | [opendronemap/nodeodm](https://hub.docker.com/r/opendronemap/nodeodm) | [webodm/webodm_webapp](https://hub.docker.com/r/webodm/webodm_webapp)
309
+ - **社区论坛:** <https://community.opendronemap.org/>
@@ -244,6 +244,7 @@ new Map({
244
244
  - **geolibre** — 浏览器/桌面里做 GIS,无需服务端:[../geolibre/SKILL.md](../geolibre/SKILL.md)
245
245
  - **whitebox-tools** — 地形/水文/LiDAR 批量分析:[../whitebox-tools/SKILL.md](../whitebox-tools/SKILL.md)
246
246
  - **pdal** — 点云 LAS/LAZ 处理与 DEM 生成:[../pdal/SKILL.md](../pdal/SKILL.md)
247
+ - **stac-cog-titiler** — 影像云原生链路:COG 出图、STAC 编目与 TiTiler 动态切片:[../stac-cog-titiler/SKILL.md](../stac-cog-titiler/SKILL.md)
247
248
 
248
249
  ## 参考资源
249
250
 
@@ -13,6 +13,8 @@ metadata:
13
13
  >
14
14
  > **最新版本:** 2.10.2(截至 2026-11,[GitHub Release](https://github.com/PDAL/PDAL/releases);conda-forge `pdal` 同为 2.10.2)
15
15
  >
16
+ > **构建依赖:** 最低要求 GDAL 3.8(`cmake/gdal.cmake` 里硬校验;发行版二进制包已自带匹配的 GDAL,无需自己编)
17
+ >
16
18
  > **PyPI:** `pdal`(Python 绑定,最新 3.5.5,截至 2026-11;版本号与主库独立)
17
19
  >
18
20
  > **许可证:** BSD-3-Clause
@@ -25,6 +27,7 @@ PDAL(Point Data Abstraction Library)是处理点云数据的开源库与命
25
27
  - **流式优先**:默认尽量使用 stream mode,大文件不必整体载入
26
28
  - **格式广泛**:内置 LazPerf,LAZ 压缩读写开箱即用
27
29
  - **生态衔接**:writers.gdal 直接输出 GeoTIFF DEM,Python 绑定返回 NumPy 数组
30
+ - **2.10 新增 stage**:`filters.m3c2`(3D 变化检测,带四叉树 PointGrid 索引)、`filters.radiusassign`(按半径条件赋值);writers.gdal 支持 `p<percentile>` 百分位波段,filters.hag_dem 新增 `min_clamp` / `max_clamp` / `nodata`
28
31
 
29
32
  ## 环境准备
30
33
 
@@ -208,7 +211,8 @@ pdal pipeline pipeline.json --stage.points.filename=data.laz # 按 tag 覆盖
208
211
  ```
209
212
 
210
213
  - `resolution` 必需(格网边长);`dimension` 默认 `Z`
211
- - `output_type` 可选 `min/max/mean/idw/count/stdev/all`(默认 `all`,输出多波段)
214
+ - `output_type` 可选 `min/max/mean/idw/count/stdev/all`(默认 `all`,输出多波段);2.10 起还支持 `p<percentile>` 百分位波段(如 `p95`),百分位波段不计入 `all`
215
+ - `binmode`(默认 false)为 true 时只统计落在像元内的点,不做距离插值
212
216
  - `gdalopts` 透传 GDAL 驱动参数;`override_srs` 指定输出栅格坐标系
213
217
 
214
218
  ### Python 绑定
@@ -308,6 +312,8 @@ for las_file in glob.glob("tiles/*.las"):
308
312
  - 输出统一用 LAZ(`compression: "true"`)减小体积,GDAL/QGIS 可直接读取
309
313
  - 用 `tag` + `inputs` 构建分支与合并(filters.merge),tag 必须先定义
310
314
  - `pdal ground` 自 2.6.0 标记 DEPRECATED,2.7 从默认安装移除、2.8 完全移除;一律改用 `filters.smrf` 的 pipeline 写法
315
+ - `readers.spz` / `writers.spz` 在 2.10 变成插件:标准安装里 `pdal --drivers` 看不到它们,需要 SPZ 支持时另装对应插件
316
+ - 2.10 起 `filters.georeference` 输出 ECEF(EPSG:4978),要经纬度结果需再接 `filters.reprojection`
311
317
  - SMRF 参数需按数据调整:window 参考最大建筑物尺寸,slope/threshold 可参考 SMRF 论文的参数组合
312
318
 
313
319
  ## 常见问题
@@ -323,6 +329,8 @@ for las_file in glob.glob("tiles/*.las"):
323
329
  | 重投影后坐标精度变差 | 在 writer 中设置 `scale_x/y/z` 与 `offset_x/y/z: "auto"` |
324
330
  | 地面分类效果不佳 | 调整 smrf 的 window/slope/threshold/scalar,先检查数据坐标系与高程单位 |
325
331
  | 报 `Couldn't create <cls> stage of type '<type>'.` | stage 名拼错或该版本没有此 stage:先 `pdal --drivers` 确认存在,再核对 `readers.*`/`filters.*`/`writers.*` 前缀 |
332
+ | 编译报 `Could not find GDAL` / `Required at least GDAL version 3.8` | PDAL 当前最低要求 GDAL 3.8,版本低于它 CMake 直接报错 | 升级 GDAL,或直接用 conda-forge / Docker 二进制包省去编译 |
333
+ | 用 `filters.range` 时收到建议迁移的提示 | 官方建议 2.5.x+ 新代码用 `filters.expression`,`filters.range` 自 PDAL 3.0 起弃用 | 新 pipeline 一律写 `{"type": "filters.expression", "expression": "..."}` |
326
334
 
327
335
  ## AI 使用建议
328
336
 
@@ -138,7 +138,7 @@ IList<double[]> projectedPoints = mt.TransformList(points);
138
138
  | `MathTransform.Transform(double[])` | 单点转换,输入 `[x, y]` 或 `[x, y, z]`,维度由变换决定 |
139
139
  | `MathTransform.Transform(double x, double y)` | 元组重载,返回 `(x, y)` |
140
140
  | `MathTransform.TransformList(IList<double[]>)` | 批量转换,返回转换后的点数组列表 |
141
- | `MathTransform.Transform(Span<double> xs, Span<double> ys)` | 分离数组的 SOA 批量转换,适合大数组 |
141
+ | `MathTransform.Transform(Span<double> xs, Span<double> ys, int strideX = 1, int strideY = 1)` | 分离数组的 SOA 批量转换,适合大数组;数组有交错间隔时用 `strideX`/`strideY` 指定步长 |
142
142
  | `MathTransform.Inverse()` | 取逆变换,用于反向换算 |
143
143
 
144
144
  坐标按 `x, y` 顺序解释(经度/东坐标在前,纬度/北坐标在后),ProjNet **不做轴序交换**;若拿到的 WKT 声明了 `AXIS["Latitude", NORTH]` 之类的轴序,需要调用方自行判断是否交换。
@@ -15,6 +15,8 @@ metadata:
15
15
  >
16
16
  > **最新版本:** 2.2.0(截至 2026-11,[PyPI](https://pypi.org/project/shapely/);[GitHub Release](https://github.com/shapely/shapely/releases))
17
17
  >
18
+ > **版本判定:** 上游 main 分支已打 `2.3.0.dev0` 开发版标签,属于未发布开发版,PyPI 稳定版仍是 2.2.0,本文按 2.2.0 写
19
+ >
18
20
  > **许可证:** BSD-3-Clause
19
21
 
20
22
  ## 概述
@@ -29,8 +31,9 @@ Shapely 是 Python 计算几何的核心库,基于 GEOS(Geometry Engine - Op
29
31
  - **空间索引**:STRtree,加速批量空间查询
30
32
  - **格式读写**:WKT、WKB、GeoJSON
31
33
  - **双重 API**:函数式(向量化,支持 NumPy 广播)+ OOP(标量便捷)
34
+ - **2.2 新增**:`minimum_width`、`get_segments`、`transform_coordseq`、`split`、`coverage_clean`;标量属性/方法的调用开销大幅下降(`p.x` 从 2-3 微秒降到约 50-100 纳秒)
32
35
 
33
- **环境要求:** Python 3.11+(Shapely 2.2 起;2.1 为 3.10+),NumPy >= 1.26,GEOS >= 3.10。PyPI 二进制 wheel 内含 GEOS 3.14。
36
+ **环境要求:** Python 3.11+(Shapely 2.2 起;2.1 为 3.10+),NumPy >= 1.26,GEOS >= 3.10。PyPI 二进制 wheel 内含 GEOS 3.14.1(2.2.0 起;2.1.2 的 wheel 是 3.13.1),Windows ARM64 wheel 自 2.2.0 起提供。
34
37
 
35
38
  ---
36
39
 
@@ -173,6 +176,18 @@ geom = shape({"type": "Point", "coordinates": [0, 0]})
173
176
  d = mapping(geom) # {"type": "Point", "coordinates": (0.0, 0.0)}
174
177
  ```
175
178
 
179
+ 常用 2.2 新增函数:
180
+
181
+ ```python
182
+ import shapely
183
+
184
+ shapely.minimum_width(polygon) # → LineString,最小宽度(最小直径)那条线段
185
+ shapely.get_segments(line) # → 每个 Linestring/LinearRing 拆成成对相邻顶点线段
186
+ shapely.transform_coordseq(geom, fn) # 按坐标序列做变换,性能优于已弃用的 shapely.ops.transform
187
+ shapely.split(geom, splitter) # 顶层 split(GEOS >= 3.15 用原生实现,否则回退 shapely.ops.split)
188
+ shapely.coverage_clean(geoms) # 清理多边形覆盖(缝隙/重叠),需 GEOS >= 3.14
189
+ ```
190
+
176
191
  > 构造操作、空间谓词、集合运算、测量、空间索引、仿射与坐标变换及线性参考的完整 API 见 [reference/operations-reference.md](reference/operations-reference.md)
177
192
 
178
193
  ## 有效性校验
@@ -188,11 +203,13 @@ shapely.make_valid(geom, method="linework") # or "structure"
188
203
  为同一几何的重复谓词判断缓存空间索引。
189
204
 
190
205
  ```python
191
- shapely.prepare(geom) # in-place, returns True if newly prepared
192
- shapely.destroy_prepared(geom) # free cache
206
+ shapely.prepare(geom) # in-place, returns True if newly prepared, False if already prepared
207
+ shapely.destroy_prepared(geom) # free cache, returns whether something was destroyed
193
208
  shapely.is_prepared(geom)
194
209
  ```
195
210
 
211
+ 2.2 起 `relate()` / `relate_pattern()` 也能利用已预处理的左输入几何,对同一几何反复做谓词判断时先 `prepare()` 更快。
212
+
196
213
  ## 缺失值
197
214
 
198
215
  `None` 表示缺失几何,各函数行为保持一致:
@@ -338,6 +355,9 @@ left_idx, right_idx = tree.query(left_geoms, predicate="intersects")
338
355
  | WKB 序列化丢失 LinearRing | WKB 规范不支持 LinearRing,会自动转为 LineString |
339
356
  | `to_geojson` 丢失 Z 坐标 | GeoJSON 标准不支持 Z,改用 WKB 或自定义序列化 |
340
357
  | `shapely.ops.transform` 弃用警告 | 2.2 起弃用,改用 `shapely.transform` 或 `shapely.transform_coordseq` |
358
+ | `AttributeError: module 'shapely' has no attribute 'minimum_width'` / `get_segments` | 装的是 2.2 之前的版本,这两个函数 2.2.0 才加入顶层命名空间 | `python -c "import shapely; print(shapely.__version__)"` 确认 >= 2.2.0 |
359
+ | `UnsupportedGEOSVersionError` 调 `coverage_clean` / `coverage_simplify` | 底层 GEOS 太旧(`coverage_clean` 需 GEOS >= 3.14、coverage 系列多数需 >= 3.12) | `shapely.geos_version` 核对;升级 shapely wheel(自带 GEOS 3.14.1)而不是只升级系统 GEOS |
360
+ | `multithreading_enabled` 装饰器告警 | 2.2 起弃用且不再内部使用,线程安全需自行保证不并发改同一批几何 | 去掉装饰器;多线程只读同一不可变几何数组时用 `shapely` 函数即可,需写时按线程切分数组 |
341
361
 
342
362
  ---
343
363
 
@@ -345,7 +365,7 @@ left_idx, right_idx = tree.query(left_geoms, predicate="intersects")
345
365
 
346
366
  - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/operations-reference.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
347
367
  - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell);`python` 不一定是 QGIS/GDAL 自带环境,先 `python -c "import sys; print(sys.executable, sys.version)"`。
348
- - **先探测版本**:`python -c "import shapely; print(shapely.__version__, shapely.geos_version)"`;本技能按 2.2.0 编写,PyPI wheel 内含 GEOS 3.14。GEOS 低版本请按第 11 条降级(如 `coverage_clean` 需 3.14、`shapely.split` 需 3.15)。
368
+ - **先探测版本**:`python -c "import shapely; print(shapely.__version__, shapely.geos_version)"`;本技能按 2.2.0 编写,PyPI wheel 内含 GEOS 3.14.1。GEOS 低版本请按第 11 条降级(如 `coverage_clean` 需 3.14、`shapely.split` 需 3.15,低版本自动回退 `shapely.ops.split`)。
349
369
  - **验证产物(必做)**:`print(shapely.is_valid(g), shapely.is_valid_reason(g))` 报无效原因;面积/长度做量级断言;序列化回读 `shapely.from_wkt(shapely.to_wkt(g, rounding_precision=-1)).equals(g)`,改过几何后再核对一次 `geom_type` 与 `get_num_geometries()`。
350
370
  - **报错先查有效性**:`TopologyException: side location conflict` 基本都是输入几何自相交,先 `shapely.make_valid(g)`(可指定 `method="structure"`)再算,不要直接加 `buffer(0)`。
351
371
  - **性能与内存**:批量操作走向量化函数(`shapely.union_all`、`shapely.buffer(geoms, r)`),别逐条 OOP 循环;十万级以上几何先 `STRtree(geoms)` 过滤,再对小集合做精确谓词。
@@ -11,6 +11,7 @@
11
11
  - Affine Transforms
12
12
  - Coordinate Transforms
13
13
  - Linear Referencing
14
+ - Coordinate Extraction & Segments (2.2)
14
15
 
15
16
  Constructive operations, predicates, set operations, measurements, indexing and coordinate operations split from SKILL.md.
16
17
 
@@ -209,3 +210,32 @@ shapely.shortest_line(a, b)
209
210
  shapely.get_segments(geom) # 提取 LineString/LinearRing 的逐段线段(2.2 新增)
210
211
  ```
211
212
 
213
+ ## Coordinate Extraction & Segments (2.2)
214
+
215
+ Added in Shapely 2.2.0.
216
+
217
+ | Function | Description |
218
+ |----------|-------------|
219
+ | `get_segments(geometry, include_z=False, return_index=False)` | Split each LineString/LinearRing into individual pairwise-vertex segments (returns ndarray of LINESTRINGs). Multi\* geometries are not supported. |
220
+ | `minimum_width(geometry)` | Minimum width (minimum diameter) as a LineString; degenerate inputs (Point/LineString) return a zero-length LineString. |
221
+ | `transform_coordseq(geometry, function)` | Apply a function per coordinate sequence (faster than the deprecated `shapely.ops.transform`). |
222
+ | `split(geometry, splitter)` | Split a geometry by another one (uses GEOS >= 3.15 when available, otherwise falls back to `shapely.ops.split`). Splitting a (Multi)Polygon by another (Multi)Polygon uses its boundary. |
223
+ | `coverage_clean(geometries, gap_width=0.0, snapping_distance=-1, merge_strategy="longest_border")` | Clean a polygonal coverage, closing gaps/overlaps (requires GEOS >= 3.14). |
224
+
225
+ ```python
226
+ import shapely
227
+ from shapely import LineString, Polygon
228
+
229
+ shapely.get_segments(LineString([(0, 0), (1, 1), (2, 2)]))
230
+ # array([<LINESTRING (0 0, 1 1)>, <LINESTRING (1 1, 2 2)>], dtype=object)
231
+
232
+ shapely.minimum_width(Polygon([(0, 0), (1, 0), (1, 1), (0, 1)]))
233
+ # <LINESTRING (0 0, 1 0)>
234
+
235
+ shapely.split(LineString([(0, 0), (2, 0)]), shapely.Point(1, 0))
236
+ # GEOMETRYCOLLECTION (LINESTRING (0 0, 1 0), LINESTRING (1 0, 2 0))
237
+ ```
238
+
239
+ ### prepare()/relate() interplay
240
+
241
+ Since 2.2, `relate()` and `relate_pattern()` accept prepared geometries on the left input and then use a faster implementation. `prepare()` and `destroy_prepared()` return whether they changed anything.
@@ -99,8 +99,14 @@ python -c "import sqlite3; c=sqlite3.connect(':memory:'); c.enable_load_extensio
99
99
  spatialite mydb.sqlite
100
100
  spatialite> .load mod_spatialite
101
101
 
102
- # CLI:一次性执行(把扩展加载与 SQL 放在同一次调用里)
103
- spatialite mydb.sqlite -cmd ".load mod_spatialite" "SELECT spatialite_version();"
102
+ # CLI:一次性执行(选项须放在数据库文件之前,与 sqlite3 CLI 的 [OPTIONS] FILENAME [SQL] 顺序一致)
103
+ spatialite -cmd ".load mod_spatialite" mydb.sqlite "SELECT spatialite_version();"
104
+
105
+ # CLI:更稳妥的写法是用 heredoc 把 dot-command 与 SQL 一起从 stdin 送入
106
+ spatialite mydb.sqlite <<'EOF'
107
+ .load mod_spatialite
108
+ SELECT spatialite_version();
109
+ EOF
104
110
  ```
105
111
 
106
112
  ```python