ListBookmarks

Summary

Returns a Python list of named tuples that provide access to each spatial bookmark's name and extent.

Discussion

ListBookmarks always returns a Python list of named tuples. Each tuple provides the bookmark's name as a string and the bookmark's extent as an Extent object. In order to return a specific tuple, an index value must be used on the list (for example, bkmk = arcpy.mapping.ListBookmarks(mxd)[0]). For loops on a list provide an easy mechanism to iterate through each tuple in the list (for example, for bkmk in arcpy.mapping.ListBookmarks(mxd):).

Wildcards are used on the name property and are not case sensitive. A wildcard string of "so*" will return a spatial bookmark with the name South East. Wildcards can be skipped in the scripting syntax by passing an empty string (""), an asterisk (*), or entering wildcard=None, or nothing at all if it is the last optional parameter in the syntax.

Avoid having spatial bookmarks in a single data frame that have the same name because the name property is really the only practical way of identifying a spatial extent. Bookmarks can have the same name if they are in different data frames.

Syntax

ListBookmarks (map_document, {wildcard}, {data_frame})

Parameter	Explanation	Data Type
map_document	A variable that references a MapDocument object.	MapDocument
wildcard	A combination of asterisks (*) and characters can be used to help limit the results. It is used to filter spatial bookmark names. (The default value is None)	String
data_frame	A variable that references a DataFrame object. This is used to find a spatial bookmark associated with a specific data frame. (The default value is None)	DataFrame

Return Value

Data Type	Explanation
List	A Python list of named tuples. extent —A GP Extent object name —A string that represents the name of a spatial bookmark

Code Sample

ListBookmarks example 1

This script will print the name of each spatial bookmark in a data frame named Transportation. The wildcard parameter is skipped using a blank string.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
for bkmk in arcpy.mapping.ListBookmarks(mxd, "", df):
    print bkmk.name
del mxd

ListBookmarks example 2

Similar to example 1, the following script will loop through each bookmark in the Transportation data frame, set the data frame extent, and export the data frame to a JPEG file.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
for bkmk in arcpy.mapping.ListBookmarks(mxd, data_frame=df):
    df.extent = bkmk.extent
    outFile = r"C:\Project\Output\\" + bkmk.name + ".jpg"
    arcpy.mapping.ExportToJPEG(mxd, outFile, df)
del mxd

ListBookmarks example 3

This sample will convert each bookmark in a map document to a feature. The resulting feature class can be used for a variety of workflows, including use as a Data Driven Pages index layer for creating map books.

import arcpy, os

# The map with the bookmarks
mxd = arcpy.mapping.MapDocument(r"C:\Project\Counties.mxd")

# The output feature class to be created -
# This feature class will store the bookmarks as features
outFC = r'C:\Project\Counties.gdb\Bookmarks'

# A template feature class that contains the attribute schema
# Including a "Name" field to store the bookmark name
template = r'C:\Project\Counties.gdb\Template'

if arcpy.Exists(outFC):
    arcpy.Delete_management(outFC)
arcpy.CreateFeatureclass_management(os.path.dirname(outFC),
                                    os.path.basename(outFC), 
                                    "POLYGON", template, 
                                    spatial_reference=template)

cur = arcpy.da.InsertCursor(outFC, ["SHAPE@", "Name"])
array = arcpy.Array()
for bkmk in arcpy.mapping.ListBookmarks(mxd):
    array.add(arcpy.Point(bkmk.extent.XMin, bkmk.extent.YMin))
    array.add(arcpy.Point(bkmk.extent.XMin, bkmk.extent.YMax))
    array.add(arcpy.Point(bkmk.extent.XMax, bkmk.extent.YMax))
    array.add(arcpy.Point(bkmk.extent.XMax, bkmk.extent.YMin))
    # To close the polygon, add the first point again
    array.add(arcpy.Point(bkmk.extent.XMin, bkmk.extent.YMin))
    cur.insertRow([arcpy.Polygon(array), bkmk.name])
    array.removeAll()

Feedback on this topic?