AddLayer (arcpy.mapping)

Summary

Provides the ability to add a layer to a data frame within a map document (.mxd) using simple placement options.

Discussion

AddLayer is an easy way to add a layer or group layer into a map document. It can add a layer with auto-arrange logic that places the new layer in a data frame similarly to how the Add Data button works in ArcMap; it places the layer based on layer weight rules and geometry type. The other placement choices are either at the top or the bottom of a data frame. For more precise layer placement options, refer to the InsertLayer function.

AddLayer is the only function that can add a layer into an empty data frame. AddLayer does not allow you to add layers to a layer file or within a group layer. If interested in managing layer files, refer to the Layer and AddLayerToGroup functions.

The layer that is added must reference an already existing layer (keep in mind that a layer can be a group layer as well). The source can either come from a layer file on disk, from within the same map document and data frame, the same map document but different data frame, or even from a completely separate map document.

The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbol(s) in the TOC. This setting is built into the layer. If a layer is collasped, saved to a layer file, and then added to a map document, the layer will be collasped in the new map document when added via AddLayer.

Syntax

AddLayer (data_frame, add_layer, {add_position})

Parameter	Explanation	Data Type
data_frame	A reference to a DataFrame object within a map document.	DataFrame
add_layer	A reference to a Layer object representing the layer to be added. This reference can point to a layer file on disk or a layer within a map document.	Layer
add_position	A constant that determines the placement of the added layer within a data frame. AUTO_ARRANGE —Automatically places the layer similar to how the Add Data button works in ArcMap BOTTOM —Places the layer at the bottom of the data frame TOP —Places the layer at the top of the data frame (The default value is AUTO_ARRANGE)	String

Code Sample

AddLayer example 1:

The following script will add a new layer from a layer (.lyr) file on disk and place it at the bottom of the data frame called New Data Frame.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "New Data Frame")[0]
addLayer = arcpy.mapping.Layer(r"C:\Project\Data\Orthophoto.lyr")
arcpy.mapping.AddLayer(df, addLayer, "BOTTOM")
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd, addLayer

AddLayer example 2:

The following script will add a new group layer called NE_Layers from another, independent map document and use auto-arrange to place the group layer within a data frame called New Data Frame.

import arcpy

#Reference layer in secondary map document
mxd2 = arcpy.mapping.MapDocument(r"C:\Project\ProjectTemplate.mxd")
df2 = arcpy.mapping.ListDataFrames(mxd2, "Layers")[0]
addLayer = arcpy.mapping.ListLayers(mxd2, "NE_Layers", df2)[0]

#Add layer into primary map document
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "New Data Frame")[0]
arcpy.mapping.AddLayer(df, addLayer, "AUTO_ARRANGE")

#Save to a new map document and clear variable references
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd, mxd2