michalisavraam.org blog

A question often asked when people venture into the wonderful world of Python Geoprocessing with ESRI is how one can read the programming model they make available on their website. As it may not be easily interpreted when one begins programming, I will do my best to unpack it and explain how one can use it more effectively. All images presented here are extracts from the actual model presented by ESRI on their website.

Dual Usages for the Geoprocessor

The geoprocessor within Python can be used for two different purposes: to access tools provided by ESRI to manipulate data (the tools one sees in the ArcToolbox), and to programatically manipulate data using the underlying structures provided by ESRI. To further explain this process, a little understanding of how software works is needed. A software package usually involves multiple components. At the heart of software are basic operations and data models, the core of your software. This core deals with things like accessing and saving data, manipulating numbers and the like. This functionality is usually bundled together to create the tools the software produces. In the case of ArcMap, a tool like buffer could use components about reading and writing data, coordinate transformation routines, and probably some sort of functionality that allows manipulation of spatial data. To bring it back to the geoprocessor, and why it is so much more powerful than using the software by itself, what you get access to is not only the tools ESRI has created for you by compiling multiple elements, but you also get access to a lot of those elements yourself that allows you to write your own buffer tool for example.

Understanding what the Geoprocessor is

When one talks about the geoprocessor, one is referring to a Python object built by ESRI, that allows one to call many different functions to perform operations. As in most Python code, the definitions of the object reside in a module that is provided to you. As with any other module, in order to access it through Python you need to import it. This is done by simply typing import arcgisscripting in your Python code.

import arcgisscripting
# Imports the module provided by ESRI

In this case, the module provides a single command accessible to you called create. This exposed function allows one to instantiate the geoprocessor object. Simply calling the create() command is enough to return to you a geoprocessor object. You can also pass parameters to it, but the only one at the moment is the number 9.3, to create a geoprocessor object that returns values based on the 9.3 iteration of the programming model.

gp = arcgisscripting.create(9.3)
# Instantiates the geoprocessor and assigns the name gp to it

Beginning our Travel in the Geoprocessor Programming Model

The box on the right represents your geoprocessor. While it seems that these are the commands available to the arcgisscripting module, that is incorrect. Therefore, in the Geoprocessor Programming Model, one always enters through the cyan box, as seen on your right. There are few interesting things to note here:

1. There are a lot of names appearing on the list.
2. Each name has a symbol ahead of it.
3. Most name have a parenthesis to their right.
4. A few of those names also have more information on the very right.

Here is how one needs to interpret this part of the diagram. The symbols on the left define what the name represents.

Geoprocessor Variables

If there is a box connected to a dash, or two boxes, then the name represents a variable. What this means is that the name represents a value. There are a few options here:

1. Box on the left of the dash: This represents a built-in variable that is read-only. You as a user have no power to change these value, but can only read it. An example is the variable called MessageCount. The value represents how many messages the geoprocessor object has thus far.
2. Box on both sides of the dash: This represents a variable you can also write too. This is a value that the software can use, and you are allowed to overwrite it with your own value. An example is the OverwriteOutput variable, which allows you to tell the geoprocessor whether it has permission to overwrite existing files.

Example usages for geoprocessor variables is below (click to expand):

import arcgisscripting
# Import the module provided by ESRI
gp = arcgisscripting.create(9.3)
# Instantiate the geoprocessor object

gp.OverwriteOutput = True
# Set the OverwriteOutput variable to True

print gp.MessageCount
# Print the number of messages on the object

Geoprocessor methods

Boxes are not the only symbols that appear on the dashes. There is also an arrow, which represents a function or procedure you are allowed to call. What this means is that by using that name, one is telling the geoprocessor to perform an operation. Some operations also allow you to define variables to be used on the operations. For example, RemoveToolBox is an operation that will remove a Toolbox from the geoprocessor, as long as you can provide its name. There are two types of operations available to you, and to distinguish them one needs to see what appears to the right of the name. here are the possibilities:

1. Methods that do not return anything: A lot of functions do not return anything to the user, and you can see this by the lack of any more information to the right of the name of the function. They perform an operation the user asks for, but do not return something the user can work with, other than a message of their success or a preset value. ResetEnvironments() is an example of such a method.
2. Methods that return objects one can manipulate: Some of the functions in the list return a new object that the user can manipulate. These objects are often Python objects (like a Python List) that contain other ESRI objects, or sometimes an ESRI defined object directly that allows us to further manipulate what the software does. An example is the InsertCursor() method, that will return an object back called a rows object. The ListFields() method returns a Python List object populated with ESRI defined Field objects.

The methods that return an object or a collection of objects also have an arrow on their right linking them with the object they return. For example, all the cursor methods connect to the row object to allow the user to see what that object provides. Similarly, the list methods oftentimes have an arrow to connect them to other objects, like the field object. The special case is the method called CreateObject(), which allows you to create a large set of objects from scratch, like spatial reference, points, valute table, etc.

Example usages of methods follow:

 import arcgisscripting
 # Import the module provided by ESRI
 gp = arcgisscripting.create(9.3)
 # Instantiate the geoprocessor object

 gp.ResetEnvironments()
 # Reset all environments on the geoprocessor object

 tools = gp.ListTools()
 # Returns a Python list of all the tools available, save in the tools variable
for tool in tools:
print tool
# Loop through each tool and print it
 

In the net part of this series I will investigate the objects connected with cursors (meaning the rows object and all connected object, like the row object (singular) and geometry).

Geoprocessor Access to Tools

The geoprocessor object also allows users to call on tools that ESRI provides. Those tools are identical to the tools found in the ArcToolbox. A list of them, with a description, is available from ESRI here (note, it is a large PDF file). Note that the Python scripting syntax is not included in that file, but the help file contains a Python example for each tool. You will need to search for it yourself unfortunately, but the thing one needs to remember is that the tool name remains the same, and all parameters to be passed to it must be within parenthesis.

I hope you enjoyed this article and be sure to visit for the remaining parts.

(5 votes, average: 5.00 out of 5)
 Loading ...

Related posts:

1. Loading the Geoprocessor Safely
2. Understanding the Geoprocessor Programming Model part 3
3. Understanding the Geoprocessor Programming Model part 2
4. 7 wishes for the new Geoprocessor
5. Python Geoprocessing in ArcGIS 9.2 vs. 9.3