Geoprocessing : Python

Using arcgisscripting's "9.3" switch

bbicking1 — Tue, 28 Jul 2009 21:46:00 GMT

This blog post was written by Ghislain Prince, Product Engineer on the Geoprocessing Team in Redlands.

Hi Everybody!

We learned in the Advanced Python Scripting Technical Workshops at UC that many of you who use ArcGIS 9.3 do not yet use the changes we made to the geoprocessor. We just wanted you guys to be aware of this option when writing your Python scripts at 9.3. The 9.3 switch option is specified when the geoprocessor is created; in code it looks like this

import arcgisscripting

gp = arcgisscripting.create(9.3)

Existing (pre-9.3) scripts will obviously not have this option as it didn’t exist before the 9.3 release. We’re sure you’ve already noticed that they continue to work unchanged. To get the 9.3 geoprocessor behavior, it is not enough to simply change gp = arcgisscripting.create() to gp = arcgisscripting.create(9.3) - that does not work, because your code needs to be updated elsewhere in your script to accommodate the changed behavior.

The main goal for this switch is that when you create new scripts in ArcGIS 9.3, you will use the “9.3” geoprocessor and get a much nicer coding experience. This “nicer” experience is achieved because the geoprocessor uses more of Python’s native structures as inputs and outputs.

It’s obvious that the improvements to the geoprocessor make it easier for you to write code and resulting code is easier to read and maintain. Of course the changes are not limited to the List functions; here’s the complete list of differences and a comparison with several code examples.

2009 Developers Summit

dmhoneycutt — Wed, 25 Mar 2009 23:54:00 GMT

The 2009 Developers Summit has come and gone. Thanks to all who attended! We enjoyed meeting with you. We've uploaded the geoprocessing presentations to the Model and Script tool gallery. Session videos have been posted to the Media Gallery.

Slides, scripts, and data from the two workshops on Designing and Building geoprocessing tools are available in the Model and Script tool gallery, or by clicking here.

Slides and other materials from the Building Geoprocessing Services session are available here.

Slides and scripts for the Python Scripting Advanced Techniques session are available here.

Send us your feedback

dmhoneycutt — Wed, 25 Mar 2009 23:47:00 GMT

You may not have noticed, but you can send us feedback about this site. There's a feedback link at the bottom right of the home page, as illustrated at the bottom of this post.

We're particularly interested in hearing from you about blog post topics you'd like to see and suggestions on how we could make this site more useful.

Tips and tricks - accessing feature shape in Calculate Field

dmhoneycutt — Fri, 06 Mar 2009 23:44:00 GMT

With the Calculate Field tool, you can easily create expressions that use some property of a feature's shape, such as length or area. You can also convert length and area to different units. The illustration below shows calculating the MILES field to the length (in miles) of each line feature.

Details about the Expression syntax

The expression syntax -- !shape.length@miles! -- starts and ends with the special 'decode field' character. This decode field character is different depending on the value of the Expression Type parameter. For Expression Type of PYTHON or PYTHON_9.3, the character is an exclamation point ("!"), as shown in the illustration above. For VB, the decode field characters are "[" and "]".

Inside the decode field characters, you can put the name of any field found on the input table. You can also use the reserved field name "shape" followed by a period and an attribute of the shape. In this case, we're using the length attribute: !shape.length!

More things you can do with the shape object and its attributes

The shape field is actually a geometry object with the following properties.

If, for example, you wanted the X-coordinate of the first point of a line, you would use !shape.firstpoint.x! To find the minimum X-coordinate of the line, use !shape.extent.xmin!

Simple equations

The expression can contain simple equations. For example, to calculate minutes it would take to traverse a street segment going 30 miles per hour, use:

!shape.length@miles! / (30.0 / 60.0)

Note that:

!shape.length@miles! / (30 / 60)

won't work - when doing real arithmetic you need the decimal point after 30 and 60.

Code blocks

See http://www.esri.com/news/arcuser/0507/files/pythonscript.pdf for information on using code blocks in Calculate Field

Tips and tricks - Error handling in Python script tools

dmhoneycutt — Mon, 01 Dec 2008 17:43:00 GMT

I recently had a project that involved creating lots of Python script tools. Since other people were going to use these tools, I wanted my error handling to be robust and informative. This post is about some tips and tricks I discovered during this project.

Error handling basics

The basics of handling Python errors are covered in the 9.3 help topic Error handling with Python. The Python.org document Errors and Exceptions has more detailed information.

Tip #1 - Use the arcgisscripting.ExecuteError exception

In version 9.2, we introduced the arcgisscripting object along with a new exception class, arcgisscripting.ExecuteError. (This arcgisscripting.ExecuteError exception class wasn't documented in version 9.2, so few people knew about it.) The arcgisscripting.ExecuteError exception is thrown whenever a geoprocessing tool or geoprocessing function encounters an error. What this means is that you can divide errors into two groups, geoprocessing errors (those that throw the arcgisscripting.ExecuteError exception) and everything else. You can then handle the errors differently, as demonstrated in the code below:

import arcgisscripting
gp = arcgisscripting.create(9.3)
try:
    result = gp.getcount("C:/blah.shp")
    # x = y
        
# Return GEOPROCESSING specific errors
#
except arcgisscripting.ExecuteError:
    gp.AddError(gp.GetMessages(2))
    
# Return any PYTHON or system specific errors
#
except:
    gp.AddError("Python or system error occurred")

The code above is used as the source for a script tool. To keep things simple, the script tool has no parameters. When the script tool is executed, the call to getcount produces an error because the dataset "C:/blah.shp" doesn't exist. As a result, the progress dialog looks as follows:

To prove how geoprocessing errors and Python errors are handled differently, change the two lines of code as follows:

    # result = gp.getcount("C:/blah.shp")
    x = y

Now when the script is executed, an error will occur because the variable 'y' is undefined, and the progress dialog will display as follows:

Tip #2 - Beware of getting error messages from a result object

Before moving on, a quick word about the result object, shown below:

    result = gp.getcount("C:/blah.shp")

If the call to getcount above raises an exception, the result object is null. This means you cannot retrieve error messages from the result object. For example:

import arcgisscripting
gp = arcgisscripting.create(9.3)
try:
    result = gp.getcount("C:/blah.shp")
        
# Return GEOPROCESSING specific errors
# (this method is INCORRECT!)
except arcgisscripting.ExecuteError:
    gp.AddError(result.GetMessages(2))
    
# Return any PYTHON or system specific errors
#
except:
    gp.AddError("Python or system error occurred")

The above code will fail with the message "name 'result' is not defined". This is due to the fact that the result object is null. Since the result object is null, a Python error will be raised since a null object doesn't have a GetMessages() method. Note -- a result object created by calling a geoprocessing service on an ArcGIS Server is never null. Null result objects a created only when a tool is run locally and it raises an error. For more information about using the result object, see Getting results from a geoprocessing tool.

Tip #3 - Use AddReturnMessage() to preserve links to error codes

In version 9.3, geoprocessing error numbers shown in the progress dialog are hyperlinks to a help page that further describes the error. To enable hyperlinks for errors in your script, you need to use the AddReturnMessage() method instead of the AddError method, as follows:

import arcgisscripting
gp = arcgisscripting.create(9.3)
try:
    result = gp.getcount("C:\\blah.shp")
        
# Return GEOPROCESSING specific errors
#
except arcgisscripting.ExecuteError:
    for msg in range(0, gp.MessageCount):
        if gp.GetSeverity(msg) == 2:
            gp.AddReturnMessage(msg)
    
# Return any PYTHON or system specific errors
#
except:
    gp.AddError("Python or system error occurred")

Now when the script is executed, the progress dialog will look as follows:

Tip #4 -- Use traceback to return more information about the error

The help system topic Error handling with Python shows you how to use Python's traceback to retrieve the line number causing the error, the name of the .py file, and, for Python errors, a description of the error.

At version 9.3, you can run script tools in-process, as described in Running a script in process. Scripts run in-process execute much faster than scripts run out-of-process, so you always want to run the script in-process. When a script is run in-process, ArcGIS reads the .py file into memory and then executes it. Because ArcGIS puts the .py files into memory, the Python traceback module doesn't know the name of the .py file and will report the file name as "<string>". If you want to report the name of the .py file causing the error (very useful for debugging), you'll have to provide it yourself.

The script below has a local routine, trace(), that uses traceback to return the line number, the file name, and the error description. The routine also contains the the hard-coded file name (shown in bold) which you must change for your script.

import arcgisscripting
gp = arcgisscripting.create(9.3)
try:
    def trace():
        import os, sys, traceback
        tb = sys.exc_info()[2]
        tbinfo = traceback.format_tb(tb)[0]  # script name + line number
        line = tbinfo.split(", ")[1]
        
        # Construct the pathname to this script.  Get the pathname
        #  to the folder containing the script using sys.path[0]. 
        #  Modify line below and replace 'myscript.py' with the name of
        #  this script. 
        #
        filename = sys.path[0] + os.sep + "myscript.py"
        
        # Get Python syntax error
        #
        synerror = traceback.format_exc().splitlines()[-1]
        return line, filename, synerror
    if __name__ == '__main__':  
        # y = x
        result = gp.getcount("C:/blah.shp")
        
except arcgisscripting.ExecuteError:
    # Call our trace routine to retrieve line number and filename.
    #  (returned variable 'err' is ignored since this is a gp error.
    #
    line, filename, err = trace()
    gp.AddError("Geoprocessing error on " + line + " of " + filename + " :")
    for msg in range(0, gp.MessageCount):
        if gp.GetSeverity(msg) == 2:
            gp.AddReturnMessage(msg)
    
except:
    line, filename, err = trace()
    gp.AddError("Python error on " + line + " of " + filename)
    gp.AddError(err)

Below are illustrations of the progress dialog showing the line number and file name for both a geoprocessing error and a Python syntax error (by commenting out the "y = x" statement).

Tip #5 -- Use Finally statement to clean up cursors

Something I discovered by reading the Python doc Errors and Exceptions is the 'finally' statement. No matter what happens in your Python script, code in a 'finally:' block always gets executed. It's a great place to put clean-up actions, such as deleting cursors, as shown in the code below.

import arcgisscripting
gp = arcgisscripting.create(9.3)

def trace():
    import os, sys, traceback
    tb = sys.exc_info()[2]
    tbinfo = traceback.format_tb(tb)[0] 
    line = tbinfo.split(", ")[1]
    filename = sys.path[0] + os.sep + "testscript.py"
    synerror = traceback.format_exc().splitlines()[-1]
    return line, filename, synerror

if __name__ == '__main__':
    # Define variables for a cursor and its row
    #
    cursor, row = None, None
    try:
        cursor = gp.searchcursor("E:/Data/CityOfSanFrancisco.gdb/FireStations")
        row = cursor.Next()
        while row:
          # Code here...
          # for demonstration...this next statement will cause an error
          y = x
          row = cursor.Next()
    except arcgisscripting.ExecuteError:
        line, filename, err = trace()
        gp.AddError("Geoprocessing error on " + line + " of " + filename + " :")
        for msg in range(0, gp.MessageCount):
            if gp.GetSeverity(msg) == 2:
                gp.AddReturnMessage(msg)
    except:
        line, filename, err = trace()
        gp.AddError("Python error on " + line + " of " + filename)
        gp.AddError(err)
    finally:
        # Close cursor and row objects.
        #
        del row, cursor
            
        # Print a message for demo purposes
        #
        gp.AddMessage("\n   ** Cursor and row have been deleted ** \n")

As illustrated below, the cursor gets deleted even if there is an error in the script.

In the main body of the script, the cursor and row object variables are declared and initialized to None (shown in bold in the above code). This ensures that these two variables exist when the del statement in the finally clause is executed; if you try to delete a non-existent variable, an exception will be thrown.

About cursors and the del statement

The Python del statement deletes a variable. You can use it to delete any Python variable, such as a list or dictionary. However, you rarely need to delete native Python variables. The del statement is mainly used for deleting non-native variables, such as geoprocessing cursors and rows obtained from the cursor. When you delete a cursor and its row, all pending changes to the row (caused by an update or insert cursor) are flushed and all locks on the dataset are removed. You should always delete cursors and rows obtained from the cursor. When deleting a cursor, delete the row object first, then the cursor.

Tips and tricks - Unix, Python, and Geoprocessing

dmhoneycutt — Mon, 27 Oct 2008 22:41:00 GMT

This posting was written by Mark Zollinger, a Product Engineer and long time UNIX user with the Geoprocessing team.

Do you like Solaris or Linux? Do you "do GIS" on one of those platforms? Maybe you've been asked to convert some ArcGIS Workstation AML applications over to ArcGIS Engine. Are you a command-line junkie? (There are more of us than you might think)

If, for one of the above or any other reason, you find yourself wondering if you should try developing GIS on Solaris or Linux, then it's time to stop wondering. Join in with others who include a flavor of *nix in their list of working development platforms.

There are several approaches to GIS development that work very well on Solaris and Linux.

If you are into low-level programming, you should consider Java or C++, both of which can access ArcGIS's ArcObjects API. I've used Java quite a bit over the years, and can tell you that the doors are wide open on what you can do with it. If this sound like the thing for you, then you can move along now, there's nothing to see here. This post isn't about ArcObjects at all.

If you lean towards scripting and higher level abstractions, then geoprocessing's more coarse-grained object model, then you are in the right place. The rest of this post will show you how to set up an IDE for Python development and write a very simple geoprocessing script.

I mentioned a moment ago that I've written my share of Java ArcObjects code. I've got to confess though, that I've always been a fan of scripting languages. Python and GP is where I spend most of my time these days.

Setting up

"Okay", you ask, "How do I start writing GP code in Python on non-Windows platforms?"

You can do Python and GP from the command line, and I often prefer the focus this brings. I've found, however, that most folks prefer to work in a graphic IDE (Integrated Development Environment).

Setting up an IDE that you can use

Probably your best choice is the Eclipse IDE with the Pydev plugin. Eclipse is an Open Source IDE, intended to work with a wide variety of programming languages. Pydev is the plugin that specifically enables Python development in Eclipse.

The latest version of Eclipse, named Ganymede, has not been fully tested by ESRI for use with ArcGIS 9.3, and is not available for some older UNIX releases. We recommend using version 3.3.2, which you can find in the archive at:

http://archive.eclipse.org/eclipse/downloads/

To install Eclipse, follow the instructions in the "Installing Eclipse" paragraph at:

http://wiki.eclipse.org/FAQ_Where_do_I_get_and_install_Eclipse%3F

(These instructions are for Ganymede, but they basically the same for version 3.3.2)

Once you have Eclipse installed and running, you need to add the Pydev plugin. Just follow the "Getting Started" link on the left side of the Pydev homepage.

http://pydev.sourceforge.net/

Note that you need the Open Source Pydev plugin. The Pydev Extensions plugin is commercial trialware, and is optional.

When you get to the "Configuring the interpreter" page, you are told to choose the Python interpreter that Pydev should use to run Python programs. Use the Python installation you use for Engine development/testing. In most cases, this is the one that got installed with the Engine Runtime:

$ARCGISHOME/python25/bin/python

Note: you might get an error message while trying to choose the interpreter. If you do, click the error dialog's Details button. The message probably includes something like this:

ld.so.1: python: fatal: libpython2.5.so.1.0: open failed: No such file or directory

This is an indication that the python interpreter is not correctly set up. The most likely cause is that your ArcGIS Engine environment has not yet been established. Exit Eclipse and source the init_engine shell script that applies to the shell you are using. When you start Eclipse the problem should go away.

Also, item 3 on the "Configuring the interpreter" page asks you to set the SYSTEM PYTHONPATH. When you do this, make sure to include $ARCGISHOME/bin. This matches the PYTHONPATH that gets set when you source init_engine.

Writing a Python script that does GP stuff

Now that you have a development environment, how do you use all this great GP stuff? Let's create a very simple Python script to get you started on the road to GP development. In most Python scripts, the first thing to do is to import the modules that you will need. For GP, we need to import the arcgisscripting module. Let's also import the os and system modules:

import arcgisscripting
import os, sys

To access GP, we need to create a Geoprocessor object. This is the object through which you will call any GP functions or objects

gp = arcgisscripting.create(9.3)

By passing in the 9.3 argument, you are getting the newer version of the Geoprocessor object, which is a little more Python friendly. For this example we won't be using any of the Python friendly features, but it is never too early to start a good habit.

Now that you have a GP object, what do you do with it? Let's set GP's workspace property and print it out, just to prove to ourselves that it really worked. For this example, let's set the workspace to a "data" directory just underneath the current Python directory.

gp.workspace = os.path.join (sys.path[0], "data")
print "GP Workspace = " + gp.workspace

(Of course you can set the workspace to any accessible directory, not just the one returned by sys.path[0]. I'm just using sys.path[0] because I know it's accessible.)

sys.path is a list of strings where Python looks for modules. The first item in the list is the current Python directory. Calling os.path.join is a great way to build up filesystem paths, since it correctly handles all the path separator issues. (More on path separators later.) When you run this script (Run -> Run As -> Python Run), you should see "GP Workspace= /some/path/data" printed in the Console tab near the bottom of the Eclipse window.

You can use Eclipse or the operating system to create the data directory, since it probably doesn't exist yet.

For this example, let's suppose you have point data representing hawk sitings in a national forest. Your study area is a subset of the forest where a particular plant in known to grow. What you need to do is clip your point data using the polygon of your study area.

Once you have copied your data into the aforementioned data directory, your script could execute the clip tool like this:

gp.clip_analysis("nat_for.gdb/hawk_sightings", "study_area.shp", "nat_for.gdb/study_sightings")

Just to be sure it worked, you can print out the messages that the tool generated like this:

print (gp.getmessages())

Notice that in calling the clip tool, we used forward slashes (/). Back slashes (\) and forward slashes work equally well in ArcGIS on ALL platforms, so you don't need to worry about switching back and forth when you change to Windows. You can even use back slashes on Linux and Solaris. The problem is that in Python, back slashes are a special character, so to use them, you have to treat them differently than most other characters.

If you stick to forward slashes on all platforms, you improve the look of your code and reduce the effort it takes to type it.

So now you have a script that looks like this:

import arcgisscripting
import os, sys

gp = arcgisscripting.create(9.3)

gp.workspace = os.path.join (sys.path[0], "data")
print "GP Workspace = " + gp.workspace

gp.clip_analysis("nat_for.gdb/hawk_sightings", "study_area.shp", "nat_for.gdb/study_sightings")
print (gp.getmessages())

Run it, and it works, creating a new featureclass in the file geodatabase. Now wasn't that easy? To get more complicated, you just string together as many of those tools as you need to get the job done.

Welcome to the world of Geoprocessing with Python!

Links

Automating workflows with scripts - Introduction to writing Python scripts for geoprocessing
Techniques for sharing Python scripts - Useful techniques for sharing Python scripts
The Python Tutorial - If you're new to Python, this is a good tutorial to start
How to duplicate AML functions in Python - For AML programmers
How to duplicate AML directives in Python- For AML programmers

Troubleshooting

Color issues

Upon using Eclipse on Solaris for the first time, you may see some color problems. For example, the text insertion caret might be white on a white background, making it invisible. Another common symptom is that you cannot see the outline of text input fields. If you run into this or something similar, check the color depth of your display. If it is set to 8 bits, change it to 24.

init_engine

You should have your Engine environment already established in the shell in which you start Eclipse. (source init_engine.sh or source init_engine.csh) If you see inexplicable error messages, this is the most likely cause.

Tips and Tricks - Debugging Python script tools

dmhoneycutt — Mon, 01 Sep 2008 22:02:00 GMT

If you create your own script tools using Python, you'll appreciate these tips and tricks on debugging.

Coding errors are inevitable and there are two basic ways to find out where the error occurred:

Using print statements to discover bugs is an obvious and common method. Since script tools have access to the tool progress dialog, you can edit your script to include calls to AddMessage(), AddWarning(), or AddError() to print values and checkpoint messages to the progress dialog. Another variation is to use an independent method of returning messages, like the win32ui module's MessageBox method. This method displays a popup dialog. Since you have to click OK on the dialog to continue execution, this method allows you to pace the execution of the script. Here's an example using both methods:

import arcgisscripting, win32ui, win32con
gp = arcgisscripting.create()
n = 5

# Print message to progress dialog
#
gp.AddMessage("Value of n = " + str(n))

# Issue a popup dialog with OK and Cancel button
#
val = win32ui.MessageBox("Value of n = " + str(n), "title", win32con.MB_OKCANCEL)

# Based on the button clicked, you can branch execution
#
if val == 1:
    gp.AddMessage("You clicked OK")
else:
    gp.AddError("You clicked Cancel")
    raise arcgisscripting.ExecuteError, "Execution stops due to Cancel button click"

gp.AddMessage("This statement reached")

The other method is to use a Python IDE (Integrated Development Environment) that supports debugging, such as:

https://sourceforge.net/projects/pywin32

http://wingware.com

Debuggers allow you to set breakpoints, step in, out, and over individual lines of code, and examine the contents of variables, all without modifying your code. Compared to inserting print statements, debuggers are much more efficient and usually allow you to quickly isolate your bug. The illustration below shows how to use debug mode in PythonWin.

One way to use a debugger is to open your script directly in your IDE, modify it so that all parameters have values, and then proceed with debugging. This works reasonably well in simple cases. However, if your script uses layer or table view parameters, these variables need created on the fly. Complex parameters like a Field Map or Spatial Reference are hard to create as variables.

Ideally, you'd like to be able to open your script tool dialog, enter parameters, and then have the Python IDE launch with your code ready to be debugged. You can do this with a few simple changes, described below.

Use GetParameterAsText()

The first step is to modify your script so that it used GetParameterAsText() instead of sys.argv[], as discussed in Understanding script tool parameters

This is a modification you can keep - there is no need to change your code back to using sys.argv[].

Create a .bat file that launches your IDE with your .py as an argument

The next step is to create a one-line batch file that will be the source of your script tool (instead of your .py file). This single line contains the pathname to your IDE plus the full path to the .py file, as illustrated below.

Below are 3 examples of how to set your batch (.bat) file for commonly used IDEs. You'll need to confirm that the path is correct for your computer. Other debuggers are of course valid options, and can be called in a similar fashion.

Python IDLE
"C:\Python25\pythonw.exe" "C:\Python25\Lib\idlelib\idle.pyw" "C:\mytools\myscript.py"

PythonWin
"C:\Python25\Lib\site-packages\pythonwin\Pythonwin.exe" "C:\mytools\myscript.py"

Wing IDE 2.1
"C:\Program Files\Wing IDE 2.1\bin\wing.exe" "C:\mytools\myscript.py"

Reset script tool path to the .bat file

The next step is to change your script tool properties to use this new batch file. In the ArcToolbox window, right-click your script tool and click Properties. Click the Source tab and change the script file to be the new .bat file you created, as illustrated below. Click OK.

Execute and debug your tool

Now you can open the script tool from the ArcToolbox window, enter the parameters, and click OK. Shortly afterwards, the debugging application specified in your batch file will open with your Python script displayed. At this point, you are free to interact with the debugging application as you would normally. You can set a breakpoint and let the script run to the breakpoint and use any other options the debugger allows. Parameter values you entered in the dialog will get picked up by GetParameterAsText().

When running the script, any interaction you would normally expect between the script and the application will still occur. So, if you're using methods like AddMessage(), AddWarning(), or AddError(), these messages will show up in the application. If you are using progressor methods (new at 9.3), the progressor will be updated in the tool dialog as you walk through your script. Once the script is finished, you can return back to the application by closing your debugger.

Reset the script tool source

Once you have fixed your bugs, you can reset the source to the script file from the .bat file back to the .py file.

Looking ahead to future releases, we will have integrated options that will make this process smoother. But for now, and with a few little tricks, you can easily perform your script tool debugging.