Overview

A SceneView displays a 3D view of a Map or WebScene instance using WebGL. To render a map and its layers in 2D, see the documentation for MapView. For a general overview of views, see View.

For a map to be visible to the user in the DOM, a SceneView must have both a valid Map instance and a DOM element with a non-zero height and width in which to render. Note that there must be valid data in the map, such as operational layers or a basemap with base layers, before the view will begin rendering the map.

// Create a basic SceneView instance with a basemap and world elevationvar view = new SceneView({
// An instance of Map or WebScene
map: newMap({
basemap: "hybrid"
}),
// The id of a DOM element (may also be an actual DOM element)
container: "viewDiv"
});

Known Limitations

The number of features that can be rendered in a SceneView varies depending on the complexity of each feature's geometry and symbol. Layers with a large number of features are dynamically loaded and displayed as you navigate the scene. For optimal performance, the number of displayed features is adjusted based on the complexity of the symbol and device capability. As a result, some features may not be visible in the view.

Read more

Using the view

A SceneView may not be immediately ready for display after it has been constructed. For example, map data may need to be loaded first to determine the spatialReference of the view, or the DOM container may not yet have a non-zero size. Many of the view methods (such as hitTest or goTo) need the view to be ready before they can be used.

SceneView navigation

The view can be navigated programmatically via goTo() and the view properties or interactively with mouse, keyboard or touch inputs. SceneView navigation is enabled by defaults, and includes the mouse, keyboard and touch interactions as described in the table below. Touch interactions are working on any touch enabled monitor or laptop screen.

Action

SceneView behavior

Drag

Pan

Double-click

Zoom in at the cursor

Scroll forward

Zoom in at the cursor

Scroll backward

Zoom out at the center of the view

Right-click+Drag

3D-rotate around the center of the view

Arrow Keys

Nudge the view left, right, up, or down (only supported in global scene)

B + Left-click+Drag

3D-rotate around the camera's position

P

Move the camera to look perpendicular to the data displayed in the view

N

Adjust the SceneView to point north

J

Move down, closer to the view (only supported in global scene)

U

Move up, higher from the view (only supported in global scene)

Drag with one or multiple fingers

Pan

Double-tap with one finger

Zoom in at the finger position

Two finger pinch in/out

Zoom out/in

Move two fingers in clockwise or counterclockwise direction

Rotate

Drag two fingers up or down the screen

Tilt the scene

To disable SceneView navigation, you must call the stopPropagation() method on the event objects of the pointer or gesture events that trigger the navigation.

SceneView navigation with Gamepad and 3DConnexion devices

Gamepad and 3Dconnexion devices, like the SpaceMouse, can be used for navigation when view.navigation.gamepad.enabled is set to true(default). Please see GamepadInputDevice for supported devices.

Gamepad Action

SceneView behavior

Left Trigger

Descend

Right Trigger

Ascend

Left Stick

Pan

Right Stick

3D-rotate around the center of the view

Action Image

SpaceMouse Action

SceneView behavior

Push (left/right/forward/backward)

Pan

Pull up

Ascend

Push down

Descend

Rotate clockwise

Rotate the view clockwise

Rotate counterclockwise

Rotate the view counterclockwise

Tilt

Tilt the scene

To disable gamepad navigation, you can set view.navigation.gamepad.enabled to false.

Programmatic navigation

Traditional 2D mapping properties, such as scale, zoom, center and extent do not always work well in 3D. For example, a map's scale is not clear when viewed in the context of a globe. The SceneView therefore supports these properties on a best effort basis, with certain limitations (see the documentation of individual properties for more information).

// Compatibility with 2D viewing properties, such as center and zoom, allows// convenient transitioning from the familiar use of the 2D MapView to the// use of the SceneView for 3D viewing.var view = new SceneView({
map: newMap({
basemap: "satellite"
}),
container: "viewDiv",
// Sets the center point of the view at a specified lon/lat
center: [-112, 38],
// Sets the zoom LOD to 13
zoom: 13
});

The nature of 3D viewing includes oblique views, z-values, and rotation, all of which add complexity to defining what is visible in the view. In contrast to 2D MapView, which are primarily defined by an extent, or center and scale, the primary view specification of the SceneView is a Camera instance. The camera is defined by a 3D position, heading and tilt. See the documentation of Camera for more details.

Because some view properties overlap (e.g. center and camera), there is a set priority in which these properties are applied during construction of the view (until the view becomes ready). The following table describes which properties have priority during view construction (properties that are overridden will have no effect during construction).

It can be difficult to define the camera for viewing data at a particular location. The goTo method provides a convenient way to set the view's camera based on data (geometries, graphics) you want to view and from any perspective using heading, tilt, scale or zoom. Additionally, goTo will provide a smooth transition to the new location of the view by default.

Viewing modes

The SceneView supports two different viewing modes, global (left picture above) and local (right picture above), specified by the viewingMode property. Global scenes render the earth as a globe, while local scenes render the surface on a flat plane. Local mode allows for navigation and feature display in a localized or clipped area. In both viewing modes the users may navigate the camera below the ground surface by setting the esri/Ground#navigationConstraint#type to none.

The viewing mode (if not explicitly set by the user) is determined based on the spatial reference of the view. If the spatial reference is either Web Mercator or WGS84, then the viewingMode will default to global. For any other spatial reference the viewingMode will default to local.

Supported coordinate systems

The SceneView supports following coordinate systems in a global scene:

Noncached layers with any spatial reference since they will be reprojected to the scene spatial reference

Using elevation data

The SceneView will use elevation layers from the Map.ground as sources for elevation when rendering the ground surface. Similar to the basemap, the ground can be initialized with a well-known name, which creates it with a known set of elevation layers.

Allows the view to be partially or fully transparent when composited with the webpage elements behind it. This property can only be set once at construction time. When alpha compositing is enabled, web scenes are less performant. It's important to set this property to true only when you need to apply transparency on the view.

A convenience property used for defining the breakpoints on the height and width of the view. The sizes specified here determine the values of the widthBreakpoint and heightBreakpoint properties depending on the view's size.

Setting up breakpoints can aid in responsive app design. It does this by watching width and height breakpoints. This is helpful as it removes the need for multiple @media calls. Instead of listening for the view's size and/or resizes property, you can set up a watch handler for either the widthBreakpoint or heightBreakpoint properties of the view.

Please refer to the styling guide for additional information on working with this.

The observation point from which the visible portion (or perspective) of the SceneView is determined. Contains properties including the elevation, tilt, and heading (in degrees) of the current view. Setting the camera immediately changes the current view. For animating the view, see goTo().

The camera property contains an internal reference which may be modified in the future. To persist or modify the camera, create a clone using camera.clone().

Z-values defined in a geographic or metric coordinate system are expressed in meters. However, in local scenes that use a projected coordinate system, vertical units are assumed to be the same as the horizontal units specified by the service.

// Initializes the view at the given (x, y, z) position with a heading of 95 degrees.// The position of the camera is a Point which will autocast in the sample// below. Note that the default Point spatial reference is WGS84 which// will only work if the SceneView has a Web Mercator or WGS84 spatial// reference. For other spatial references, create a new position Point// with an explicit spatial reference.var view = new SceneView({
camera: {
position: [
-122, // lon38, // lat50000// elevation in meters
],
heading: 95
}
});

// Clone the camera to modify its propertiesvar camera = view.camera.clone();
// Set new values for heading and tilt
camera.heading = 180;
camera.tilt = 45;
// Set the new properties on the view's camera
view.camera = camera;

// Set the view's camera to a new position, heading and tilt with the goTo() method
view.goTo({
target: [-122, 38, 50000],
heading: 180,
tilt: 45
});

Represents the view's center point; when setting the center you may pass a Point instance or an array of numbers representing at longitude/latitude pair ([-100.4593, 36.9014]). Setting the center immediately changes the current view. For animating the view, see goTo().

If set in the constructor, this property will be ignored if the viewpoint, camera, or extent properties are also set in the constructor.

The center property contains an internal reference which may be modified in the future. To persist or modify the center, create a clone using center.clone().

Z-values defined in a geographic or metric coordinate system are expressed in meters. However, in local scenes that use a projected coordinate system, vertical units are assumed to be the same as the horizontal units specified by the service.

// view.center needs to be set (not modified in place) to have an effect.// To modify only the center.x, first clone the current center, modify// the .x property and then set it on the view.var center = view.center.clone();
// Offset the center 1km to the east
center.x += 1000;
view.center = center;

Specifies the mode of the constraint which is either auto or manual. In auto mode, the near and far clip distance values are automatically determined. In manual mode, the near and far clip distance values are user defined, constant values. Note that the mode automatically changes to manual whenever the near or far property is set.

Specifies the mode of the constraint. There are two possible values: auto or manual. In auto mode, the maximum tilt value is automatically determined based on the altitude of the view camera. In manual mode, the maximum tilt value is a user defined, constant value. Note: The mode automatically changes to manual whenever the max property is set.

Specifies how the background of the scene (which lies behind sky, stars and atmosphere) should be displayed. By default this is simply a single, fully opaque, black color. Currently ColorBackground is the only type of background supported.

The extent represents the visible portion of a map within the view as an instance of Extent. Setting the extent immediately changes the view without animation. To animate the view, see goTo().

Rather than using extent to change the visible portion of the map in a SceneView, you should use camera since it easily allows you to define the heading, elevation and tilt of the observation point from which the view's perspective is created.

When set in the constructor, this property overrides the center, scale, and zoom properties. This property will be ignored if the viewpoint or camera are also set in the constructor.

The extent property contains an internal reference which may be modified in the future. To persist or modify the extent, create a clone using extent.clone().

Z-values defined in a geographic or metric coordinate system are expressed in meters. However, in local scenes that use a projected coordinate system, vertical units are assumed to be the same as the horizontal units specified by the service.

A convenience property indicating the general size of the view's height. This value is determined based on where the view's height falls in the ranges defined in the breakpoints property. See the table below for a list of possible values. Use the breakpoints property to override the default thresholds.

Please refer to the styling guide for additional information on working with this.

Use the padding property to make the center, and extent, etc. work off a subsection of the full view. This is particularly useful when layering UI elements or semi-transparent content on top of portions of the view. See the view padding sample for an example of how this works.

A Popup object that displays general content or attributes from layers in the map.

The view has a default instance of Popup with predefined styles and a template for defining content. The content in this default instance may be modified directly in the popup's content or in a layer's PopupTemplate.

You may create a new Popup instance and set it to this property to customize the style, positioning, and content of the popup in favor of using the default popup instance on the view.

In addition, if wanting to prevent any popups from opening, use the syntax below:

SceneView can draw scenes in three different quality modes: high, medium and low.

The low quality profile significantly increases performance on slower browsers and devices by reducing the memory limit and the visual quality in the following aspects:

Map resolution

Scene layer detail level

Anti-aliasing (edge smoothing)

The high and medium quality profiles only differ in the maximum amount of memory which the view is allowed to use. A higher memory limit improves quality in complex web scenes with many layers, but can have a negative impact on drawing performance and stability.

The default value is based on the detected browser:

low for Internet Explorer 11 and certain mobile devices

medium for any other browser

Overriding the default value is best done in the constructor (see example below). If the value is modified after construction, only a subset of the quality aspects are affected.

When a view becomes ready it will resolve itself and invoke the callback defined in when() where code can execute on a working view. Subsequent changes to a view's readiness would typically be handled by watching view.ready and providing logic for cases where the map or container change.

The viewing mode (local or global). Global scenes render the earth as a sphere. Local scenes render the earth on a flat plane and allow for navigation and feature display in a localized or clipped area. Users may also navigate the camera of a local scene below the surface of a basemap.

Value

Example

Description

global

Global scenes allow the entire globe to render in the view, showing the curvature of the earth.

local

Local scenes render the earth on a flat surface. They can be constrained to only show a "local" area by setting the clippingArea property. Local scenes also allow for displaying and exploring data that would otherwise be hidden by the surface of the earth.

Represents the current view as a Viewpoint or point of observation on the view. In SceneViews, camera should be used in favor of viewpoint for watching or changing the point of view. Setting the viewpoint immediately changes the current view. For animating the view, see goTo().

When set in the constructor, this property overrides the extent, center, scale, and zoom properties. This property will be ignored if camera is also set in the constructor.

The viewpoint property contains an internal reference which may be modified in the future. To persist or modify the viewpoint, create a clone using viewpoint.clone().

A convenience property indicating the general size of the view's width. This value is determined based on where the view's width falls in the ranges defined in the breakpoints property. See the table below for a list of possible values. Use the breakpoints property to override the default thresholds.

Please refer to the styling guide for additional information on working with this.

Possible Value

Description

Default thresholds (pixels)

xsmall

The width of the view is smaller than the value set in the xsmallbreakpoint.

< 545

small

The width of the view is between the values set in the xsmall and smallbreakpoints.

545 - 768

medium

The width of the view is between the values set in the small and mediumbreakpoints.

769 - 992

large

The width of the view is between the values set in the medium and largebreakpoints.

Object with a combination of target, center, scale, position, heading and tilt properties (with target being any of the types listed above). The center property is provided as a convenience to animate the SceneView.center and is the equivalent of specifying the target with the center Point. The target must be provided in the spatial reference of the view.

This function returns a promise which resolves as soon as the new view has been set to the target. If the transition is animated, then the ongoing animation can be obtained using SceneView.animation.

If the given target is far away from the current camera position, then heading and tilt will be automatically set to their neutral values (facing north, looking top down). Tilt and heading can always be explicitly set to override this behavior.

Increases or decreases the animation speed by the specified factor. A speedFactor of 2 will make the animation twice as fast, while a speedFactor of 0.5 will make the animation half as fast. Setting the speed factor will automatically adapt the default maxDuration accordingly.

Set the exact duration (in milliseconds) of the animation. Note that by default, animation duration is calculated based on the time required to reach the target at a constant speed. Setting duration overrides the speedFactor option. Note that the resulting duration is still limited to the maxDuration.

The easing function to use for the animation. This may either be a preset (named) function, or a user specified function. Supported named presets are: linear, in-cubic, out-cubic, in-out-cubic, in-expo, out-expo, in-out-expo, in-out-coast-quadratic. See easing functions for graphical representations of these functions.

By default, animations that are less than 1000 ms use the out-expo easing function; longer animations use the in-out-coast-quadratic easing function.

// goTo returns a Promise which resolves when the animation has finished.// This promise may be chained to create a sequence of animations.
view.goTo(graphic1)
.then(function() {
return view.goTo(graphic2);
})
.then(function() {
return view.goTo(graphic3);
});

// goTo returns a Promise which resolves when the animation has finished.// This promise may be chained to create a sequence of animations.
view.goTo(graphic1)
.then(function() {
return view.goTo(graphic2);
})
.then(function() {
return view.goTo(graphic3);
});

hasEventListener()

Indicates whether there is an event listener on the instance that matches the provided event name.

Draped graphics (i.e. graphics in layers where the elevation mode is on-the-ground) are currently not returned from this method, even when they intersect the input screen point.

When the ground surface is hit, but no graphic is found, then the result of hitTest will be a single object with its mapPoint set to the point on the surface that was hit, but its graphic will be set to null.

Additional modifier keys to filter events. Please see Key Values for possible values. All the standard key values are supported. Alternatively, if no modifiers are required, the function will call when the event fires.

Create a screenshot of the current view. Screenshots include only elements that are rendered on the canvas (all geographical elements), but excludes overlayed DOM elements (UI, popups, measurement labels, etc.). By default, a screenshot of the whole view is created. Different options allow for creating different types of screenshots, including taking screenshots at different aspect ratios, different resolutions and creating thumbnails.

Screenshots are always taken inside the padded area of the view (see padding).

Specifies whether to take a screenshot of a specific area of the view. The area coordinates are relative to the origin of the padded view (see padding) and will be clipped to the view size. Defaults to the whole view (padding excluded).

// Take a screenshot at the same resolution of the current view
view.takeScreenshot().then(function(screenshot) {
var imageElement = document.getElementById("screenshotImage");
imageElement.src = screenshot.dataUrl;
});

when() may be leveraged once an instance of the class is created. This method takes two input parameters: a callback function and an errback function. The callback executes when the instance of the class loads. The errback executes if the instance of the class fails to load.

Returns a new promise for the result of callback that may be used to chain additional functions.

Example:

// Although this example uses MapView, any class instance that is a promise may use then() in the same wayvar view = new MapView();
view.when(function(){
// This function will execute once the promise is resolved
}, function(error){
// This function will execute if the promise is rejected due to an error
});

Gets the LayerView created on the view for the given layer. The returned promise resolves when the layer view for the given layer has been created, or rejects with an error (for example if the layer is not part of the view, or if the layer type is not supported in this view).

An array of result objects returned from the hitTest(). Results are returned when the location of the input screen coordinates intersect a Graphic in the view. See the table below for the specification of each object in this array.

A graphic present in the view that intersects the input screen coordinates. If the graphic comes from a layer with an applied Renderer, then the symbol property will be empty. Other properties will be empty based on the context in which the graphic is fetched.

Fires after a user clicks on the view. This event emits slightly slower than a pointer-down event to make sure that a double-click event isn't triggered instead. The immediate-click event can be used for responding to a click event without delay.

// Set up a click event handler and retrieve the screen point
view.on("click", function(event) {
// the hitTest() checks to see if any graphics in the view// intersect the given screen x, y coordinates
view.hitTest(event)
.then(getGraphics);
});

view.on("click", function(event) {
// you must overwrite default click-for-popup// behavior to display your own popup
view.popup.autoOpenEnabled = false;
// Get the coordinates of the click on the viewvar lat = Math.round(event.mapPoint.latitude * 1000) / 1000;
var lon = Math.round(event.mapPoint.longitude * 1000) / 1000;
view.popup.open({
// Set the popup's title to the coordinates of the location
title: "Reverse geocode: [" + lon + ", " + lat + "]",
location: event.mapPoint // Set the location of the popup to the clicked location
content: "This is a point of interest"// content displayed in the popup
});
});

view.on("hold", function(event) {
// The event object contains the mapPoint and the screen coordinates of the location// that was clicked.console.log("hold at screen point", event.x, event.y);
console.log("hold at map point", event.mapPoint);
});

Fires right after a user clicks on the view. In contrast to the click event, the immediate-click event is emitted as soon as the user clicks on the view, and is not inhibited by a double-click event. This event is useful for interactive experiences that require feedback without delay.

// Set up an immediate-click event handler and retrieve the screen point
view.on("immediate-click", function(event) {
// the hitTest() checks to see if any graphics in the view// intersect the given screen x, y coordinates
view.hitTest(event)
.then(getGraphics);
});

// This function fires each time a layer view is created for a layer in// the map of the view.
view.on("layerview-create", function(event) {
// The event contains the layer and its layer view that has just been// created. Here we check for the creation of a layer view for a layer with// a specific id, and log the layer viewif (event.layer.id === "satellite") {
// The LayerView for the desired layerconsole.log(event.layerView);
}
});