Introduction to arcpy.mapping (arcpy.mapping)
What is arcpy.mapping?
Arcpy.mapping is a Python scripting module that is part of the ArcPy site package. It gets installed with ArcGIS for Desktop and is available to all licenses. It was designed primarily to manipulate the contents of existing map documents (.mxd) and layer files (.lyr). It also provides functions to automate exporting and printing. Arcpy.mapping can be used to automate map production; it extends the capabilities of Data Driven Pages and is required to build complete map books because it includes functions to export to, create, and manage PDF documents. Finally, arcpy.mapping scripts can be published as geoprocessing services and the script functionality can be made available to web applications.
It is easiest to understand the capabilities of arcpy.mapping by describing some scenarios it facilitates. Here are only a few of the many scenarios that an arcpy.mapping script can accomplish:
- Create a report on information contained in map documents such as data frame coordinate system, layer data sources, layers with broken data sources, or layout element positioning.
- Update, repair, or replace layer data sources in a map document or layer file.
- Update layer symbology without having to physically open map documents.
- Find and replace a text string for all map documents within a folder.
- Save map documents to a prior ArcGIS version for distribution.
- Updating the map document metadata (for example, keywords, summary, and description).
- Create geographic data in batch using map export commands, such as a series of GeoTIFF images driven by a list of features in a data frame.
- Automate the creation and management of map services to be published with ArcGIS for Server.
- Build a variety of PDF map books:
- A thematic or temporal map book with title page, multiple map pages, and any number of additional pages with supporting content such as tabular reports and contact lists.
- A reference map book based on Data Driven Pages output.
Who is arcpy.mapping for? Why was it built?
Arcpy.mapping was built for the professional GIS analyst (as well as for developers). Traditionally, the scenarios listed above had to be done using ArcObjects and it often proved to be a very difficult programming environment to learn for the average GIS professional. Arcpy.mapping is a courser-grained object model, meaning that the functions are designed in a way that a single arcpy.mapping function can replace many lines of ArcObjects code. The following is a very simple example of how arcpy.mapping can be used to reference an existing map document and export it to a PDF document with only two lines of code.
mxd = arcpy.mapping.MapDocument("C:/Project/Watersheds.mxd")
arcpy.mapping.ExportToPDF(mxd, "C:/Project/Output/Watersheds.pdf")
Arcpy.mapping is not a replacement for ArcObjects but rather an alternative for the different scenarios it supports. ArcObjects is still necessary for finer-grain development and application customization, whereas arcpy.mapping is intended for automating the contents of existing map documents and layer files.
Best ways to get started
- Try out the Getting started with arcpy.mapping tutorial.
- Review the Alphabetical list of arcpy.mapping functions and the Alphabetical list of arcpy.mapping classes to get a sense of the functionality that is available. These are also nice printouts to have available when scripting with arcpy.mapping.
- All arcpy.mapping functions and class help topics have detailed explanations and contain sample snippets of code that can be copied and pasted directly into the Python window.
- Search the Geoprocessing Model and Script Tool Gallery within the ArcGIS Resource Center for more advanced arcpy.mapping sample applications.