ArcGIS Runtime SDK for macOS

Display a scene

Scenes allow you to display and share collections of 3D geographical data across the ArcGIS platform. This guide explains how to display a pre-configured scene that is stored within a web scene or within a mobile scene package. The difference between 2D maps and 3D scenes is described in the topic Maps and scenes.

Note:

If you want to learn how to create your own scene in your app using code, see Build a new scene.

Open a scene from a web scene

Web scenes can be accessed using either their URL or directly from a portal using their portal item ID. Both methods are described below along with the authentication process required to access the scene if it, or its data is not public.

Using a web scene URL

You can open a scene directly from a URL in one of the following formats:

  • Scene viewer URL - https://www.arcgis.com/home/webscene/viewer.html?webscene=31874da8a16d45bfbc1273422f772270
  • Item URL - https://www.arcgis.com/home/item.html?id=31874da8a16d45bfbc1273422f772270
  • Item data URL - https://www.arcgis.com/sharing/rest/content/items/31874da8a16d45bfbc1273422f772270/data

//create scene from the URL
let scene = AGSScene(url: URL(string: "https://www.arcgis.com/home/item.html?id=31874da8a16d45bfbc1273422f772270")!)

If the scene is not public, the API’s authentication challenge handler automatically requests that the user provides their credentials.

Using a web scene portal item

You can construct a scene object using the scene's portal item ID. You can find this 32 character ID within any of the three URLs described above.

//initialize portal with AGOL
portal = AGSPortal.arcGISOnline(withLoginRequired: false)
        
//get the portal item
let portalItem = AGSPortalItem.init(portal: portal, itemID: "31874da8a16d45bfbc1273422f772270")
        
//create scene from portal item
let scene = AGSScene(item: portalItem)

Authentication

If the scene or its layers are not public, you need to provide credentials to access them. In these cases you can either: rely on the API’s authentication challenge handler to prompt the user for their credentials, or you can provide your own login facility and pass the credentials to the portal's credential property as described in the Access the ArcGIS platform topic.

Open a scene from a mobile scene package

Mobile scene packages allow you to work with scenes, 3D layers, elevation sources and associated data in a disconnected environment. You can create a mobile scene package (.mspk) file using ArcGIS Pro and deliver it using a platform-specific transfer mechanism such as AirDrop, or download it from a portal to the device. For more information, see Create mobile scene package.

To access the scenes in a mobile scene package:

  1. Confirm whether the mobile scene package file (.mspk) can be read directly or whether it needs to be unpacked into a directory.
  2. Construct the mobile scene package object from the (.mspk) file path, or the unpack directory, if necessary.

    self.mobileScenePackage = AGSMobileScenePackage(fileURL: theURL)

  3. Load the mobile scene package to access or display any of the scenes in the package. Each package can contain one or more scenes.
    self.mobileScenePackage.load {[weak self]  (error) -> Void in
     guard error == nil else {
      print(error!.localizedDescription)
      return
     }
     theScene = self?.mobileScenePackage.scenes[0]
    }

If you want to obtain or set any of the scene's properties before displaying it, then load the scene first using the loadable pattern. If not, then just pass the scene to the scene view and the scene will be loaded automatically.

Display a scene in a scene view

To display the scene, pass the AGSScene object to the AGSSceneView. This provides access to the scene, its layers and data, sets the camera's viewpoint on the scene, and enables a range of 3D navigation tools for your app users.

sceneView.scene = scene

Monitor scene drawing

The scene is redrawn whenever the user:

  • pans, rotates or zooms
  • a camera controller updates the camera
  • data is added or removed from the scene

You can add an observer to the AGSSceneView to detect these changes to the drawStatus.

//add observer for drawStatus on scene view
sceneView.addObserver(self, forKeyPath: "drawStatus", options: .new, context: nil)

...

override func observeValue(forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey : Any]?, context: UnsafeMutableRawPointer?) {      
 if self.sceneView.drawStatus == AGSDrawStatus.inProgress {           
  print("Drawing")
 }
}

Navigate the scene

The scene defines the initial viewpoint. Users can then navigate the scene using the mouse, keyboard or touch screen, as available. See Navigate a scene view to learn about the various interaction options and how to programmatically navigate the scene.

Configure the scene view

There are a number of important concepts to consider when configuring a scene view:

  • Camera controllers - define how navigation operates in the scene. For example, they can be used to follow a feature or graphic, or to orbit a specific location. To learn about camera controllers, see Follow a graphic in a scene view.
  • Lighting - you can set the ambient light color (ambientLightColor), specify whether there are shadows (sunLighting) and control the position of the sun by setting the date and time on the sunTime property
  • Atmosphere effect - defines how the sky looks. There are three observer effect options:
    • Realistic - There is an atmosphere effect applied to both the sky and the surface as viewed from above.
    • Horizon only - There is an atmosphere effect applied to the sky (horizon) only.
    • None - There is no atmosphere effect; anything that isn't a part of the scene is rendered black with a starfield consisting of randomly placed white dots.

    You can apply any of these options to the scene view's AtmosphereEffect property.

    Visualization of the scene atmosphere effect options, showing both zoomed in scenes and scenes as viewed from space

Filter data by time

Some layer types contain data that can be filtered by time values. Runtime has rich support for time-aware layers and data. See Visualize and compare data over time to learn more.