Skip To Content

Layer

Summary

Provides access to basic layer properties and methods.

Discussion

Layers can be referenced from within a project using the listLayers method on the Map class or in a layer file (.lyr or .lyrx) stored on disk using the listLayers method on the LayerFile class.

The Layer object has a single, generic design to work with all layers. There are numerous types of layers and not all of them support the same set of properties. For example, a feature layer supports a definition query, whereas a raster layer does not, but a raster catalog does. Rather than having to work with different, individual layer objects for all the possible layer types and property combinations, there are some useful properties that allow you to obtain information about a layer and its supported properties. There are many is properties that allow you to determine if a layer fits into a general category: is3DLayer, isFeatureLayer, isGroupLayer, isRasterLayer, and isServiceLayer.

There are a few specialized layers and datasets that don't fall into one of these general categories: annotation subclasses, dimension features, terrain datasets, topology datasets, and so on. In these cases you may need to test other properties to isolate a layer of interest before doing something to it. The supports method is available to help identify which specific layer supports which specific layer property. It gives you the ability to test if the layer supports a property before trying to get or set its value and therefore reducing the need for additional error trapping. For example,

if lyr.supports("BRIGHTNESS"):
    lyr.brightness = 10

The listLayers method on the Map Class returns index values that are generated from top to bottom as they appear in the table of contents or the way they appear in a layer file. The same applies if a group layer is within another group layer. For example, a map with a single group layer that contains three sublayers will return a list of four layer names, the group layer being the first and the three sublayers being the second, third, and fourth. There are two ways of determining if a layer is a group layer. First, you can check to see if the layer supports the isGroupLayer property. Second, you can evaluate the longName property. A layer's longName value will include the group name in addition to the layer name. For example, a layer named Layer1 in a group layer named Group1 will have a longName value of Group1\Layer1. If the name value is equal to the longName value, the layer is not inside a group layer.

ArcGIS ProArcGIS Pro can read legacy .lyr file types, but it can only save to .lyrx file types. If an .lyr file type is being referenced and the save method is called, it will be converted to an.lyrx file type but with the same file name.

Changing a layer's data source is a common requirement. There is a method and a property on the Layer object that help with this. For a more detailed discussion, parameter information, scenarios, and code samples, please refer to the Updating and fixing data sources help topic.

Properties

PropertyExplanationData Type
brightness
(Read and Write)

A layer's brightness value. The default, normal brightness, is 0%. Enter any value between +100% and -100%. Enter a plus or minus sign to the left of the value to specify whether it is above or below 0.

Integer
connectionProperties
(Read Only)

Returns a layer's data source connection information as a Python dictionary.

Dictionary
contrast
(Read and Write)

A layer's contrast value. The default, neutral contrast, is 0%. Enter any value between +100% and -100%. Enter a plus or minus sign to the left of the value to specify whether it is above or below 0.

Integer
dataSource
(Read Only)

Returns the complete path for the layer's data source. It includes the full workspace path and name of the dataset.

String
definitionQuery
(Read and Write)

A layer's definition query.

String
is3DLayer
(Read Only)

Returns True if a layer is a 3D layer.

Boolean
isBasemapLayer
(Read Only)

Returns True if a layer is a basemap layer.

Boolean
isBroken
(Read Only)

Returns True if a layer's data source is broken.

Boolean
isFeatureLayer
(Read Only)

Returns True if a layer is a feature layer.

Boolean
isGroupLayer
(Read Only)

Returns True if a layer is a group layer.

Boolean
isNetworkAnalystLayer
(Read Only)

Returns True if a layer is an ArcGIS Network Analyst extension layer.

Boolean
isNetworkDatasetLayer
(Read Only)

Returns True if a layer is an ArcGIS Network Analyst extension network dataset layer.

Boolean
isRasterLayer
(Read Only)

Returns True if a layer is a raster layer.

Boolean
isWebLayer
(Read Only)

Returns True if a layer is a GIS service layer. GIS services are automated geographic information services that are published and accessed over the web using standard technologies and protocols. Esri basemaps are an example.

Boolean
longName
(Read Only)

A layer's full path including group layer folder structure.

String
maxThreshold
(Read and Write)

A layer's maximum scale threshold for 2D maps and its maximum distance above ground for 3D maps. A layer will not display when zoomed in beyond the maximum scale. To clear the maximum scale, set the value to 0.

Double
minThreshold
(Read and Write)

A layer's minimum scale threshold for 2D maps and its maximum distance above ground for 3D maps. A layer will not display when zoomed out beyond the minimum scale. To clear the minimum scale, set the value to 0.

Double
name
(Read and Write)

The name of a layer the way it would appear in the table of contents. Spaces can be included. It is important that all layers in a map have a unique name so they can be easily referenced by their names.

String
showLabels
(Read and Write)

Controls the display of labels for a layer. If set to True, labels will display; if set to False, labels will not be drawn.

Boolean
symbology
(Read and Write)

Provides access to a layer's symbology.

Object
transparency
(Read and Write)

A layer's transparency value. This enables you to see through a layer. Use values between 0 and 100. A value of 0 is not transparent. A transparency value of more than 90% usually results in the layer not being drawn at all.

Integer
visible
(Read and Write)

Controls the display of a layer. If set to True, the layer will draw; if set to False, the layer will not be drawn.

Boolean

Method Overview

MethodExplanation
extrusion ({extrusion_type}, {expression})

Extrudes 2D features in a layer to display 3D symbology.

getSelectionSet ()

Returns a layer's selection as a Python set of object IDs.

listLabelClasses ({wildcard})

Returns a Python list of LabelClass objects in a layer.

listLayers ({wildcard})

Returns a Python list of Layer objects in a layer file.

saveACopy (file_name)

Saves a layer to a layer file (.lyrx).

setSelectionSet ({oidList}, {method})

Sets a layer's selection using a Python list of Object IDs.

supports (layer_property)

Used to determine if a particular layer type supports a property on the layer object. Not all layers support the same set of properties; the supports property can be used to test if a layer supports that property before attempting to set it.

updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate})

Replaces connection properties using a dictionary or a path to a workspace.

updateLayerFromJSON (json_data)

Updates a Layer from a JSON string.

Methods

extrusion ({extrusion_type}, {expression})
ParameterExplanationData Type
extrusion_type

A string that specifies the extrusion method. The default value is NONE which turns off layer extrusion.

  • ABSOLUTE_HEIGHTThe feature is extruded to the specified z-value, as a flat top, regardless of the z-values of the feature.
  • BASE_HEIGHTA z-value is calculated for each vertex of the feature's base, and the feature is extruded to the various z-values creating a multifaceted top.
  • MAX_HEIGHTAdds extrusion height to the minimum z-value of the feature, and the feature is extruded to a flat top at that value.
  • MIN_HEIGHTAdds extrusion height to the minimum z-value of the feature, and the feature is extruded to a flat top at that value.
  • NONEFeatures are not extruded.

(The default value is NONE)

String
expression

A string that defines the extrusion expression, which provides an absolute extrusion height for each feature.

(The default value is None)

String

Extrusion is the process of vertically stretching a flat 2D shape to create a 3D object. This provides a method to create three-dimensional symbology from two-dimensional features. Polygon and line features have all five extrusion_type options available; point features don't use MAX_HEIGHT or MIN_HEIGHT options.

getSelectionSet ()

Provides an easy way to retrieve the layer's current selection.

listLabelClasses ({wildcard})
ParameterExplanationData Type
wildcard

A wildcard is based on the label class name and is not case sensitive. A combination of asterisks (*) and characters can be used to help limit the resulting list.

(The default value is None)

String
Return Value
Data TypeExplanation
List

Returns a Python list of LabelClass objects in a layer.

Returns a Python list of LabelClass objects in a layer.

listLayers ({wildcard})
ParameterExplanationData Type
wildcard

A wildcard is based on the layer name and is not case sensitive. A combination of asterisks (*) and characters can be used to help limit the resulting list.

(The default value is None)

String
Return Value
Data TypeExplanation
List

Returns a Python list of Layer objects in a layer file.

Returns a Python list of Layer objects in a layer file.

saveACopy (file_name)
ParameterExplanationData Type
file_name

A string that includes the location and name of the output layer file (.lyrx).

String

If a group layer is being saved, all of the layers below it in the TOC will also be saved to the layer file (.lyrx).

setSelectionSet ({oidList}, {method})
ParameterExplanationData Type
oidList
[oidList,...]

A Python list of Object IDs to use along with the appropriate selection method.

(The default value is None)

Integer
method

A string that specifies which selection method to use.

  • NEWCreates a new feature selection from the oidList.
  • DIFFERENCESelects the features that are not in the current selection but are in the oidList.
  • INTERSECTSelects the features that are in the current selection and the oidList.
  • SYMDIFFERENCESelects the features that are in the current selection or the oidList but not both.
  • UNIONSelects all the features in both the current selection and those in the oidList.

(The default value is NEW)

String

This method provides an easy way to manage a layer's selection. To clear the selection, use the NEW selection method with an empty list or don't set any parameters.

Note: Python Lists are used for setting the oidList but Python Sets get returned from the getSelectionSet method on the Layer object.

supports (layer_property)
ParameterExplanationData Type
layer_property

The name of a particular layer property that will be tested.

  • BRIGHTNESSA raster layer's brightness value.
  • CONNECTIONPROPERTIESA Layer's connection information.
  • CONTRASTA raster layer's contrast value
  • CREDITSA layer's credit information.
  • DATASOURCEA layer's file path or connection file.
  • DEFINITIONQUERYA layer's definition query string.
  • LONGNAMEA layer's path including the group layers it may be nested within.
  • MAXTHRESHOLDA layer's maximum threshold to display the features.
  • MINTHRESHOLDA layer's minimum threshold to display the features.
  • NAMEA layer's name.
  • TRANSPARENCYA layer's transparency value.

(The default value is name)

String
Return Value
Data TypeExplanation
Boolean

There are numerous types of layers and not all of them support the same properties. For example, a feature layer supports a definition query, whereas a raster layer does not, but a raster catalog does. Rather than creating individual layer objects for all possible layer types and property combinations, a supports method was created to help identify which layer types support which properties. The support method gives you the option of testing the property before trying to get or set its value on a layer type that doesn't support it. The supports property will return a True if a layer supports that property.

Boolean properties don't need to be tested using supports because if a layer property isn't supported for that layer type, a False value gets returned.

updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate})
ParameterExplanationData Type
current_connection_info

A string that represents the workspace path or a Python dictionary that contains connection properties to the source you want to update.

String
new_connection_info

A string that represents the workspace path or a Python dictionary that contains connection properties with the new source information.

String
auto_update_joins_and_relates

If set to True, the updateConnectionProperties method will also update the connections for associated joins or relates.

(The default value is True)

Boolean
validate

If set to True, the connection properties will only be updated if the new_connection_info value is a valid connection. If it is not valid, the connection will not be replaced. If set to False, the method will set all connections to match the new_connection_info, regardless of a valid match. In this case, if a match does not exist, then the data sources would be broken.

(The default value is True)

Boolean

For more detailed discussion, parameter information, scenarios, and code samples, refer to the Updating And Fixing Data Sources help topic.

updateLayerFromJSON (json_data)
ParameterExplanationData Type
json_data

The layer definition in JavaScript Object Notation (JSON) format. See the ExportWebMap JSON specification for more information. ArcGIS API for JavaScript and Web AppBuilder for ArcGIS allow you to get this JSON string from the web app. The layer definition is a subset of the webmap_json used in the ConvertWebMapToArcGISProject function. You don't need to create the web map JSON; the APIs take care of it for you. However, you need to extract the layer definition from the full webmap_json.

String

This function is intended to be used in a web tool that uses the ConvertWebMapToArcGISProject function in web map printing applications that support changing the renderer (or other properties) of dynamic web service layers. If your web tool replaces the service layers with staged vector layers after running ConvertWebMapToArcGISProject, updateLayerFromJSON will apply the renderer (or other layer properties) as specified in the webmap_json to the corresponding vector layers staged in the layout template. For more information and a code sample, see ConvertWebMapToArcGISProject.

Code sample

Layer example 1

The following script prints the name of each map in a project and lists the names of the layers in each map. The script also appends a (BROKEN) prefix to the layer name if it has a broken data source.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
for m in aprx.listMaps():
    print("Map: {0} Layers".format(m.name))
    for lyr in m.listLayers():
        if lyr.isBroken:
            print("(BROKEN) " + lyr.name)
        else:
            print("  " + lyr.name)
del aprx
Layer example 2

The following script clears all layer definition queries and turns off labels for all layers in a map named Yosemite National Park.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
m = aprx.listMaps("Yosemite National Park")[0]
for lyr in m.listLayers():
    if lyr.supports("DEFINITIONQUERY"):
        lyr.definitionQuery = ""
    if lyr.supports("SHOWLABELS"):
        lyr.showLabels = False
aprx.save()
del aprx