@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.
- package/CHANGELOG.md +71 -0
- package/README.md +79 -43
- package/THIRD_PARTY_NOTICES.md +9 -0
- package/adaptations/brutile.md +8 -0
- package/adaptations/cesiumjs.md +8 -0
- package/adaptations/common.md +16 -0
- package/adaptations/deck-gl.md +8 -0
- package/adaptations/duckdb-spatial.md +8 -0
- package/adaptations/gdal-api.md +8 -0
- package/adaptations/gdal.md +8 -0
- package/adaptations/geolibre.md +8 -0
- package/adaptations/geometry-api-java.md +8 -0
- package/adaptations/geometry-api-net.md +8 -0
- package/adaptations/geonode.md +8 -0
- package/adaptations/geopandas.md +8 -0
- package/adaptations/geopipe-agent.md +8 -0
- package/adaptations/geoserver-cloud.md +8 -0
- package/adaptations/geoserver-rest-api.md +8 -0
- package/adaptations/geoserver.md +8 -0
- package/adaptations/geotools.md +8 -0
- package/adaptations/grass-gis.md +8 -0
- package/adaptations/jts.md +8 -0
- package/adaptations/kepler-gl.md +8 -0
- package/adaptations/leaflet.md +8 -0
- package/adaptations/mapbox-gl-js.md +8 -0
- package/adaptations/mapserver.md +8 -0
- package/adaptations/mapsui.md +8 -0
- package/adaptations/nettopologysuite.md +8 -0
- package/adaptations/opengis-all.md +8 -0
- package/adaptations/opengis-daf.md +8 -0
- package/adaptations/opengis-utils-for-java.md +8 -0
- package/adaptations/opengis-utils-for-net.md +8 -0
- package/adaptations/openlayers.md +8 -0
- package/adaptations/pdal.md +8 -0
- package/adaptations/postgis.md +8 -0
- package/adaptations/proj.md +8 -0
- package/adaptations/projnet4geoapi.md +8 -0
- package/adaptations/pyqgis.md +8 -0
- package/adaptations/qgis-process.md +8 -0
- package/adaptations/qgis-server.md +8 -0
- package/adaptations/shapely.md +8 -0
- package/adaptations/sharpmap.md +8 -0
- package/adaptations/spatialite.md +8 -0
- package/adaptations/whitebox-tools.md +8 -0
- package/assets/brutile/SKILL.md +289 -0
- package/assets/cesiumjs/SKILL.md +78 -29
- package/assets/deck-gl/SKILL.md +20 -20
- package/assets/duckdb-spatial/SKILL.md +370 -0
- package/assets/gdal/SKILL.md +50 -55
- package/assets/gdal-api/SKILL.md +12 -29
- package/assets/geolibre/SKILL.md +364 -0
- package/assets/geometry-api-java/SKILL.md +11 -19
- package/assets/geometry-api-net/SKILL.md +66 -29
- package/assets/geonode/SKILL.md +347 -0
- package/assets/geopandas/SKILL.md +22 -28
- package/assets/geopipe-agent/SKILL.md +25 -30
- package/assets/geoserver/SKILL.md +21 -24
- package/assets/geoserver-cloud/SKILL.md +23 -34
- package/assets/geoserver-rest-api/SKILL.md +18 -23
- package/assets/geotools/SKILL.md +13 -21
- package/assets/grass-gis/SKILL.md +19 -20
- package/assets/jts/SKILL.md +12 -17
- package/assets/kepler-gl/SKILL.md +313 -0
- package/assets/leaflet/SKILL.md +42 -17
- package/assets/mapbox-gl-js/SKILL.md +19 -18
- package/assets/mapserver/SKILL.md +18 -18
- package/assets/mapsui/SKILL.md +87 -58
- package/assets/nettopologysuite/SKILL.md +96 -27
- package/assets/opengis-all/SKILL.md +80 -292
- package/assets/opengis-all/reference/data-stages.md +262 -4
- package/assets/opengis-daf/SKILL.md +12 -14
- package/assets/opengis-utils-for-java/SKILL.md +52 -47
- package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
- package/assets/opengis-utils-for-net/SKILL.md +106 -40
- package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
- package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
- package/assets/openlayers/SKILL.md +71 -14
- package/assets/pdal/SKILL.md +21 -15
- package/assets/postgis/SKILL.md +66 -18
- package/assets/proj/SKILL.md +29 -42
- package/assets/projnet4geoapi/SKILL.md +299 -0
- package/assets/pyqgis/SKILL.md +28 -54
- package/assets/qgis-process/SKILL.md +67 -39
- package/assets/qgis-server/SKILL.md +21 -32
- package/assets/shapely/SKILL.md +133 -84
- package/assets/sharpmap/SKILL.md +96 -61
- package/assets/spatialite/SKILL.md +365 -0
- package/assets/whitebox-tools/SKILL.md +269 -0
- package/lib/adaptations.d.ts +47 -0
- package/lib/adaptations.js +268 -0
- package/lib/index.d.ts +1 -1
- package/lib/index.js +14 -2
- package/lib/skill-file.js +31 -7
- package/locale/en.json +1 -1
- package/locale/zh.json +1 -1
- package/package.json +12 -2
- package/upstream.json +56 -40
package/assets/pyqgis/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pyqgis
|
|
3
|
-
description: "Use when
|
|
3
|
+
description: "Use when scripting QGIS with Python — QgsApplication standalone init, QgsVectorLayer / QgsRasterLayer loading, processing.run after Processing.initialize(), QgsGeometry / QgsExpression, QgsMapSettings rendering and QgsLayoutExporter PDF/PNG export, qgis._3d, or debugging \"import qgis.core\" failures. PyQGIS for QGIS 4.2.3 and LTR 3.44.15 (use the interpreter bundled with QGIS, not system Python)."
|
|
4
4
|
tags:
|
|
5
5
|
- python
|
|
6
6
|
- qgis
|
|
@@ -39,7 +39,7 @@ PyQGIS 主要包含以下模块:
|
|
|
39
39
|
| `qgis.core` | 核心类——图层、要素、几何、坐标系、项目、Processing 等 |
|
|
40
40
|
| `qgis.gui` | GUI 组件——地图画布、地图工具、符号选择器等 |
|
|
41
41
|
| `qgis.analysis` | 空间分析——插值、网络分析、栅格计算等 |
|
|
42
|
-
| `
|
|
42
|
+
| `processing` | Processing 算法调用入口(独立 Python 模块,`processing.run()`;非 `qgis.processing`) |
|
|
43
43
|
| `qgis.server` | QGIS Server Python 插件接口 |
|
|
44
44
|
| `qgis._3d` | 3D 地图视图相关类 |
|
|
45
45
|
| `qgis.PyQt` | PyQt5/PyQt6 兼容层 |
|
|
@@ -51,7 +51,13 @@ PyQGIS 主要包含以下模块:
|
|
|
51
51
|
### 前置条件
|
|
52
52
|
|
|
53
53
|
- 安装 QGIS 4.2+(当前稳定版)或 3.44 LTR(长期支持版)([查看 QGIS LTR/最新版](https://qgis.org/download/))
|
|
54
|
-
-
|
|
54
|
+
- 使用 **QGIS 发行包自带的 Python 解释器**(4.2 的 Windows 安装目录为 `apps/Python312`),不要用系统 Python 直接 `pip install qgis`
|
|
55
|
+
|
|
56
|
+
探测发行包实际使用的解释器版本(在任何 QGIS Python 环境里):
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
python -c "import sys; print(sys.version)"
|
|
60
|
+
```
|
|
55
61
|
|
|
56
62
|
### 在 QGIS Python 控制台中使用
|
|
57
63
|
|
|
@@ -176,7 +182,7 @@ python3 my_pyqgis_script.py
|
|
|
176
182
|
|
|
177
183
|
| 类 | 模块 | 用途 |
|
|
178
184
|
|---|---|---|
|
|
179
|
-
| `processing.run()` | `
|
|
185
|
+
| `processing.run()` | `processing`(QGIS 插件目录模块) | **执行 Processing 算法的核心入口** |
|
|
180
186
|
| `QgsProcessingFeedback` | `qgis.core` | 算法执行反馈(进度、日志) |
|
|
181
187
|
| `QgsProcessingContext` | `qgis.core` | 算法执行上下文 |
|
|
182
188
|
| `QgsProcessingAlgorithm` | `qgis.core` | 自定义算法基类 |
|
|
@@ -380,52 +386,6 @@ qgs.exitQgis()
|
|
|
380
386
|
|
|
381
387
|
更多工作流(批量缓冲融合、栅格裁剪、打印布局导出)见 [reference/processing-rendering.md](reference/processing-rendering.md)。
|
|
382
388
|
|
|
383
|
-
## AI 使用建议
|
|
384
|
-
|
|
385
|
-
### 推荐工作流
|
|
386
|
-
|
|
387
|
-
1. **初始化环境**:独立脚本需 `QgsApplication` 初始化;QGIS 控制台中可直接使用
|
|
388
|
-
2. **加载数据**:使用 `QgsVectorLayer` / `QgsRasterLayer` 加载数据源
|
|
389
|
-
3. **执行分析**:优先使用 `processing.run()` 调用算法(参数统一、算法丰富);精细操作使用 `QgsGeometry` 方法
|
|
390
|
-
4. **导出结果**:使用 `QgsVectorFileWriter` 写出矢量,`QgsRasterFileWriter` 写出栅格
|
|
391
|
-
5. **清理退出**:独立脚本调用 `qgs.exitQgis()`
|
|
392
|
-
|
|
393
|
-
### 关键注意事项
|
|
394
|
-
|
|
395
|
-
1. **始终检查图层有效性**:加载图层后必须检查 `layer.isValid()`,无效时检查路径和 Provider。
|
|
396
|
-
2. **坐标系一致性**:空间运算前确保所有图层使用相同 CRS;使用 `native:reprojectlayer` 或 `QgsCoordinateTransform` 进行转换。
|
|
397
|
-
3. **编辑模式**:修改图层数据需 `startEditing()` → 操作 → `commitChanges()`;失败可 `rollBack()`。
|
|
398
|
-
4. **Processing 内存输出**:将 OUTPUT 设为 `'memory:name'` 可得到内存图层,避免创建临时文件。
|
|
399
|
-
5. **椭球面计算**:对地理坐标(经纬度)计算距离/面积时,使用 `QgsDistanceArea` 并设置椭球体,或使用 Processing 算法指定椭球体。
|
|
400
|
-
6. **Headless 环境**:无显示器的服务器上必须设置 `QT_QPA_PLATFORM=offscreen`。
|
|
401
|
-
7. **文件路径使用绝对路径**:避免工作目录不确定导致文件找不到。
|
|
402
|
-
8. **大数据量优化**:使用 `QgsSpatialIndex` 加速空间查询;使用 `QgsFeatureRequest` 限制返回字段和范围。
|
|
403
|
-
9. **表达式语法**:字段名用双引号 `"field"`,字符串值用单引号 `'value'`。
|
|
404
|
-
10. **QGIS 版本兼容**:部分 API 在不同版本间有变化,建议使用 LTR 版本([查看当前 LTR](https://qgis.org/download/))以获得稳定接口;QGIS 当前稳定版为 4.2.3(2026-09 发布),3.44 LTR(最新 3.44.15)仍受支持(截至 2026-10)。
|
|
405
|
-
|
|
406
|
-
### 错误处理
|
|
407
|
-
|
|
408
|
-
```python
|
|
409
|
-
# 图层加载失败
|
|
410
|
-
layer = QgsVectorLayer(path, name, provider)
|
|
411
|
-
if not layer.isValid():
|
|
412
|
-
print(f"图层加载失败: {layer.error().message()}")
|
|
413
|
-
|
|
414
|
-
# Processing 算法错误
|
|
415
|
-
try:
|
|
416
|
-
result = processing.run("native:buffer", params, feedback=feedback)
|
|
417
|
-
except Exception as e:
|
|
418
|
-
print(f"算法执行失败: {e}")
|
|
419
|
-
|
|
420
|
-
# 编辑提交失败
|
|
421
|
-
if not layer.commitChanges():
|
|
422
|
-
errors = layer.commitErrors()
|
|
423
|
-
print(f"提交失败: {errors}")
|
|
424
|
-
layer.rollBack()
|
|
425
|
-
```
|
|
426
|
-
|
|
427
|
-
---
|
|
428
|
-
|
|
429
389
|
## 常见问题
|
|
430
390
|
|
|
431
391
|
| 问题 | 解决 |
|
|
@@ -441,6 +401,18 @@ if not layer.commitChanges():
|
|
|
441
401
|
|
|
442
402
|
---
|
|
443
403
|
|
|
404
|
+
## AI 使用建议
|
|
405
|
+
|
|
406
|
+
- **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/processing-rendering.md`、`reference/vector-raster-layers.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
|
|
407
|
+
- **执行环境**:必须用 QGIS 自带的解释器(Windows 在 `C:\Program Files\QGIS 4.2\apps\Python312\python.exe`,LTR 为 `QGIS 3.44`),不要用系统 Python;命令在终端 / shell 中执行(Windows 用 PowerShell),`export QT_QPA_PLATFORM=offscreen` 改写为 `$env:QT_QPA_PLATFORM = "offscreen"`。
|
|
408
|
+
- **先探测版本**:`python -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"`;本技能同时覆盖 4.2.3(最新)与 3.44.15(LTR),4.x 与 3.x 存在 API 差异,回答里要写明按哪个版本写、低版本哪些类/方法不可用。
|
|
409
|
+
- **验证产物**:独立脚本按 `QgsApplication` → `initQgis()` → 处理 → `exitQgis()` 收尾;写出后重开图层核对 `isValid()`、`featureCount()`、`crs().authid()`,`processing.run()` 的返回值只给路径,结果要二次打开;渲染或布局导出的 PNG 要实际打开看是否空白。
|
|
410
|
+
- **模块名易错**:3D 模块是 `qgis._3d`(下划线,不是 `qgis.3d`),例如 `from qgis._3d import Qgs3DMapSettings`;`processing.run()` 前必须先 `Processing.initialize()`,否则报算法不存在。
|
|
411
|
+
- **进程与日志**:批量脚本不要跨任务复用同一个 `QgsProject.instance()`;长任务放后台运行,QGIS 日志(`QgsApplication.messageLog()`)与 stderr 重定向到文件后分段查看。
|
|
412
|
+
- **安全与权限**:`startEditing()`/`commitChanges()` 直接改源数据(Shapefile、PostGIS),先备份或把中间结果写 `memory:`;覆盖已有输出文件、安装 QGIS、把数据写进系统目录前先征得用户同意。
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
444
416
|
## 相关技能
|
|
445
417
|
|
|
446
418
|
- **qgis-process** — QGIS 命令行处理工具:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
|
|
@@ -452,8 +424,10 @@ if not layer.commitChanges():
|
|
|
452
424
|
## 参考资源
|
|
453
425
|
|
|
454
426
|
- **QGIS 源码仓库:** <https://github.com/qgis/QGIS>
|
|
455
|
-
- **PyQGIS 开发者手册(3.44
|
|
456
|
-
- **PyQGIS API 参考(
|
|
427
|
+
- **PyQGIS 开发者手册(3.44,4.2 章节尚未定稿):** <https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/>
|
|
428
|
+
- **PyQGIS API 参考(4.2):** <https://qgis.org/pyqgis/4.2/>
|
|
457
429
|
- **QGIS 文档仓库:** <https://github.com/qgis/QGIS-Documentation>
|
|
458
|
-
- **QGIS
|
|
459
|
-
- **PyQGIS
|
|
430
|
+
- **QGIS 用户手册(3.44):** <https://docs.qgis.org/3.44/en/docs/user_manual/>
|
|
431
|
+
- **PyQGIS 速查表(3.44):** <https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/cheat_sheet.html>
|
|
432
|
+
|
|
433
|
+
> **注意:** `docs.qgis.org/4.2/...` 目前会 302 跳到 `/testing/`,4.2 的 cookbook 与用户手册尚未定稿;查阅 4.2 类与方法签名以 <https://qgis.org/pyqgis/4.2/> 为准。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: qgis-process
|
|
3
|
-
description: "Use when running QGIS geoprocessing
|
|
3
|
+
description: "Use when running QGIS geoprocessing headless via qgis_process — native:buffer / native:reprojectlayer / native:clip, qgis_process list / help --json / run --json, .model3 models and .py scripts, batch CI pipelines, or debugging \"Algorithm ... not found!\"; includes QT_QPA_PLATFORM=offscreen and the qgis/qgis images (stable 4.2, ltr 3.44)."
|
|
4
4
|
tags:
|
|
5
5
|
- cli
|
|
6
6
|
- qgis
|
|
@@ -20,7 +20,7 @@ tags:
|
|
|
20
20
|
>
|
|
21
21
|
> **在线文档:** <https://docs.qgis.org/4.2/en/docs/user_manual/processing/standalone.html>
|
|
22
22
|
>
|
|
23
|
-
> **最新版本:** QGIS 4.2.3;3.44 LTR 最新 3.44.15(截至2026-10,GitHub Releases;`qgis_process` 自 QGIS 3.16 起可用)
|
|
23
|
+
> **最新版本:** QGIS 4.2.3;3.44 LTR 最新 3.44.15(截至 2026-10,GitHub Releases;`qgis_process` 自 QGIS 3.16 起可用)
|
|
24
24
|
>
|
|
25
25
|
> **许可证:** GPL-2.0+
|
|
26
26
|
|
|
@@ -300,39 +300,70 @@ qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
|
|
|
300
300
|
|
|
301
301
|
---
|
|
302
302
|
|
|
303
|
-
>
|
|
303
|
+
> 常用内置算法速查与参数类型参考见 [reference/algorithm-cheatsheet.md](reference/algorithm-cheatsheet.md)
|
|
304
304
|
|
|
305
|
-
##
|
|
305
|
+
## 典型工作流
|
|
306
|
+
|
|
307
|
+
目标:把 `data/points.shp` 做 50 m 缓冲区写入 GeoPackage,并在 CI 中批量重复同一流程。
|
|
306
308
|
|
|
307
|
-
###
|
|
309
|
+
### 1. 先用 help 确认参数,不要凭记忆
|
|
308
310
|
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
4. **执行算法**:`qgis_process run <algorithm_id> --json -- PARAM=VALUE ...` 或通过 STDIN 传入 JSON
|
|
313
|
-
5. **解析结果**:解析 JSON 输出获取结果路径和日志信息
|
|
311
|
+
```bash
|
|
312
|
+
qgis_process help native:buffer --json > buffer-help.json
|
|
313
|
+
```
|
|
314
314
|
|
|
315
|
-
|
|
315
|
+
读取 `parameters` 中 `INPUT` / `DISTANCE` / `SEGMENTS` / `OUTPUT` 的名称与类型;`DISTANCE` 是 `distance` 类型,单位取图层 CRS 单位(投影坐标系下即米,地理坐标系下是度,极易算错)。
|
|
316
316
|
|
|
317
|
-
|
|
318
|
-
2. **先查 help 再构造参数**:每个算法的参数名和类型不同,先用 `help --json` 确认参数定义。
|
|
319
|
-
3. **枚举类型传数字索引**:枚举参数用数字(如 `0`、`1`)而非文字。help 输出的 `available_options` 提供了索引到含义的映射。
|
|
320
|
-
4. **多值参数多次指定**:如 `LAYERS=a.shp LAYERS=b.shp`(在 `--` 之后,参数不带前导 `--`)。
|
|
321
|
-
5. **复杂参数用 STDIN JSON**:字典类型的参数值适合通过 STDIN JSON 方式传入。
|
|
322
|
-
6. **文件路径使用绝对路径**:避免工作目录不确定导致的文件找不到。
|
|
323
|
-
7. **Headless 环境设置 `QT_QPA_PLATFORM=offscreen`**:在无显示器的服务器上必须设置。
|
|
324
|
-
8. **需要项目文件的算法**:某些算法(如打印布局导出)需要通过 `--project_path` 指定项目文件。
|
|
325
|
-
9. **取消正在运行的算法**:使用 `CTRL+C` 可取消执行中的算法。
|
|
326
|
-
10. **`--no-python` 和 `--skip-loading-plugins` 可加速启动**:如果不需要第三方插件提供的算法,使用这两个选项可显著缩短启动时间。
|
|
317
|
+
### 2. 运行算法写出 GPKG
|
|
327
318
|
|
|
328
|
-
|
|
319
|
+
```bash
|
|
320
|
+
qgis_process run native:buffer --json -- \
|
|
321
|
+
INPUT=data/points.shp \
|
|
322
|
+
DISTANCE=50 \
|
|
323
|
+
SEGMENTS=8 \
|
|
324
|
+
DISSOLVE=false \
|
|
325
|
+
OUTPUT=out/points_buffer_50m.gpkg
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
`results.OUTPUT` 是实际写出的绝对路径,用它决定后续校验对象,不要自己拼路径。
|
|
329
|
+
|
|
330
|
+
### 3. 校验产物
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
ogrinfo -so out/points_buffer_50m.gpkg points_buffer_50m
|
|
334
|
+
```
|
|
329
335
|
|
|
330
|
-
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
-
|
|
336
|
+
核对要素数、CRS、几何类型;GPKG 内图层名默认取输出文件名(去扩展名)。`log` 里出现 `returned non-zero` 时即使进程退出码为 0 也算失败。
|
|
337
|
+
|
|
338
|
+
### 4. 批量循环(CI 脚本)
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
mkdir -p out
|
|
342
|
+
for f in data/*.shp; do
|
|
343
|
+
base=$(basename "$f" .shp)
|
|
344
|
+
qgis_process run native:buffer --json -- \
|
|
345
|
+
INPUT="$f" DISTANCE=50 OUTPUT="out/${base}_buffer.gpkg" \
|
|
346
|
+
|| { echo "FAILED: $f" >&2; exit 1; }
|
|
347
|
+
done
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
每次 `run` 都会新起一个 QGIS 进程(数秒开销);文件量大时改用 PyQGIS 的 `processing.run()` 在单进程内循环,见 [../pyqgis/SKILL.md](../pyqgis/SKILL.md)。
|
|
351
|
+
|
|
352
|
+
输入 `data/points.shp` → `native:buffer` → `out/points_buffer_50m.gpkg` → `ogrinfo` 校验,构成 qgis_process 批处理的最小闭环。
|
|
353
|
+
|
|
354
|
+
## 常见问题
|
|
355
|
+
|
|
356
|
+
| 问题 | 解决方案 |
|
|
357
|
+
|------|---------|
|
|
358
|
+
| 提示 `command not found: qgis_process` | 将 QGIS 的 `bin` 目录加入 `PATH`;Windows 下改用 OSGeo4W Shell 运行 |
|
|
359
|
+
| 无显示器的服务器上崩溃或卡住 | 设置环境变量 `QT_QPA_PLATFORM=offscreen` |
|
|
360
|
+
| `Algorithm <id> not found!` | 用 `qgis_process list` 确认算法 ID 与 Provider 前缀(如 `native:`、`gdal:`) |
|
|
361
|
+
| 缺少必填参数 | 先用 `qgis_process help <id> --json` 查看参数名、类型与默认值 |
|
|
362
|
+
| 枚举参数报错 | 枚举值需传数字索引,`help --json` 中的 `available_options` 提供索引映射 |
|
|
363
|
+
| 多值参数只生效一项 | 在 `--` 之后多次指定同一参数(如 `LAYERS=a.shp LAYERS=b.shp`) |
|
|
364
|
+
| 路径含空格或中文时报错 | 使用绝对路径并对参数值加引号 |
|
|
365
|
+
| 启动速度慢 | 不需要 Python/插件时添加 `--no-python` 与 `--skip-loading-plugins` |
|
|
366
|
+
| 模型/脚本或算法不可用 | 报 `File <path> is not a valid Processing model!` / `... is not a valid Processing script!` / `not available for use outside of the QGIS desktop application` 时,改用 QGIS 桌面或 PyQGIS 脚本 |
|
|
336
367
|
|
|
337
368
|
---
|
|
338
369
|
|
|
@@ -351,18 +382,15 @@ qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
|
|
|
351
382
|
|
|
352
383
|
---
|
|
353
384
|
|
|
354
|
-
##
|
|
385
|
+
## AI 使用建议
|
|
355
386
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
| 多值参数只生效一项 | 在 `--` 之后多次指定同一参数(如 `LAYERS=a.shp LAYERS=b.shp`) |
|
|
364
|
-
| 路径含空格或中文时报错 | 使用绝对路径并对参数值加引号 |
|
|
365
|
-
| 启动速度慢 | 不需要 Python/插件时添加 `--no-python` 与 `--skip-loading-plugins` |
|
|
387
|
+
- **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/algorithm-cheatsheet.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
|
|
388
|
+
- **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell)。Windows 下 `qgis_process` 在 `C:\Program Files\QGIS 4.2\bin`(LTR 为 `C:\Program Files\QGIS 3.44\bin`)或 OSGeo4W Shell 里;PowerShell 设 `$env:QT_QPA_PLATFORM = "offscreen"`,不要照抄 `export`。
|
|
389
|
+
- **先探测版本**:`qgis_process --version`(QGIS 4.2.3 或 LTR 3.44.15)、`qgis_process list`;低于 3.16 没有 `qgis_process`,只能改用 PyQGIS 脚本;`--no-python`、`--skip-loading-plugins` 可显著加快启动。
|
|
390
|
+
- **验证产物**:`run ... --json` 里的 `results.OUTPUT` 是实际写出的绝对路径,再用 `ogrinfo -so`(矢量)或 `gdalinfo -json`(栅格)核对要素数、CRS、范围;日志中出现 `returned non-zero` 说明算法内部失败,不要只看进程退出码。
|
|
391
|
+
- **参数约定**:`--` 之后的参数不带前导 `--`;枚举传数字索引(`help --json` 里的 `available_options` 是映射表);多值参数重复同一键(`LAYERS=a.shp LAYERS=b.shp`);路径含空格或中文时加引号,尽量用绝对路径。
|
|
392
|
+
- **常见报错**:`Algorithm <id> not found!` 先查 provider 前缀(`native:`、`gdal:`、`grass:`),`The following mandatory parameters were not specified` 回看 `help --json`,`requires a QGIS project to execute` 补 `--project_path`。
|
|
393
|
+
- **安全与权限**:`OUTPUT=` 指向已有文件会被覆盖;`--project_path` 会加载项目内的数据源与凭证,注意不要把含密码的项目传给外部环境;启动 Docker 或安装 QGIS 前先征得用户同意,长任务放后台运行。
|
|
366
394
|
|
|
367
395
|
---
|
|
368
396
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: qgis-server
|
|
3
|
-
description: "Use when publishing QGIS projects (.qgs/.qgz) as OGC web services
|
|
3
|
+
description: "Use when publishing QGIS projects (.qgs/.qgz) as OGC web services — WMS GetMap/GetPrint, WFS and WFS-T, WMTS, OGC API Features via qgis_mapserv.fcgi with Apache mod_fcgid, Nginx, or Docker, plus QGIS_SERVER_* tuning (MAX_THREADS, PARALLEL_RENDERING, LOG_STDERR); covers \"Service unknown or unsupported\" and MAP/GetCapabilities checks. QGIS 4.2.3 and LTR 3.44.15."
|
|
4
4
|
tags:
|
|
5
5
|
- qgis
|
|
6
6
|
- server
|
|
@@ -15,9 +15,9 @@ tags:
|
|
|
15
15
|
|
|
16
16
|
> **项目地址:** <https://github.com/qgis/QGIS>
|
|
17
17
|
>
|
|
18
|
-
> **官方文档:** <https://docs.qgis.org/
|
|
18
|
+
> **官方文档:** <https://docs.qgis.org/3.44/en/docs/server_manual/>(`/latest/` 目前 302 到 3.44 手册,4.2 手册尚未单独发布)
|
|
19
19
|
>
|
|
20
|
-
> **最新版本:** 4.2.3(截至 2026-10
|
|
20
|
+
> **最新版本:** 4.2.3(稳定版);LTR 3.44.15(截至 2026-10,实测 `qgis/qgis` 镜像 tag 与 <https://qgis.org/download/>)
|
|
21
21
|
>
|
|
22
22
|
> **许可证:** GPL-2.0
|
|
23
23
|
|
|
@@ -119,7 +119,9 @@ WMS 的 `LAYERS` 支持按短名或图层 ID 选择,多个图层用逗号分
|
|
|
119
119
|
|
|
120
120
|
WMTS 的 `TILEMATRIXSET` 定义金字塔所用 CRS(形如 `EPSG:XXXX`),`TILEMATRIX`/`TILEROW`/`TILECOL` 定位具体瓦片;`FORMAT` 仅支持 `jpg`/`jpeg`/`image/jpeg`/`image/png`,其余值回退为 PNG。`GetFeatureInfo` 的 `INFOFORMAT` 默认 `text/plain`,用 `I`/`J` 指定像素坐标。
|
|
121
121
|
|
|
122
|
-
OGC API - Features(WFS3)是面向 REST 的 JSON
|
|
122
|
+
OGC API - Features(OAPIF,旧称 WFS3)是面向 REST 的 JSON/HTML 接口,按项目发布,服务根为 `/wfs3`(如 `/wfs3/collections`、`/wfs3/collections/{id}/items`),`/wfs3/api` 提供自描述文档,支持 `limit`、`bbox`、`datetime` 等查询参数。该服务是否可用取决于项目 `OWS Server` 页的发布设置。
|
|
123
|
+
|
|
124
|
+
> 官方注意:OAPIF 遵循 OpenAPI 规范,不接受额外查询参数,因此**不建议**在 URL 里暴露 `MAP`;改用 `QGIS_PROJECT_FILE` 环境变量或 Web 服务器重写规则指定项目(实测 QGIS 3.44/4.2 Server 手册 "OGC API Features" 一节)。
|
|
123
125
|
|
|
124
126
|
### 在项目中启用服务
|
|
125
127
|
|
|
@@ -205,19 +207,18 @@ location /qgis {
|
|
|
205
207
|
| `GetPrint` 报错或输出空白 | Linux 无 X 环境,需安装并启动 `Xvfb`,在 Web 服务器配置 `DISPLAY=:99` |
|
|
206
208
|
| WFS `Transaction` 提交失败 | 需通过 POST 提交(删除可用 `OPERATION`),且数据源必须可写、图层勾选相应发布权限 |
|
|
207
209
|
| 高并发下响应缓慢 | 开启 `QGIS_SERVER_PARALLEL_RENDERING`、调大 `QGIS_SERVER_MAX_THREADS` 与项目缓存 |
|
|
210
|
+
| 直接执行 `qgis_mapserv.fcgi` 无输出 | 正常:FCGI 需由 Web 服务器以 FastCGI 协议调用;用 `curl` 带 `SERVICE=WMS&REQUEST=GetCapabilities` 验证 |
|
|
208
211
|
|
|
209
212
|
---
|
|
210
213
|
|
|
211
|
-
##
|
|
212
|
-
|
|
213
|
-
- QGIS Server 手册:<https://docs.qgis.org/latest/en/docs/server_manual/>
|
|
214
|
-
- 配置与环境变量:<https://docs.qgis.org/latest/en/docs/server_manual/config.html>
|
|
215
|
-
- WMS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wms.html>
|
|
216
|
-
- WFS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wfs.html>
|
|
217
|
-
- WMTS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wmts.html>
|
|
218
|
-
- 容器化部署:<https://docs.qgis.org/latest/en/docs/server_manual/containerized_deployment.html>
|
|
214
|
+
## AI 使用建议
|
|
219
215
|
|
|
220
|
-
|
|
216
|
+
- **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell),Windows 上 `curl` 要写 `curl.exe`;Apache/Nginx 片段属于目标服务器配置,本机会话改不了远端,需在主机上执行或用容器验证。
|
|
217
|
+
- **先探测版本**:用同一安装的 `qgis --version` / `qgis_process --version`(或 `dpkg -l qgis-server`、容器镜像 tag)确认服务端版本;Debian/Ubuntu 的服务入口是 `/usr/lib/cgi-bin/qgis_mapserv.fcgi`,直接执行返回 `ServiceExceptionReport` 即安装可用。本技能覆盖 4.2.3(最新)与 3.44.15(LTR),生成项目的 QGIS Desktop 与服务端大版本应一致。
|
|
218
|
+
- **验证服务**:先 `curl "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities"` 存盘后核对 `<Service>` 与 `<Layer>` 清单,再测 `GetMap` 出图(导出的 PNG 要实际打开看是否空白)、`GetFeature`、`GetTile`。
|
|
219
|
+
- **常见报错**:`Service unknown or unsupported` 是缺 `SERVICE`/`MAP` 参数而非服务故障;`GetMap` 空白先查 `MAP` 路径可读性与项目 `OWS Server` 页的 `published` 勾选,再查 CRS/`BBOX`。
|
|
220
|
+
- **日志与生效**:`QGIS_SERVER_LOG_STDERR=1` 交给 journald 或容器日志;`QGIS_SERVER_LOG_FILE` 已废弃,不要再用;`QGIS_SERVER_*` 改动要重启 FCGI 进程(或容器)才生效。
|
|
221
|
+
- **安全与权限**:启动容器、开放端口、改 Web 服务器配置前先征得用户同意;`GetPrint` 在无 X 的 Linux 上需 `Xvfb`;项目文件可能含数据库凭证,命令与回答里不要回显密码。
|
|
221
222
|
|
|
222
223
|
## 相关技能
|
|
223
224
|
|
|
@@ -228,23 +229,11 @@ location /qgis {
|
|
|
228
229
|
|
|
229
230
|
---
|
|
230
231
|
|
|
231
|
-
##
|
|
232
|
-
|
|
233
|
-
### 关键注意事项
|
|
234
|
-
|
|
235
|
-
- **`MAP` 必填**:几乎所有 QGIS 扩展请求都要求 `MAP` 指向存在的项目文件;用 `QGIS_PROJECT_FILE` 可设默认值。
|
|
236
|
-
- **版本匹配**:生成项目的 Desktop 与服务端版本尽量一致,跨大版本先在小环境验证。
|
|
237
|
-
- **日志优先 stderr**:`QGIS_SERVER_LOG_FILE` 已废弃,统一用 `QGIS_SERVER_LOG_STDERR`。
|
|
238
|
-
- **发布开关**:图层是否出现在服务中取决于项目 `OWS Server` 页的 `published`/`queryable` 设置,而非仅由 URL 决定。
|
|
239
|
-
|
|
240
|
-
### 常见配置模式
|
|
232
|
+
## 参考资源
|
|
241
233
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
└── Docker (qgis-server + nginx)
|
|
249
|
-
└── MAP / QGIS_PROJECT_FILE + QGIS_SERVER_* 环境变量
|
|
250
|
-
```
|
|
234
|
+
- QGIS Server 手册:<https://docs.qgis.org/latest/en/docs/server_manual/>
|
|
235
|
+
- 配置与环境变量:<https://docs.qgis.org/latest/en/docs/server_manual/config.html>
|
|
236
|
+
- WMS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wms.html>
|
|
237
|
+
- WFS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wfs.html>
|
|
238
|
+
- WMTS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wmts.html>
|
|
239
|
+
- 容器化部署:<https://docs.qgis.org/latest/en/docs/server_manual/containerized_deployment.html>
|