Executing ArcGIS Tools from Geoprocessing Scripts (Part 5)

Posted on February 28, 2008. Filed under: ESRI, Geoprocessing | Tags: , , , , |

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)

Introduction
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. 

Dynamic Tools
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.

Tool Syntax
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.

More Information
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 )

More ArcGIS Geoprocessing Concepts – Enumeration Objects (Part 3)

Posted on February 8, 2008. Filed under: ESRI, Geoprocessing | Tags: , , , , |

Other posts in this series on scripting your ArcGIS geoprocessing tasks:
Scripting Your ArcGIS Geoprocessing Tasks (Part 1)

Scripting Your ArcGIS Geoprocessing Tasks with Cursors (Part 2)

We all make lists in our daily lives.  Perhaps we create a grocery or shopping list, a “to do” list, a list of goals, or wish lists.  Whatever the case may be we are all familiar with the concept of lists.  Enumeration objects in the geoprocessing framework are essentially the same concept in that these objects contain lists of objects.  These may be lists of feature classes, fields, indexes, rasters, toolboxes, and many others.  As you can see below the GpDispatch/arcgisscripting object contains a number of methods that can be used to generate these enumeration objects.

We’ll start first with the ListFields and ListIndexes methods which return specific enumeration objects. 

ListFields Method
The ListFields method on GpDispatch takes three arguments as you can see below.

  • InputValue – a string representing the path to a feature class or table
  • wildCard – an optional parameter used to limit the fields returned.  If no value is given, all fieds are returned.  Using a combination of * and characters can be used to limit the fields returned
  • fieldType – an optional parameter used to limit the fields returned by data type (i.e. integer, string, date)

A Fields object is returned by the ListFields( ) method.

The Fields object is a type of enumeration which contains a list or collection of individual Field objects.  What you’ll notice about each of the enumeration objects is the existence of the Next and Reset methods.  These methods allow you to navigate the structure of the enumeration, and return the objects contained within as seen in the diagram below.

 

 Below you will see a visual depiction of the process for navigating an enumeration.  Although we are depicting the navigation of a Fields enumeration, the same process occurs in any other enumeration object.  In this example, we’re using the ListFields method to return an object named lstFields.  This object contains a list of individual Field objects for the shapefile that we specified in the ListFields method.  Each enumeration object contains a pointer that is used to access individual members of the collection.  This pointer is initially set just above the first object in the collection.  The first call to the Next method return the first Field object in the collection.  In this case, we’re returning a field named Pop1990.  A second call to the Next method will return the Pop2000 Field object.  Each successive call on the Next method will return the next Field until the end of the collection is reached at which point a None reference will be returned.  These are forward moving enumerations meaning that you can’t move back through the list.  You can however use the Reset method to move the pointer back to the top of the list.

Once the individual Field objects are retrieved from the enumeration you have read only access to the field information.  Notice on the figure below that each of the properties have a single sided barbell indicating that they are read only properties.  You can obtain a lot of information about the individual field objects including the name, aliasname, domain, length, type, and several others.

ListIndexes Method
The concepts that we discussed above in relation to the ListFields method and the Fields enumeration object returned as a result also apply to the ListIndexes method.  Instead of returning a Fields object we get an Indexes object which is also an enumeration object with the same Next and Reset methods.

 

The only difference in the method signatures between ListIndexes and ListFields is that ListIndexes does not have the optional dataType parameter. 

As you can see above the Indexes enumeration object contains individual Index objects which you can access from the collection.  Each index has a number of read only properties including the name, ascending and unique status, and the Fields on which the index operates.

Other Enumeration Methods
The remaining enumeration methods on GpDispatch return a generic enumeration object containing objects of type featureclass, raster, table, dataset, workspace, environment, toolbox, or tool.  One important thing to note on these methods is that you will need to specify the workspace before calling this methods.

import arcgisscripting
gp = arcgisscripting.create()
gp.toolbox = “analysis”

# Set the workspace
gp.workspace = “c:\\Houston\\CrimeData”

# Call ListFeatureClasses
fcs = gp.ListFeatureClasses( )

#loop through the feature classes and buffer
fcs.reset()
fc = fcs.next()

while fc:
     outName = “buffered_” + fc
     gp.buffer(fc, outName, ’500 Feet’)
     fc = fcs.next()

More Information
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.   This class has a maximum size of 10 students and is filling up quickly.  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 )

Scripting Your ArcGIS Geoprocessing Tasks with Cursors (Part 2)

Posted on February 6, 2008. Filed under: ESRI, Geoprocessing | Tags: , , , , , , , |

In our last post we gave an overview of some basic ArcGIS geoprocessing concepts.  The next few posts will cover the functional groupings of geoprocessing objects, and we’ll start with the cursor objects which are displayed in an orange color on the Geoprocessing Object Model Diagram.

In database terms a cursor refers to a subset of records that is obtained by applying an attribute and/or spatial query on a feature class or table. This subset of records is held in memory rather than visually displayed. Do not confuse cursors with selections sets. Selection objects are used to display the currently selected features or rows in the ArcMap display, while cursors are not used for display purposes. For instance a search cursor could be used to programmatically generate a mailing list of all parcels of land with a property value greater than $100,000. The Geoprocessing framework provides the ability to obtain cursors from geographic datasets (Feature Classes) as well as regular database tables. These cursor objects allow you to manage a subset of records in a single object. In this article we will explore the Geoprocessor classes, methods, and properties used to manipulate cursors as specified through the Geoprocessor Object Model Diagram which you can see in the figure below.

Types of Cursors
There are three distinct types of cursors that can be created through the use of corresponding methods found on the GpDispatch object. The most commonly used type of cursor is the “Search Cursor” which is used in query operations to return a subset of records that meet the query conditions. Search cursors are read-only cursors which you can iterate through to obtain information. You can not use a search cursor to insert, update, or delete records from a table. A second type of cursor is the “Insert Cursor” which is specifically used to insert a new record in your table or feature class. Finally, the “Update Cursor” is used to update or delete records in a table or feature class. The records returned in an update or search cursor can be constrained to match attribute criteria.

It is important that you create the proper type of cursor for the operation that you are performing. For example, don’t create a search cursor if you are attempting to update data in a table. As we mentioned, search cursors are read-only structures so you won’t be able to update the data. We’ll explore each of the cursor types in more detail later in this article.

Cursor Objects in the Geoprocessor Object Model Diagram
The GpDispatch or arcgisscripting object, also called the Geoprocessor Object, is the point of entry for all scripts accessing the Geoprocessor objects.

 

Among many other properties and methods, the GpDispatch object contains three methods that can be used to create cursor objects.

Each of these methods return a cursor type that corresponds to the method name on GpDispatch.  For instance, calling the InsertCursor method would return an instance of an InsertCursor that can be used to insert new rows in a table or feature class. Each method takes a required “InputValue” parameter that points to a data source (table, feature class, etc). In addition, the SearchCursor and UpdateCursor methods take an optional “WhereClause” parameter that allows you to constrain the records that are returned through the use of a where clause.

InsertCursor Class
The InsertCursor method on GpDispatch is used to return an InsertCursor object which is used to add rows to a table.

 This class contains three methods. The NewRow( ) method is used to create a new row object as seen in the figure below.

Once a new Row object has been created you can use the FieldName property in conjunction with the SetValue( ) method to populate data for a particular field name in the new row. After you’ve created a new row with the NewRow( ) method and optionally set the values for the fields in this row you’ll need to call the InsertRow( ) method on InsertCursor to add the row to your table or feature class.

To add a new row to a feature class, you must populate the Shape field as well. You can use the Point and Array objects which are also found on the Geoprocessor Object Model Diagram to accomplish this task.


Take a look at the following Python code example that shows how you can use the InsertCursor object to insert a new record in a table.

SearchCursor Class
The SearchCursor method on GpDispatch is used to return a SearchCursor object which is used to obtain a read-only subset of records from a table or feature class.

This class contains two methods which are used to iterate through the collection of rows that are returned. Remember that the SearchCursor( ) method on GpDispatch can include an optional “WhereClause” parameter that can be used to restrict the number of records that are returned in this class. For instance, perhaps you only want to return the hydrant inspections done by an employee by the name of Steve Smith. You could call the Search Cursor( ) method as follows to accomplish this limitation on the records returned.

searchCursor = gp.SearchCursor(“Hydrants”,”Ins_By = “Steve Smith”)

After the SearchCursor( ) method has been called and returned a SearchCursor object, you can access the individual Row objects within the SearchCursor object through the Next and Reset methods.

When the SearchCursor is initially created, a pointer is placed at the top of the rows returned, just above the first record. To obtain the first Row in the cursor you will need to make a call to the Next( ) method similar to the code example below.

row = searchCursor.Next( )

Each successive call to the Next( ) method will return the next Row in the cursor until the end of the record collection has been reached at which point the row variable will be set to a value of “None”. Cursor objects are referred to as “forward-moving” objects which simply means that you can move forward one record at a time, but not backwards. However, you can use the Reset( ) method to reset the pointer back to the top of the cursor.

You will notice that the Row object returned by a Search Cursor is slightly different than a Row object returned by an Insert or Update Cursor. Rows returned in a SearchCursor object do not have a SetValue( ) method. The reason for this is that SearchCursor’s are read-only objects so you can’t update or insert values into these records.

Take a look at the following Python code example that shows how you can use the SearchCursor object to obtain a read only set of rows from a table.

UpdateCursor Class
The UpdateCursor method on GpDispatch is used to return an UpdateCursor object which is used to update or delete records from a table or feature class.

This class contains Next( ) and Reset( ) methods for navigating through the records that were returned along with an UpdateRow( ) method for updating values in the table or feature class and a DeleteRow( ) method for deleting records. Similar to the SearchCursor( ) method, the UpdateCursor( ) method on GpDispatch can also include an optional “WhereClause” parameter that can be used to restrict the number of records that are returned in this object.


Rows can be updated in an UpdateCursor through the SetValue( ) method and the FieldName property.

Take a look at the code example below to see an example of how you can use an UpdateCursor to delete records from a table.

Geometry Class
Each Row object in a FeatureClass has an associated Geometry object containing the geometric content for the row. This is more commonly known as the “Shape” field. When you access the “Shape” field from a Row object a Geometry object is returned, and contains a number of read only properties that give you geographic information about the current row. Notice the relationship between Row objects and Geometry objects in the figure below.

Some of the more commonly used properties include:

  • Type – data type (point, polyline, polygon)
  • Extent – geographic extent (bounding box) of the feature
  • Area – area of a polygon feature
  • Length – length of a polyline feature

Conclusion
Geoprocessor cursor structures provide you with the ability to query, insert, update, and delete records from Feature Classes and Tables. These easy to create and flexible cursor structures are in-memory collections of records that can be constrained through the use of a “WhereClause” parameter that can be used on the GpDispatch methods that create these cursors. Once generated, these cursor structures provide an easy to navigate, forward-moving structure that can be used to investigate the contents of individual records.

Cursor objects are but one small section of the Geoprocessing programming library. To obtain more information on these objects as well as other functionality exposed by this library please see our comprehensive virtual training course “Introduction to Geoprocessing with Python”.

More Information
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.

Read Full Post | Make a Comment ( 1 so far )

Scripting Your ArcGIS Geoprocessing Tasks (Part 1)

Posted on February 5, 2008. Filed under: ESRI, Geoprocessing | Tags: , , , , |

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. 

Click here to see a demonstration of the functionality contained on the Geoprocessor OMD.

OMD Symbology
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.

Cursor Objects
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.

Describe 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. 

Miscellaneous Objects
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.

More Information
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.

Read Full Post | Make a Comment ( 2 so far )

Liked it here?
Why not try sites on the blogroll...

Follow

Get every new post delivered to your Inbox.

Join 46 other followers