Position graphics relative to a surface using different surface placement modes.
Use case
Depending on the use case, data might be displayed at an absolute height (e.g. flight data recorded with altitude information), at a relative height to the terrain (e.g. transmission lines positioned relative to the ground), at a relative height to objects in the scene (e.g. extruded polygons, integrated mesh scene layer), or draped directly onto the terrain (e.g. location markers, area boundaries).
How to use the sample
The application loads a scene showing four points that use individual surface placement modes (Absolute, Relative, Relative to Scene, and either Draped Billboarded or Draped Flat). Use the toggle to change the draped mode and the slider to dynamically adjust the Z value of the graphics. Explore the scene by zooming in/out and by panning around to observe the effects of the surface placement rules.
How it works
- Create a
GraphicsOverlayfor each placement mode, settingLayerSceneProperties.surfacePlacement:Absolute, position graphic using only its Z value.Relative, position graphic using its Z value plus the elevation of the surface.DrapedBillboarded, position graphic upright on the surface and always facing the camera, not using its z value.DrapedFlat, position graphic flat on the surface, not using its z value.RelativeToScene, position graphic using its Z value plus the altitude values of the scene.
- Add graphics to the graphics overlay,
GraphicsOverlay.graphics.append(Graphic). - Add each graphics overlay to the scene view by calling
SceneView.graphicsOverlays.append(overlay).
Relevant API
- Graphic
- GraphicsOverlay
- LayerSceneProperties.surfacePlacement
- SceneProperties
- Surface
About the data
The scene launches with a view of Brest, France. Four points are shown hovering with positions defined by each of the different surface placement modes.
Additional information
This sample uses an elevation service to add elevation/terrain to the scene. Graphics are positioned relative to that surface for the DrapedBillboarded, DrapedFlat, and Relative surface placement modes. It also uses a scene layer containing 3D models of buildings. Graphics are positioned relative to that scene layer for the RelativeToScene surface placement mode.
Tags
3D, absolute, altitude, draped, elevation, floating, relative, scenes, sea level, surface placement
Sample Code
SetSurfacePlacementMode.qml
// [WriteFile Name=SetSurfacePlacementMode, Category=Scenes]
// [Legal]
// Copyright 2016 Esri.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// [Legal]
import QtQuick
import QtQuick.Controls
import QtQuick.Layouts
import Esri.ArcGISRuntime
Rectangle {
width: 800
height: 600
// Add a scene view
SceneView {
id: sceneView
anchors.fill: parent
Component.onCompleted: {
// Set the focus on SceneView to initially enable keyboard navigation
forceActiveFocus();
}
// Add a scene with the imagery basemap and world elevation surface
Scene {
Basemap {
initStyle: Enums.BasemapStyleArcGISImageryStandard
}
Surface {
ArcGISTiledElevationSource {
url: "https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"
}
}
ArcGISSceneLayer {
url: "https://tiles.arcgis.com/tiles/P3ePLMYs2RVChkJx/arcgis/rest/services/Buildings_Brest/SceneServer"
}
// set an initial viewpoint
ViewpointCenter {
Point {
id: initialViewpoint
x: -4.45968
y: 48.3889
z: 37.9922
spatialReference: SpatialReference { wkid: 4326 }
}
targetScale: 62.013264927081764
Camera {
id: camera
location: initialViewpoint
heading: 329.91
pitch: 96.6632
roll: 0
}
}
}
// Graphics overlay with draped flat surface placement
GraphicsOverlay {
id: drapedFlatOverlay
sceneProperties.surfacePlacement: Enums.SurfacePlacementDrapedFlat
visible: false
// Graphics will be draped on the surface of the scene and will appear flat
Graphic {
geometry: surfaceRelatedPoint
SimpleMarkerSymbol {
color: "red"
style: Enums.SimpleMarkerSymbolStyleTriangle
size: 20
}
}
Graphic {
geometry: surfaceRelatedPoint
TextSymbol {
size: 20
text: "DRAPED FLAT"
color: "blue"
horizontalAlignment: Enums.HorizontalAlignmentLeft
verticalAlignment: Enums.VerticalAlignmentMiddle
offsetX: 20
}
}
}
// Graphics overlay with draped billboard surface placement
GraphicsOverlay {
id: drapedBillboardedOverlay
sceneProperties.surfacePlacement: Enums.SurfacePlacementDrapedBillboarded
// Graphics will be draped on the surface of the scene and will always face the camera.
Graphic {
geometry: surfaceRelatedPoint
SimpleMarkerSymbol {
color: "red"
style: Enums.SimpleMarkerSymbolStyleTriangle
size: 20
}
}
Graphic {
geometry: surfaceRelatedPoint
TextSymbol {
size: 20
text: "DRAPED BILLBOARDED"
color: "blue"
horizontalAlignment: Enums.HorizontalAlignmentLeft
verticalAlignment: Enums.VerticalAlignmentMiddle
offsetX: 20
}
}
}
// Graphics overlay with relative surface placement
GraphicsOverlay {
id: relativeOverlay
sceneProperties.surfacePlacement: Enums.SurfacePlacementRelative
// Graphics will be placed at z value relative to the surface
Graphic {
geometry: surfaceRelatedPoint
SimpleMarkerSymbol {
color: "red"
style: Enums.SimpleMarkerSymbolStyleTriangle
size: 20
}
}
Graphic {
geometry: surfaceRelatedPoint
TextSymbol {
size: 20
text: "RELATIVE"
color: "blue"
horizontalAlignment: Enums.HorizontalAlignmentLeft
verticalAlignment: Enums.VerticalAlignmentMiddle
offsetX: 20
}
}
}
// Graphics overlay with absolute surface placement
GraphicsOverlay {
id: absoluteOverlay
sceneProperties.surfacePlacement: Enums.SurfacePlacementAbsolute
// Graphics will be placed at absolute z value
Graphic {
geometry: surfaceRelatedPoint
SimpleMarkerSymbol {
color: "red"
style: Enums.SimpleMarkerSymbolStyleTriangle
size: 20
}
}
Graphic {
geometry: surfaceRelatedPoint
TextSymbol {
size: 20
text: "ABSOLUTE"
color: "blue"
horizontalAlignment: Enums.HorizontalAlignmentLeft
verticalAlignment: Enums.VerticalAlignmentMiddle
offsetX: 20
}
}
}
GraphicsOverlay {
id: relToScene
sceneProperties.surfacePlacement: Enums.SurfacePlacementRelativeToScene
// Graphics will be placed at absolute z value
Graphic {
geometry: sceneRelatedPoint
SimpleMarkerSymbol {
color: "red"
style: Enums.SimpleMarkerSymbolStyleTriangle
size: 20
}
}
Graphic {
geometry: sceneRelatedPoint
TextSymbol {
size: 20
text: "RELATIVE TO SCENE"
color: "blue"
horizontalAlignment: Enums.HorizontalAlignmentRight
verticalAlignment: Enums.VerticalAlignmentMiddle
offsetX: -20
}
}
}
}
Rectangle {
anchors {
top: parent.top
left: parent.left
margins: 3
}
width: childrenRect.width
height: childrenRect.height
color: "#000000"
opacity: .8
radius: 5
ColumnLayout {
Text {
Layout.alignment: Qt.AlignHCenter
Layout.margins: 2
text: qsTr("Draped mode")
color: "white"
}
Switch {
id: surfacePlacementMode
Layout.alignment: Qt.AlignHCenter
Layout.margins: 2
onCheckedChanged: {
drapedFlatOverlay.visible = !drapedFlatOverlay.visible;
drapedBillboardedOverlay.visible = !drapedBillboardedOverlay.visible;
}
}
}
}
Rectangle {
anchors {
top: parent.top
right: parent.right
margins: 5
}
width: childrenRect.width
height: childrenRect.height
color: "#000000"
opacity: .8
radius: 5
MouseArea {
anchors.fill: parent
onClicked: mouse => mouse.accepted = true
onWheel: wheel => wheel.accepted = true
}
ColumnLayout {
Text {
id: zValueSliderLabel
text: qsTr("Z-Value")
color: "white"
Layout.margins: 2
Layout.alignment: Qt.AlignHCenter
}
Slider {
id: zValueSlider
from: 0
to: 140
value: 70
Layout.alignment: Qt.AlignHCenter
Layout.margins: 2
orientation: Qt.Vertical
onMoved: changeZValue(value.toFixed(0));
// Custom slider handle that displays the current value
handle: Item {
x: parent.leftPadding + parent.availableWidth / 2 - headingHandleNub.width / 2
y: parent.topPadding + parent.visualPosition * (parent.availableHeight - headingHandleNub.height)
Rectangle {
id: headingHandleNub
color: headingHandleRect.color
radius: width * 0.5
width: 20
height: width
}
Rectangle {
id: headingHandleRect
height: childrenRect.height
width: childrenRect.width
radius: 3
x: headingHandleNub.x - width
y: headingHandleNub.y - height / 2 + headingHandleNub.height / 2
color: zValueSlider.background.children[0].color
Text {
id: headingValue
font.pixelSize: 14
padding: 3
horizontalAlignment: Qt.AlignHCenter
verticalAlignment: Qt.AlignVCenter
text: (zValueSlider.value).toFixed(0)
color: "white"
}
}
}
}
}
}
// create a point with a z value of 70
Point {
id: sceneRelatedPoint
x: -4.4610562
y: 48.3902727
z: 70
spatialReference: SpatialReference { wkid: 4326 }
}
// create a point with a z value of 70
Point {
id: surfaceRelatedPoint
x: -4.4609257
y: 48.3903965
z: 70
spatialReference: SpatialReference { wkid: 4326 }
}
function changeZValue(zValue) {
sceneView.graphicsOverlays.forEach( function(overlay) {
overlay.graphics.forEach( function(graphic) {
// create new graphic with the same existing information but a new Z-value
const graphicPoint = ArcGISRuntimeEnvironment.createObject("Point", {
x:graphic.geometry.x,
y:graphic.geometry.y,
z:zValue,
spatialReference: graphic.geometry.spatialReference
});
graphic.geometry = graphicPoint;
});
});
}
}