The ArcPy.Mapping module is new to ArcGIS 10 and brings some really exciting features for mapping automation including the ability to manage map documents and layer files as well as the data within these files. Support is also provided for automating map export and printing as well as the creation of PDF map books and the publication of map documents to ArcGIS Server map services. I’m going to be writing a series of posts of the next few weeks covering some of the functionality provided by this module.
ArcPy.Mapping scripts can be run from a variety of environments just like any other geoprocessing script that you’ve developed with Python for use with the ArcGIS geoprocessor. The new Python Window in ArcMap is a great interface for writing and testing small code blocks. Once tested, these code blocks are often moved into stand-alone Python scripts which can be executed from an IDE such as PythonWin, IDLE, or Wing, but they can also be executed from custom script tools in ArcToolbox, the command line or as scheduled tasks. Many people choose to attach their scripts to script tools in ArcMap or ArcCatalog to provide a visual interface for the scripts within the familiar ArcGIS Desktop environment. Finally, scripts can also be published as geoprocessing tasks in ArcGIS Server.
Before you can actually perform any operations on a map document file you need to get a reference to it in your Python script. This is done by calling the MapDocument() method on the arcpy.mapping module. You can reference either the currently running document or a document at a specific location. To reference the currently active document you simply supply the keyword “CURRENT” as a parameter to the MapDocument() function. This gets the currently active document in ArcMap. To reference a map document on disk you simply supply the path to the map document as well as the map document name as a parameter to MapDocument(). The two code examples below illustrate each of these operations.
In today’s post I’m going to cover a number of the new list functions provided by Arcpy.Mapping. There are a number of list functions provided by Arcpy.Mapping. Each of these list functions returns a Python list which is a highly functional data structure for storing information. Normally, the list functions are used as part of a multi-step process where creating a list is only the first step. Subsequent processing in the script will iterate over one or more of the items in this list. For example, you might obtain a list of broken data links in your map document file and iterate over these links, fixing each as you progress.
The ListLayers() function returns a Python list of all the layers within an mxd file, a data frame within an mxd file, or a layer file. As with all other list functions you can iterate this list through the use of a ‘for’ loop which cycles through each element in the list.
ListDataFrames() returns a Python list of data frames in a map document file. An integer index value can be used to access an individual data frame or you can test for a specific data frame name before applying further processing to the data within the data frame. You can also use a wildcard to filter the data frames that are returned.
Data sources in your map document files are often broken due to data being deleted or moved to a new location. The result can be broken data sources in many map document files. ListBrokenDataSources() returns a list of layer objects that have a broken data connection. In ArcMap, a broken data connection is signified by the red exclamation point just before the layer name.
Typically, the ListBrokenDataSources() function is used as the first step in a script that iterates through the list and fixes the data source. In a future post I’ll show an example script that lists and fixes broken data sources.
ListTableViews() returns a list of Table objects in a map document. You can use a wildcard to return a filtered list of tables.
ListLayoutElements() returns a list of Layout elements in the form of various Layout classes. Each element can be one of: GraphicElement, LegendElement, PictureElement, TextElement, MapSurroundElement, or PictureElement. I’ve outlined some of these layout elements below.
ListLayoutElements() is a versatile function which in its most basic form is used to return a list of all the layout elements on the page layout of a map document. However, there are two optional parameters that you can supply to filter this list. The first type of filter is an element type filter in which you specify that you only want to return one of the layout element types seen on this slide. You can also apply a wildcard to filter the returned list. These two types of filters can be used in combination. For example, in the code example below we are specifying that we only want to return LEGEND_ELEMENT objects with the name “Legend Crime”. This would likely result in a highly filtered list.
In the next post in this series you’ll learn how to fix broken data sources based on a list generated by the ListBrokenDatasources() function.
The next session of our Internet based, instructor led course, GIS Programming 101: Mastering Python for Geoprocessing in ArcGIS begins October 25th. This course is only $499 when you register by August 31st. The regular price of this course is $667.