Layer (arcpy.mapping)
摘要
用于对图层的属性和方法进行访问。它可以引用地图文档 (.mxd) 或图层 (.lyr) 文件中的图层。
讨论
对于管理地图文档 (.mxd) 或图层 (.lyr) 文件中的图层来说，图层对象是必不可少的。图层对象提供了对 ArcMap 图层属性对话框中出现的众多常用图层属性的访问，同时也提供了用于保存图层文件的各种方法。Legend 对象中的 Layer 函数、ListLayers 函数和 listLegendItemLayers 方法都提供了引用 Layer 对象的方法。
图层类型千差万别，所支持的属性集也并不都一样。例如，要素图层支持定义查询，而栅格图层不支持，但栅格目录支持。supports 一种方法可用于帮助识别图层类型与图层属性之间的支持关系，从而无需在各种不同的图层对象中查找所有可能的图层类型与属性的组合。如果不知道图层类型是否支持该属性，在试图获取或设置其属性值之前，supports 方法可用于测试该图层是否支持这一属性，从而可减少不必要的错误信息。
地图文档中存在三大类图层：要素图层、图层组和栅格图层。通过 isFeatureLayer、isGroupLayer 和 isRasterLayer 属性，您可以标识或分离出主要的图层类型，但并非全部。还有少数专题图层和数据集并不属于这三种类别：注记子类、尺寸要素、网络数据集、terrain 数据集、拓扑数据集等。这种情况下，对所关注的图层执行操作前，您需要先测试其他属性以分离该图层。
并非所有的图层属性都可通过 Layer 对象进行访问。ArcMap 图层属性对话框中所列属性中有许多并未提供给 arcpy 脚本环境（例如，显示属性、字段别名、选择内容的符号系统等）。通过 UpdateLayer 函数，您可以使用包含自定义信息的图层文件 (.lyr) 替换 ArcMap 图层属性对话框中列出的所有图层属性。
图层组和其他子图层（例如，注记类）将被视为普通图层。ListLayers 函数将返回按图层在内容列表中的显示顺序或在图层 (.lyr) 文件中的显示顺序从上至下生成的索引值。以上规则也适用于嵌套的图层组。例如，如果地图文档中包含一个内含三个子图层的图层组，则它将返回一个包含四个图层名的列表，图层组的名称作为第一项，子图层的名称依次为第二、第三、第四项。有两种方式用于确定某个图层是否为图层组。第一种方式，可以查看该图层是否支持 isGroupLayer 属性。第二种方式，可以评估 longName 属性。图层的 longName 属性值除了图层名称外还包括组名称。例如，在一个名称为 Group1 的图层组中，名称为 Layer1 的图层的 longName 值是 Group1\Layer1。如果 name 值与 longName 的值相同，则表示该图层不是图层组或该图层不在图层组内。
由于用户名和密码信息未保存在图层文件内或地图文档内，所以地图文档或图层文件内的一些图层可能受密码保护。打开包含这些图层的地图文档时将会提示用户输入相应的信息。默认情况下，arcpy.mapping 脚本环境将在执行过程中禁止使用这些对话框，但这意味着这些图层的数据源将被视为已经损坏。换言之，受保护的图层将不会在任何输出中进行渲染。如果希望适当地渲染这些图层，则应采取如下做法。首先，将用户名和密码信息随图层一同保存。其次，使用 CreateArcSDEConnectionFile 地理处理函数创建一个同样保留在内存中的连接文件。如果在使用 MapDocument 函数打开地图文档 (.mxd) 或使用 Layer 函数打开图层文件之前执行此函数，那么 SDE 图层将得到渲染。目前尚没有针对受保护 Web 服务的操作方法。
引用磁盘上的图层文件 (.lyr) 的变量将锁定该文件。最好在脚本结尾或在 Python try/except 语句中使用 Python del 命令移除对象引用。
通常会需要您更改图层的数据源。Layer 对象中有两种方法可以实现此目的。findAndReplaceWorkspacePath 方法用于替换部分或全部的图层工作空间路径。replaceDataSource 方法用于更改图层的工作空间或源数据集。有关详细说明、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
根据符号系统的类型，您可以修改图层的符号系统。只有极少数受支持的符号系统类型，其属性和方法可供使用。最好先测试图层的 symbologyType 属性。如果返回 OTHER 值，则不可以修改图层的符号系统。如果返回值不是 OTHER，则图层的 symbology 属性将返回以下某个符号系统类，每个符号系统类都包含一组特有的方法和属性：GraduatedColorsSymbology、GraduatedSymbolsSymbology、RasterClassifiedSymbology 和 UniqueValuesSymbology。
可以对启用时间的图层执行时间管理操作。并非所有的图层类型都支持时间属性。因此，最好首先使用 supports 方法测试图层是否支持时间。如果图层支持时间，则可从 LayerTime 类访问时间属性。
语法
| 参数 | 说明 | 数据类型 |
lyr_file_path |
A string that includes the full path and file name of an existing layer (.lyr) file. | String |
属性
| 属性 | 说明 | 数据类型 |
| brightness (读写) |
Provides the ability to get or set the 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. Not all layers support the brightness property (for example, group layers and feature layers), so it is good practice to test for this ahead of time using the supports method. | Integer |
| contrast (读写) |
Provides the ability to get or set the 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. Not all layers support the contrast property (for example, annotation layers and fabric layers), so it is good practice to test for this ahead of time using the supports method. | Integer |
| credits (读写) |
Provides the ability to either get or set the map document's credits or copyright information. | String |
| datasetName (只读) |
Returns the name of the layer's dataset the way it appears in the workspace, not in the TOC. Not all layers support the datasetName property (for example, web services), so it is good practice to test for this ahead of time using the supports method. | String |
| dataSource (只读) |
Returns the complete path for the layer's data source. It includes the workspacePath and the datasetName properties combined. Not all layers support the dataSource property (for example, annotation classes and web services), so it is good practice to test for this ahead of time using the supports method. | String |
| definitionQuery (读写) |
Provides the ability to get or set a layer's definition query. Not all layers support the definitionQuery property (for example, raster layers and group layers), so it is good practice to test for this ahead of time using the supports method. | String |
| description (读写) |
Provides the ability to either get or set the layer's description information. Not all layers support the description property (for example, topology layers), so it is good practice to test for this ahead of time using the supports method. | String |
| isBroken (只读) | Returns True if a layer's data source is broken. | Boolean |
| isFeatureLayer (只读) | Returns True if a layer is a feature layer. | Boolean |
| isGroupLayer (只读) | Returns True if a layer is a group layer. | Boolean |
| isNetworkAnalystLayer (只读) | Returns True if a layer is an ArcGIS Network Analyst 扩展模块 layer type. | Boolean |
| isRasterizingLayer (只读) | Returns True if a layer will cause rasterization of other vector layers in the data frame when the map is printed or exported. Rasterization of vector layers during output most often occurs when layer transparency is used but can also happen when a layer has raster-based picture symbols or field-based transparency. | Boolean |
| isRasterLayer (只读) | Returns True if a layer is a raster layer. | Boolean |
| isServiceLayer (只读) | 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. | Boolean |
| labelClasses (读写) |
Provides access to a layer's label class properties by returning a list of LabelClass objects. Individual LabelClass object properties can be read and/or modified and written back to the layer. Not all layers support the labelClasses property (for example, raster layers and annotation layers), so it is good practice to test for this ahead of time using the supports method. | LabelClass |
| longName (只读) |
This property is valuable when trying to determine whether a layer belongs to a group layer. If a layer does not belong to a group layer, the long name will equal the layer name. If a layer does belong to a group layer, the group layer structure will be included in the long name. For example, the name of a layer nested inside a group layer within another group layer may look something like Group1\Group2\LayerName. All layer types support this property. | String |
| maxScale (读写) |
Provides the ability to set or get the layer's maximum scale threshold. | Double |
| minScale (读写) |
Provides the ability to set or get the layer's minimum scale threshold. | Double |
| name (读写) |
Provides the ability to set or get the name of a layer the way it would appear in the ArcMap table of contents. Spaces can be included. All layer types support this property. | String |
| serviceProperties (只读) |
Provides access to connection information for ArcSDE and web service layers. The returned results are dictionary key-value pairs. There are two different dictionaries returned based on the type of layer. The first is for ArcSDE connections, and the second is for all web service layer types. The web services dictionary contains keys that work for all service layer types and also includes specific keys that work for only a particular web service type (for example, WMS has a key called WMSTitle). Either your script can check the ServiceType key before evaluating specific keys or you can use the get method that allows you to bypass keys that are not available. Not all layers support the serviceProperties property (for example, layers that are not ArcSDE or web service layers), so it is good practice to test for this ahead of time using the supports method. Keys for an ArcSDE dictionary
Keys for a Web service dictionary
| Dictionary |
| showLabels (读写) |
Controls the display of labels for a layer. If set to True, labels will display; if set to False, labels will not be drawn. Not all layers support the showLabels property (for example, raster layers and annotation layers), so it is good practice to test for this ahead of time using the supports method. Layer types that support the showLabels property also support the labelClasses property. | Boolean |
| symbology (只读) | Returns a reference to the layer's symbology class. Each supported layer symbology class has its own unique set of properties. It is best to first determine the layer's symbologyType before attempting to modify the symbology class properties. | Object |
| symbologyType (只读) | Returns a string that represents the layer's symbology class type. Not all layer symbology class types are supported; for those that are not, the keyword OTHER is returned. The following is a list of possible values:
| Object |
| time (只读) |
Returns the LayerTime class that provides access to time properties of time-enabled layers. | Object |
| transparency (读写) |
Provides the ability to get or set the transparency value. This enables you to see through a layer to the layers underneath. Type 0 if you don't want a layer to be transparent. A transparency value of more than 90% usually results in the layer not being drawn at all. Not all layers support the transparency property (for example, fabric group layers and web service sublayers), so it is good practice to test for this ahead of time using the supports method. | Integer |
| visible (读写) |
Controls the display of a layer. This has the same effect as checking the check box next to the layer in the table of contents in ArcMap. If set to True, the layer will draw; if set to False, the layer will not be drawn. Not all layers support the visible property (for example, restricted web service layers), so it is good practice to test for this ahead of time using the supports method. | Boolean |
| workspacePath (只读) |
Returns a path to the layer's workspace or connection file. Not all layers support the workspacePath property (for example, web services), so it is good practice to test for this ahead of time using the supports method. | String |
方法概述
| 方法 | 说明 |
| findAndReplaceWorkspacePath (find_workspace_path, replace_workspace_path, {validate}) |
查找图层的工作空间路径并替换为新工作空间路径。 |
| getExtent ({symbolized_extent}) |
Returns a layer's geometric or symbolized extent. |
| getSelectedExtent ({symbolized_extent}) |
Returns a layer's geometric or symbolized extent for selected features. |
| replaceDataSource (workspace_path, workspace_type, {dataset_name}, {validate}) |
为地图文档 (.mxd) 或图层 (.lyr) 文件中的图层替换数据源。其提供转换工作空间类型的能力（例如，用 SDE 数据源替换文件地理数据库数据源）。 |
| save () |
Saves a layer (.lyr) file. |
| saveACopy (file_name, {version}) |
将图层 (.lyr) 文件另存为其他文件名称，或较早版本。 |
| supports (layer_property) |
并非所有图层都支持相同的属性集。supports 属性可用来测试图层支持的属性。 |
方法
| 参数 | 说明 | 数据类型 |
find_workspace_path |
A string that represents the workspace path or connection file you want to find. If an empty string is passed, then all workspace paths will be replaced with the replace_workspace_path parameter depending on the value of the validate parameter. | String |
replace_workspace_path |
A string that represents the workspace path or connection file you want to replace. | String |
validate | If set to True, the workspace will only be updated if the replace_workspace_path value is a valid workspace. If it is not valid, the workspace will not be replaced. If set to False, the method will set the workspace to match the replace_workspace_path, regardless of a valid match. In this case, if a match does not exist, then the layer's data source would be broken. (默认值为 True) | Boolean |
有关详细说明、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
| 参数 | 说明 | 数据类型 |
symbolized_extent |
A value of True will return the layer's symbolized extent; otherwise, it will return the geometric extent. The symbolized extent takes into account the area the symbology covers so that it does not get cut off by the data frame's boundary. (默认值为 True) | Boolean |
| 数据类型 | 说明 |
| Extent |
The getExtent method will honor a layer's definition query so if a subset of features are queried, getExtent will return the extent for only those features.
A symbolized extent takes into account the area of the feature's symbol when building the extent rectangle. Returning a symbolized extent may be best for cartographic results because symbols won't be cut off at the data frame's edges. A geometric extent may be best for analysis.
| 参数 | 说明 | 数据类型 |
symbolized_extent |
A value of True will return the layer's symbolized extent; otherwise, it will return the geometric extent. The symbolized extent takes into account the area the symbology covers so that it does not get cut off by the data frame's boundary. (默认值为 True) | Boolean |
| 数据类型 | 说明 |
| Extent |
A symbolized extent takes into account the area of the feature's symbol when building the extent rectangle. Returning a symbolized extent may be best for cartographic results because symbols won't be cut off at the data frame's edges. A geometric extent may be best for analysis.
| 参数 | 说明 | 数据类型 |
workspace_path |
A string that includes the workspace path to the new data or connection file. | String |
workspace_type | A string keyword that represents the workspace type of the new data.
| String |
dataset_name | A string that represents the name of the dataset the way it appears in the new workspace (not the name of the layer in the TOC). If dataset_name is not provided, the replaceDataSource method will attempt to replace the dataset by finding a table with a the same name as the layer's current dataset property. | String |
validate | If set to True, a workspace will only be updated if the workspace_path value is a valid workspace. If it is not valid, the workspace will not be replaced. If set to False, the method will set the source to match the workspace_path, regardless of a valid match. In this case, if a match does not exist, then the data source would be broken. (默认值为 True) | Boolean |
有关详细论述、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
There is a subtle difference between a layer (.lyr) file and a map layer (a layer in a map document). The save method only works when a variable references a layer file and will not work with a map layer. When a layer is loaded from a layer file it will remember the file name and use that when the save method is called. If a map layer is being referenced, a file name is not initially set, so you will need to use the saveACopy method instead.
| 参数 | 说明 | 数据类型 |
file_name |
A string that includes the location and name of the output layer (.lyr) file. | String |
version |
A string that sets the output version number. The default value will use the current version.
(默认值为 None) | String |
可选择将图层 (.lyr) 文件另存为其他文件名称，或较早版本。较早版本的软件中不支持的功能将从新保存的图层中移除。
| 参数 | 说明 | 数据类型 |
layer_property |
The name of a particular layer property that will be tested.
(默认值为 name) | String |
| 数据类型 | 说明 |
| Boolean |
图层类型多种多样，并且不是所有图层类型都支持相同的属性。例如，要素图层支持定义查询，而栅格图层不支持，但栅格目录支持。support 方法主要用于协助识别哪些图层类型支持哪些属性，而不是创建所有可能图层类型和属性组合的各个图层对象。如果您不知道图层类型是否支持此属性，在获得或设置属性值前，您可以使用 support 方法对其进行测试。如果图层支持此属性，则 supports 属性将返回 true。
代码实例
以下脚本将引用图层 (.lyr) 文件，查找名为 Highways 的所有图层，打开标注，然后将结果保存到新图层文件中。
import arcpy
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Streets.lyr")
for lyr in arcpy.mapping.ListLayers(lyrFile):
if lyr.name.lower() == "highways":
lyr.showLabels = True
lyr.saveACopy(r"C:\Project\Data\StreetsWithLabels.lyr")
del lyrFile
#Or with one less line using a wild card:
import arcpy
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Streets.lyr")
for lyr in arcpy.mapping.ListLayers(lyrFile, "Highways"):
lyr.showLabels = True
lyr.saveACopy(r"C:\Project\Data\StreetsWithLabels.lyr")
del lyrFile
以下脚本将在打开需要输入密码的地图文档前，通过在内存中创建 SDE 连接确保适当地渲染受保护图层。此脚本简单地定义了连接信息，然后将地图文档导出至 PDF 文件。在脚本关闭之前从内存中删除此引用是一项最佳做法。
import arcpy, os
#Remove temporary connection file if it already exists
sdeFile = r"C:\Project\Output\TempSDEConnectionFile.sde"
if os.path.exists(sdeFile):
os.remove(sdeFile)
#Create temporary connection file in memory
arcpy.CreateArcSDEConnectionFile_management(r"C:\Project\Output", "TempConnection", "myServerName", "5151", "myDatabase", "DATABASE_AUTH", "myUserName", "myPassword", "SAVE_USERNAME", "myUser.DEFAULT", "SAVE_VERSION")
#Export a map document to verify that secured layers are present
mxd = arcpy.mapping.MapDocument(r"C:\Project\SDEdata.mxd")
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\output\SDEdata.pdf")
os.remove(sdeFile)
del mxd
以下脚本将会打印每个 SDE 或 Web 服务图层的名称以及相应的服务信息。与以上示例类似，由于某些 SDE 图层可能使用密码信息进行保护，因此将创建一个临时 SDE 连接文件。此示例不会打印关于非 SDE 或 Web 服务图层的信息。
import arcpy, os
#Remove temporary connection file if it already exists
sdeFile = r"C:\Project\Output\TempSDEConnectionFile.sde"
if os.path.exists(sdeFile):
os.remove(sdeFile)
#Create temporary connection file in memory
arcpy.CreateArcSDEConnectionFile_management(r"C:\Project\Output", "TempConnection", "myServerName", "5151", "myDatabase", "DATABASE_AUTH", "myUserName", "myPassword", "SAVE_USERNAME", "myUser.DEFAULT", "SAVE_VERSION")
#Report service properties for layers in a map that support SERVICEPROPERTIES
mxd = arcpy.mapping.MapDocument(r"C:\Project\ServerData.mxd")
for lyr in arcpy.mapping.ListLayers(mxd):
if lyr.supports("SERVICEPROPERTIES"):
servProp = lyr.serviceProperties
print "Layer name:" + lyr.name
print "-----------------------------------------------------"
if lyr.serviceProperties["ServiceType"] != "SDE":
print "Service Type: " + servProp.get('ServiceType', 'N/A')
print " URL: " + servProp.get('URL', 'N/A')
print " Connection: " + servProp.get('Connection', 'N/A')
print " Server: " + servProp.get('Server', 'N/A')
print " Cache: " + str(servProp.get('Cache', 'N/A'))
print " User Name: " + servProp.get('UserName', 'N/A')
print " Password: " + servProp.get('Password', 'N/A')
print ""
else:
print "Service Type: " + servProp.get('ServiceType', 'N/A')
print " Database: " + servProp.get('Database', 'N/A')
print " Server: " + servProp.get('Server', 'N/A')
print " Service: " + servProp.get('Service', 'N/A')
print " Version: " + servProp.get('Version', 'N/A')
print " User name: " + servProp.get('UserName', 'N/A')
print " Authentication: " + servProp.get('AuthenticationMode', 'N/A')
print ""
del mxd
以下脚本将修改地图文档中图层的符号系统。它首先通过磁盘上的图层文件使用 UpdateLayer 函数来更新图层的符号系统。该图层文件包含适用于图层的自定义色带。然后，该脚本会验证图层是否具有分级颜色符号系统。最后，该脚本会修改 GraduatedColors 符号系统类中的大量属性，并将结果导出至 PDF。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Census")[0]
lyr = arcpy.mapping.ListLayers(mxd, "StatePopulation", df)[0]
lyrFile = arcpy.mapping.Layer(r"C:\Project\LYRs\Population.lyr")
arcpy.mapping.UpdateLayer(df, lyr, lyrFile, True)
if lyr.symbologyType == "GRADUATED_COLORS":
lyr.symbology.valueField = "POP2000"
lyr.symbology.numClasses = 4
lyr.symbology.classBreakValues = [250000, 999999, 4999999, 9999999, 35000000]
lyr.symbology.classBreakLabels = ["250,000 to 999,999", "1,000,000 to 4,999,999",
"5,000,000 to 9,999,999", "10,000,000 to 35,000,000"]
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Output\StatePopulation.pdf")
del mxd, lyrFile
以下脚本用于测试图层文件是否支持时间，以及时间属性是否已设置。该脚本随后使用时间信息（开始时间和结束时间）来计算已启用时间的图层的时间范围。
import arcpy, datetime
lyr = arcpy.mapping.Layer(r'C:\Project\Data\Time\TemperatureWithTime.lyr')
if lyr.supports("TIME"):
lyrTime = lyr.time
if lyr.time.isTimeEnabled:
startTime = lyrTime.startTime
endTime = lyrTime.endTime
timeDelta = endTime - startTime
print "Start Time: " + str(startTime)
print "End Time: " + str(endTime)
print "Time Extent: " + str(timeDelta)
else:
print "No time properties have been set on the layer"
else:
print "Time is not supported on this layer"