Learn how to evaluate the horizontal, vertical, and direct distances between two points in a 3D Scene.
A distance measurement analysis is a type of measurement analysis that calculates and displays the distance between start point and end point locations. The analysis evaluates the vertical, horizontal, and direct distances between the two 3D points and renders a measurement visualization on-screen.
In this tutorial you will perform and display a distance measurement analysis in a web scene. Using the distance measurement analysis you will measure distances between hotspots in the Yosemite Valley.
Prerequisites
Before starting this tutorial:
-
You need an ArcGIS Location Platform or ArcGIS Online account.
-
Your system meets the system requirements.
Steps
Open the Xcode project
-
To start this tutorial, first complete the Display a web scene tutorial or download and unzip the solution.
-
Open the
.xcodeproj
file in Xcode. -
If you downloaded the solution, get an access token and set the API key.
An API Key gives your app access to secure resources used in this tutorial.
-
Go to the Create an API key tutorial to obtain a new API key access token. Ensure that the following privilege is enabled: Location services > Basemaps > Basemap styles service. Copy the access token as it will be used in the next step.
-
In Xcode, in the Project Navigator, click AppDelegate.swift.
-
In the editor, set the
API
property on theKey AGS
with your access token.ArcGIS Runtime Environment AppDelegate.swiftUse dark colors for code blocks func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { AGSArcGISRuntimeEnvironment.apiKey = "YOUR_ACCESS_TOKEN" return true }
-
Get the web scene item ID
You can use ArcGIS tools to create and view web scenes. Use the Scene Viewer to identify the web scene item ID. This item ID will be used later in the tutorial.
- Go to the Yosemite Valley Hotspots web scene in the Scene Viewer in ArcGIS Online. This web scene displays terrain and hotspots in the Yosemite Valley.
- Make a note of the item ID at the end of the browser's URL. The item ID should be 7558ee942b2547019f66885c44d4f0b1.
Update the scene
-
In Xcode, in the Project Navigator, click ViewController.swift.
-
In the editor, modify the
setup
method to create anScene() AGS
for the web scene. To do this, create a portal item providing the web scene's item ID and anScene AGS
referencing ArcGIS Online.Portal ViewController.swiftUse dark colors for code blocks 29 30 31 32 34 35 36 37 38 39Change line private func setupScene() { let scene: AGSScene = { let portal = AGSPortal.arcGISOnline(withLoginRequired: false) let item = AGSPortalItem(portal: portal, itemID: "7558ee942b2547019f66885c44d4f0b1") return AGSScene(item: item) }() sceneView.scene = scene }
Add a UI to control the distance measurement analysis
To control the distance measurement analysis, some UI is required.
-
Define a private method named
setup
. Create aU I() "
button and assign it to the navigation bar. The clear button removes the distance measurement analysis from the scene. You set an action on the clear button using a selector for a method that will be added in a later step.Clear" ViewController.swiftUse dark colors for code blocks 48Add line. Add line. Add line. Add line. Add line. private func setupUI() { navigationItem.title = "Long press and drag." let clear = UIBarButtonItem(title: "Clear", style: .plain, target: self, action: #selector(clearScene)) navigationItem.rightBarButtonItem = clear }
-
Define a method named
clear
and assign it theScene( _:) @objc
keyword. This method is performed when the user taps the clear button. The@objc
method keyword exposes the method to Objective-C, a necessary step for using theUI
API.Bar Button Item ViewController.swiftUse dark colors for code blocks 43 44 45 46 47 48Add line. Add line. Add line. Add line. private func setupUI() { navigationItem.title = "Long press and drag." let clear = UIBarButtonItem(title: "Clear", style: .plain, target: self, action: #selector(clearScene)) navigationItem.rightBarButtonItem = clear } @objc func clearScene(_ sender: UIBarButtonItem) { }
-
In
view
, call the methodDid Load() setup
.U I() ViewController.swiftUse dark colors for code blocks 21 22 23 24 26 27Add line. override func viewDidLoad() { super.viewDidLoad() setupScene() setupUI() }
-
In Xcode, in the Project Navigator, click Main.storyboard.
-
In the editor, select
View
. In the menu bar, click Editor > Embed In > Navigation Controller.Controller Embedding
View
within a Navigation Controller will place a navigation bar at the top ofController View
. Inside the navigation bar you will find the UI elements.Controller -
Check that your UI is set up properly. Press <Command+R> to run the app. You should see a "Clear" button contained by the navigation bar, the default title should be displayed, and the app should load the Yosemite Valley Hotspots web scene.
Format measurements for readability
-
In Xcode, in the Project Navigator, click ViewController.swift.
-
In the editor, create a private static
Measurement
namedFormatter measurement
. The measurement formatter is used to convert measurement values into strings that are in a format localized to the user's device.Formatter ViewController.swiftUse dark colors for code blocks 64Add line. Add line. Add line. Add line. Add line. Add line. private static let measurementFormatter: MeasurementFormatter = { let measurementFormatter = MeasurementFormatter() measurementFormatter.numberFormatter.minimumFractionDigits = 2 measurementFormatter.numberFormatter.maximumFractionDigits = 2 return measurementFormatter }()
-
Define a private method named
set
. This method is used to format a string to communicate the direct, horizontal, and vertical measurements to the user, placing the results in the navigation bar's title.Title For Distance Measurements(direct :horizontal :vertical :) Because
set
performs a UI operation and you cannot guarantee that it will be called from the main thread, you must ensure that the operation is performed asynchronously on the main thread.Title For Distance Measurements ViewController.swiftUse dark colors for code blocks 58 59 60 61 62 63 64Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. private static let measurementFormatter: MeasurementFormatter = { let measurementFormatter = MeasurementFormatter() measurementFormatter.numberFormatter.minimumFractionDigits = 2 measurementFormatter.numberFormatter.maximumFractionDigits = 2 return measurementFormatter }() private func setTitleForDistanceMeasurements(direct: AGSDistance, horizontal: AGSDistance, vertical: AGSDistance) { DispatchQueue.main.async { [weak self] in guard let self = self else { return } if self.measurement.isVisible { self.navigationItem.title = String( format: "Direct: %@ | Horizontal: %@ | Vertical: %@", Self.measurementFormatter.string(from: Measurement(value: direct.value, unit: Unit(symbol: direct.unit.abbreviation))), Self.measurementFormatter.string(from: Measurement(value: horizontal.value, unit: Unit(symbol: horizontal.unit.abbreviation))), Self.measurementFormatter.string(from: Measurement(value: vertical.value, unit: Unit(symbol: vertical.unit.abbreviation))) ) } else { self.navigationItem.title = "Long press and drag." } } }
Create a distance measurement analysis
Use a AGS
to perform and display a distance measurement analysis using 3D points to define the start and end locations.
-
Create a private lazy
AGS
namedLocation Distance Measurement measurement
. Upon launch, the distance measurement visualization should not be visible.ViewController.swiftUse dark colors for code blocks 91Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. private lazy var measurement: AGSLocationDistanceMeasurement = { let point = AGSPointMake3D(0, 0, 0, 0, .wgs84()) let measurement = AGSLocationDistanceMeasurement(startLocation: point, endLocation: point) measurement.measurementChangedHandler = setTitleForDistanceMeasurements measurement.isVisible = false measurement.unitSystem = .metric // .imperial return measurement }()
-
Define a private method named
setup
to add the distance measurement analysis to the scene.Analysis Overlay() The distance measurement analysis is added to a scene view using an analysis overlay. An analysis overlay is a container for analyses. It can be used to display visual analyses in a scene view. You can add more than one analysis overlay and they are displayed on top of all other layers.
ViewController.swiftUse dark colors for code blocks 83 84 85 86 87 88 89 90 91Add line. Add line. Add line. Add line. Add line. private lazy var measurement: AGSLocationDistanceMeasurement = { let point = AGSPointMake3D(0, 0, 0, 0, .wgs84()) let measurement = AGSLocationDistanceMeasurement(startLocation: point, endLocation: point) measurement.measurementChangedHandler = setTitleForDistanceMeasurements measurement.isVisible = false measurement.unitSystem = .metric // .imperial return measurement }() private func setupAnalysisOverlay() { let analysisOverlay = AGSAnalysisOverlay() analysisOverlay.analyses.add(measurement) sceneView.analysisOverlays.add(analysisOverlay) }
-
Define a private method named
start
that receives a point as a parameter. This method is used to set the distance measurement analysisDistance Measurement(point :) start
.Location ViewController.swiftUse dark colors for code blocks 92 93 94 95 96 97Add line. Add line. Add line. Add line. Add line. private func setupAnalysisOverlay() { let analysisOverlay = AGSAnalysisOverlay() analysisOverlay.analyses.add(measurement) sceneView.analysisOverlays.add(analysisOverlay) } private func startDistanceMeasurement(point: AGSPoint) { measurement.isVisible = false measurement.startLocation = point measurement.endLocation = point }
-
Define a private method named
move
that receives a point as a parameter. This method is used to set the distance measurement analysisDistance Measurement(point :) end
and make it visible, if it's not visible already.Location ViewController.swiftUse dark colors for code blocks 98 99 100 101 102 103Add line. Add line. Add line. Add line. Add line. Add line. private func startDistanceMeasurement(point: AGSPoint) { measurement.isVisible = false measurement.startLocation = point measurement.endLocation = point } private func moveDistanceMeasurement(point: AGSPoint) { measurement.endLocation = point if !measurement.isVisible { measurement.isVisible = true } }
-
Define a private method named
clear
. This method is used to hide the distance measurement analysis.Measurement() ViewController.swiftUse dark colors for code blocks 104 105 106 107 108 109 110Add line. Add line. Add line. Add line. private func moveDistanceMeasurement(point: AGSPoint) { measurement.endLocation = point if !measurement.isVisible { measurement.isVisible = true } } private func clearMeasurement() { measurement.isVisible = false navigationItem.title = "Long press and drag." }
-
Call
clear
when the user taps the "Clear" button.Measurement() ViewController.swiftUse dark colors for code blocks 51 52 53 55 56Add line. @objc func clearScene(_ sender: UIBarButtonItem) { clearMeasurement() }
-
In
view
, call the methodDid Load() setup
.Analysis Overlay() ViewController.swiftUse dark colors for code blocks 21 22 23 24 25 26 28 29Add line. override func viewDidLoad() { super.viewDidLoad() setupScene() setupUI() setupAnalysisOverlay() }
Display the distance measurement analysis with touch events
Touch events determine where to perform and display the distance measurement analysis. A user can long-press and drag to reveal and move the distance measurement analysis' location around the screen.
-
Extend
View
to conform to theController AGS
protocol and include the four long-press geoview touch delegate methods.Geo View Touch Delegate ViewController.swiftUse dark colors for code blocks Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. extension ViewController: AGSGeoViewTouchDelegate { func geoView(_ geoView: AGSGeoView, didLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { } func geoView(_ geoView: AGSGeoView, didMoveLongPressToScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { } func geoView(_ geoView: AGSGeoView, didEndLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { } func geoViewDidCancelLongPress(_ geoView: AGSGeoView) { } }
-
When the user begins a long-press touch event, call
start
.Distance Measurement(point :) ViewController.swiftUse dark colors for code blocks 122 123 124 125 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142Add line. extension ViewController: AGSGeoViewTouchDelegate { func geoView(_ geoView: AGSGeoView, didLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { startDistanceMeasurement(point: mapPoint) } func geoView(_ geoView: AGSGeoView, didMoveLongPressToScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { } func geoView(_ geoView: AGSGeoView, didEndLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { } func geoViewDidCancelLongPress(_ geoView: AGSGeoView) { } }
-
When the user moves and ends a long-press touch event, call
move
.Distance Measurement(point :) ViewController.swiftUse dark colors for code blocks 122 123 124 125 126 127 128 129 130 131 133 134 135 136 137 139 140 141 142 143 144 145 146Add line. Add line. extension ViewController: AGSGeoViewTouchDelegate { func geoView(_ geoView: AGSGeoView, didLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { startDistanceMeasurement(point: mapPoint) } func geoView(_ geoView: AGSGeoView, didMoveLongPressToScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { moveDistanceMeasurement(point: mapPoint) } func geoView(_ geoView: AGSGeoView, didEndLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { moveDistanceMeasurement(point: mapPoint) } func geoViewDidCancelLongPress(_ geoView: AGSGeoView) { } }
-
When the user cancels the long-press touch event, call
clear
.Measurement() This may happen, for instance, when you have the magnifier visible and attempt to take a screenshot using the home/lock button combination.
ViewController.swiftUse dark colors for code blocks 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 145 146 147 148Add line. extension ViewController: AGSGeoViewTouchDelegate { func geoView(_ geoView: AGSGeoView, didLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { startDistanceMeasurement(point: mapPoint) } func geoView(_ geoView: AGSGeoView, didMoveLongPressToScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { moveDistanceMeasurement(point: mapPoint) } func geoView(_ geoView: AGSGeoView, didEndLongPressAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) { moveDistanceMeasurement(point: mapPoint) } func geoViewDidCancelLongPress(_ geoView: AGSGeoView) { clearMeasurement() } }
-
In the
setup
method, assignScene() View
toController scene
.View.touch Delegate
This step connects the scene
user touch interactions with View
via the AGS
protocol.
private func setupScene() {
let scene: AGSScene = {
let portal = AGSPortal.arcGISOnline(withLoginRequired: false)
let item = AGSPortalItem(portal: portal, itemID: "7558ee942b2547019f66885c44d4f0b1")
return AGSScene(item: item)
}()
sceneView.scene = scene
sceneView.touchDelegate = self
}
Run the app
Press Command + R to run the app.
If you are using the Xcode simulator your system must meet these minimum requirements: macOS Big Sur 11.3, Xcode 13, iOS 13. If you are using a physical device, then refer to the system requirements.
You should see a scene of hotspots in the Yosemite Valley. Long-press and drag to display and move a distance measurement analysis to evaluate the horizontal, vertical, and direct distances between two park locations.
What's next?
Learn how to use additional API features, ArcGIS location services, and ArcGIS tools in these tutorials: