Summary
Provides access to methods and properties for managing the individual pages within a map document that has Data Driven Pages enabled.
Discussion
Map series can be created without any scripting at all by using the Data Driven Pages toolbar from within ArcMap. The reverse is also true: map series can be completely scripted using arcpy.mapping without using the Data Driven Pages user interface in ArcMap, but there are good reasons for combining both techniques. The ArcMap Data Driven Pages toolbar may not provide enough options for creating the "perfect" map series, but the inherent behavior of a Data Driven Pages-enabled map document can save many lines of code because the page extents, scales, dynamic text, and so forth, are all managed automatically within the map document so that code does not need to be written.
An example of this would be a scenario where a text element's string information needs to be formatted using custom logic or needs to be constructed from multiple fields. It would be unnecessary to have to do everything in arcpy.mapping just because of such a simple, custom requirement. In this case, the map document can still be authored with Data Driven Pages enabled, and arcpy.mapping can handle the custom text element string requirements. A code sample below addresses this scenario.
Data Driven Pages must first be enabled and authored within a map document (.mxd) using the Data Driven Pages toolbar in ArcMap before it can be referenced with arcpy.mapping.
The DataDrivenPages class only has a single exportToPDF method but that does not mean other export files can't be created. See the first code sample below.
For more information about Data Driven Pages, see the following topics:
Properties
| Property | Explanation | Data Type |
| currentPageID (Read and Write) | The currentPageID property represents the active or current page for a map document (.mxd) that has Data Driven Pages enabled. This value is displayed in the Data Driven Pages toolbar when Show Page is selected; it represents the x of x of y. | Long |
| dataFrame (Read Only) | Returns a reference to the data frame the index layer resides within a Data Driven Pages enabled map document. | DataFrame |
| indexLayer (Read Only) | Returns a reference to the index layer in a Data Driven Pages enabled map document. | Layer |
| pageCount (Read Only) | The pageCount property returns the total page count for a map document (.mxd) that has Data Driven Pages enabled. This value is displayed in the Data Driven Pages toolbar when Show Page is selected; it represents the y of x of y. | Long |
| pageNameField (Read Only) | Returns a field object that represents the field used in the index feature class when setting up Data Driven Pages. | Field |
| pageRow (Read Only) | Use pageRow to return the index layer's row object for the active or current page. The index layer fields can then be read and/or modified as necessary. | Row |
| selectedPages (Read Only) | Returns a Python list of index numbers that represent selected index layer features in a Data Driven Pages enabled map document. | List |
Method Overview
| Method | Explanation |
| exportToPDF (out_pdf, {page_range_type}, {page_range_string}, {multiple_files}, {resolution}, {image_quality}, {colorspace}, {compress_vectors}, {image_compression}, {picture_symbol}, {convert_markers}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality}, {show_selection_symbology}) | Exports a specified set of pages to a multipage PDF document for a map document (.mxd) that has Data Driven Pages enabled |
| getPageIDFromName (page_name) | Returns a Data Driven Pages index value based on the name of the page |
| printPages ({printer_name}, {page_range_type}, {page_range_string}, {out_print_file}, {show_selection_symbology}) | Prints specific pages from a Data Driven Pages-enabled map document (.mxd) to a specified printer |
| refresh () | Refreshes an existing Data Driven Pages series |
Methods
exportToPDF (out_pdf, {page_range_type}, {page_range_string}, {multiple_files}, {resolution}, {image_quality}, {colorspace}, {compress_vectors}, {image_compression}, {picture_symbol}, {convert_markers}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality}, {show_selection_symbology})| Parameter | Explanation | Data Type |
out_pdf | A string that represents the path and file name for the output export file. | String |
page_range_type | The string value that designates how the pages will be printed, similar to the Pages tab within the ArcMap Export Map dialog box for PDF documents.
(The default value is ALL) | String |
page_range_string | A string that identifies the pages to be printed if the RANGE option in the page_range_type parameter is used (for example, 1, 3, 5-12). | String |
multiple_files | An option to control how the output PDF is created. By default, all pages are exported into a single, multipage document. You can also specify that individual, single-page PDF documents be exported using two different options.
(The default value is PDF_SINGLE_FILE) | String |
resolution | An integer that defines the resolution of the export file in dots per inch (dpi). (The default value is 300) | Integer |
image_quality | A string that defines output image quality.
(The default value is BEST) | String |
colorspace | A string that defines the color space of the export file.
(The default value is RGB) | String |
compress_vectors | A Boolean that controls compression of vector and text portions of the output file. Image compression is defined separately. (The default value is True) | Boolean |
image_compression | A string that defines the compression scheme used to compress image or raster data in the output file.
(The default value is ADAPTIVE) | String |
picture_symbol | A string that defines whether picture markers and picture fills will be converted to vector or rasterized on output.
(The default value is RASTERIZE_BITMAP) | String |
convert_markers | A Boolean that controls the conversion of character-based marker symbols to polygons. This allows the symbols to appear correctly if the symbol font is not available or cannot be embedded. However, setting this parameter to True disables font embedding for all character-based marker symbols, which can result in a change in their appearance. (The default value is False) | Boolean |
embed_fonts | A Boolean that controls the embedding of fonts in an export file. Font embedding allows text and character markers to be displayed correctly when the document is viewed on a computer that does not have the necessary fonts installed. (The default value is True) | Boolean |
layers_attributes | A string that controls inclusion of PDF layer and PDF object data (attributes) in the export file.
(The default value is LAYERS_ONLY) | String |
georef_info | A Boolean that enables exporting of coordinate system information for each data frame into the output PDF file. (The default value is True) | Boolean |
jpeg_compression_quality | A number that controls compression quality value when image_compression is set to ADAPTIVE or JPEG. The valid range is 1 to 100. A jpeg_compression_quality of 100 provides the best quality images but creates large export files. The recommended range is between 70 and 90. (The default value is 80) | Integer |
show_selection_symbology | A Boolean that controls whether the selection symbology should be displayed in the output. (The default value is False) | Boolean |
Data Driven Pages are exported to a multipage PDF document. The map document must have Data Driven Pages enabled. PDF files are designed to be consistently viewable and printable across different platforms. They are commonly used for distributing documents on the Web and are becoming a standard interchange format for content delivery. ArcMap PDFs are editable in many graphics applications and retain annotation, labeling, and attribute data for map layers from the ArcMap table of contents. PDF exports from ArcMap support embedding of fonts and thus can display symbology correctly even if the user does not have Esri fonts installed. PDF exports from ArcMap can define colors in CMYK or RGB values.
Refer to the Exporting your map topic in ArcGIS for Desktop Help for more detailed discussions on exporting maps.
getPageIDFromName (page_name)
| Parameter | Explanation | Data Type |
page_name | A value in the index layer that corresponds to the Name field that was used to set up Data Driven Pages | String |
Many of the Data Driven Pages properties and methods use an internal index value rather than the literal names of the pages used to create the index layer. The index values are automatically generated based on the Name and Sort fields. It may not be obvious which index value represents a specific page. The getPageIDFromName method provides a mechanism for this translation.
pageID = mxd.dataDrivenPages.getPageIDFromName("HarborView")
mxd.dataDrivenPages.currentPageID = pageID
printPages ({printer_name}, {page_range_type}, {page_range_string}, {out_print_file}, {show_selection_symbology})| Parameter | Explanation | Data Type |
printer_name | A string that represents the name of a printer on the local computer. (The default value is None) | String |
page_range_type | The string value that designates how the pages will be printed, similar to the Pages tab within the ArcMap Export Map dialog box for PDF documents.
(The default value is ALL) | String |
page_range_string | A string that identifies the pages to be printed if the RANGE option in the page_range_type parameter is used (for example, 1, 3, 5-12). | String |
out_print_file | A path that includes the name of an output print file. The format created is dependent on the printer. If you're using a PostScript printer, the format will be PostScript, and it is recommended that a .ps extension be provided. If you're using a Windows printer, use a .prn extension. (The default value is None) | String |
show_selection_symbology | A Boolean that controls whether the selection symbology should be displayed in the output. (The default value is False) | Boolean |
The ListPrinterNames() function is an easy way to get the string for the printer_name parameter.
The following script prints a specific set of Data Driven Pages to a local printer:
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
mxd.dataDrivenPages.printPages(r"\\olyfile\OLYCanon", "RANGE", "1,3,5-12")
refresh ()
You will want to use the refresh method if one of the following occurs: (1) features are added to or deleted from your index layer; (2) edits are made to the Sort or Name field values; (3) the data frame extent is changed due to zooming, panning, or change to map scale; or (4) edits are made to any field being used by Data Driven Pages for an index layer feature that is driving the current geographic extent. Data Driven Pages will retain the original settings in these cases until the refresh method is executed.
Code Sample
DataDrivenPages example 1
The following script exports each page of a Data Driven Pages series into an individual PNG file.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
for pageNum in range(1, mxd.dataDrivenPages.pageCount + 1):
mxd.dataDrivenPages.currentPageID = pageNum
print "Exporting page {0} of {1}".format(str(mxd.dataDrivenPages.currentPageID), str(mxd.dataDrivenPages.pageCount))
arcpy.mapping.ExportToPNG(mxd, r"C:\Project\OutPut\ParcelAtlas_Page" + str(pageNum) + ".png")
del mxd
DataDrivenPages example 2
The following script will print only a set of map pages using a list of page names and also modifies text element map title information using customized logic that can only be accomplished within the scripting environment (in other words, the title string is custom built based on an attribute value). The script loops through each named page and sets the currentPageID accordingly. It then extracts the value from a field in the index layer called TRS. It next parses the values, strips away leading zeros, reconstructs the text element title string, and sends the results to a printer.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
pageNameList = ["MPB", "PJB", "AFB", "ABB"]
for pageName in pageNameList:
pageID = mxd.dataDrivenPages.getPageIDFromName(pageName)
mxd.dataDrivenPages.currentPageID = pageID
fieldValue = mxd.dataDrivenPages.pageRow.TSR #example values from a field called TSR are "080102", "031400"
TRSTitle = arcpy.mapping.ListLayoutElements(MXD, "TEXT_ELEMENT", "TRSTitle")[0]
township, range, section = fieldValue[:2].strip("0"), fieldValue[2:-2].strip("0"), fieldValue[-2:].strip("0")
if section != "":
TRSTitle.text = "Section {0} T.{1}N. R.{2}W. W.M.".format(section, township, range)
else:
TRSTitle.text = "T.{0}N. R.{1}W. W.M.".format(township, range)
mxd.dataDrivenPages.printPages(r"\\olyfile\SUITE_303", "CURRENT")
del mxd
DataDrivenPages example 3
The following script will export only the selected index pages (pages 1-10) out to individual PDF files. The resulting PDFs will have the index number appended to the output file name.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
ddp = mxd.dataDrivenPages
indexLayer = ddp.indexLayer
arcpy.SelectLayerByAttribute_management(indexLayer, "NEW_SELECTION",
'"PageNumber" >= 1 AND "PageNumber" <= 10')
for indexPage in ddp.selectedPages:
ddp.currentPageID = indexPage
ddp.exportToPDF(r"C:\Project\Output\Page" + str(indexPage) + ".pdf", "CURRENT")
del mxd