Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.mapping.view

Class SceneView

  • All Implemented Interfaces:
    SceneViewNavigation, Styleable, EventTarget, Skinnable
    public final class SceneView
extends GeoView
implements SceneViewNavigation
    A user interface control that displays three-dimensional (3D) geographic content defined by an ArcGISScene.

    To display an ArcGISScene, add a SceneView control to your app and assign the scene to it. This loads the scene, its Surface, Basemap and collection of operational layers, and displays their content on screen.

    User interactions such as pan, zoom, tilt, rotate, and identify or selection are supported in the SceneView using touch, mouse, keyboard or pen/pencil. If required, you can override keys, clicks, and gestures to provide a specific user experience.

    The visible area of the SceneView is represented by the Viewpoint. It is determined by a Camera object and a CameraController is used to enable or constrain user interaction.

    To zoom to a specific visible area, pass a Viewpoint to the GeoView.setViewpoint(Viewpoint) method. To zoom to the Viewpoint specified by a camera, pass the Camera to setViewpointCamera(Camera).

    To determine the current visible area, call GeoView.getCurrentViewpoint(Viewpoint.Type). Make sure that any user-initiated or programmatic navigation is complete before getting the current Viewpoint by calling GeoView.isNavigating().

    In an MVC architecture, this class represents the View tier. The Model tier is represented by the ArcGISScene object which provides a collection of operational layers, a Basemap and a Surface. A Layer provides a visual representation of geographic information and comes in many forms. The types of layers that are displayed in a SceneView are three-dimensional in nature; meaning they are displayed in X/Y/Z coordinate space.

    This class must only be created and used on the UI thread. 

     ArcGISScene scene = new ArcGISScene(BasemapStyle.ARCGIS_LIGHT_GRAY);
 SceneView sceneView = new SceneView();
 sceneView.setArcGISScene(scene);
    Since:
    100.0.0
    See Also:
    ArcGISScene

    • Constructor Detail

      • SceneView

        public SceneView()
        Creates a new scene view
        Since:
        100.0.0

    • Method Detail

      • setArcGISScene

        public void setArcGISScene​(ArcGISScene scene)
        Sets the scene that the SceneView is displaying.

        If you assign an ArcGISScene to a SceneView, the scene, its Surface, Basemap, and collection of operational layers automatically start to load. When loading completes, the layers and basemap are rendered over the Surface in the scene view.

        You can load an ArcGISScene into your app before you assign it to a SceneView by calling GeoModel.loadAsync(). This is useful if you want to validate the content of a scene before you display it.

        Parameters:
        scene - the scene that the SceneView is displaying
        Since:
        100.0.0

      • getArcGISScene

        public ArcGISScene getArcGISScene()
        Gets the ArcGISScene displayed in this view.
        Returns:
        the ArcGISScene
        Since:
        100.0.0

      • fieldOfViewProperty

        public ReadOnlyDoubleProperty fieldOfViewProperty()
        The horizontal field of view of the scene view in degrees.

        The value of the field of view is influenced by the size and orientation of the device screen. A landscape orientation has a larger field of view value than a portrait orientation.

        Since:
        200.0.0
        See Also:
        getFieldOfView()

      • getFieldOfView

        public double getFieldOfView()
        Gets the value of the property fieldOfView.
        Property description:
        The horizontal field of view of the scene view in degrees.

        The value of the field of view is influenced by the size and orientation of the device screen. A landscape orientation has a larger field of view value than a portrait orientation.

        Since:
        200.0.0

      • fieldOfViewDistortionRatioProperty

        public ReadOnlyDoubleProperty fieldOfViewDistortionRatioProperty()
        The ratio indicating how much the vertical field of view is distorted.

        A distortion factor less than 1.0 causes the visuals to be stretched taller in comparison to their width. A distortion factor greater than 1.0 causes the visuals to be shrunk shorter in comparison to their width.

        The default value is 1.0.

        Since:
        200.0.0
        See Also:
        getFieldOfViewDistortionRatio()

      • getFieldOfViewDistortionRatio

        public double getFieldOfViewDistortionRatio()
        Gets the value of the property fieldOfViewDistortionRatio.
        Property description:
        The ratio indicating how much the vertical field of view is distorted.

        A distortion factor less than 1.0 causes the visuals to be stretched taller in comparison to their width. A distortion factor greater than 1.0 causes the visuals to be shrunk shorter in comparison to their width.

        The default value is 1.0.

        Since:
        200.0.0

      • setViewpointCamera

        public void setViewpointCamera​(Camera camera)
        Animates the display to the viewpoint specified by the given camera.
        Specified by:
        setViewpointCamera in interface SceneViewNavigation
        Parameters:
        camera - the camera to set
        Throws:
        java.lang.IllegalArgumentException - if camera is null
        Since:
        100.0.0

      • setViewpointCameraAsync

        public ListenableFuture<java.lang.Boolean> setViewpointCameraAsync​(Camera camera)
        Animates the display to the viewpoint specified by the given camera.

        Use setViewpointCameraAsync(Camera, float) to set a viewpoint that animates over a specified duration.

        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Throws:
        java.lang.IllegalArgumentException - if the camera is null
        Since:
        100.0.0

      • setViewpointCameraAsync

        public ListenableFuture<java.lang.Boolean> setViewpointCameraAsync​(Camera camera,
                                                                   float durationSeconds)
        Animates the display to the viewpoint specified by the given camera using the specified duration to arrive.
        Parameters:
        camera - the new camera information for the scene view
        durationSeconds - the time for the transition animation to complete, in seconds
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Throws:
        java.lang.IllegalArgumentException - if the camera is null
        Since:
        100.0.0

      • getSpatialReference

        public SpatialReference getSpatialReference()
        Gets the spatial reference.
        Specified by:
        getSpatialReference in class GeoView
        Returns:
        the spatial reference, null if the ArcGISScene is null
        Since:
        100.0.0

      • getAmbientLightColor

        public Color getAmbientLightColor()
        Gets the value of the property ambientLightColor.
        Property description:
        The color of the scene view's ambient light.

        The ambient light is visible if the getSunLighting() is set to LightingMode.LIGHT or LightingMode.LIGHT_AND_SHADOWS.

        Attempting to set the color to null will throw an exception.

        Since:
        200.0.0

      • setAmbientLightColor

        public void setAmbientLightColor​(Color color)
        Sets the value of the property ambientLightColor.
        Property description:
        The color of the scene view's ambient light.

        The ambient light is visible if the getSunLighting() is set to LightingMode.LIGHT or LightingMode.LIGHT_AND_SHADOWS.

        Attempting to set the color to null will throw an exception.

        Since:
        200.0.0

      • setAmbientLightColor

        @Deprecated(since="200.0.0",
            forRemoval=true)
public void setAmbientLightColor​(int color)
        Deprecated, for removal: This API element is subject to removal in a future version.
        as of 200.0.0, replaced by setAmbientLightColor(Color)
        Sets the color of the ambient light.
        Parameters:
        color - the color of the ambient light, in 0xAARRGGBB format
        Since:
        100.0.0

      • setAtmosphereEffect

        public void setAtmosphereEffect​(AtmosphereEffect atmosphereEffect)
        Sets the effect to be applied to the scene view's atmosphere.
        Parameters:
        atmosphereEffect - the atmosphere effect
        Throws:
        java.lang.IllegalArgumentException - if atmosphereEffect is null
        Since:
        100.0.0

      • getAtmosphereEffect

        public AtmosphereEffect getAtmosphereEffect()
        Returns the atmosphere effect on the scene view.

        The default value is AtmosphereEffect.HORIZON_ONLY.

        Returns:
        the atmosphere effect on the scene view
        Since:
        100.0.0

      • setSunTime

        public void setSunTime​(java.util.Calendar sunTime)
        Sets the Date and Time that determine the position of the Sun in the sky.
        Parameters:
        sunTime - the Date and Time that determine the position of the Sun in the sky
        Throws:
        java.lang.IllegalArgumentException - if sunTime is null
        Since:
        100.0.0
        See Also:
        setSunLighting(com.esri.arcgisruntime.mapping.view.LightingMode)

      • getSunTime

        public java.util.Calendar getSunTime()
        Gets the Date and Time that determine the position of the Sun in the sky. Default is Fri Sep 22 2000 12:00:00 GMT+0000.
        Returns:
        the Date and Time that determine the position of the Sun in the sky
        Since:
        100.0.0

      • setSunLighting

        public void setSunLighting​(LightingMode lightingMode)
        Sets the type of sun lighting to be applied to the scene view. For example, this can be used to control whether the shadows of terrain and 3D models are cast.
        Parameters:
        lightingMode - the lighting mode to be applied for this scene view
        Throws:
        java.lang.IllegalArgumentException - if lightingMode is null
        Since:
        100.0.0
        See Also:
        setSunTime(java.util.Calendar)

      • getSunLighting

        public LightingMode getSunLighting()
        Returns the type of Sun lighting applied to the scene view.

        Default is LightingMode.NO_LIGHT.

        Returns:
        the type of Sun lighting
        Since:
        100.0.0

      • locationToScreen

        public LocationToScreenResult locationToScreen​(Point location)
        Converts a location in map coordinates to a point in JavaFX local coordinates relative to the upper-left corner of the scene view.

        The screen coordinates are in device-independent pixels (DIP) relative to the upper-left corner of the scene view at position 0,0. The LocationToScreenResult indicates whether the screen coordinates are visible in the scene view. They can be invisible if they are on the other side of the globe, not in the Viewpoint, or are blocked by the base surface or elevation layer.

        To call this method, assign a scene to the scene view, ensure that it is loaded and the draw status is DrawStatus.COMPLETED.

        Specified by:
        locationToScreen in interface SceneViewNavigation
        Parameters:
        location - a location defined within the spatial reference of the scene view
        Returns:
        the location to screen result
        Throws:
        java.lang.IllegalArgumentException - if location is null
        Since:
        100.0.0

      • screenToBaseSurface

        public Point screenToBaseSurface​(Point2D screenPoint)
        Converts the specified JavaFX local coordinate, relative to the upper-left corner of the scene view, to a location on the base surface in map coordinates.

        To call this method, assign a scene to the scene view, ensure that it is loaded and the draw status is DrawStatus.COMPLETED.

        Specified by:
        screenToBaseSurface in interface SceneViewNavigation
        Parameters:
        screenPoint - the JavaFX local coordinates
        Returns:
        the scene location on the base surface
        Throws:
        java.lang.IllegalArgumentException - if screenPoint is null
        Since:
        100.0.0

      • screenToLocationAsync

        public ListenableFuture<Point> screenToLocationAsync​(Point2D screenPoint)
        Asynchronously converts a screen coordinate relative to the upper-left corner of the scene view to a location in map coordinates.

        This is a high performance calculation executed on the GPU using a triangular mesh. Note that elevation values are approximated, and as the distance between the camera and the surface increases, the precision of the elevation value decreases.

        To call this method, assign a scene to the scene view, ensure that it is loaded and the draw status is DrawStatus.COMPLETED.

        Parameters:
        screenPoint - the JavaFX local coordinates
        Returns:
        a ListenableFuture. Add a listener to this to know when the result is ready. The result of the future is the location of the screen point.
        Throws:
        java.lang.IllegalArgumentException - if screenPoint is null
        Since:
        100.0.0

      • setCameraController

        public void setCameraController​(CameraController cameraController)
        Sets the camera controller manages the position, orientation, and movement of the camera for a SceneView.

        The controller handles user-interaction with the SceneView and updates the Camera. You can assign a CameraController with a specific navigation mode that is free roaming, following a moving target, fixed on a stationary target, or that supports AR transformation matrices. For more information, see CameraController.

        Parameters:
        cameraController - camera controller
        Throws:
        java.lang.IllegalArgumentException - if cameraController is null
        Since:
        100.1.0

      • getCameraController

        public CameraController getCameraController()
        Gets the camera controller manages the position, orientation, and movement of the camera for a SceneView.

        The controller handles user-interaction with the SceneView and updates the Camera. You can assign a CameraController with a specific navigation mode that is free roaming, following a moving target, fixed on a stationary target, or that supports AR transformation matrices. For more information, see CameraController.

        The default camera is the GlobeCameraController.

        Returns:
        the camera controller manages the position, orientation, and movement of the camera for a SceneView
        Since:
        100.1.0

      • getAnalysisOverlays

        public ListenableList<AnalysisOverlay> getAnalysisOverlays()
        Gets a modifiable list of analysis overlays that render the results of 3D visual analysis on the scene view.

        Dynamic 3D analyses, such as LineOfSight and Viewshed, generate visual results that are rendered on the scene view. To display the results, add the Analysis to a collection of AnalysisOverlay.getAnalyses() and then add the AnalysisOverlay to the collection of getAnalysisOverlays().

        Note that the SceneView.getAnalysisOverlays() collection can be empty but is never null. It's created for a specific SceneView so you can't reuse an AnalysisOverlay collection from another SceneView. Each AnalysisOverlay can only exist in one SceneView.getAnalysisOverlays() collection.

        Returns:
        a collection of analysis overlays that render the results of 3D visual analysis on the scene view
        Since:
        100.2.0

      • setSpaceEffect

        public void setSpaceEffect​(SpaceEffect spaceEffect)
        Sets the effect to be applied to the scene view's background.
        Parameters:
        spaceEffect - the space effect
        Throws:
        java.lang.IllegalArgumentException - if spaceEffect is null
        Since:
        100.6.0

      • getSpaceEffect

        public SpaceEffect getSpaceEffect()
        Gets the space effect on the scene view.

        The default value is SpaceEffect.STARS.

        Returns:
        the space effect on the scene view
        Since:
        100.6.0

      • getImageOverlays

        public java.util.List<ImageOverlay> getImageOverlays()
        Gets a modifiable list of overlays for displaying images in the scene view.

        An image overlay collection cannot belong to more than one SceneView. If the collection contains multiple image overlays, they display in the order in which they were added to the collection. So the first overlay in the collection (at index 0) displays at the bottom and each one that follows displays on top of the previous ones. If the SceneView also has a GraphicsOverlay, it displays on top of the ImageOverlay.

        Returns:
        the image overlays
        Since:
        100.8.0