Qgis Process

项目地址： https://github.com/qgis/QGIS

文档地址： https://github.com/qgis/QGIS-Documentation

在线文档： https://docs.qgis.org/4.2/en/docs/user_manual/processing/standalone.html

许可证： GPL-2.0+

概述

qgis_process 是 QGIS 自带的命令行工具（QGIS Processing Executor），允许在不启动 QGIS 桌面应用的情况下，直接从命令行运行 Processing 算法和模型（内置算法或由插件提供）。它适用于服务器端批量处理、CI/CD 自动化流水线、脚本化 GIS 工作流等场景。

源码位置：src/process/ 目录下的 main.cpp、qgsprocess.cpp、qgsprocess.h。

环境准备

前置条件

• 安装 QGIS 3.16+（qgis_process 从 QGIS 3.16 开始可用）
• 确保 qgis_process 可执行文件在 PATH 中

无窗口系统（Headless 服务器）

在没有窗口管理器的系统上运行前，需设置环境变量：

export QT_QPA_PLATFORM=offscreen

验证安装

qgis_process --version

命令行语法

qgis_process [--help] [--version] [--json] [--verbose] [--no-python] [--skip-loading-plugins] [command] [algorithm id | model path | script path] [parameters]

全局选项

可用命令

注意： 只有在 metadata.txt 中声明了 hasProcessingProvider=yes 的已安装插件才能被 qgis_process 识别和加载。

核心用法

1. 列出所有算法

qgis_process list

输出所有已注册 Provider 及其提供的算法 ID。

2. 查看算法帮助

qgis_process help qgis:regularpoints

输出算法的描述、参数列表（名称、类型、默认值、是否可选）和输出定义。

JSON 格式帮助（推荐 AI 使用）

qgis_process help native:buffer --json

JSON 输出结构：

{
  "qgis_version": "...",
  "algorithm_details": {
    "id": "native:buffer",
    "name": "Buffer",
    "tags": ["..."]
  },
  "provider_details": {
    "id": "native",
    "name": "QGIS (native c++)"
  },
  "parameters": {
    "INPUT": {
      "name": "INPUT",
      "description": "Input layer",
      "type": {
        "id": "source",
        "name": "Vector Features",
        "acceptable_values": ["Path to a vector layer"]
      },
      "optional": false,
      "default_value": null
    },
    "DISTANCE": {
      "name": "DISTANCE",
      "description": "Distance",
      "type": {
        "id": "distance",
        "name": "Distance"
      },
      "optional": false,
      "default_value": 10
    },
    "OUTPUT": {
      "name": "OUTPUT",
      "description": "Buffered",
      "type": {
        "id": "sink",
        "name": "Vector Layer Destination"
      },
      "is_destination": true,
      "optional": false
    }
  },
  "outputs": {
    "OUTPUT": {
      "description": "Buffered",
      "type": "outputVector"
    }
  }
}

3. 运行算法

基本语法

qgis_process run <algorithm_id> -- PARAM1=VALUE1 PARAM2=VALUE2 ...

示例：缓冲区分析

qgis_process run native:buffer -- INPUT=source.shp DISTANCE=2 OUTPUT=buffered.shp

示例：合并图层（多值参数）

同一参数多次指定即可传入列表值：

qgis_process run native:mergevectorlayers -- LAYERS=input1.shp LAYERS=input2.shp OUTPUT=merged.shp

run 命令附加选项

JSON 格式运行结果

qgis_process run native:buffer --json -- INPUT=source.shp DISTANCE=2 OUTPUT=buffered.shp

JSON 输出结构：

{
  "qgis_version": "...",
  "algorithm_details": { "id": "native:buffer" },
  "inputs": {
    "INPUT": "source.shp",
    "DISTANCE": "2",
    "OUTPUT": "buffered.shp"
  },
  "results": {
    "OUTPUT": "/full/path/to/buffered.shp"
  },
  "log": ["..."]
}

4. 通过 STDIN 传入 JSON 参数（复杂参数）

当参数本身是复杂对象（如字典类型）时，可通过 STDIN 传入 JSON：

qgis_process run <algorithm_id> -

末尾的 - 表示从 STDIN 读取参数。JSON 必须包含 "inputs" 键：

echo '{"inputs": {"INPUT": "my_shape.shp", "DISTANCE": 5}}' | qgis_process run native:buffer -

完整 JSON 结构（含可选配置）：

{
  "ellipsoid": "EPSG:7019",
  "distance_units": "feet",
  "area_units": "ha",
  "project_path": "/path/to/project.qgs",
  "inputs": {
    "INPUT": "my_shape.shp",
    "DISTANCE": 5,
    "SEGMENTS": 8,
    "OUTPUT": "output.shp"
  }
}

注意： 通过 STDIN 传入 JSON 时，输出自动使用 JSON 格式。

5. 插件管理

# 列出插件
qgis_process plugins

# 启用插件
qgis_process plugins enable cartography_tools

# 禁用插件
qgis_process plugins disable cartography_tools

6. 运行模型文件

qgis_process run /path/to/my_model.model3 -- INPUT=data.shp OUTPUT=result.shp

7. 运行 Python 脚本

qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp

常用内置算法速查、参数类型参考与典型工作流示例见 reference/algorithm-cheatsheet.md

AI 使用建议

推荐工作流

1. 发现算法：qgis_process list → 获取所有可用算法 ID
2. 查看帮助：qgis_process help <algorithm_id> --json → 获取参数定义的 JSON
3. 构造参数：根据 JSON 帮助信息构造参数
4. 执行算法：qgis_process run <algorithm_id> --json -- PARAM=VALUE ... 或通过 STDIN 传入 JSON
5. 解析结果：解析 JSON 输出获取结果路径和日志信息

关键注意事项

1. 始终使用 --json 选项：JSON 输出结构化、易解析，是 AI 最友好的交互方式。
2. 先查 help 再构造参数：每个算法的参数名和类型不同，先用 help --json 确认参数定义。
3. 枚举类型传数字索引：枚举参数用数字（如 0、1）而非文字。help 输出的 available_options 提供了索引到含义的映射。
4. 多值参数多次指定：如 LAYERS=a.shp LAYERS=b.shp（在 -- 之后，参数不带前导 --）。
5. 复杂参数用 STDIN JSON：字典类型的参数值适合通过 STDIN JSON 方式传入。
6. 文件路径使用绝对路径：避免工作目录不确定导致的文件找不到。
7. Headless 环境设置 QT_QPA_PLATFORM=offscreen：在无显示器的服务器上必须设置。
8. 需要项目文件的算法：某些算法（如打印布局导出）需要通过 --project_path 指定项目文件。
9. 取消正在运行的算法：使用 CTRL+C 可取消执行中的算法。
10. --no-python 和 --skip-loading-plugins 可加速启动：如果不需要第三方插件提供的算法，使用这两个选项可显著缩短启动时间。

错误处理

• 算法不存在：Algorithm <id> not found!
• 缺少必填参数：The following mandatory parameters were not specified
• 模型文件无效：File <path> is not a valid Processing model!
• Python 脚本无效：File <path> is not a valid Processing script!
• 算法不可在命令行使用：The "<id>" algorithm is not available for use outside of the QGIS desktop application
• 需要项目文件：The "<id>" algorithm requires a QGIS project to execute

算法 Provider 分类

相关技能

• pyqgis — QGIS Python 绑定：../pyqgis/SKILL.md
• gdal — 命令行数据处理：../gdal/SKILL.md
• geopipe-agent — AI 原生分析流水线：../geopipe-agent/SKILL.md
• geoserver-rest-api — REST API 自动化：../geoserver-rest-api/SKILL.md

源码结构参考

源码位于 QGIS 仓库 src/process/ 目录：

核心类

• QgsProcessingExec：命令行执行器，负责解析命令和参数、加载插件、执行算法
• ConsoleFeedback：继承自 QgsProcessingFeedback，处理控制台输出和进度显示，支持文本和 JSON 两种输出模式
• QgsProcessingExec::Flags：执行标志（UseJson、SkipPython、SkipLoadingPlugins）

关键方法