My latest work project has taken me down the path of custom GIS desktop application development using the PyQGis API. I’ve been very impressed with both the range of functionality provided by the PyQGis API as well as the efficiency and ease in becoming productive in this environment relatively quickly. I come from a more traditional ArcObjects background so maybe that’s why I’ve come to this conclusion — anybody who’s worked in ArcObjects can probably appreciate the fact that it’s very powerful but a total bear to really wrap your head around.
I found one of the biggest challenges in getting going with the QGis API was simply setting up a development environment (since it was all new to me). A huge plus with the QGis framework is that it can be deployed on a variety of platforms — you’re not limited to Windows. However, in my case, I was developing a custom GIS application with an explicit requirement to integrate with an old Win32 COM dll so I knew from the beginning that I was limited to this platform. Since I was targeting the application for a Windows environment, it naturally made the most sense to do my development work in Windows as well.
So this post is a basic tutorial on (at least one way) of setting up a PyQGis development environment on Windows. It’s primarily intended for developers that have an interest in, but limited exposure to Python and QGis. A true pythonista could get started with PyQGis in a matter of minutes, but that was not my position when I got started and I’m sure there are others out there who don’t fall into this category. Plus, I’ll be migrating from Windows to a Mac in the next couple of weeks and this tutorial will provide me with the necessary documentation should I ever find myself developing PyQGis on Windows again in the future (I tend to forget things relatively quickly if they’re not right in front of my face or if I don’t repeat them over and over).
So with that being said, let’s get started.
From the PyQGis documentation, you’ll find that there are three main ways to utilize the PyQGis API:
- via commands in python console window in QGis (via plugins menu)
- via development of custom plugins to the QGis application
- via creation of custom desktop applications
The first two methods above are more or less tightly integrated into the QGis application. I’ll be focusing on the third category in which you develop custom applications using the PyQGis API more or less independent of the QGis application itself.
From the My Aptana view in Aptana Studio, you can install the PyDev plugin by clicking on the Plugins icon
and activating the Platform tab. You’ll see PyDev in the list of plugins — simply click the Get it link:
Select PyDev in the following screen and click Next
Click Next on the following screen and accept the license terms.
GET PyQGis BINDINGS
Once PyDev is installed and you’ve restarted Aptana, the next step is to actually get the PyQGis python bindings themselves. Even though we’ll be building standalone custom GIS applications outside of QGis, the easiest way to get the PyQGis bindings and their dependencies is to install the QGis application itself. There are two easy ways to achieve this in a Windows environment: 1) install the QGis application via the standalone installer OR 2) install the PyQGis python bindings via the OSGeo4W installer. Going this approach also allows us to later explore the other two ways of leveraging the QGis API — via the python command line within QGis and via developing custom QGis plugins. The other advantage to this approach is that the PyQGis API dependencies are also installed with the QGis application (Python, PyQt4 and SIP).
QGis Standalone Installer:
Very straightforward, just follow the prompts.
Can be a little more involved because there are a lot more options. The easiest method is to select the Express Desktop Install option and make sure that "Quantum GIS" is selected in the second screen:
Once QGis is installed, the last step is to configure your PyDev environment to define the environment variables necessary to run the python interpreter and point to the PyQGis python bindings. The configuration paths are different depending upon the type of QGis installation above but the process is the same.
CONFIGURE PYTHON INTERPRETER
The first step is to define the location of the python interpreter (python.exe) that PyDev will use to execute python code. In PyDev, click on Window –> Preferences. Once the preferences window is open, click onPyDev –> Interpreter – Python in the left hand tree view and you should see the following screen:
In the Python Interpreters section at the top, click on New and provide a name and path to the python interpreter (python.exe). For example, for the standalone QGis installation the interpreter should be defined as follows:
For the OSGeo4W QGis installation, the interpreter should be defined as follows:
DEFINE PYTHONPATH ENVIRONMENT VARIABLE
After clicking OK, deselect all options in the next screen (we will add these manually). Next, we need to define all folders to be included in the PYTHONPATH environment variable. Click on New Folder and add the following folders to the PYTHONPATH:
C:\Program Files\Quantum GIS Tethys\apps\Python25
C:\Program Files\Quantum GIS Tethys\apps\Python25\Lib
C:\Program Files\Quantum GIS Tethys\apps\Python25\sip
C:\Program Files\Quantum GIS Tethys\apps\qgis\python
DEFINE PATH ENVIRONMENT VARIABLE
Once the PYTHONPATH environment variable is configured, the last step is to configure the PYTHONHOME and PATH environment variables. Click on the Environment tab in the middle of the screen and then click the New button. Define the PATH environment variable as follows:
C:\Program Files\Quantum GIS Tethys\bin;C:\Program Files\Quantum GIS Tethys\apps\qgis\bin;%PATH%
DEFINE PYTHONHOME ENVIRONMENT VARIABLE
The last configuration to define is the PYTHONHOME environment variable. Click the New button and define this as follows:
C:\Program Files\Quantum GIS Tethys\apps\Python25
TEST THE ENVIRONMENT
Open up a python console window or create a new Python file and type the following commands:
from qgis.gui import *
from qgis.core import *
PyQt4 is a Python module that is a dependency of the PyQGis python bindings. It is a set of python bindings for the Qt application framework — a very robust cross-platform application and GUI framework. QGis.gui and qgis.core are the main modules of the PyQGis python bindings. If everything is configured correctly, these commands should execute without error. If there is a problem in the configuration, you may see an error such as the following:
Traceback (most recent call last):
File "", line 1, in
ImportError: No module named qgis.core
This simply means that a necessary Python module could not be found — check each step and try again until these commands execute without error.