The arcpy mapping module What mapping can do

The arcpy mapping module What mapping can do in Python automate map publication manage existing map documents Map doc structure mapping classes Map. Document classes Data Frame classes Layer classes Manipulate layers Modify map surround elements Modify layer symbology Dr. Tateosian

arcpy mapping module r o p o t t PD Ad F d lay ers yers M a l e th t s i Ex L oom! Z Get the exte nt s e m a r f s e a l t i t t e a Chang d e th t s i And L e ov le s nd ge more… 2

arcpy mapping classes and functions • Mapping module has classes and functions • Classes: Map. Document, Data. Frame, Layer, and more • Two function categories Exporting and printing Managing Documents and layers • Alphabetical ‘Help’ lists of classes and functions are useful (print them if using a lot) 3

Export to PNG example • Syntax: arcpy. mapping. function. Name(…) arcpy. mapping. Export. To. PNG(…) • Arguments: Map. Document object, output file name Line 3 creates the Map. Document object 4

Map. Document object • Need this for most arcpy mapping scripts. • Required argument for many function. import arcpy map. Name = "C: /gispy/scratch/ch 24/maps/" mxd = arcpy. mapping. Map. Document(map. Name) Map. Document Map. Document object constructor In class – Explore Map. Document objects 5

In Class - Exploring Map. Document follow-up 1 #1. What is mxd? >>> mxd <Map. Document object at 0 x 146 d 4 c 90[0 x 146 d 4 b 80]> #2. What does mxd. relative. Paths mean? >>> mxd. relative. Paths False # Meaning: Does the map use a relative path to the data layers? # 3. How can you change mxd. file. Path from a Python script? >>> mxd. file. Path u'C: \gispy\data\ch 24\maps\states. mxd' >>> mxd. file. Path = 'C: \gispy\data\ch 24\maps\US. mxd' Name. Error: The attribute 'file. Path' is not supported on this instance of Map. Document. #You can’t! # 4. How do you get or change the author of the map from a Python script? >>> mxd. author u'' >>> mxd. author = "Me" >>> mxd. author u'Me' # 5. How can you force the map to refresh to show changes you've made in the current session? >>> mxd. title u'Hey hey' >>> mxd. title = 'Eastern US' >>> arcpy. Refresh. Active. View( ) 6

In Class - Exploring Map. Document follow-up 2 #6. In the Python. Win IDE, what does/doesn't work: >>> mxd 1 = arcpy. mapping. Map. Document('CURRENT') # Throws Runtime. Error. Guess why? Runtime. Error: Object: Create. Object cannot open map document >>> arcpy. env. workspace = "C: /gispy/scratch/ch 24/maps/“ >>> map. Name = 'states. mxd‘ >>> mxd 2 = arcpy. mapping. Map. Document(map. Name) # Throws Assertion. Error. Guess why? Assertion. Error: Invalid MXD filename >>> map. Name = "C: /gispy/scratch/ch 24/maps/states. mxd" >>> mxd 3 = arcpy. mapping. Map. Document(map. Name) # Works! >>> mxd 3. save() # fails. More on next slide. #7. What does os. startfile do? import os os. startfile('C: /gispy/scratch/ch 24/maps/land. Cover. mxd') # Launches Arc. Map with that map open. #8. a. Where can you find a list of all the Map. Document properties and methods. Online help for arcpy mapdocument class b. Which properties can be modified from a Python script? Some say read-only other read/write—try to change them and see what happens. 7

Saving Map. Document methods >>> mxd <Map. Document object at 0 x 146 d 4 c 90[0 x 146 d 4 b 80]> >>> mxd. save() Traceback (most recent call last): File "<interactive input>", line 1, in <module> File "C: Program Files (x 86)Arc. GISDesktop 10. 0arcpyutils. py", line 179, in fn_ return fn(*args, **kw) File "C: Program Files (x 86)Arc. GISDesktop 10. 0arcpy_mapping. py", line 617, in save return convert. Arc. Object. To. Python. Object(self. _arc_object. save(*gp_fixargs((), True))) IOError: Map. Doc. Object: Unable to save. Check to make sure you have write access to the specified file and that there is enough space on the storage device to hold your document. This error occurred because I tried to save the map with Python while it was open. Instead I can save a copy. >>> copy. Name = map. Name[: -4] + "modified. mxd" >>> mxd. save. ACopy(copy. Name) Then I can make changes to that map and save it because it’s not open in Arc. Map. >>> mxd 2 = arcpy. mapping. Map. Document(copy. Name) >>> mxd 2. title = "Foo 2“ >>> mxd 2. save() 8

Map name vs. ‘CURRENT’ map 'CURRENT' only works for code running inside Arc. Map– in the Scripting window or in a Script Tool run there. >>> mxd = arcpy. mapping. Map. Document('CURRENT') Runtime. Error: Object: Create. Object cannot open map document Outside of Arc. Map, you must use the full path file name of the map 9

Map hierarchy 10

Data. Frame object • The List. Data. Frames method lists Data. Frame objects >>> map. Name = "C: /gispy/scratch/ch 24/maps/states. mxd" >>> mxd = arcpy. mapping. Map. Document(map. Name) >>> # Get a list of data frame objects. >>> dfs = arcpy. mapping. List. Data. Frames(mxd) >>> # Get the first data frame. >>> df = dfs[0] >>> df <Data. Frame object at 0 x 147278 d 0[0 x 14712 cf 0]> >>> df. name u'Northeast‘ >>> df 2 = dfs[1] >>> ext = df 2. extent >>> ext. Ymin 29. 99437527717719 >>> arcpy. Select. Layer. By. Attribute_management('VA') >>> df 2. zoom. To. Selected. Features( ) 11

Layer object import arcpy map. Name = "C: /gispy/scratch/ch 24/maps/states. mxd" mxd = arcpy. mapping. Map. Document(map. Name) # Get a list of data frame objects. dfs = arcpy. mapping. List. Data. Frames(mxd) # Get the first data frame. df = dfs[0] # Get a list of layer objects in this data frame. layers = arcpy. mapping. List. Layers(mxd, "*", df) for layer in layers: # Print the name of the layer. print layer. name >>> VT RI CT In class – Exploring Data. Frame and Layer objects 12

In class - Explore Data. Frame & Layer objects: 1. How can you list all layers? >>> layers = arcpy. mapping. List. Layers(mxd) >>> for my. Layer in layers: . . . print my. Layer. name 2. How can you use Python to zoom? >>> arcpy. Select. Layer. By. Attribute_management('VA') >>> df. zoom. To. Selected. Features( ) OR >>> e = my. Layer. get. Extent( ) >>> df. extent = e 3. How could you get the 5 th layer in the 3 rd dataframe? 1. >>> dfs = arcpy. mapping. List. Data. Frames(mxd) 2. >>> df = dfs[2] >>> layers = arcpy. mapping. List. Layers(mxd, "*", df) >>> my. Layer = layers[4] • Where can you find a complete list of layer properties and methods? Search online for arcpy Layer class 13

Methods for manipulating layers • Arcpy mapping module can move, remove, and add layers. • First instantiate Map. Document and Data. Frame objects. • Layer manipulation methods: Add. Layer (TOP or BOTTOM) Insert. Layer (Relative position) Move. Layer (Relative position) Remove. Layer Update. Layer (setting symbology) 14

Removing a layer 15

Adding a feature layer 16

In class – list feature layers • Add a raster to the state. mxd by hand. • Add code to print the name of the data frames & feature type layers in a map (not the raster layers) as shown: • Hint 1: Need nested looping to loop through the data frames and the layers. • Hint 2: layer objects have an is. Feature. Layer property 17

list. Feature. Layers 18

List. Broken. Data. Sources 19

Managing layout elements • • arcpy CAN’T create new elements! For projects where you want to modify layout elements, use an existing map as a template map to modify. Template map elements can be ‘hidden’ outside the initial viewing box. Getting a layout element to modify its properties, often need to know the element name. When you add an element to a map document, it gets a name. However, for some elements, the default name is an empty string (e. g. , text elements). Use meaningful names for each element in the template map. Layout Workflow GET map document object GET layout element(s) of interest MODIFY layout element property SAVE the map DELETE the map document object 2009 20

List layout elements List. Layout. Elements (map_document, {element_type}, {wildcard}) element types: 'DATAFRAME_ELEMENT‘ 'GRAPHIC_ELEMENT' 'LEGEND_ELEMENT‘ 'MAPSURROUND_ELEMENT‘ 'PICTURE_ELEMENT‘ 'TEXT_ELEMENT' Element type is optional but will not accept a place holder; must use a legitimate element type if you want to use a wildcard List all layout elements objects: elems = arcpy. mapping. List. Layout. Elements(mxd) pics = arcpy. mapping. List. Layout. Elements(mxd, 'PICTURE_ELEMENT') horse. Labels = arcpy. mapping. List. Layout. Elements(mxd, 'TEXT_ELEMENT', 'HOR*') 21

Explain what the code does… Part 1: >>> mxd = arcpy. mapping. Map. Document('CURRENT') >>> arrow = arcpy. mapping. List. Layout. Elements(mxd, 'MAPSURROUND_ELEMENT', '*Arrow*')[0] >>> arrow. name u'North Arrow' Part 2: >>> mxd = arcpy. mapping. Map. Document('CURRENT') >>> elems = arcpy. mapping. List. Layout. Elements(mxd) >>> for e in elems: . . . print e. name Text Box North Arrow Legend Title Layers >>> for e in elems: . . . if 'Title' in e. name: . . . title = e >>> dfs = arcpy. mapping. List. Data. Frames(mxd) >>> df = dfs[0] >>> title. element. Position. X = df. element. Position. X + (df. element. Width*0. 5) - (title. element. Width*0. 5) >>> arcpy. Refresh. Active. View( ) >>> title. element. Position. Y = df. element. Position. Y + df. element. Height - title. element. Height 22

Explain what the code does… Part 1: # Print the name of the north arrow. >>> mxd = arcpy. mapping. Map. Document('CURRENT') >>> arrow = arcpy. mapping. List. Layout. Elements(mxd, 'MAPSURROUND_ELEMENT', '*Arrow*')[0] >>> arrow. name u'North Arrow' Part 2: # Print the names of all the elements. >>> mxd = arcpy. mapping. Map. Document('CURRENT') >>> elems = arcpy. mapping. List. Layout. Elements(mxd) >>> for e in elems: . . . print e. name Text Box North Arrow Legend Title Layers # Get >>> for e in elems: . . . if 'Title' in e. name: . . . title = e the element named Title. # Move the Title to the # center (top) of the first data frame >>> dfs = arcpy. mapping. List. Data. Frames(mxd) >>> df = dfs[0] >>> title. element. Position. X = df. element. Position. X + (df. element. Width*0. 5) - (title. element. Width*0. 5) >>> arcpy. Refresh. Active. View( ) >>> title. element. Position. Y = df. element. Position. Y + df. element. Height - title. element. Height 23

Layer symbology. Type • Layer objects have a ‘symbology. Type’ property >>> layer 1. symbology. Type u'OTHER' >>> layer 2. symbology. Type u'GRADUATED_COLORS' symbology. Type values 'GRADUATED_COLORS' 'GRADUATED_SYMBOLS' 'UNIQUE_VALUES' 'RASTER_CLASSIFIED' 'OTHER' Depending on its symbology. Type, a Layer object can have a 'symbology' class. If the symbology. Type is ‘OTHER’, the layer has no ‘symbology’ property. >>> layer 1. symbology Name. Error: The attribute 'symbology' is not supported on this instance of Layer. >>> layer 2. symbology <Graduated. Symbols. Symbology object at 0 x 192 a 6[0 x 22026 b 0]> • Python can not change a layer’s symbology. Type with an assignment statement. >>> layer 1. symbology. Type = 'GRADUATED_COLORS' Runtime. Error: Layer. Object: Set attribute symbology. Type does not exist • • • ‘. lyr' files (Layer Files) can store symbology for a dataset. Add a Layer file data to a map and it uses the stored symbology. Type; Otherwise, the default symbology. Type is 'OTHER'. 24

Modify symbology • symbology. Type can be modified using a pre-prepared ‘. lyr' file. >>> src. Lay = "C: /gispy/data/ch 24/symbol. Training/grad. Colors. NE. lyr' >>> src. Lay. Obj = arcpy. mapping. Layer(src. Lay) >>> arcpy. mapping. Update. Layer(df, layer. To. Modify, src. Lay. Obj) >>> layer. To. Modify. symbology. Type u'GRADUATED_COLORS' • Graduated color symbology properties can be modified • Change the value field for calculating the colors & number of color classes: >>> layer. To. Modify. symbology. value. Field u'Category' >>> layer. To. Modify. symbology. value. Field = 'AVE_FAM_SZ' >>> arcpy. Refresh. Active. View() >>> layer. To. Modify. symbology. num. Classes 5 >>> layer. To. Modify. symbology. num. Classes = 3 25

Summing up • Topics discussed • Map. Document, Data. Frame, Layer objects – – – Map name or 'CURRENT' map Check map properties List map objects Save map documents Move, remove, and add layers • Modify layout element properties • Modify symbology • Up next • HTML • Additional topics • arcpy package organization • data driven pages 26

Appendix 27

Additional Explore Data. Frame & Layer objects examples >>> df <Data. Frame object at 0 x 147278 d 0[0 x 14712 cf 0]> >>> df. name u'Northeast' >>> df. description u'' >>> df. description = "My very cool data frame" >>> df. description u'My very cool data frame' >>> df. display. Units u'Decimal. Degrees' >>> layer. is. Feature. Layer True >>> layer. is. Raster. Layer False >>> e = layer. get. Extent() >>> e <Extent object at 0 x 146 d 41 d 0[0 x 1472 a 9 e 0]> >>> e. XMax -75. 45046915555109 >>> layer. data. Source u'C: \Temp\NC. shp' 28

Dynamic text string • Text placed on a map layout that changes dynamically based on the current properties of the map document, data frame, and Data Driven Page • • A user name The date a map document was saved The file path for the map document The page numbers … • Text Element example date/time Update a static 9. 3 map document date/time text element string Uses dynamic text strings. 29

In class - review user-defined classes 1. create a parcel object named my. Parcel with value 145000 & residential zoning. 2. 3. print the parcel value and zoning for my. Parcel print the tax for my. Parcel. class Human: def __init__(self): self. shorts =“ugly yellow” self. heart. Rate = 60 def fall. In. Love(self): self. heart. Rate = 120 print ‘I love GIS’ 1. create an instance of a human object named ken. 2. print ken’s shorts property. 3. call ken’s fall. In. Love method 30

Python packages • Python module - a single Python script (. py file) containing tightly related definitions and statements. • Python package - a special way of structuring a set of related Python modules. - a directory containing modules and sometimes subpackages, which also contain modules. • A module name __init__. py tells Python that the directory contains a package. Module B within package A can be accessed using the dotted name notation, A. B Example: arcpy. ddd 31

Arcpy package • Search under the Arc. GIS install for the arcpy directory Module B within package A can be accessed using the dotted name notation, A. B Example: arcpy. mapping 32

What is arcpy. mapping for? • Examples of things you can do with arcpy. mapping… • • Before Arc. GIS 10 items things were done with Arc. Objects --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 Arc. Objects code • 33