Creating a GenGIS plugin

The functionality of GenGIS can be extended by writing a Python plugin. Python plugins reside in the plugins folder within your GenGIS directory. In this tutorial we will create a simple "Hello World" plugin which writes a simple greeting to the GenGIS viewport.

Specifying Plugin Details

Begin by creating the directory HelloWorld within the GenGIS plugins' directory. Within this directory create a file called __init__.py. This file contains general information about your plugin which is used by GenGIS. For our Hello World plugin, enter the following into __init__.py:

def name():
  return "Hello World"

def version():
  return "Version 1.0"

def description():
  return "Prints Hello World to the Viewport."

def authors():
  return "Donovan Parks"

def publicationDate():
  return "March 1, 2012"
	
def minimumVersionOfGenGIS(): 
  return "2.0"

def requireR():
  return False

All plugins require an __init__.py file and must contain all the functions shown above.

Writing the Plugin

The plugin must contain a Python file with the same name as the directory in which it resides. In this example, we need to have a file called HelloWorld.py and this file must contain a class called HelloWorld. Within GenGIS an object of this class is created whenever a user invokes the plugin. A plugin interacts with GenGIS through an API which is exposed through a module called GenGIS. Create the file HelloWorld.py with the following code:

import GenGIS

class HelloWorld():
  def __init__(self, parent=None):
    label = GenGIS.VisualLabel("Hello World!", GenGIS.Colour(0,0,0), 36, GenGIS.LABEL_RENDERING_STYLE.ORTHO)
    label.SetScreenPosition(GenGIS.Point3D(10,40,1))
    GenGIS.graphics.AddLabel(label)
    GenGIS.viewport.Refresh()

Further information about the GenGIS API can be found in the GenGIS manual. We also recommend consulting existing plugins in order to see how they function and make use of the GenGIS API.

Creating a GUI for your Plugin

GenGIS makes uses the wxPython library for creating user interfaces. Under Windows, we have found the program wxFormBuilder to be extremely helpful as it provides a simple WYSIWYG interface for creating GUIs. All the plugins currently use wxFormBuilder. wxFormBuilder saves interfaces as *.fbp files which are compiled by wxFormBuilder to generate Python code. See any of the provided plugins for examples on how to create a GUI for your plugin.

Releasing a Plugin

We encourage you to make your plugins available to other GenGIS users. If you wish to have your plugin made available on the GenGIS website please contact Rob Beiko (beiko@cs.dal.ca).