A symbol layer uses a volumetric 3D shape (such as a sphere, cube, or cylinder) to define the appearance of a symbol. More...
| Header | #include <Model |
| Since | Esri |
| Inherits | Esri |
Public Functions
| Model | |
| Model | |
| virtual | ~ |
| Esri | anchor() const |
| QColor | color() const |
| double | depth() const |
| double | heading() const |
| double | height() const |
| double | pitch() const |
| double | roll() const |
| void | set |
| void | set |
| void | set |
| void | set |
| void | set |
| void | set |
| void | set |
| void | set |
| QUrl | url() const |
| double | width() const |
Reimplemented Public Functions
| virtual void | cancel |
| virtual void | load() override |
| virtual Esri | load |
| virtual Esri | load |
| virtual void | retry |
Signals
| void | done |
| void | load |
Detailed Description
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 URL 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 height, width, and 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 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 height, width, and depth remain unchanged, and rendering is not affected. - If the height of the original bounding box is non-zero, height updates, while width and depth scale proportionally. - If the width or depth of the original bounding box is 0, those dimensions remain unchanged.
The 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 — height, width, or 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 anchor. The orientation of the model symbol layer can be changed using the heading, pitch, and roll properties.
Member Function Documentation
[explicit] ModelSymbolLayer::ModelSymbolLayer (Esri::ArcGISRuntime::ModelShape shape, QObject *parent = nullptr)
Creates a model symbol layer from a well-known 3D primitive shape.
- shape - Primitive shape.
- parent - The optional parent QObject.
This creates a new model symbol layer and sets up the following default properties: - anchor defaults to nullptr, which is the origin of the ModelShape. The origin is located at the center of the ModelShape for ModelShape::Sphere, ModelShape::Cube, and ModelShape::Diamond, and at the bottom center for ModelShape::Cylinder, ModelShape::Cone, and ModelShape::Tetrahedron. - fully opaque white (RGBA(255, 255, 255, 255)) - height, width, and depth of 10.0 DIPs - heading, pitch, and roll of 0.0 degrees - an empty URL
After creating, the load status of ModelSymbolLayer will be set to LoadStatus::Loaded.
[explicit] ModelSymbolLayer::ModelSymbolLayer (const QUrl &url, QObject *parent = nullptr)
Creates a model symbol layer from a URL that references a 3D model.
- url - The URL location of the 3D model to use in the symbol layer.
- parent - The optional parent QObject.
This creates a new model symbol layer and sets up the following default properties: - anchor defaults to nullptr, which is the origin of the 3D model. - fully transparent black (RGBA(0, 0, 0, 0)) - height, width, and depth of 0.0 DIPs - heading, pitch, and roll of 0.0 degrees - URL set to the specified URL
After creating, call load to load the 3D model from the URL asynchronously. Once the model is loaded, its properties will be populated using the values defined in the model if not set explicitly.
By default, if not explicitly specified, the color of a loaded model symbol layer is reported as transparent black.
The URL can be a local file path or a web address. The URL must point to a 3D model in one of the supported formats: COLLADA (.dae), 3ds Max (.3ds), Filmbox (.fbx), Wavefront (.obj), GL Transmission Format (.glTF), or Binary GL Transmission Format (.glb).
[override virtual noexcept] ModelSymbolLayer::~ModelSymbolLayer ()
Destructor.
Esri::ArcGISRuntime::SymbolAnchor ModelSymbolLayer::anchor() const
Returns 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.
The anchor defaults to empty, which is the origin of the 3D model or ModelShape. An anchor with SymbolAnchorPlacementMode::Absolute is not supported for model symbol layers. See the SymbolAnchor documentation for a detailed description of the object.
See also setAnchor().
[override virtual] void ModelSymbolLayer::cancelLoad ()
Reimplements: Loadable::cancelLoad().
Cancels loading metadata for the object.
Cancels loading the metadata if the object is loading and always calls doneLoading.
QColor ModelSymbolLayer::color() const
Returns 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.
By default: - A model symbol layer created from a primitive shape uses fully opaque white (RGBA(255, 255, 255, 255)). - A model symbol layer created from a URL uses fully transparent black (RGBA(0, 0, 0, 0)) until the layer is loaded.
See also setColor().
double ModelSymbolLayer::depth() const
Returns 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.
The default value is 10.0 DIPs for a model symbol layer created from a primitive shape and 0.0 DIPs for a model symbol layer created from a URL before the symbol layer is LoadStatus::Loaded. If not explicitly set, the depth is populated from metadata defined in the model and applied after the symbol layer is loaded. If the depth is explicitly set to 0 or a negative number, the depth dimension will collapse, resulting in a loss of proportion among the width, height, and depth.
See also setDepth().
[signal] void ModelSymbolLayer::doneLoading (const Esri::ArcGISRuntime::Error &loadError )
Signal emitted when this object is done loading.
- loadError - Details about any error that may have occurred.
Note: If there is a load error it will also be emitted on the errorOccurred signal.
double ModelSymbolLayer::heading() const
Returns 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.
See also setHeading().
double ModelSymbolLayer::height() const
Returns 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.
The default value is 10.0 DIPs for a model symbol layer created from a primitive shape and 0.0 DIPs for a model symbol layer created from a URL before the symbol layer is LoadStatus::Loaded. If not explicitly set, the height is populated from metadata defined in the model and applied after the symbol layer is loaded. If the height is explicitly set to 0 or a negative number, the height dimension will collapse, resulting in a loss of proportion among the width, height, and depth.
See also setHeight().
[override virtual] void ModelSymbolLayer::load()
Reimplements: Loadable::load().
Loads the metadata for the object asynchronously.
Loads the metadata if the object is not loaded and always calls doneLoading.
[override virtual] Esri::ArcGISRuntime::Error ModelSymbolLayer::loadError () const
Reimplements: Loadable::loadError() const.
Returns the load error.
See also Error.
[override virtual] Esri::ArcGISRuntime::LoadStatus ModelSymbolLayer::loadStatus () const
Reimplements: Loadable::loadStatus() const.
Returns the load status.
See also LoadStatus.
[signal] void ModelSymbolLayer::loadStatusChanged (Esri::ArcGISRuntime::LoadStatus loadStatus )
loadStatus See Loadable.
double ModelSymbolLayer::pitch() const
Returns 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.
See also setPitch().
[override virtual] void ModelSymbolLayer::retryLoad ()
Reimplements: Loadable::retryLoad().
Loads or retries loading metadata for the object asynchronously.
Will retry loading the metadata if the object is failed to load. Will load the object if it is not loaded. Will not retry to load the object if the object is loaded. Will always call the done loading if this is called.
double ModelSymbolLayer::roll() const
Returns 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.
See also setRoll().
void ModelSymbolLayer::setAnchor (const Esri::ArcGISRuntime::SymbolAnchor &anchor)
Sets the anchor to anchor.
See also anchor.
void ModelSymbolLayer::setColor (const QColor &color)
Sets the color to color.
See also color.
void ModelSymbolLayer::setDepth (double depth)
Sets the depth to depth.
See also depth.
void ModelSymbolLayer::setHeading (double heading)
Sets the heading to heading.
See also heading.
void ModelSymbolLayer::setHeight (double height)
Sets the height to height.
See also height.
void ModelSymbolLayer::setPitch (double pitch)
Sets the pitch to pitch.
See also pitch.
void ModelSymbolLayer::setRoll (double roll)
Sets the roll to roll.
See also roll.
void ModelSymbolLayer::setWidth (double width)
Sets the width to width.
See also width.
QUrl ModelSymbolLayer::url() const
Returns the URL of the 3D model to be loaded in a model symbol layer.
The URL is an empty string when the model symbol layer is created from a ModelShape. To load the 3D model at the specified URL, call load.
double ModelSymbolLayer::width() const
Returns 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.
The default value is 10.0 DIPs for a model symbol layer created from a primitive shape and 0.0 DIPs for a model symbol layer created from a URL before the symbol layer is LoadStatus::Loaded. If not explicitly set, the width is populated from metadata defined in the model and applied after the symbol layer is loaded. If the width is explicitly set to 0 or a negative number, the width dimension will collapse, resulting in a loss of proportion among the width, height, and depth.
See also setWidth().