目录
1 引言
本文档既可作为教程,也可作为参考指南。 虽然它没有列出所有可能的用例,但是对主要功能有一个很好的概述。
对于 Python支持最初是在QGIS 0.9中引入的。 目前,在QGIS桌面版中有几种方法可以使用Python ,如下 :
-
在QGIS的Python控制台中
-
创建并使用插件
-
QGIS启动时自动运行Python代码
-
基于QGIS API创建自定义应用程序
Python绑定也可用于QGIS服务,包括Python插件(请参阅QGIS Server Python插件)和Python绑定,可用于将QGIS服务嵌入到Python应用程序中。 这里有一个完整的QGIS API参考——用于记录QGIS库中的类。 Pythonic QGIS API(pyqgis)几乎与C ++ API相同。 学习如何执行常见任务的一个好办法——是从插件仓库下载现有插件并学习它们的代码。
1.1 在Python控制台中编写脚本
QGIS为脚本编写提供了一个集成的python控制台。可以从插件→python控制台菜单中打开:
上面的截图说明了如何获取图层列表中当前选定的图层,并显示其ID,如果是矢量图层,还可以选择显示要素个数。对于与qgis环境的交互,有一个iface变量,它是QgisInterface的一个实例。此接口允许访问地图画布、菜单、工具栏和QGIS应用程序的其他部分。
为了方便用户,在启动控制台时将会执行以下语句(将来可以设置更多的初始命令)
from qgis.core import *
import qgis.utils
对于经常使用控制台的用户,设置打开控制台的快捷方式可能很有用(在设置→键盘快捷键...)
1.2 Python插件
可以使用插件来扩展QGIS的功能。现在也可以使用Python编写插件。与C ++插件相比,主要优点是分发简单(不对每个平台进行编译)、更容易的开发。
自从引入对Python的支持以来,已经编写了许多涵盖各种功能的插件。插件安装程序允许用户轻松获取、升级和删除Python插件。有关插件和插件开发的更多信息,请参阅Python插件页面。
在Python中创建插件很简单,请参阅开发Python插件以获取详细说明。
小贴士:Python插件也可用于QGIS服务器(QGIS as OGC数据服务器),有关详细信息,请参阅QGIS Server Python插件。
1.3 QGIS启动时运行Python代码
每次QGIS启动时,都有两种不同的方法来运行Python代码。
-
创建startup.py脚本
-
将
PYQGIS_STARTUP
环境变量设置为现有Python文件
1.3.1 startup.py文件
每次QGIS启动时,用户的Python主目录都会搜索名为startup.py
的文件。 如果该文件存在,则由嵌入式Python解释器执行。
-
Linux:
.local/share/QGIS/QGIS3/profiles/default/python
-
Windows:
AppData\Roaming\QGIS\QGIS3\profiles\default\python
-
macOS:
Library/Application Support/QGIS/QGIS3/profiles/default
小贴士:默认路径取决于操作系统。要查找适合您的路径,请打开Python控制台,并运行QStandardPaths.standardLocations(QStandardPaths.AppDataLocation)
查看默认目录列表。
1.3.2 PYQGIS_STARTUP环境变量
你可以在QGIS初始化完成之前将PYQGIS_STARTUP
环境变量设置为现有Python文件的路径来运行Python代码。
此代码将在QGIS初始化完成之前运行。此方法对于清理sys.path非常有用——可能存在不需要的路径,或用于隔离/加载初始环境——无需虚拟环境,例如在Mac上使用homebrew或MacPorts。
1.4 Python应用程序
为自动化流程创建脚本通常很方便。使用PyQGIS,这是完全可能的——导入qgis.core
模块,初始化它,你就可以进行处理了。
或者您可能想要创建一个使用GIS功能的交互式应用程序——执行测量、将地图导出为PDF或任何其他功能。qgis.gui
模块带来了各种GUI组件,最值得注意的是可以合并到应用程序中的地图画布控件——支持缩放,平移和任何其他自定义地图工具。
必须配置PyQGIS自定义应用程序或独立脚本以定位QGIS资源,例如投影信息,用于读取矢量和栅格图层的提供者等。QGIS资源通过在应用程序或脚本的开头添加几行(代码)来初始化。为自定义应用程序和独立脚本初始化QGIS的代码类似。以下提供各自的实例。
小贴士:千万不能使用qgis.py
作为你的测试脚本的名称,否则Python将无法导入绑定。
1.4.1 在独立脚本中使用PyQGIS
要启动独立脚本,请在脚本开头初始化QGIS资源,类似于以下代码:
from qgis.core import *
# 提供qgis安装位置的路径(windows默认:C:\Program Files\QGIS 3.4\apps\qgis-ltr)
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
# 创建对QgsApplication的引用,第二个参数设置为False将禁用GUI
qgs = QgsApplication([], False)
# 加载提供者
qgs.initQgis()
# 在这里编写代码,加载一些图层,使用处理算法等
# 脚本完成后,调用exitQgis()从内存中删除提供者和图层注册
qgs.exitQgis()
我们首先导入qgis.core
模块,然后配置前缀路径。前缀路径是安装QGIS的路径。它通过调用setPrefixPath
方法在脚本中配置。第二个参数设置为True
,它控制是否使用默认路径。
QGIS安装路径因平台而异,在系统中找到它的最简单方法是在QGIS中使用Python控制台运行 QgsApplication.prefixPath()
并查看输出。
配置前缀路径后,我们在变量qgs
中保存了一个对QgsApplication
的引用。第二个参数设置为False
,表示我们不打算使用GUI,因为我们正在编写一个独立的脚本。配置QgsApplication
后 ,我们通过调用qgs.initQgis()
方法加载QGIS数据提供者和图层注册。在QGIS初始化后,我们准备编写脚本的其余部分。最后,我们通过调用qgs.exitQgis()
从内存中删除数据提供者和图层注册来结束。
1.4.2 在自定义应用程序中使用PyQGIS
在独立脚本中使用PyQGIS和自定义PyQGIS应用程序之间的唯一的区别是在实例化QgsApplication
时的第二个参数。传递True
而不是False
,表示我们计划使用GUI。
from qgis.core import *
# 提供qgis安装位置的路径(windows默认:C:\Program Files\QGIS 3.4\apps\qgis-ltr)
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
# 创建对QgsApplication设置的引用第二个参数为True启用GUI,我们需要这样做,因为这是一个自定义应用程序
qgs = QgsApplication([], True)
# 加载提供者
qgs.initQgis()
# 在这里编写代码,加载一些图层,使用处理算法等
# 脚本完成后,调用exitQgis()从内存中删除提供者和图层注册
qgs.exitQgis()
现在,你可以使用QGIS API——加载图层并执行一些处理或使用地图画布启动GUI。
1.4.3 运行自定义应用程序
如果它们不在一个众所周知的位置,你需要告诉系统在哪里搜索QGIS库和合适的Python模块——否则Python会抛出异常:
>>> import qgis.core
ImportError: No module named qgis.core
可以通过设置PYTHONPATH
环境变量来修复。在以下命令中,<qgispath>
应替换为你的实际QGIS安装路径:
-
在Linux上:export PYTHONPATH=/qgispath/share/qgis/python
-
在Windows上:set PYTHONPATH=c:\qgispath\python
-
在macOS上:export PYTHONPATH=/qgispath/Contents/Resources/python
现在,PyQGIS模块的路径设置完成,但它们依赖于qgis_core
和qgis_gui
库(仅仅作为封装的Python模块 )。这些库的路径通常是操作系统未知的,因此再次出现导入错误(错误消息可能因系统而异):
>>> import qgis.core
ImportError: libqgis_core.so.3.2.0: cannot open shared object file:No such file or directory
通过将QGIS库所在的目录添加到动态链接器的搜索路径来解决此问题:
-
在Linux上:export LD_LIBRARY_PATH=/qgispath/lib
-
在Windows上:set PATH=C:\qgispath\BIN; C:\qgispath\APPS\qgisrelease\BIN;PATH% ,其中
qgisrelease
应替换成您的发布类型(例如,qgis-ltr
,qgis
,qgis-dev
)
这些命令可以放入一个引导脚本,负责启动。使用PyQGIS部署自定义应用程序时,通常有两种可能:
-
要求用户在安装应用程序之前在其平台上安装QGIS。应用程序安装程序应查找QGIS库的默认位置,并允许用户设置路径(如果未找到)。该方法具有更简单的优点,但是它需要用户执行更多步骤。
-
将QGIS与你的应用程序一起打包。发布应用程序可能更具挑战性,并且程序包将更大,但用户将免于下载和安装其他软件的负担。
这两种部署模型可以混合使用——在Windows和macOS上部署独立应用程序,但是对于Linux,将QGIS的安装留给用户和他的包管理器。
1.5 有关PyQt和SIP的技术说明
我们决定使用Python,是因为它是最受欢迎的脚本语言之一。QGIS 3中的PyQGIS绑定依赖于SIP和PyQt5。使用SIP而不是更广泛使用的SWIG的原因是QGIS代码依赖于Qt库。Qt(PyQt)的Python绑定也使用SIP完成,这允许PyQGIS与PyQt无缝集成。
写在最后:文中难免有翻译错误,欢迎您的指正。完整版翻译移步PyQGIS开发者手册-完整版