Other posts in this series:
Scripting Your ArcGIS Geoprocessing Tasks (Part 1)
Scripting Your ArcGIS Geoprocessing Tasks with Cursors (Part 2)
More ArcGIS Geoprocessing Concepts – Enumeration Objects (Part 3)
Obtaining Descriptive Information About GIS Datasets with ArcGIS Geoprocessing Objects (Part 4)
In this final post in our five part series on scripting your geoprocessing tasks in ArcGIS we will take a look at how you can take advantage of the built in geoprocessing tools in ArcGIS through your scripts. These are the tools available through ArcToolbox.
Each of these tools is accessible from your Python scripts through dynamic methods on the Geoprocessor object. We’ll take a look at the tools that are available, the syntax you need to use to access them, aliases for the toolboxes that you can use in referencing the tools, and some examples of how you can use these tools in your code.
The arcgisscripting/GpDispatch object on the Geoprocessor OMD contains a section called Dynamic Methods and Properties. The Tool method seen below is a generic method meant to imply the existence of multiple tools.
This generic “Tool” method can be a bit confusing until you understand some additional information. There is a single “Tool” method on the OMD for two reasons. First, there are simply too many geoprocessing tools to fit on the OMD. Remember, if you have the ArcInfo license this would mean you’d have access to approximately 200 tools. In addition, the tools available will depend upon the license level that you have. Not only does this include the basic license level (ArcView, ArcEditor, ArcInfo), but also the ArcGIS extensions that you are licensing (3D Analyst, Spatial Analyst, many others). So, as you can see it simply makes sense to group all these tools into a single generic “Tool” method.
Toolbox Names and Aliases
All system toolboxes have an alias property. This alias is important because it is possible to have multiple tools with the same name. For instance, a Buffer tool can be found in both the Analysis and Coverage toolboxes. Therefore, to distinguish the correct tool in your code you’ll need to add the suffix “_<alias>” when calling a tool. For example:
gp.buffer_analysis(“Roads.shp”,”Road_Buff.shp”, “150 feet”)
This specifically tells the geoprocessor to execute the buffer tool found in the analysis toolbox. This is a bit inefficient though and most people prefer to set the Toolbox parameter in their code before calling the tool. For example:
gp.toolbox = “analysis”
gp.buffer(“Roads.shp”,”Road_Buff.shp”, “150 feet”)
The alias for each toolbox can be found by right-clicking the toolbox in ArcToolbox and selecting Properties.
To run a tool from the geoprocessing library you need to know the correct syntax for doing so. For example, the Buffer tool requires several inputs including the input features to buffer, an output feature class, and a buffer distance. You must give Python the parameters it needs to run the tool correctly. There are a number of ways that you can access syntax information for a tool, but perhaps the easiest is to use the online ArcGIS Desktop help system. Here is the link to help information for the Buffer(Analysis) tool. The help system contains an illustration, usage tips, command line syntax and examples, scripting syntax, and script examples for each tool. For this post we’ll concentrate on the scripting syntax. Scroll down near the bottom of the help page until you get to the Scripting syntax section. In this case you should see the following:
Just below this you’ll see an explanation of each paramter including required or optional information, a descriptive explanation, and the data type. Required parameters must be included when you call the tool while optional parameters are just that. In some cases you may have a need to include these parameters and sometimes you won’t. So, a very simple buffer script could look something like the figure below.
We will be presenting a new Virtual GIS Classroom course, “GIS Programming 101: Mastering Python for Geoprocessing in ArcGIS” starting March 24th and ending April 18th. We still have 2 seats of available so hurry to reserve your seat now. We do offer a 15% discount for government, educational, and non-profit entities.
We also offer an e-learning course entitled “Introduction to Geoprocessing with Python” which contains even more detailed information on ArcGIS geoprocessing with approximately 200 slides of audio and video lectures, visual software demonstrations, exercises and data.Read Full Post | Make a Comment ( None so far )
This week I’ll be starting a new series of posts covering the use of scripting for the automation of ArcGIS geoprocessing tasks. In particular we’ll be covering the use of the Python language to automate many of your common tasks. In this first post we’ll take a look at the Geoprocessor Object Model Diagram. Before you can begin scripting your geoprocessing tasks with any language you need to have a fundamental understanding of the objects you’ll be working with and how the interrelate.
An Object Model Diagram graphically portrays the classes, methods, properties, and events that are available in the class library as well as the interrelationships between the objects. This is a high level document that allows you to research the functionality available on each class. You can think of the Geoprocessor object model diagram as a blueprint for writing ArcGIS geoprocessing scripts. In this diagram, notice that each class is color coded by functionality. For example, the Geoprocessor (arcgisscripting/GpDispatch) class is a cyan color. This is not always the case as the ArcObjects OMDs are not color coded.
Let’s discuss some of the symbols that you will see when looking at the object model diagram. Each class is represented with a colored box that helps group the objects by functional category. The class name is listed at the top of the box. Below, the GpDispatch or arcgisscripting class is shown in a cyan color.
Class Properties are symbolized by barbells. Some properties have a single barbell while others have two. A single barbell represents a read only property whereas a double barbell represents a property that is read-write. Read-write properties allow you to change the existing value of a property by assigning a value. Read only property only allow you to read the current value stored in the property.
Class Methods are represented as arrows on the object model diagram. Methods are actions that an object performs, and can optionally take arguments. For example, the Describe(InputValue) takes an input value that represents a path to a dataset and performs the action of returning an object containing descriptive information about the dataset.
Geoprocessor Object (also called GpDispatch or arcgisscripting
The Geoprocessor object, also known by its technical names, GpDispatch and arcgisscripting, is the highest level object in the Geoprocessor library. This object is the entry point for writing all geoprocessing scripts in Python, and can be used to accomplish many GIS tasks. The Geoprocessor object has many methods and properties some of which are dynamic. All geoprocessing tools (i.e. Buffer, Merge, Dissolve, etc) are dynamic methods found on Geoprocessor. Because they are so numerous and dependent upon the software license level in use, these methods are not included on the object model diagram. For example, the Buffer Tool is a frequently used tool in ArcGIS, but no reference to this tool is found on the Geoprocessor OMD. Instead, the OMD has a reference to Dynamic Methods and Properties found at the bottom of the GpDispatch object. The dynamic Tool(tool parameters) method is a generic reference to all tools currently available at your ArcGIS license level.
Because it is the entry point for all geoprocessing tasks you must obtain a reference to GpDispatch in each geoprocessing script that you write. To access this object you must follow a two step process. Below you will see a code example of this process using both the ArcGIS 9.2 native module and the dispatch method (pre ArcGIS 9.2). Since ArcObjects was built on the COM protocol and Python supports COM through the win32com.client module, you must first import the Python module, and this is what the first line of each script accomplishes. The second step of the process creates the Geoprocessor object. This is accomplished through the create( ) method on arcgisscripting or the Dispatch method on win32com.client.
We’ll have more to say about this object in coming posts.
I have covered cursor objects previously, and will repost this to the blog in the near future. For now I’ll briefly state that cursors are in-memory objects that contain records from a Table or Feature Class. Three types of cursors exist: search, insert, and update. Search cursors are created for read-only access to records. Insert cursors are used to insert new records, and update cursors are used to update or delete data. We’ll cover cursors in much greater detail in a coming post.
Enumeration Objects (Lists Methods)
Enumeration objects hold lists of some type of object. This list could includes the fields or indexes available on a feature class or table or simply a list of all the raster datasets within a given workspace. As you will see there are a number of enumeration methods available in the geoprocessing framework.
As their name implies, List methods on Geoprocessor are used to create lists of various objects (fields, indexes, datasets, feature classes, rasters, tables, etc). Here are the list methods available on Geoprocessor for creating these enumeration objects.
The Describe method on GpDispatch is used to obtain detailed information about your data including data type, name, spatial reference, and many others. This method returns a describe object containing descriptive information about the data type. For instance, calling the Describe( ) method on a Feature Class would return a FeatureClass object. This object is often used to test for the type of data (either point, line, or polygon) before further processing. Various read-only properties are available through this object including ShapeType which returns the basic data type such as point, line, or polygon, ShapeFieldName, Fields, and Extent.
The Geoprocessor OMD contains a number of additional miscellaneous objects including SpatialReference, FieldMappings, FieldMap, Result and a few others. We’ll cover these objects in a future post.
As you may have read, we will be presenting a new Virtual GIS Classroom course, “GIS Programming 101: Mastering Python for Geoprocessing in ArcGIS” starting March 24th and ending April 18th.