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

Class OrbitGeoElementCameraController

java.lang.Object
com.esri.arcgisruntime.mapping.view.CameraController
com.esri.arcgisruntime.mapping.view.OrbitGeoElementCameraController
public final class OrbitGeoElementCameraController extends CameraController
Support Orbital Camera navigation around a stationary or moving point GeoElement object.

Interactions on the scene view will pivot the camera around the target so that the camera is always looking at the target. The camera will move with a relative position to a target. When active, setting the viewpoint on the scene view will be disabled.

Since:
100.1.0
See Also:

  • Constructor Details

    • OrbitGeoElementCameraController

      public OrbitGeoElementCameraController(GeoElement targetGeoElement, double cameraDistance)
      Creates an orbit geo-element camera controller given a target geo-element, and camera's distance from target.

      An Orbit camera controller is used to associate camera navigation and movement with a GeoElement point object. This can take the form of a Graphic, a Feature, or a DynamicEntity. When the controller is set on the Scene View using SceneView.setCameraController(CameraController) the interaction mode will change for the active navigation model to be focused on the input GeoElement allowing the user to rotate around and zoom in and out from the object. For a moving GeoElement the camera will move in synchronization with it. Adjust its position, heading, pitch and roll with the object by simply changing the object with no requirement to change the camera.

      Parameters:
      targetGeoElement - target geo-element for the camera to follow and look at
      cameraDistance - distance between the camera and the target, in meters
      Throws:
      IllegalArgumentException - if targetGeoElement is null
      IllegalArgumentException - if cameraDistance is zero or less
      Since:
      100.1.0

  • Method Details

    • getTargetGeoElement

      public GeoElement getTargetGeoElement()
      Gets the target geo-element for the camera to follow and look at.

      When the target moves, the camera will move with the target to maintain its relative position. To update the target's heading, pitch, and roll, use a Renderer and the GeoElement's attributes.

      The target GeoElement can represent either a point Graphic, a point Feature, or a point DynamicEntity. The target determines the focal point of the camera managed by the orbit camera controller.

      Returns:
      the target geo-element for the camera to follow and look at
      Since:
      100.1.0

    • moveCameraAsync

      public ListenableFuture<Boolean> moveCameraAsync(double deltaDistance, double deltaHeadingOffset, double deltaPitchOffset, float duration)
      Moves the camera to a new offset position with the specified duration.
      Parameters:
      deltaDistance - the change in distance to apply in the animation, in meters
      deltaHeadingOffset - the change in heading to apply in the animation, in degrees
      deltaPitchOffset - the change in pitch to apply in the animation, in degrees
      duration - the duration of the animation, 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
      Since:
      100.1.0

    • setTargetOffsetsAsync

      public ListenableFuture<Boolean> setTargetOffsetsAsync(double x, double y, double z, float duration)
      Moves the camera to focus on target's location offset by specified values.

      By default the camera focuses on the target's geometry center point. Using the offsets you can move the focal point to a new position relative to that center point.

      Parameters:
      x - offset along x-axis, in meters
      y - offset along y-axis, in meters
      z - offset along z-axis, in meters
      duration - the duration of the animation, 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
      Since:
      100.1.0

    • setCameraDistance

      public void setCameraDistance(double distance)
      Sets the distance between the camera and the target. The camera position is derived from this distance plus the camera offsets.
      Parameters:
      distance - distance between the camera and the target, in meters
      Throws:
      IllegalArgumentException - if distance is zero or less
      Since:
      100.1.0

    • getCameraDistance

      public double getCameraDistance()
      Gets the distance between the camera and the target.
      Returns:
      the distance between the camera and the target, in meters
      Since:
      100.1.0

    • setCameraHeadingOffset

      public void setCameraHeadingOffset(double headingOffset)
      Sets the clockwise angle in the target symbol's horizontal plane starting directly behind the symbol. The default value is 0 degrees.

      If the headingOffset is not between minCameraHeadingOffset and maxCameraHeadingOffset, it will be normalized as follows:

      1. if headingOffset < minCameraHeadingOffset, then 360 will be added to headingOffset until the new value is above minCameraHeadingOffset. If the new value is less than maxCameraHeadingOffset, it will be used. Otherwise, the new value will be set to minCameraHeadingOffset.
      2. if headingOffset > maxCameraHeadingOffset, then 360 will be subtracted from headingOffset until the new value is below maxCameraHeadingOffset. If the new value is greater than minCameraHeadingOffset, it will be used. Otherwise, the new value will be set to maxCameraHeadingOffset.
      Parameters:
      headingOffset - camera heading offset, in degrees
      Since:
      100.1.0

    • getCameraHeadingOffset

      public double getCameraHeadingOffset()
      Gets the camera heading offset. The default value is 0 degrees.

      The return value can be different than what was set. See setCameraHeadingOffset(double) for details.

      Returns:
      the camera heading offset, in degrees
      Since:
      100.1.0

    • setCameraPitchOffset

      public void setCameraPitchOffset(double pitchOffset)
      Sets anti-clockwise angle from the positive z-axis of the target's symbol to the symbol's horizontal plane. The default value is 45 degrees.

      The value will be clamped to minCameraPitchOffset and maxCameraPitchOffset.

      Parameters:
      pitchOffset - camera pitch offset, in degrees
      Since:
      100.1.0

    • getCameraPitchOffset

      public double getCameraPitchOffset()
      Gets the camera pitch offset. The default value is 45 degrees.

      The value is clamped to minCameraPitchOffset and maxCameraPitchOffset.

      Returns:
      the camera pitch offset, in degrees
      Since:
      100.1.0

    • setMinCameraDistance

      public void setMinCameraDistance(double minDistance)
      Sets the minimum distance from the camera to the target.

      Must be greater than 0. Defaults to 0. Animations and interactions are bounded by this limit.

      Parameters:
      minDistance - the minimum distance from the camera to the target, in meters
      Throws:
      IllegalArgumentException - if minDistance is negative
      Since:
      100.1.0

    • getMinCameraDistance

      public double getMinCameraDistance()
      Gets the minimum distance from the camera to the target.

      Must be greater than 0. Defaults to 0. Animations and interactions are bounded by this limit.

      Returns:
      the minimum distance between the camera and the target, in meters
      Since:
      100.1.0

    • setMaxCameraDistance

      public void setMaxCameraDistance(double maxDistance)
      Sets the maximum distance from the camera to the target.

      Animations and interactions are bounded by this distance. The default value is Double.MAX_VALUE meters.

      Parameters:
      maxDistance - the minimum distance from the camera to the target, in meters
      Throws:
      IllegalArgumentException - if maxDistance is negative
      Since:
      100.1.0

    • getMaxCameraDistance

      public double getMaxCameraDistance()
      Gets the maximum distance from the camera to the target.

      Animations and interactions are bounded by this distance. The default value is Double.MAX_VALUE meters.

      Returns:
      the maximum distance between the camera and the target, in meters
      Since:
      100.1.0

    • setMinCameraHeadingOffset

      public void setMinCameraHeadingOffset(double minHeadingOffset)
      Sets the minimum camera heading offset. Interactions and animations are limited by this. The default value is -180 degrees.
      Parameters:
      minHeadingOffset - the minimum camera heading offset, in degrees
      Since:
      100.1.0

    • getMinCameraHeadingOffset

      public double getMinCameraHeadingOffset()
      Gets the minimum camera heading offset. Interactions and animations are limited by this. The default value is -180 degrees.
      Returns:
      the minimum camera heading offset, in degrees
      Since:
      100.1.0

    • setMaxCameraHeadingOffset

      public void setMaxCameraHeadingOffset(double maxHeadingOffset)
      Sets the maximum camera heading offset. Interactions and animations are limited by this. The default value is 180 degrees.
      Parameters:
      maxHeadingOffset - the maximum camera heading offset, in degrees
      Since:
      100.1.0

    • getMaxCameraHeadingOffset

      public double getMaxCameraHeadingOffset()
      Gets the maximum camera heading offset. Interactions and animations are limited by this. The default value is 180 degrees.
      Returns:
      the maximum camera heading offset, in degrees
      Since:
      100.1.0

    • setMinCameraPitchOffset

      public void setMinCameraPitchOffset(double minPitchOffset)
      Sets the minimum camera pitch offset. Interactions and animations are limited by this. The default value is 0 degrees.
      Parameters:
      minPitchOffset - the minimum camera pitch offset, in degrees
      Since:
      100.1.0

    • getMinCameraPitchOffset

      public double getMinCameraPitchOffset()
      Gets the minimum camera pitch offset. Interactions and animations are limited by this. The default value is 0 degrees.
      Returns:
      the minimum camera pitch offset, in degrees
      Since:
      100.1.0

    • setMaxCameraPitchOffset

      public void setMaxCameraPitchOffset(double maxPitchOffset)
      Sets the maximum camera pitch offset. Interactions and animations are limited by this. The default value is 180 degrees.
      Parameters:
      maxPitchOffset - the maximum camera pitch offset, in degrees
      Since:
      100.1.0

    • getMaxCameraPitchOffset

      public double getMaxCameraPitchOffset()
      Gets the maximum camera pitch offset. Interactions and animations are limited by this. The default value is 180 degrees.
      Returns:
      the maximum camera pitch offset, in degrees
      Since:
      100.1.0

    • setCameraDistanceInteractive

      public void setCameraDistanceInteractive(boolean distanceInteractive)
      Sets whether a zoom interaction can affect the camera distance. The default value is true.
      Parameters:
      distanceInteractive - true to let a zoom interaction affect the camera distance, otherwise false
      Since:
      100.1.0

    • isCameraDistanceInteractive

      public boolean isCameraDistanceInteractive()
      Gets whether a zoom interaction can affect the camera distance. The default value is true.

      When enabled, the user can interactively change the distance between the camera and the target object.

      Returns:
      true if a zoom interaction affect the camera distance, otherwise false
      Since:
      100.1.0

    • setCameraHeadingOffsetInteractive

      public void setCameraHeadingOffsetInteractive(boolean headingOffsetInteractive)
      Sets whether a horizontal pan interaction can affect the camera heading offset. The default value is true.
      Parameters:
      headingOffsetInteractive - true to let a horizontal pan interaction affect the camera heading offset, otherwise false
      Since:
      100.1.0

    • isCameraHeadingOffsetInteractive

      public boolean isCameraHeadingOffsetInteractive()
      Gets whether a horizontal pan interaction can affect the camera heading offset. The default value is true.

      When interactive heading is enabled, the user is able to manually change the relative heading between the target focal point and the camera.

      Returns:
      true if a horizontal pan interaction affect the camera heading offset, otherwise false
      Since:
      100.1.0

    • setCameraPitchOffsetInteractive

      public void setCameraPitchOffsetInteractive(boolean pitchOffsetInteractive)
      Sets whether a vertical pan interaction can affect the camera pitch offset. The default value is true.
      Parameters:
      pitchOffsetInteractive - true to let a vertical pan interaction affect the camera pitch offset, otherwise false
      Since:
      100.1.0

    • isCameraPitchOffsetInteractive

      public boolean isCameraPitchOffsetInteractive()
      Gets whether a vertical pan interaction can affect the camera pitch offset. The default value is true.

      When interactive pitch is enabled the user is able to manually change the relative pitch between the target focal point and the camera.

      Returns:
      true if a vertical pan interaction affect the camera pitch offset, otherwise false
      Since:
      100.1.0

    • setAutoHeadingEnabled

      public void setAutoHeadingEnabled(boolean autoHeadingEnabled)
      Determines if CameraHeadingOffset is updated with target's heading.

      If true, the camera will maintain its heading offset when the target's heading changes. Defaults to true. The graphic's heading can be controlled using an expression in the renderer class.

      Parameters:
      autoHeadingEnabled - determines if CameraHeadingOffset is updated with target's heading
      Since:
      100.1.0
      See Also:

    • isAutoHeadingEnabled

      public boolean isAutoHeadingEnabled()
      Determines if CameraHeadingOffset is updated with target's heading.

      If true, the camera will maintain its heading offset when the target's heading changes. Defaults to true. The graphic's heading can be controlled using an expression in the renderer class.

      Returns:
      determines if CameraHeadingOffset is updated with target's heading
      Since:
      100.1.0
      See Also:

    • setAutoPitchEnabled

      public void setAutoPitchEnabled(boolean autoPitchEnabled)
      Determines if CameraPitchOffset is updated with target's pitch.

      If true, the camera will maintain its pitch offset when the target's pitch changes. Defaults to true. The graphic's pitch can be controlled using an expression in the renderer class.

      Parameters:
      autoPitchEnabled - determines if CameraPitchOffset is updated with target's pitch
      Since:
      100.1.0
      See Also:

    • isAutoPitchEnabled

      public boolean isAutoPitchEnabled()
      Determines if CameraPitchOffset is updated with target's pitch.

      If true, the camera will maintain its pitch offset when the target's pitch changes. Defaults to true. The graphic's pitch can be controlled using an expression in the renderer class.

      Returns:
      determines if CameraPitchOffset is updated with target's pitch
      Since:
      100.1.0
      See Also:

    • setAutoRollEnabled

      public void setAutoRollEnabled(boolean autoRollEnabled)
      Determines if CameraRollOffset is updated with target's roll.

      If true, the camera will maintain its roll offset when the target's roll changes. Defaults to true. The graphic's roll can be controlled using an expression in the renderer class.

      Parameters:
      autoRollEnabled - determines if CameraRollOffset is updated with target's roll
      Since:
      100.1.0
      See Also:

    • isAutoRollEnabled

      public boolean isAutoRollEnabled()
      Determines if CameraRollOffset is updated with target's roll.

      If true, the camera will maintain its roll offset when the target's roll changes. Defaults to true. The graphic's roll can be controlled using an expression in the renderer class.

      Returns:
      determines if CameraRollOffset is updated with target's roll
      Since:
      100.1.0
      See Also:

    • setTargetOffsetX

      public void setTargetOffsetX(double targetOffsetX)
      The X offset of the target focus point relative to the target object in the x-axis in the symbol coordinate system. The default value is 0.

      Setting the offsets for the target allows the user to move the focal point from the target's geometry to any point on the symbol.

      Parameters:
      targetOffsetX - target offset along x-axis, in meters
      Since:
      100.1.0
      See Also:

    • getTargetOffsetX

      public double getTargetOffsetX()
      The X offset of the target focus point relative to the target object in the x-axis in the symbol coordinate system. The default value is 0.

      Setting the offsets for the target allows the user to move the focal point from the target's geometry to any point on the symbol.

      Returns:
      the target offset along x-axis, in meters
      Since:
      100.1.0
      See Also:

    • setTargetOffsetY

      public void setTargetOffsetY(double targetOffsetY)
      The Y Offset of the target focus point relative to the target object in the Y axis in the symbol coordinate system. The default value is 0.

      Setting the offsets for the target focus point relative to the target object in the y-axis in the symbol coordinate system.

      Parameters:
      targetOffsetY - target offset along y-axis, in meters
      Since:
      100.1.0
      See Also:

    • getTargetOffsetY

      public double getTargetOffsetY()
      The Y Offset of the target focus point relative to the target object in the Y axis in the symbol coordinate system. The default value is 0.

      Setting the offsets for the target focus point relative to the target object in the y-axis in the symbol coordinate system.

      Returns:
      the target offset along y-axis, in meters
      Since:
      100.1.0
      See Also:

    • setTargetOffsetZ

      public void setTargetOffsetZ(double targetOffsetZ)
      Sets the target offset along z-axis. The default value is 0.
      Parameters:
      targetOffsetZ - target offset along z-axis, in meters
      Since:
      100.1.0

    • getTargetOffsetZ

      public double getTargetOffsetZ()
      The Z Offset of the target focus point relative the target object in the z-axis in the symbol coordinate system.

      Setting the offsets for the target allows the user to move the focal point from the target's geometry to any point on the symbol.

      Returns:
      the target offset along z-axis, in meters
      Since:
      100.1.0

    • setTargetVerticalScreenFactor

      public void setTargetVerticalScreenFactor(float verticalFactor)
      Sets the vertical position of the target on the screen. Allowed values are 0 (bottom of screen) to 1 (top). Defaults to 0.5 (centered vertically).
      Parameters:
      verticalFactor - the vertical position of the target on the screen
      Throws:
      IllegalArgumentException - if verticalFactor is less than 0 or greater than 1
      Since:
      100.1.0

    • getTargetVerticalScreenFactor

      public float getTargetVerticalScreenFactor()
      Gets the vertical position of the target on the screen. Allowed values are 0 (bottom of screen) to 1 (top). Defaults to 0.5 (centered vertically).
      Returns:
      the vertical position of the target on the screen
      Since:
      100.1.0

    • addCameraDistanceChangedListener

      public void addCameraDistanceChangedListener(CameraDistanceChangedListener<OrbitGeoElementCameraController> listener)
      Adds a listener for when distance between camera and target has changed.
      Parameters:
      listener - the listener
      Throws:
      IllegalArgumentException - if the listener is null
      Since:
      100.1.0

    • removeCameraDistanceChangedListener

      public boolean removeCameraDistanceChangedListener(CameraDistanceChangedListener<OrbitGeoElementCameraController> listener)
      Removes a camera distance changed listener.
      Parameters:
      listener - the listener
      Returns:
      true if successful, otherwise false
      Since:
      100.1.0

    • addCameraHeadingOffsetChangedListener

      public void addCameraHeadingOffsetChangedListener(CameraHeadingOffsetChangedListener<OrbitGeoElementCameraController> listener)
      Adds a listener for when camera heading offset has changed.
      Parameters:
      listener - the listener
      Throws:
      IllegalArgumentException - if the listener is null
      Since:
      100.1.0

    • removeCameraHeadingOffsetChangedListener

      public boolean removeCameraHeadingOffsetChangedListener(CameraHeadingOffsetChangedListener<OrbitGeoElementCameraController> listener)
      Removes a camera heading offset changed listener.
      Parameters:
      listener - the listener
      Returns:
      true if successful, otherwise false
      Since:
      100.1.0

    • addCameraPitchOffsetChangedListener

      public void addCameraPitchOffsetChangedListener(CameraPitchOffsetChangedListener<OrbitGeoElementCameraController> listener)
      Adds a listener for when camera pitch offset has changed.
      Parameters:
      listener - the listener
      Throws:
      IllegalArgumentException - if the listener is null
      Since:
      100.1.0

    • removeCameraPitchOffsetChangedListener

      public boolean removeCameraPitchOffsetChangedListener(CameraPitchOffsetChangedListener<OrbitGeoElementCameraController> listener)
      Removes a camera pitch offset changed listener.
      Parameters:
      listener - the listener
      Returns:
      true if successful, otherwise false
      Since:
      100.1.0