LayerElevation

Summary

The LayerElevation class allows you to define height characteristics for 3D layers in a Map.

Discussion

For spatial data to be displayed in 3D, you can set height options for layers in the 3D Layers category of your local or global scene. This includes defining the layer's elevationMode and verticalUnits as well as optionally defining a cartographicOffset.

The elevationMode allows you to choose where a feature renders in relation to the Ground or custom elevation surface. See the ElevationSurface class for more examples on working with the Ground or custom elevation surfaces. A cartographic offset can be applied to adjust where features are drawn vertically relative to the base height. Use the vertical units property in situations where your Z values may have a different linear unit than your XY values.

For more information concerning the configuration of layer elevation settings in ArcGIS Pro, review the Define height characteristics for layers help topic.

Note:

3D layers may or may not support all elevation modes. Use error handling to set the desired elevation mode for a given layer type. See examples below for how to do this.

Properties

Property	Explanation	Data Type
cartographicOffset (Read and Write)	Gets and sets the cartographic offset. The offset can be applied to adjust where features are drawn vertically relative to the base height established by the elevationMode value.	Double
elevationMode (Read and Write)	Gets and sets the elevation mode that controls the layer's height. Layers in the 3D Layers category in the Contents pane support ON_THE_GROUND, ABSOLUTE_HEIGHT, ON_CUSTOM_SURFACE , RELATIVE_TO_GROUND, RELATIVE_TO_SCENE, and RELATIVE_TO_CUSTOM_SURFACE.	String
verticalExaggeration (Read and Write)	Gets and sets the vertical exaggeration. All features are exaggerated based on the value specified. The units of this value match the Vertical Units. This only applies if the elevationMode is set to ABSOLUTE_HEIGHT, RELATIVE_TO_GROUND, or RELATIVE_TO_CUSTOM_SURFACE.	Double
verticalUnits (Read and Write)	Gets or sets the vertical units for the layer. If the data source of a layer has a vertical coordinate system defined, the elevation unit of the layer is the same as the linear unit of the vertical coordinate system. Note: The vertical units displayed in Elevation category in the Layer Properties dialog, may display a value of "Data source vertical units" but the verticalUnits property will return the specific unit.	String

Method Overview

Method	Explanation
setElevationMode (elevation_mode, expression, surface)	The layer's base height is configured using one or more parameters depending on the elevation_mode that is specified.
setVerticalUnits ({vertical_units})	A string constant that sets the elevation vertical units. It is recommended that vertical units always match the horizontal units of the layer when no vertical coordinate system is present. There may be cases, for example, where a dataset was created with horizontal linear units of meters but the vertical units are in feet.

Methods

setElevationMode (elevation_mode, expression, surface)

Parameter	Explanation	Data Type
elevation_mode	Below is a list of valid strings. ABSOLUTE_HEIGHT— For features that occur at a constant height above a datum, regardless of ground elevation, such as airplanes. In addition, you can add a vertical exaggeration to the absolute height. Use the Shape.Z keyword for the expression argument. ON_CUSTOM_SURFACE— For features that occur on a surface not represented by ground level, such as a well site intersection on a subsurface geologic plane. You can choose a custom elevation surface from a list of defined surfaces in the scene. ON_THE_GROUND— For features that are situated at ground level, such as trees. RELATIVE_TO_CUSTOM_SURFACE— Where additional height values are added to the feature's location on a custom surface. You need a custom elevation surface to use this option. Use the feature's Z values or use the Feature Z profile to create an Arcade expression to adjust feature Z values. RELATIVE_TO_GROUND— For features that are placed at a known height above the ground, such as security camera positions on the side of a building. Use the feature's Z values or use the Feature Z profile to create an Arcade expression to adjust feature Z values. RELATIVE_TO_SCENE— For features that know where they are compared to the scene. These features align to the ground and 3D objects such as extruded polygons or buildings.	String
expression	An optional VB Script or Arcade expression to be applied depending on the specified elevation_mode. Note: VB Script is deprecated in Windows. It is recommended to use Arcade.	String
surface	An optional ElevationSurface to be applied depending on the specified elevation_mode.	Object

setVerticalUnits ({vertical_units})

Parameter	Explanation	Data Type
vertical_units	Below is a list of valid strings. FEET—Feet KILOMETERS—Kilometers METERS—Meters MILES—Miles YARDS—Yards (The default value is METERS)	String

It's important to define a vertical coordinate system when working with 3D data. If the data source of a layer has a vertical coordinate system defined, the elevation unit of the layer is the same as the linear unit of the vertical coordinate system.

Code sample

LayerElevation example 1

The following script will iterate over 3D layers in your scene and set their elevation mode to On the ground.

import arcpy

aprx = arcpy.mp.ArcGISProject("C:/projects/redlands/redlands.aprx")
m = aprx.listMaps("Scene")[0]
for lyr in m.listLayers():
    e = lyr.elevation
    # Use try/except for layers that support on the ground and 
    # skip over layers that do not support this elevation mode
    try:
        e.setElevationMode('ON_THE_GROUND')
    except Exception as e:
        print(f"An error occurred: {e} for {lyr.name}")
aprx.save()

LayerElevation example 2

The following script will iterate over 3D layers in your scene and set their elevation mode to Relative to a custom surface with an arcade expression of 50.

import arcpy

aprx = arcpy.mp.ArcGISProject("C:/projects/redlands/redlands.aprx")
m = aprx.listMaps("Scene")[0]
for lyr in m.listLayers():
    e = lyr.elevation
    # Use try/except for layers that support on the ground and 
    # skip over layers that do not support this elevation mode
    try:
        e.setElevationMode('RELATIVE_TO_CUSTOM_SURFACE','50',s)
    except Exception as e:
        print(f"An error occurred: {e} for {lyr.name}")
aprx.save()

LayerElevation example 3

The following script will iterate over 3D layers in your scene and set their elevation mode to Absolute height based on the features Z values.

import arcpy

aprx = arcpy.mp.ArcGISProject("C:/projects/redlands/redlands.aprx")
m = aprx.listMaps("Scene")[0]
for lyr in m.listLayers():
    e = lyr.elevation
    # Use try/except for layers that support on the ground and 
    # skip over layers that do not support this elevation mode
    try:
        e.setElevationMode('ABSOLUTE_HEIGHT', 'Shape.Z')
    except Exception as e:
        print(f"An error occurred: {e} for {lyr.name}")
aprx.save()

LayerElevation example 4

The following script will iterate over 3D layers in your scene and set the cartographic offset to 100 if the current offset is 0.

import arcpy

aprx = arcpy.mp.ArcGISProject("C:/projects/redlands/redlands.aprx")
m = aprx.listMaps("Scene")[0]
for lyr in m.listLayers():
    e = lyr.elevation
    if e.cartographicOffset == 0:
        e.cartographicOffset = 100
aprx.save()