arcgis-maps-kotlin/com.arcgismaps.mapping.symbology/ModelSymbolLayer

ModelSymbolLayer

class ModelSymbolLayer : SymbolLayer, Loadable

A symbol layer uses a volumetric 3D shape (such as a sphere, cube, or cylinder) to define the appearance of a symbol. A ModelSymbolLayer is typically used with a MultilayerPointSymbol to visualize point geometries at a specific location relative to the geometry in a scene view.

The ModelSymbolLayer can be created from a built-in primitive shape or from a URI pointing to a 3D graphical model stored on the web or locally on the device. Supported formats for 3D models include COLLADA (.dae), 3ds Max (.3ds), Filmbox (.fbx), Wavefront (.obj), GL Transmission Format (.glTF), or Binary GL Transmission Format (.glb).

You can customize the appearance of the model symbol layer, such as its color and size. The size of a symbol can be controlled through the properties ModelSymbolLayer.height, ModelSymbolLayer.width, and ModelSymbolLayer.depth. By default, these values are specified in device-independent pixels (DIPs). To define the size in meters instead, set MultilayerSymbol.sceneSizeUnit to SymbolSizeUnits.Meters. This changes the interpretation of the size properties from screen-based units to real-world units, giving the symbol a fixed measurable size in world space. As a result, the symbol appears smaller when viewed from a distance and larger up close, consistent with a real-world perspective.

When a model symbol layer is added to a MultilayerPointSymbol, the ModelSymbolLayer.height property serves as the primary sizing axis. Adjusting MultilayerPointSymbol.size modifies the height of the model symbol layer, while the width and depth are proportionally adjusted based on the original 3D model's bounding box ratio (or 1:1:1 for basic shapes). Setting MultilayerPointSymbol.size to 0 prevents the symbol from rendering and sets all dimensions (height, width, depth) of the model symbol layer to 0. When MultilayerPointSymbol.size is set to a positive value, the behavior is determined by the original dimension ratio:

If the height of the original bounding box is 0, the ModelSymbolLayer.height, ModelSymbolLayer.width, and ModelSymbolLayer.depth remain unchanged, and rendering is not affected.
If the height of the original bounding box is non-zero, ModelSymbolLayer.height updates, while ModelSymbolLayer.width and ModelSymbolLayer.depth scale proportionally.
If the width or depth of the original bounding box is 0, those dimensions remain unchanged.

The ModelSymbolLayer.height property defines the size of the symbol layer for MultilayerPointSymbol.size. If the height is set to 0 or a negative value, MultilayerPointSymbol.size will report 0. If any of the dimensions — ModelSymbolLayer.height, ModelSymbolLayer.width, or ModelSymbolLayer.depth — are explicitly set to 0 or a negative value, the corresponding dimension of the model symbol layer will collapse, resulting in the symbol being flattened along that axis.

Additionally, you can modify the relative position of the model symbol layer by tweaking the ModelSymbolLayer.anchor. The orientation of the model symbol layer can be changed using the ModelSymbolLayer.heading, ModelSymbolLayer.pitch, and ModelSymbolLayer.roll properties.

Since

300.0.0

Constructors

ModelSymbolLayer

constructor(shape: ModelShape)

Creates a model symbol layer from a well-known 3D primitive shape. This creates a new model symbol layer and sets up the following default properties:

constructor(uri: String)

Creates a model symbol layer from a URI that references a 3D model. This creates a new model symbol layer and sets up the following default properties:

Properties

anchor

var anchor: SymbolAnchor?

The anchor of the model symbol layer. The anchor determines how the ModelSymbolLayer is positioned relative to the geometry. SymbolAnchor specifies the 3D model's anchor point and anchor placement mode. When you rotate or resize a model symbol layer, the transformation originates from the anchor point.

color

var color: Color

The color of the 3D model. Applying a color to a 3D model with textures tints the model using the specified color. For models that use primitive ModelShape, the shape's color is updated to the specified value. Note that, when the color is set to transparent black, a ModelShape does not render and the 3D model instead appears with its baked-in textures and colors.

depth

var depth: Double

The depth of the model symbol layer. The input value must be a positive number. By default, the depth is measured in DIPs. To use meters instead, set the MultilayerSymbol.sceneSizeUnit property to SymbolSizeUnits.Meters after adding the model symbol layer to a MultilayerPointSymbol.

heading

var heading: Double

The rotation angle around Z-axis in degrees. At 0 degrees, the model points in the direction of the Y-axis. Positive values indicate clockwise rotation. The default value is 0.0 degrees.

height

var height: Double

The height of the model symbol layer. The input value must be a positive number. By default, the height is measured in DIPs. To use meters instead, set the MultilayerSymbol.sceneSizeUnit property to SymbolSizeUnits.Meters after adding the model symbol layer to a MultilayerPointSymbol.

pitch

var pitch: Double

The rotation angle around X-axis in degrees. At 0 degrees, the model is level. A positive value lifts the front and lowers the back of the model. The default value is 0.0 degrees.

roll

var roll: Double

The rotation angle around Y-axis in degrees. At 0 degrees, the model is level. A positive value lifts the left part and lowers the right part of the model. The default value is 0.0 degrees.

uri

val uri: String?

The URI of the 3D model to be loaded in a model symbol layer. The URI is an empty string when the model symbol layer is created from a ModelShape. To load the 3D model at the specified URI, call ModelSymbolLayer.load.

width

var width: Double

The width of the model symbol layer. The input value must be a positive number. By default, the width is measured in DIPs. To use meters instead, set the MultilayerSymbol.sceneSizeUnit property to SymbolSizeUnits.Meters after adding the model symbol layer to a MultilayerPointSymbol.

Inherited properties

isColorLocked

var isColorLocked: Boolean

The symbol layer color locked property. The color-locked status of the symbol layer. If color_locked is true, the color of that layer will not change.

isEnabled

var isEnabled: Boolean

The symbol layer enabled property. The enable status of the symbol layer. Layer will be rendered only if it is enabled.

loadStatus

open override val loadStatus: StateFlow<LoadStatus>

The load status.