Class ArcGISScene

java.lang.Object
com.esri.arcgisruntime.mapping.GeoModel
com.esri.arcgisruntime.mapping.ArcGISScene
All Implemented Interfaces:
Loadable

public final class ArcGISScene extends GeoModel
A scene is a container for layers. You use a scene together with a SceneView to display layers of geographic data in 3D.

ArcGISScene contains layers of mapping data and information such as elevation data, renderers, and labels which define the scene's capabilities. You can access ArcGISScene content directly or, more commonly, visualize the scene in a SceneView.

In an MVC architecture, ArcGISScene represents the model and SceneView represents the 3D view. ArcGISScene specifies how the geographic data is organized, and SceneView renders the data on the screen and allows users to interact with it.

A scene can contain a base surface, a basemap, and one or more operational layers:

  • A base surface is the default surface on which layers are draped or from which relative layers are offset. The ground height is provided by ElevationSource objects that are combined to make the Surface.
  • A basemap is a layer that helps orient the user of the scene. It is composed of a collection of base layers, such as imagery or hillshade, that are draped on the surface, and/or reference layers such as street labels that are displayed on top of operational layers. This content is relatively static.
  • An operational layer provides content that is of unique interest to the app and the task at hand, such as data about earthquakes, traffic, or weather. This content can change frequently.
You can create a scene from an existing web scene using its URL or PortalItem. Alternatively, you can get a scene directly from a MobileScenePackage.getScenes() collection. ArcGISScene properties are hydrated when the scene is loaded.

If you create a new scene, the spatial reference of the first layer you add, which is typically the first layer in the Basemap, defines the spatial reference of the entire scene.

See Scenes 3D for more information about scenes.

Since:
100.0.0
See Also:
  • Constructor Details

    • ArcGISScene

      public ArcGISScene()
      Creates an empty ArcGISScene instance.
      Since:
      100.0.0
      See Also:
    • ArcGISScene

      public ArcGISScene(Basemap basemap)
      Creates an ArcGISScene instance which will contain just a Basemap.
      Parameters:
      basemap - the Basemap used with this ArcGISScene
      Throws:
      IllegalArgumentException - if the basemap is null
      Since:
      100.0.0
      See Also:
    • ArcGISScene

      public ArcGISScene(Basemap basemap, Surface baseSurface)
      Creates an ArcGISScene instance which will contain a basemap and a base surface.
      Parameters:
      basemap - the Basemap used with this ArcGISScene
      baseSurface - the Surface to use as the base surface of this scene
      Throws:
      IllegalArgumentException - if the basemap is null
      IllegalArgumentException - if the base surface is null
      Since:
      100.0.0
      See Also:
    • ArcGISScene

      public ArcGISScene(ArcGISScene.SceneViewTilingScheme sceneViewTilingScheme)
      Creates a scene with a specific tiling scheme.

      The tiling scheme determines which cached tiled services can render in the scene.

      Parameters:
      sceneViewTilingScheme - the tiling scheme for tiled layers
      Throws:
      IllegalArgumentException - if the sceneViewTilingScheme is null
      Since:
      100.2.1
    • ArcGISScene

      public ArcGISScene(PortalItem portalItem)
      Creates a scene with a portal item of type PortalItem.Type.WEB_SCENE.

      The PortalItem automatically loads when the ArcGISScene loads. If the loaded PortalItem is not a portal item of type Type.WEB_SCENE, the scene fails to load.

      Parameters:
      portalItem - the web scene PortalItem
      Throws:
      IllegalArgumentException - if the portalItem is null
      Since:
      100.3.0
      See Also:
    • ArcGISScene

      public ArcGISScene(String webSceneUrl)
      Creates a scene with the URL to a web scene.

      If the specified URL is a portal item URL, the underlying PortalItem is created and can be accessed through GeoModel.getItem(). The URL may be a direct URL to web scene JSON content or the URL of a portal item.

      Examples of supported URL formats:

      • The web scene viewer page, for example: https://www.arcgis.com/home/webscene/viewer.html?webscene=579f97b2f3b94d4a8e48a5f140a6639b
      • The web scene item details page, for example: https://www.arcgis.com/home/item.html?id=579f97b2f3b94d4a8e48a5f140a6639b
      • The REST sharing API data, for example: https://www.arcgis.com/sharing/rest/content/items/579f97b2f3b94d4a8e48a5f140a6639b/data
      • The REST sharing API page (with or without the query parameter f=json), for example: https://www.arcgis.com/sharing/rest/content/items/579f97b2f3b94d4a8e48a5f140a6639b?f=json.
      Parameters:
      webSceneUrl - URL of the web scene on ArcGIS Online or ArcGIS Enterprise portal
      Throws:
      IllegalArgumentException - if the URL is null or empty
      IllegalArgumentException - if the URL does not match the basic URL types
      Since:
      100.3.0
      See Also:
    • ArcGISScene

      public ArcGISScene(BasemapStyle basemapStyle)
      Creates an ArcGISScene from a BasemapStyle.

      These basemaps are secured and access requires either an ArcGISRuntimeEnvironment.setApiKey(String) or a named user.

      Parameters:
      basemapStyle - a basemap style
      Throws:
      IllegalArgumentException - if basemapStyle is null
      Since:
      100.10.0
  • Method Details

    • copy

      public ArcGISScene copy()
      Creates a copy of this ArcGISScene instance.
      Returns:
      a deep copy of this ArcGISScene instance, which means that copies of all fields of this scene are made including its loading state.
      Since:
      100.13.0
    • fromJson

      public static ArcGISScene fromJson(String json)
      Creates an ArcGISScene instance from a JSON string.
      Parameters:
      json - the JSON representation of an ArcGISScene
      Returns:
      an ArcGISScene instance deserialized from the JSON string
      Throws:
      IllegalArgumentException - if json is null or empty
      Since:
      100.3.0
    • getUnknownJson

      public Map<String,Object> getUnknownJson()
      Gets unknown data from the source JSON.

      Unknown JSON is a Map of values not defined in the ArcGIS web scene specification used to create this object but found in the source JSON. If the object is written back to JSON, any unknown JSON data is not persisted.

      Returns:
      an unmodifiable Map containing unknown data from the source JSON
      Since:
      100.3.0
    • getUnsupportedJson

      public Map<String,Object> getUnsupportedJson()
      Gets unsupported data from the source JSON.

      Unsupported JSON is a Map of values defined in the ArcGIS web scene specification used to create this object but not currently used in this API. If the object is written back to JSON, any unsupported JSON data is persisted.

      Returns:
      an unmodifiable Map containing unsupported data from the source JSON
      Since:
      100.3.0
    • setBaseSurface

      public void setBaseSurface(Surface baseSurface)
      Sets the base surface of this ArcGISScene.

      The base surface is the default surface on which layers are draped or from which relative layers are offset.

      Parameters:
      baseSurface - the base surface of this ArcGISScene
      Throws:
      IllegalArgumentException - if baseSurface is null
      Since:
      100.0.0
      See Also:
    • getBaseSurface

      public Surface getBaseSurface()
      Gets the base surface of this ArcGISScene.

      The base surface is the default surface on which layers are draped or from which relative layers are offset.

      Returns:
      the scene's base surface with a new surface
      Since:
      100.0.0
      See Also:
    • getSceneViewTilingScheme

      public ArcGISScene.SceneViewTilingScheme getSceneViewTilingScheme()
      Gets the tiling scheme, which defines how tile based data is rendered.

      The tiling scheme property is used by the SceneView to determine how to render tiled data.

      This property is determined during GeoModel.loadAsync(). The SpatialReference of the first tiled elevation source (ArcGISTiledElevationSource) or tiled layer in the basemap or operational layer (see ArcGISTiledLayer) determines whether the value is ArcGISScene.SceneViewTilingScheme.GEOGRAPHIC or ArcGISScene.SceneViewTilingScheme.WEB_MERCATOR.

      If you create a new scene, you can set this value before adding the base surface, basemap or operational layers. The ArcGISScene.SceneViewTilingScheme must correspond to the SpatialReference of the layers to ensure they render correctly.

      The default value is SceneViewTilingScheme.WEB_MERCATOR.

      Returns:
      the tiling scheme to use for tiled layers
      Since:
      100.2.1
    • addBasemapChangedListener

      public void addBasemapChangedListener(ArcGISScene.BasemapChangedListener listener)
      Adds a BasemapChangedListener to this ArcGISScene that gets invoked when the Basemap has changed.

      Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

      Parameters:
      listener - a BasemapChangedListener that gets invoked when the Basemap has changed
      Throws:
      IllegalArgumentException - if the listener is null
      Since:
      100.0.0
    • removeBasemapChangedListener

      public boolean removeBasemapChangedListener(ArcGISScene.BasemapChangedListener listener)
      Removes a BasemapChangedListener from this ArcGISScene.
      Parameters:
      listener - the BasemapChangedListener to remove
      Returns:
      true if the BasemapChangedListener has been removed, otherwise false
      Throws:
      IllegalArgumentException - if the listener is null
      Since:
      100.0.0