The surface contains elevation sources and defines a surface upon which layers and overlays can be draped. More...
| Header | #include <Surface.h |
| Since | Esri |
| Inherits | Esri |
Public Functions
| Surface(QObject *parent = nullptr) | |
| Surface(const QList | |
| virtual | ~ |
(since Esri QFuture | apply |
(since Esri Esri | background |
(since Esri QFuture | elevation |
| float | elevation |
| Esri | elevation |
| bool | is |
| QString | name() const |
(since Esri Esri | navigation |
(since Esri float | opacity() const |
(since Esri void | set |
| void | set |
| void | set |
| void | set |
(since Esri void | set |
(since Esri void | set |
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
The surface is used to represent the ground in a scene. It is comprised of a collection of elevation sources (ElevationSource) which are combined in the scene to generate the surface.
Surface provides methods for retrieving elevation values at one or more locations. Use applyElevationAsync to efficiently determine the elevation for all vertices in a geometry. Use elevationAsync when you only need the elevation for a single point.
Relevant samples:
- Create terrain surface from a local raster: Set the terrain surface with elevation described by a raster file.
- Create terrain surface from a local tile package: Set the terrain surface with elevation described by a local tile package.
- Display a scene layer: Add a scene layer to a scene.
- Filter features in scene: Filter 3D scene features out of a given geometry with a polygon filter.
- Set surface placement mode: Position graphics relative to a surface using different surface placement modes.
- Terrain exaggeration: Vertically exaggerate terrain in a scene.
- View content beneath terrain surface: See through terrain in a scene and move the camera underground.
Member Function Documentation
[explicit] Surface::Surface(QObject *parent = nullptr)
Default constructor that takes an optional parent.
[explicit] Surface::Surface(const QList<Esri::ArcGISRuntime::ElevationSource *> &elevationSources , QObject *parent = nullptr)
Constructor that takes a list of ElevationSource elevationSources and an optional parent.
[override virtual noexcept] Surface::~Surface ()
Destructor
[since Esri::ArcGISRuntime 300.0] QFuture<Esri::ArcGISRuntime::Geometry > Surface::applyElevationAsync (const Esri::ArcGISRuntime::Geometry &geometry)
Gets and applies an elevation (in meters) for each point in the input geometry.
The method returns a copy of the input geometry, but with updated elevation (Z) values for all points. Each point’s elevation is taken from the highest‑detail data available in the provided elevation sources. Because of this, the returned geometry may contain elevation values with a higher resolution than what is currently rendered on the screen.
This takes any geometry type as an input and the only exception is when the input geometry is an Envelope in which case, an exception is thrown.
If the elevation for a vertex cannot be determined, its Z value in the returned geometry is set to NaN.
- geometry - The geometry that contains the points to fetch the elevations for.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 300.0.
[since Esri::ArcGISRuntime 100.1] Esri::ArcGISRuntime::BackgroundGrid Surface::backgroundGrid () const
Returns the grid and color settings to render the background grid of this surface.
The background grid is visible when no data is draped on the surface.
This function was introduced in Esri::ArcGISRuntime 100.1.
See also setBackgroundGrid().
[override virtual] void Surface::cancelLoad ()
Reimplements: Loadable::cancelLoad().
See Loadable.
[signal] void Surface::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.
[since Esri::ArcGISRuntime 200.2] QFuture<double> Surface::elevationAsync (const Esri::ArcGISRuntime::Point &point)
Returns the elevation (in meters) for the specified location on the surface.
The returned elevation value is based on the highest possible level of detail available into the surface from the provided elevation sources. This results in the highest possible resolution for the elevation value for the given location. Note that this may differ from the value of the elevation currently being rendered which may be at a lower resolution.
- point - The point location to find the elevation for.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
See also applyElevationAsync(const Esri::ArcGISRuntime::Geometry&).
float Surface::elevationExaggeration () const
Returns the exaggeration for the surface.
The altitude values of the surface data are multiplied by the exaggeration value. The default value is 1.0, indicating no exaggeration.
See also setElevationExaggeration().
Esri::ArcGISRuntime::ElevationSourceListModel *Surface::elevationSources () const
Returns the elevation sources for the surface.
Elevation sources are an ordered collection of ElevationSource data that are combined to generate elevation values for the surface. The order of the elevation sources in the collection indicate which elevation has priority when the sources are spatially coincident. The collection is specific to a surface so you cannot reuse an elevation source collection coming from another Surface.
See also Surface.
bool Surface::isEnabled () const
Returns true if the surface is enabled, false otherwise.
This value indicates if the surface is enabled and is rendered. If true, the surface's elevation sources are only used in the calculation of the surface if their ElevationSource::setEnabled is also true.
[override virtual] void Surface::load()
Reimplements: Loadable::load().
See Loadable.
[override virtual] Esri::ArcGISRuntime::Error Surface::loadError () const
Reimplements: Loadable::loadError() const.
See Loadable.
[override virtual] Esri::ArcGISRuntime::LoadStatus Surface::loadStatus () const
Reimplements: Loadable::loadStatus() const.
See Loadable.
[signal] void Surface::loadStatusChanged (Esri::ArcGISRuntime::LoadStatus loadStatus )
Signal emitted when the loadStatus property changes.
See also Loadable.
QString Surface::name() const
Gets the name of the surface.
See also setName().
[since Esri::ArcGISRuntime 100.5] Esri::ArcGISRuntime::NavigationConstraint Surface::navigationConstraint () const
Returns the type of navigation constraint of the surface.
This property determines whether the camera altitude is affected by the elevation at the location of the camera. You can restrict the camera to stay above the ground or allow it to move below the surface. The default value is NavigationConstraint::StayAbove.
This function was introduced in Esri::ArcGISRuntime 100.5.
See also setNavigationConstraint().
[since Esri::ArcGISRuntime 100.5] float Surface::opacity() const
Returns the opacity applied to the surface.
The opacity value of all layers in the basemap, associated with this surface, and the backgroundGrid are multiplied by this opacity value. The value can be between 0 and 1.0, where 0 is transparent and 1.0 is solid or opaque.
This function was introduced in Esri::ArcGISRuntime 100.5.
See also setOpacity().
[override virtual] void Surface::retryLoad ()
Reimplements: Loadable::retryLoad().
See Loadable.
[since Esri::ArcGISRuntime 100.1] void Surface::setBackgroundGrid (const Esri::ArcGISRuntime::BackgroundGrid &backgroundGrid )
Sets the surface's background grid to backgroundGrid.
This function was introduced in Esri::ArcGISRuntime 100.1.
See also backgroundGrid().
void Surface::setElevationExaggeration (float exaggeration)
Sets the elevation exaggeration for the surface.
See also elevationExaggeration().
void Surface::setEnabled (bool enabled)
Sets whether the surface is enabled.
See also isEnabled().
void Surface::setName (const QString &name)
Sets the name of the surface.
See also name().
[since Esri::ArcGISRuntime 100.5] void Surface::setNavigationConstraint (Esri::ArcGISRuntime::NavigationConstraint navigationConstraint )
Sets the type of navigation constraint from the surface to navigationConstraint.
The default value is NavigationConstraint::StayAbove.
This function was introduced in Esri::ArcGISRuntime 100.5.
See also navigationConstraint().
[since Esri::ArcGISRuntime 100.5] void Surface::setOpacity (float opacity) const
Sets the opacity of the ground surface.
You can adjust this ground surface opacity property to see through the ground. Changing this property also changes the transparency of the basemap. (Draped operational layers are not affected by this property.) Valid opacity values are from 0.0 (full transparency) to 1.0 (full opacity). The opacity affects all base layers and the grid color:
- If an individual base layer has 50% opacity and the surface has 50% opacity, the effect will be multiplicative, i.e. the base layer will appear to have 25% opacity.
- If the grid color has an alpha value of 50% and the surface has 50% opacity, the effect on the grid will also be multiplicative.
The default value is 1.0.
This function was introduced in Esri::ArcGISRuntime 100.5.
See also opacity().