ModelSymbolLayer class final

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.