require(["esri/WebScene"], function(WebScene) { /* code goes here */ });
Class: esri/WebScene
Inheritance: WebScene Map Accessor
Since: ArcGIS API for JavaScript 4.0

The web scene is the core element of 3D mapping across the ArcGIS platform. It defines the content, style, environment, and slides of your scene and it can be shared across multiple ArcGIS web and desktop applications. Web scenes can be created, published, and consumed in ArcGIS Pro and ArcGIS Online with the Scene Viewer. The web scene is saved as a JSON document that can be consumed by the ArcGIS API for JavaScript via the WebScene class to easily create compelling 3D applications. The JSON document is written according to the web scene specification.

Although you can easily create your own scenes, there are thousands of publicly available web scenes in ArcGIS Online that you can use to get started with the API. You may modify or add new content to these scenes.

To load a WebScene into a SceneView, you need to simply reference the ID of the web scene item in ArcGIS Online via the portalItem property of this class.

var scene = new WebScene({
  // autocasts as esri/portal/PortalItem
  portalItem: {
    id: "affa021c51944b5694132b2d61fe1057"  // ID of the WebScene on arcgis.com
  }
});

To load a WebScene from an on-premise portal, set the portal url in esriConfig.portalurl.

esriConfig.portalUrl = "https://myHostName.esri.com/arcgis";

var scene = new WebScene({
  // autocasts as esri/portal/PortalItem
  portalItem: {
    id: "0614ea1f9dd043e9ba157b9c20d3c538"  // ID of the WebScene on the on-premise portal
  }
});

Then you must reference the WebScene instance in the map property of a SceneView.

var view = new SceneView({
  map: scene,  // The WebScene instance created above
  container: "viewDiv"
});

This will start loading all layers and scene options into the 3D SceneView. The when() method on the WebScene instance can be called to execute processes that may only run after the WebScene is loaded.

scene.when(function() {
  // All layers and the basemap have been created
});
view.when(function() {
  // All layer and basemap resources have been loaded and are ready to be displayed
});

webscene

The WebScene defines the content of your scene and how the scene looks when it is loaded in your application. There are several common properties of a web scene that you will likely interact with when using this class:

  • Layers: defines the content and styling of the web scene, as well as popups, labels, legend and other settings.
  • Basemap: defines the basemap layers of the web scene.
  • Ground: defines the elevation layers of the web scene.
  • Presentation: contains the web scene slides.
  • InitialViewProperties
    • Environment: configures lighting, shadows and atmosphere of the scene.
    • Viewpoint: configures the initial viewpoint.
    • ViewingMode: defines if the web scene is global or local.

For more information on properties of a web scene, please consult the web scene specification.

There are two types of web scenes: global or local. Global scenes render the earth as a sphere while Local scenes render the earth on a flat plane. Global web scenes can be created with a WebMercator or GCS WGS84 spatial reference, while local web scenes can be created with any projected coordinate system. Read the ArcGIS Online help to learn more about choosing global or local scenes.

Slides store a snapshot of a visualization state of the scene that can be re-applied to the scene at a later time. Slides contain properties for viewpoint, layer visibilities, basemap and environment (as well as a title and thumbnail) so that users of a 3D application can easily navigate the scene and accurately recreate a stored view of that scene.

Web scenes can be saved to ArcGIS Online or Portal using saveAs() or save(). Define the portal and once it is loaded, save the web scene.

var portal = new Portal({
  url: "http://myportal.arcgis.com/", // the url of the portal
  authMode: "immediate" // user authenticates by signing in when the Portal is loaded
});
// once the portal is loaded save the web scene to the portal as a new web scene
portal.load().then(function() {
  webscene.saveAs({
    title: "My Scene",
    portal: portal
  })
  .then(function() {
    console.log("Scene was saved");
  })
  .catch(function(err) {
    console.log(err);
  });
})

It's important to note that GraphicsLayer, ImageryLayer and StreamLayer can't be saved to a web scene. A cached image service can be saved to a web scene, by declaring it as a TileLayer. An OpenStreetMapLayer can be saved as a baseLayer. For more information on types of layers that can be saved in a web scene, see the web scene specification.

See also:

Constructors

new WebScene(properties)
Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Example:
// Typical usage
var map = new WebScene({
  portalItem: {
    id: "affa021c51944b5694132b2d61fe1057"
  }
});

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
Collection<Layer>

A flat collection of all the layers in the map.

more details
more detailsMap
ApplicationProperties

Configuration of application and UI elements.

more details
more detailsWebScene
Basemap

Specifies a basemap for the map.

more details
more detailsMap
Extent

This property only applies to local scenes.

more details
more detailsWebScene
Boolean

This property only applies to local scenes.

more details
more detailsWebScene
String

The name of the class.

more details
more detailsAccessor
Ground

Specifies the surface properties for the map.

more details
more detailsMap
HeightModelInfo

The height model info of the WebScene.

more details
more detailsWebScene
InitialViewProperties

The initial view of the WebScene.

more details
more detailsWebScene
Collection<Layer>

A collection of operational layers.

more details
more detailsMap
Boolean

Indicates whether the instance has loaded.

more details
more detailsWebScene
Error

The Error object returned if an error occurred while loading.

more details
more detailsWebScene
String

Represents the status of a load operation.

more details
more detailsWebScene
PortalItem

The portal item from which the WebScene is loaded.

more details
more detailsWebScene
Presentation

Provides a Collection of slides that act as bookmarks for saving predefined viewpoints and visible layers.

more details
more detailsWebScene
Object

The version of the source document from which the WebScene was read.

more details
more detailsWebScene
String

The URL to the thumbnail used for the web scene.

more details
more detailsWebScene

Property Details

allLayersCollection<Layer>readonly inherited

A flat collection of all the layers in the map. This collection contains basemap layers, operational layers and ground layers. Group Layers and their children layers are also part of this collection. Reference layers in the basemap will always be included at the end of the collection.

Layers should not be added directly to this collection. They must only be added via the layers, basemap or ground properties.

Example:
// Find a layer with title "US Counties"
var foundLayer = map.allLayers.find(function(layer) {
 return layer.title === "US Counties";
});

// Create a filtered collection of the non-group layers
var nonGroupLayers = map.allLayers.filter(function(layer) {
 return !foundLayer.layers;
});

// Listen for any layer being added or removed in the Map
map.allLayers.on("change", function(event) {
 console.log("Layer added: ", event.added);
 console.log("Layer removed: ", event.removed);
 console.log("Layer moved: ", event.moved);
});
applicationPropertiesApplicationProperties
Since: ArcGIS API for JavaScript 4.7

Configuration of application and UI elements.

Autocasts from String|Object

Specifies a basemap for the map. The basemap is a set of tile layers that give geographic context to the MapView or SceneView and the other operational layers in the map.

This value can be an instance of Basemap or one of the strings listed in the table below.

ValueDescription
streetsbasemap-streets
satellitebasemap-satellite
hybridbasemap-hybrid
topobasemap-topo
graybasemap-gray
dark-graybasemap-dark-gray
oceansbasemap-oceans
national-geographicbasemap-national-geographic
terrainbasemap-terrain
osmbasemap-osm
dark-gray-vectordark-gray-vector
gray-vectorgray-vector
streets-vectorstreets-vector
topo-vectortopo-vector
streets-night-vectorstreets-night-vector
streets-relief-vectorstreets-relief-vector
streets-navigation-vectorstreets-navigation-vector
Example:
// Set the basemap in the constructor
var map = new Map({
  basemap: "streets"
});

// Set the basemap after the map instance is created
map.basemap = "topo";
clippingAreaExtentautocast

This property only applies to local scenes. Represents an optional clipping area used to define the bounds or Extent of a local scene. If defined, only data (including the basemap) within the area will be displayed.

Set the clippingEnabled property to true to apply the specified clippingArea to the view.

See also:
clippingEnabledBoolean

This property only applies to local scenes. Determines whether clipping using the clippingArea is enabled.

Default Value:false
See also:
declaredClassStringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

Autocasts from String|Object

Specifies the surface properties for the map. This property is only relevant when adding the map to a 3D SceneView. It renders the terrain or topographical variations in the real world on the map's surface with a collection of ElevationLayer.

This value can be an instance of Ground, or one of the following strings:

  • world-elevation for a default instance of ground using the Terrain3D Service.
  • world-topobathymetry for an instance of ground that combines surface elevation and bathymetry using the TopoBathy3D Service.

The ground may not be set to null or undefined, it is guaranteed to always contain an instance of type Ground. The elevation can be removed from the ground by setting the ground property to a new empty Ground instance or by removing all the ground layers.

See also:
Examples:
// Use the world elevation service
var map = new Map({
  basemap: "topo",
  ground: "world-elevation"
});
// Create a map with the world elevation layer overlaid by a custom elevation layer
var worldElevation = ElevationLayer({
  url: "//elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"
});
var customElevation = ElevationLayer({
  url: "https://my.server.com/arcgis/rest/service/MyElevationService/ImageServer"
});
var map = new Map({
  basemap: "topo",
  ground: new Ground({
   layers: [ worldElevation, customElevation ]
  })
});
Since: ArcGIS API for JavaScript 4.5

The height model info of the WebScene. This object defines the characteristics of the vertical coordinate system used by the scene. In a SceneView, the height model info is used to avoid combining layers that have incompatible vertical coordinate systems.

initialViewPropertiesInitialViewPropertiesautocast

The initial view of the WebScene. This object contains properties such as viewpoint, spatialReference, viewingMode, and environment that should be applied to the SceneView when the scene loads.

Autocasts from Layer[]

A collection of operational layers. This property only contains interactive operational layers, such as FeatureLayers, WebTileLayers and GraphicsLayers that may be queried, assigned different renderers, analyzed, etc. It does not include basemaps.

A layer is a collection of one or more features, or graphics, that represent real-world phenomena. Each feature contains a symbol and geographic data that allows it to be rendered on the map as a graphic with spatial context. Features within the layer may also contain data attributes that provide additional information that may be viewed in popup windows and used for rendering the layer.

Layers may be added in the constructor, with the add() or addMany() methods, or directly to the layers collection using add() or addMany().

A layer may only be added to one parent. Adding the same layer to multiple Maps or GroupLayers is not possible. If you attempt to do so, the layer will automatically be removed from its current parent and placed in the new parent.

var layer = new GraphicsLayer();
// The layer belongs to map1
map1.layers.add(layer);
// The layer now belongs to map2
// and implicitly does: map1.layers.remove(layer)
map2.layers.add(layer);
Example:
// Add layers in the constructor of Map using an array
var fl = new FeatureLayer(url);
var gl = new GraphicsLayer();
var map = new Map({
  layers: [fl, gl]
});

// Add layers using add()
map.addMany([fl, gl]);

// Add layers using layers collection
map.layers.addMany([fl, gl]);
loadedBooleanreadonly

Indicates whether the instance has loaded. When true, the properties of the object can be accessed. A WebScene is considered loaded when its layers and basemap are fully created, but not yet loaded.

Default Value:false
loadErrorErrorreadonly

The Error object returned if an error occurred while loading.

Default Value:null
loadStatusStringreadonly

Represents the status of a load operation.

ValueDescription
not-loadedThe object's resources have not loaded.
loadingThe object's resources are currently loading.
loadedThe object's resources have loaded without errors.
failedThe object's resources failed to load. See loadError for more details.
Default Value:not-loaded

The portal item from which the WebScene is loaded.

Provides a Collection of slides that act as bookmarks for saving predefined viewpoints and visible layers.

See also:
sourceVersionObjectreadonly
Since: ArcGIS API for JavaScript 4.1

The version of the source document from which the WebScene was read. The WebScene must be version 1.x to load into an app.

Properties:
major Number

The major version of the WebScene.

minor Number

The minor version of the WebScene.

thumbnailUrlString
Since: ArcGIS API for JavaScript 4.9

The URL to the thumbnail used for the web scene. The thumbnail will by default be the thumbnail URL from the portal item associated to the web scene. The thumbnail of the web scene may be updated by changing the thumbnail URL and saving the web scene. Use #updateFrom to update the thumbnail automatically from a specified view.

Example:
scene.updateFrom(view)
  .then(function() {
    return scene.save();
  })
  .then(function(portalItem) {
    console.log("Saved to portal", portalItem.id);
  })
  .catch(function(error) {
    console.error("Error saving to portal", error);
  });

Method Overview

NameReturn TypeSummaryClass

Adds a layer to the layers collection.

more details
more detailsMap

Adds a layer or an array of layers to the layers collection.

more details
more detailsMap
Layer

Returns a layer based on the given layer id.

more details
more detailsMap
*

Creates a new instance of this class and initializes it with values from a JSON object generated from a product in the ArcGIS platform.

more details
more detailsWebScene
Boolean

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected).

more details
more detailsWebScene
Boolean

isRejected() may be used to verify if creating an instance of the class is rejected.

more details
more detailsWebScene
Boolean

isResolved() may be used to verify if creating an instance of the class is resolved.

more details
more detailsWebScene
Promise

Triggers the loading of the WebScene instance.

more details
more detailsWebScene
Promise<WebScene>

Loads all the externally loadable resources associated with the webscene.

more details
more detailsWebScene
Layer

Removes the specified layer from the layers collection.

more details
more detailsMap
Layer[]

Removes all layers.

more details
more detailsMap
Layer[]

Removes the specified layers.

more details
more detailsMap
Layer

Changes the layer order.

more details
more detailsMap
Promise<PortalItem>

Saves the webscene to its associated portal item.

more details
more detailsWebScene
Promise<PortalItem>

Saves the webscene to a new portal item.

more details
more detailsWebScene
Object

Converts an instance of this class to its ArcGIS portal JSON representation.

more details
more detailsWebScene
Promise

Update properties of the WebScene related to the view.

more details
more detailsWebScene
Promise

when() may be leveraged once an instance of the class is created.

more details
more detailsWebScene

Method Details

add(layer, index)inherited

Adds a layer to the layers collection.

Parameters:

Layer or a Promise<Layer> to be added to the layers collection.

index Number
optional

A layer can be added at a specified index in the layers collection. If no index is specified or the index specified is greater than the current number of layers, the layer is automatically appended to the list of layers in the layers collection and the index is normalized.

addMany(layers, index)inherited

Adds a layer or an array of layers to the layers collection.

Parameters:
layers Layer[]

Layer(s) to be added to the layers collection.

index Number
optional

A layer can be added at a specified index in the layers collection. If no index is specified or the index specified is greater than the current number of layers, the layer is automatically appended to the list of layers in the layers collection and the index is normalized.

findLayerById(layerId){Layer}inherited

Returns a layer based on the given layer id.

Parameter:
layerId String

The ID assigned to the layer.

Returns:
TypeDescription
LayerReturns the requested layer object.
fromJSON(json){*}static

Creates a new instance of this class and initializes it with values from a JSON object generated from a product in the ArcGIS platform. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. If the WebScene is used outside of a view, you must call load() explicitly to interact with its resources. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameter:
json Object

A JSON representation of the instance in the ArcGIS format. See the web scene specification for more detailed information on serializing web scenes to JSON.

Returns:
TypeDescription
*Returns a new instance of this class.
Example:
// Retrieve a WebScene JSON by url and deserialize it into a WebScene API instance
require(["esri/request", "esri/WebScene"], function(esriRequest, WebScene) {
  esriRequest("http://domain/url/to/webscene.json").then(function(json) {
    var scene = WebScene.fromJSON(json);

    var view = new SceneView({
      map: scene,
      container: "viewDiv"
    });
  });
});
isFulfilled(){Boolean}

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected). If it is fulfilled, true will be returned.

Returns:
TypeDescription
BooleanIndicates whether creating an instance of the class has been fulfilled (either resolved or rejected).
isRejected(){Boolean}

isRejected() may be used to verify if creating an instance of the class is rejected. If it is rejected, true will be returned.

Returns:
TypeDescription
BooleanIndicates whether creating an instance of the class has been rejected.
isResolved(){Boolean}

isResolved() may be used to verify if creating an instance of the class is resolved. If it is resolved, true will be returned.

Returns:
TypeDescription
BooleanIndicates whether creating an instance of the class has been resolved.
load(){Promise}

Triggers the loading of the WebScene instance.

A WebScene is considered loaded when its operational layers, basemap and ground are fully created. When created with a portalItem, load() will first fetch its data to create the content, otherwise it resolves immediately.

The SceneView automatically calls the load() method when a WebScene instance is added to its map property so it can display in the view and load each individual layer. If the WebScene is used outside of a view, for example to preload it, you must call load() explicitly to interact with its resources.

Returns:
TypeDescription
PromiseResolves when the WebScene is loaded.
See also:
Example:
// programmatically load all the layers
require([
  "esri/WebScene",

  "dojo/promise/all"
], function(
  WebScene,
  all
) {

  var scene = new WebScene({
    portalItem: {
      id: "affa021c51944b5694132b2d61fe1057"
    }
  });

  scene.load()
    .then(function() {
      // load the basemap to get its layers created
      return scene.basemap.load();
    })
    .then(function() {
      // grab all the layers and load them
      var allLayers = scene.allLayers;
      var promises = allLayers.map(function(layer) {
        return layer.load();
      });
      return all(promises.toArray());
    })
    .then(function(layers) {
      // each layer load promise resolves with the layer
      console.log("all " + layers.length + " layers loaded");
    })
    .catch(function(error) {
      console.error(error);
    });
});
loadAll(){Promise<WebScene>}
Since: ArcGIS API for JavaScript 4.9

Loads all the externally loadable resources associated with the webscene. For the webscene this will load the ground, basemap, layers and slide basemaps.

Returns:
TypeDescription
Promise<WebScene>Resolves when all the loadable resources have been loaded.
See also:
remove(layer){Layer}inherited

Removes the specified layer from the layers collection.

Parameter:
layer Layer

Layer to remove from the layers collection.

Returns:
TypeDescription
LayerReturns the layer removed from the layers collection.
removeAll(){Layer[]}inherited

Removes all layers.

Returns:
TypeDescription
Layer[]Returns the layers removed from the layers collection.
removeMany(layers){Layer[]}inherited

Removes the specified layers.

Parameter:
layers Layer[]

Array of layers to remove from the layers collection.

Returns:
TypeDescription
Layer[]Returns the layers removed from the layers collection.
reorder(layer, index){Layer}inherited

Changes the layer order. The first layer added is always the base layer, even if its order is changed.

Parameters:
layer Layer

The layer to be moved.

index Number

The index location for placing the layer. The bottom-most layer has an index of 0.

Returns:
TypeDescription
LayerReturns the layer that was moved.
save(options){Promise<PortalItem>}
Since: ArcGIS API for JavaScript 4.1

Saves the webscene to its associated portal item. The portal item to save to must already exist and be valid. This is a convenience method that will use PortalItem to store the webscene in the item. The web scene is saved according to web scene specification standards.

Use updateFrom to store the current view properties in the webscene before saving it.

Note that this saves the webscene to its existing item. Depending on how the scene is shared, users that do not own the scene may modify it. To save an existing scene as a new item owned by the user signed into the portal instance, use saveAs().

The webscene will be automatically loaded if it is not already before saving.

Parameters:
options Object
optional

Additional options.

Specification:
ignoreUnsupported Boolean
optional

When true, the scene will save even if it contains unsupported content (layers, renderers, symbols). Any content that is not supported will not be saved and the scene may appear different when reloaded from its portal item.

Returns:
TypeDescription
Promise<PortalItem>A promise that resolves with the PortalItem instance when the item has successfully been saved, or rejects otherwise.
See also:
saveAs(portalItem, options){Promise<PortalItem>}
Since: ArcGIS API for JavaScript 4.1

Saves the webscene to a new portal item. If saving has completed successfully, then the saved portal item will be set in the portalItem property of the WebScene. This is a convenience method that will create a new PortalItem and use PortalUser.addItem() to store the webscene in a Portal.

Use updateFrom to store the current view properties in the webscene before saving it.

Note that this always saves the webscene as a new portal item owned by the user performing the edits and executing the saveAs() method. If you want to modify the existing item without changing its ownership use save().

The webscene will be automatically loaded if it is not already before saving.

Parameters:
portalItem PortalItem autocast
Autocasts from Object

The new portal item to which the scene will be saved.

Portal item properties such as the title or description need to be explicitly set on the item and will not be automatically copied from the current associated scene portal item (if any).

options Object
optional

additional save options.

Specification:
optional

the folder in which to save the item.

ignoreUnsupported Boolean
optional

allow the scene to be saved even in the case it contains unsupported content (layers, renderers, symbols). Any content that is not supported will not be saved and the scene may appear different when reloaded from its portal item.

Returns:
TypeDescription
Promise<PortalItem>a promise that resolves with the PortalItem instance when the item has successfully been saved, or rejects otherwise.
See also:
Example:
var scene = new Webscene();
scene.saveAs({
  // autocasts as new PortalItem()
  title: "New WebScene"
});
toJSON(){Object}

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() topic in the Guide and the web scene specification for more information.

Returns:
TypeDescription
ObjectThe ArcGIS portal JSON representation of an instance of this class.
updateFrom(view, options){Promise}

Update properties of the WebScene related to the view. This should usually be called just before saving a scene. The following properties are updated from the view:

  1. initialViewProperties.spatialReference
  2. initialViewProperties.viewingMode
  3. clippingArea
  4. heightModelInfo

Depending on the provided options, the following properties are also updated:

  1. initialViewProperties.environment
  2. initialViewProperties.viewpoint
  3. thumbnail
Parameters:

the view to update from.

options Object
optional

update options.

Parameters:
environmentExcluded Boolean
optional

do not update the initial environment from the view, defaults to false.

viewpointExcluded Boolean
optional

do not update the initial viewpoint from the view, defaults to false.

thumbnailExcluded Boolean
optional

do not update the thumbnail from the view, defaults to viewpointExcluded.

thumbnailSize Object
optional

the size of the thumbnail. Defaults to 600x400 (ratio 1.5:1). Note that the thumbnail size may currently not be larger than the size of the view.

Specification:
width Number

the width of the thumbnail.

height Number

the height of the thumbnail.

Returns:
TypeDescription
PromiseResolves when the update has completed.
See also:
when(callback, errback){Promise}
Since: ArcGIS API for JavaScript 4.6

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.

Parameters:
callback Function
optional

The function to call when the promise resolves.

errback Function
optional

The function to execute when the promise fails.

Returns:
TypeDescription
PromiseReturns 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 way
var 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
});

API Reference search results

NameTypeModule
Loading...