Introduction to scenes (3D)

The Scene component is used to display a scene and handle user interactions, popups, and the viewpoint in 3D space.

Creating a map for a scene

Scenes are created from the Map or WebScene class and displayed using the Scene component. To display maps in 2D, use the Map component.

Create a scene from a web scene

One way to create a scene is to load a web scene (for 3D scenes) or a web map (for 2D maps).

Web scenes and web maps are JSON structures that contain settings for a scene or a map. This includes settings for the basemap, layers, layer styling, popups, legends, labels, and more. They are typically created interactively with the ArcGIS Online Scene Viewer or the ArcGIS Online Map Viewer. ArcGIS Online or ArcGIS Enterprise stores them as portal items that can be referenced by a unique item ID.

You can load a web scene by referencing its item ID in the item-id attribute of the Scene component:

1
<arcgis-scene item-id="3a9976baef9240ab8645ee25c7e9c096"></arcgis-scene>

You can also access web scene and web map properties in JavaScript with the WebScene and WebMap classes. To render a scene in JavaScript, set the web scene instance to the map property of arcgis-scene.

When the WebScene object is loaded, all of the settings are automatically applied to the Scene component's map. For example, the basemap and layers are set, the layer styles are applied, and the popups are defined for each layer.

1
2
3
4
5
6
7
8
9
10
11
12
13
// import the webscene class
const WebScene = await $arcgis.import("@arcgis/core/WebScene.js");
// get the Scene component from HTML
const sceneElement = document.querySelector("arcgis-scene");
// create the webscene and set it on the Scene component
const webScene = new WebScene({
  // Define the web scene reference
  portalItem: {
    id: "3a9976baef9240ab8645ee25c7e9c096",
    portal: "https://www.arcgis.com", // Default: The ArcGIS Online Portal
  },
});
sceneElement.map = webScene;

Create a new scene from scratch

The second way to create a scene is to start from scratch with a basemap, ground and optionally a collection of layers.

The basemap attribute can be set from a named ID on the Scene component in HTML, the same with ground:

1
<arcgis-scene basemap="topo-3d" ground="world-elevation"></arcgis-scene>

Or a new instance of the Map class can be created and set on the Scene component in JavaScript:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<arcgis-scene></arcgis-scene>

<script type="module">
  // import the Scene class
  const Map = await $arcgis.import("@arcgis/core/Map.js");
  // get the Scene component from HTML
  const sceneElement = document.querySelector("arcgis-scene");

  // create the map and set it on the Scene component
  const myMap = new Map({
    basemap: "topo-3d",
    ground: "world-elevation",
    layers: additionalLayers, // Optionally, add additional layers collection
  });
  sceneElement.map = myMap;
</script>

Working with the Scene component

The primary role of the Scene component is to display layers, popups, and other components, handle user interactions, and to specify which portion of the world the scene should be focused on (i.e. the extent of the scene).

Set the visible portion of the scene

The initial camera view for the scene can be set by setting the camera attribute when the Scene component is created. The camera view can also be updated after it is initialized by updating the properties programmatically.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// set the zoom and center as attributes on the map component
<arcgis-scene
  basemap="satellite"
  ground="world-elevation"
  camera-position="12.3808, 46.3959, 4400"
  camera-tilt="75"
  camera-heading="300">
</arcgis-scene>

<script type="module">
  const sceneElement = document.querySelector("arcgis-scene");

  // change the tilt property programmatically
  sceneElement.tilt = 50;
</script>

Animate the view to a new position

The goTo method also changes the location of the scene and provides the additional option to transition to that location smoothly. This technique is often used to "fly" from one location to another on the surface or to zoom to results of a search.

The goTo method can accept a Geometry, Graphic, Viewpoint, or Camera object. Additional options can control the animation.

1
2
3
4
5
6
7
8
9
10
11
12
13
<arcgis-scene item-id="3a9976baef9240ab8645ee25c7e9c096"></arcgis-scene>

<script type="module">
  const sceneElement = document.querySelector("arcgis-scene");
  // wait for the view to be ready
  await sceneElement.viewOnReady();

  sceneElement.goTo(
    // go to point with a custom animation duration
    { target: feature, tilt: 70, heading: 350 },
    { duration: 5000 },
  );
</script>

Interacting with the scene

The Scene component is also responsible for handling user interaction and displaying popups. The component provides multiple events for user interactions such as mouse clicks, keyboard input, touch screen interactions, joysticks, and other input devices.

When a user clicks on the scene, the default behavior is to show any popups that have been pre-configured in your layers. This behavior can also be approximated manually with the following code by listening for the arcgisViewClick event and using the hitTest() method to find features where the user clicked.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
sceneElement.popupEnabled = false; // Disable the default popup behavior

sceneElement.addEventListener("arcgisViewClick", (event) => {
  // Listen for the click event
  sceneElement.hitTest(event.detail).then((hitTestResults) => {
    // Search for features where the user clicked
    if (hitTestResults.results) {
      sceneElement.openPopup({
        // open a popup to show some of the results
        location: event.detail.mapPoint,
        title: "Hit Test Results",
        content: hitTestResults.results.length + "Features Found",
      });
    }
  });
});

Adding UI components to the Scene

The Scene component is also a container for overlaying components and HTML Elements. It contains many named slots for placing components and elements in the view, such as "top-right" or "bottom-left".

The code snippet below demonstrates adding a component that allows users to search for an address or place.

1
2
3
4
<arcgis-scene item-id="3a9976baef9240ab8645ee25c7e9c096">
  // search component will be placed in the top right slot of the map
  <arcgis-search slot="top-right"></arcgis-search>
</arcgis-scene>