geospatial_desktop_gis_scripting

G A R Y S H E R M A NT H E G E O S PAT I A LD E S K T O PO P E N S O U R C E G I S A N D M A P P I N GThe Geospatial Desktop: Open Source GIS and Mappingby Gary ShermanPublished by Locate PressCopyright 2012 Gary ShermanAll rights reserved978-0-9868052-1-9No part of this work may be reproduced or transmitted in any formor by any means, electronic or mechanical, including photocopying,recording, or by any information storage or retrieval system, with-out the prior written permission of the copyright owner and thepublisher.Direct permission requests to , or mail toLocate Press, PO Box 4844, Williams Lake, BC, Canada V2G 2V8.Editor Tyler MitchellCover Design Julie SpringerInterior Design Based on Tufte-LATEXPublisher Website Book Website ContentsTable of Contents . . . . . . . . . . . . . . . . . . . . . . . . 31 Forward 515 GIS Scripting 26915.1 GRASS . . . . . . . . . . . . . . . . . . . . . . . . . . . 27015.2 QGIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270To get the book, see 51ForwardLocate Press is proud to bring this second edition of Garys bookinto print. The original title, Desktop GIS, published by PragmaticPress successfully sold out, yet there is increasing pressure to haveit back in print.It is special in another way too. It is the first title being publishedby Locate Press. As our flagship book for this new venture weare thrilled to have such a well-known and competent author asGary Sherman. His enthusiasm and inspiration have been a pivotalinfluence in helping us start our publishing endeavour. Thank youGary!Weve found that it is particularly sought-after by academics look-ing for a text book for introducing open source GIS into their courses.Seasoned open source GIS users also have been looking for copiesto give to their friends.The demand for having long term stable access to titles like thiswont be going away anytime soon. Open source geospatial tech-nology continues to take root around the world and across sectors.Financial crises tend to encourage open source adoption due to theExcerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved6 CHAPTER 1. FORWARDlow price tag. Likewise more organisations need to adopt open stan-dards for interoperability and open source geo applications haveproven themselves regularly on that front. So now, more than ever,users are seeking out high quality training material from subjectmatter experts such as Gary.The movement toward both cloud computing and mobile appli-cation platforms also puts increased stress on those products thatcannot operate in a free and open source operating system. For-tunately, most open source geo applications are available across allmajor desktop and server operating systems. So when you need tomove from one operating system to the other, your experience willstill be similar to what you will learn in this book.You are likely to find that this book will fill gaps in ways you didntexpect, from practical everyday tips for selecting software to in-depth examples for completing obscure tasks. I believe this is aspecial book, without comparison, as few other authors have yettaken on the challenge of covering this broad landscape with signif-icant depth.Enjoy the book,Tyler MitchellPublisherExcerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved26915GIS Scripting(Partial Excerpt from The Geospatial Desktop)Most GIS users that I know end up doing a bit of programming,regardless of the software they are using. There is always somelittle task that is easier done with a script or a bit of code. In thischapter, well look at some methods for automating tasks in OSGISsoftware. You dont have to be a programmer to do a bit of scriptwriting, especially when you can get jump-started by downloadingexamples and snippets.The script languages available to you depend on the application youare using. Applications and tools with a command-line interface(CLI) can be scripted with most any language available. Othershave bindings for specific languages. Some nonexhaustive examplesinclude the following: GRASS: Shell, Tcl/Tk, Perl, Ruby, Python QGIS: Python GDAL/OGR: Shell, Perl, Ruby, Python PostGIS: Any language that works with PostgreSQL, includingPerl, Python, PHP, and RubyExcerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved270 CHAPTER 15. GIS SCRIPTINGSome OSGIS applications even provide bindings that allow you towrite a custom application using a language such as Python.In this chapter, we will explore some of the techniques used withthese applications.15.1 GRASSSince the real core of GRASS is comprised of CLI applications, itspretty easy to use most any scripting language to perform tasks.From Perl, Python, Ruby, and Tcl/Tk, you can “call” an applicationand capture the output. This makes GRASS easy to automate.Shell GameWhat do we mean by a shell? Its a command interpreter pro-vided with your operating system. If you use OS X, Linux, ora Unix variant, you likely have bash, csh, and/or ksh availableto you. Windows has cmd, which has its own language andprobably isnt going to be real helpful in shell scripting. Checkout MSYS () and Cygwin ().Probably the simplest way to automate GRASS tasks is using thescripting capabilities of your shell. On Linux and OS X, this is apretty natural thing to do, because both come with a fully capableshell. On Windows, you may have to install a Unix-like shell suchas MSYS or Cygwin to be able to accomplish the same results.15.2 QGISSince version 0.9.x, QGIS has included support for scripting withPython. QGIS provides the following options for using Python: Use the Python console from which you can run scripts using theobjects and methods in the QGIS API.Excerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved15.2. QGIS 271 Write plugins in Python instead of C+. Use PyQt1 to build complete mapping applications using Python 1 /software/pyqt/introand the QGIS libraries.Why would you want to do any of this? Youd be surprised at thethings you might dream up. QGIS has been designed to make thelibraries easily usable in your own plugins and applications. Withthe Python bindings, this brings a whole new world of possibilityfrom simple plugins to complete applications. There is a large as-sortment of Python plugins for QGIS. To find out whats available,view the current list from the Plugins!Fetch Python Plugins menu.Were going to take a look at a simple plugin to help us get an ideaof what can be done with the PyQGIS bindings. Using Python to getstarted is pretty easy, so dont be afraid if you arent a programmer.Lets start by looking at the console.The Python ConsoleThe console is a bit like using Python from the command line. Itlets you interactively enter bits of code and see the result. This isa good way to experiment with the interface and can actually behelpful when you are writing a plugin or application.To bring up the Python console, go to the Plugins menu, and choosePython Console. The console looks similar to a terminal or com-mand window. Make sure you read the little tip at the top.The console is not of much use if we dont know what to enter intoit. Lets try a simple example and change the title of the main QGISwindow. The iface object provides you with access to the QGISAPI. Using it, we can reference the main window and set the title:qgis.utils.iface.mainWindow().setWindowTitle(Hello from Desktop GIS!)In Figure 15.1, on the following page, we can see the result of ourExcerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved272 CHAPTER 15. GIS SCRIPTINGFigure 15.1: Changing the window ti-tle with Pythonlittle example, with the console in front and the new title showingon the QGIS window behind it.Changing the title isnt all that useful, but it shows you how toaccess the interface to the QGIS internals. The console is a goodexploratory tool for learning about the QGIS API.To manipulate the map canvas, we can try:qgis.utils.iface.zoomFull()Excerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved15.2. QGIS 273This will zoom the map to its full extent. Now youre probablywondering how to find out what functions are available. The an-swer is the QGIS API documentation, available from the website.2 2 /apiThe API may be a bit intimidating at first, but its very useful, infact essential, to our Python exploits. When you use the ifaceobject in the Python console, you are actually using an instanceof the QgisInterface class.3 If we look at the documentation for 3 /api/classQgisInterface.htmlQgisInterface, we find functions such as the following: zoomFull(): Zoom to full extent of map layers. zoomToPrevious(): Zoom to previous view extent. zoomToActiveLayer(): Zoom to extent of the active layer. addVectorLayer(QString vectorLayerPath, QString baseName,QString providerKey): Add a vector layer. addRasterLayer(QString rasterLayerPath): Add a raster layergiven a raster layer filename. addRasterLayer(QString rasterLayerPath, QString baseName=QString():Add a raster layer given a QgsRasterLayer object. addProject(QString theProject): Add a project. newProject(bool thePromptToSaveFlag=false): Start a blank project.We already used the zoomFull method to zoom to the full extent ofall the layers on our map. You can see there is a lot of potential herefor manipulating the map, including adding layers and projects.We can use these same methods in our plugins and stand-aloneapplications as well. As you dive into PyQGIS, the documentationwill be your friend. You should also keep a copy of the PyQGISDeveloper Cookbook4 handy as well. It contains a lot of information 4 /pyqgis-cookbook/for doing common operations like adding and working with layers,dealing with projections, styling layers.Think of the Python console as a workbench for trying methods andusing classes in the QGIS API. Once you get that under your belt,youre ready for some real programming. Well start out by creatinga little plugin using Python.Excerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved274 CHAPTER 15. GIS SCRIPTINGA PyQGIS PluginWriting plugins in Python is much simpler than using C+. Letswork up a little plugin that implements something missing from theQGIS interface. For this exercise, youll need QGIS 1.0 or greater,Python, PyQt, and the Qt developer tools.Harrison just received the latest Birding Extraordinaire magazine,and in it he finds an article that describes locations for the exoticMooseFinch. The locations are in latitude and longitude, whichMooseFinch: A mythical creaturedont mean much to Harrison unless hes in his backyard. He firesup QGIS, adds his layer containing the world boundaries, and be-gins hunting for the coordinates. Sure, he can use the coordinatedisplay in the status bar to eventually find what he wants, butwouldnt it be nice to be able to just zoom to the coordinates byentering them? Well, thats what our little plugin will do for us(and Harrison).Before we get started, we need to learn a little bit about how theplugin mechanism works. When QGIS starts up, it scans certaindirectories looking for both C+ and Python plugins. For a file(shared library, DLL, or Python script) to be recognized as a plugin,it has to have a specific signature. For Python plugins the require-ments are pretty simple and, as well see in a moment, somethingwe dont have to worry about.Regardless of your platform, youll find your Python plugins areinstalled in the .qgis subdirectory of your home directory: Mac OS X and Linux: .qgis/python/plugins Windows: .qgispythonpluginsFor QGIS to find our Python plugin, we have to place it in the appro-priate plugin directory for our platform. Each plugin is contained inits own directory. When QGIS starts up, it will scan each subdirec-tory in our plugin directory (for example, $HOME/.qgis/python/pluginson Linux and Mac) and initialize any plugins it finds. Once thatsdone, our Python plugin will show up in the QGIS plugin managerExcerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved15.2. QGIS 275where we can activate it just like the other plugins that come withQGIS. You can also specify an additional path for QGIS to search forplugins by using the QGIS_PLUGINPATH environment variable. OK,enough of that, lets get started writing our plugin.Setting Up the StructureBack in the old days (around version 0.9) we had to create all the Boilerplate: standardized pieces oftext for use as clauses in contracts oras part of a computer programboilerplate for a Python plugin by hand. This was tedious and ba-sically the same for each plugin. Fortunately thats no longer thecasewe can generate a plugin template using the Plugin Builder.The Plugin Builder is itself a Python plugin that takes some inputfrom you and creates all the files needed for a new plugin. Itsthen up to you to customize things and add the code that doesthe real work. To use the Plugin Builder, first install it from thePlugins!Fetch Python Plugins menu as seen in Figure 15.2.Figure 15.2: Installing the PluginBuilderWhen you click on the Install plugin button the Plugin Builder willbe installed and youll find a tool for it on the Plugins toolbar andExcerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved276 CHAPTER 15. GIS SCRIPTINGmenu entries under Plugins!Plugin BuilderLets generate the structure for our Zoom to Point plugin by click-ing on the Plugin Builder tool or menu item. We are presentedwith a dialog that contains all the fields needed to create the plugin.On the left side of the plugin dialog youll see some hints aboutwhat is expected for each field. Figure 15.3 shows all the fieldsneeded to generate the Zoom to Point plugin.Figure 15.3: Plugin Builder Ready toGenerate the Zoom to Point PluginWhen we click on OK, the Plugin Builder generates a bunch of files:icon.pngA default icon used on the toolbar. You will likely want to cus-tomize this to better represent your plugin._init_.pyThis script initializes the plugin, making it known to QGIS. Thename, description, version, icon, and minimum QGIS version areeach defined as Python methods.Excerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved15.2. QGIS 277MakefileThis is a GNU makefile that can be used to compile the resourcefile resources.qrc and the user interface file (.ui). This requiresgmake and works on both Linux and Mac OS X and should alsowork under Cygwin on Windows.metadata.txtThe metadata file contains information similar to the methods in_init.py_. Beginning with QGIS 2.0, the metadata file will beused instead of _init.py_ to validate and register a Pythonplugin.resources.qrcThis is a Qt resource file that contains the name of the pluginsicon.ui_zoomtopoint.uiThis is the Qt Designer form that provides a blank dialog withOK and Cancel buttons. Its up to you to customize this to buildyour plugins user interface.zoomtopoint.pyThis is the main Python class for your plugin that handles load-ing and unloading of icons and menus, and implements the runmethod that is called by QGIS when your plugin is activated.Youll need to customize the run method to make the plugin doits magic.zoomtopointdialog.pyThis Python class contains the code needed to initialize the plu-gins dialog.Youll notice the naming of a number of the files is based on a lowercase version of the name you provide for your plugin, in this casezoomtopoint.After the plugin generates the needed files, a results dialog is shownthat contains some helpful information, as shown in Figure 15.4, onthe next page.Excerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved278 CHAPTER 15. GIS SCRIPTINGFigure 15.4: Results of Generatingthe ZoomToPoint PluginThe results dialog contains helpful information including: Where the generated plugin was saved The location of your QGIS plugin directory Instructions on how to install the plugin Instructions on how to compile the resource and user interfacefiles How to customize the plugin to make it do something usefulAt a minimum the only files we have to modify to get the pluginfunctional are the user interface file (.ui) and the implementationfile (zoomtopoint.py). If you need additional resources (icons orimages) you will need to modify resources.qrc.Excerpted from The Geospatial Desktop Copyright 2012 Gary Sherman, All rights reserved15.2. QGIS 279Defining ResourcesIf you use the Plugin Builder you dont have to modify the resourcesfile, but you do have to compile it. Lets take a look at whats in theresource file:icon.pngThis resource file uses a prefix to prevent naming clashes with otherplugins. Its good to make sure your prefix will be uniqueusuallyusing the name of your plugin is adequate.5 The icon is just a PNG 5 Plugin Builder created the prefix foryou based on the plugin name.image that will be used in the toolbar when we activate our plugin.You can create your own PNG or use an existing one. The only realrequirement is that it be 22-by-22 pixels so it will fit nicely on the You dont have to change the icon dur-ing developmentthe default createdby Plugin Builder works fine.toolbar. You can also use other formats (XPM for one), but PNG isconvenient, and there are a lot of existing icons in that format.Once we have the resource file built, we need to use the PyQt re-source compiler to compile it:pyrcc4 -o resources.py resources.qrcThe -o switch is used to define the output file. If you dont includeit, the output of pyrcc4 will be wr