Class OrbitLocationCameraController

java.lang.Object
com.esri.arcgisruntime.mapping.view.CameraController
com.esri.arcgisruntime.mapping.view.OrbitLocationCameraController

public final class OrbitLocationCameraController extends CameraController
A camera controller that supports orbital camera navigation around a stationary point in a SceneView.

An orbit camera controller locks navigation around a target point. The camera can orbit around the target point but always focuses directly on the point. To activate the controller, use SceneView.setCameraController(CameraController) to set the controller. Once applied, the target point cannot be changed and setting the viewpoint on the SceneView is disabled. In this mode, the user can rotate around and zoom in and out from the target point.

Since:
100.1.0
See Also:
  • Constructor Details

    • OrbitLocationCameraController

      public OrbitLocationCameraController(Point targetLocation, double cameraDistance)
      Creates an orbit camera controller object with the given target point and distance from that point.

      The orbit camera controller locks navigation around a target point. When this camera controller is applied, using SceneView.setCameraController(CameraController), navigation interaction always focuses on the target point object. In this mode, the user can rotate around and zoom in and out from the point. Once specified, the target point cannot be changed.

      Parameters:
      targetLocation - the Point for the camera to focus on
      cameraDistance - distance from the point at which the camera will be placed
      Throws:
      IllegalArgumentException - if targetLocation is null
      IllegalArgumentException - if cameraDistance is zero or less
      Since:
      100.1.0
    • OrbitLocationCameraController

      public OrbitLocationCameraController(Point targetLocation, Point cameraLocation)
      The orbit camera controller calculates the distance of the camera from the target point and locks navigation around that target point. When this camera controller is applied, using SceneView.setCameraController(CameraController), navigation interaction always focuses on the target point object. In this mode, the user can rotate around and zoom in and out from the point. Once specified, the target point cannot be changed.
      Parameters:
      targetLocation - a Point which will be the focus of the camera
      cameraLocation - location of the camera
      Throws:
      IllegalArgumentException - if targetLocation or cameraLocation are null
      Since:
      100.3.0
  • Method Details

    • moveCameraAsync

      public ListenableFuture<Boolean> moveCameraAsync(double deltaDistance, double deltaHeadingOffset, double deltaPitchOffset, float duration)
      Animates the camera to a new offset position relative to the target with the specified duration.

      The heading and pitch delta values may be greater than 360 degrees and the angle is not normalized. For example, a heading delta of 720 will make the camera do two circles around the target within the duration time.

      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 Future used to check whether the animation completed successfully
      Since:
      100.1.0
    • setCameraDistance

      public void setCameraDistance(double distance)
      Sets the distance from the camera to the getTargetLocation(), in meters.

      The camera position and orientation is derived from this distance plus any 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 from the camera to the getTargetLocation(), in meters.

      The camera position and orientation is derived from this distance plus any camera offsets.

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

      public void setCameraHeadingOffset(double headingOffset)
      Sets the heading of the camera relative to the getTargetLocation(), in degrees.

      The clockwise angle in the horizontal plane of the OrbitLocationCameraController.getTargetLocation() starting from due south. Any angle in degrees is valid and will automatically be normalized between -180 to 180. Defaults to 0 degrees.

      Parameters:
      headingOffset - camera heading offset, in degrees
      Since:
      100.1.0
    • getCameraHeadingOffset

      public double getCameraHeadingOffset()
      Gets the heading of the camera relative to the getTargetLocation(), in 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 the pitch of the camera relative to the getTargetLocation(), in degrees.

      The anti-clockwise angle from the positive Z axis through the target location to the target's horizontal plane. Any angle in degrees is valid and will automatically be normalized between 0 and 180. Defaults to 45 degrees.

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

      public double getCameraPitchOffset()
      Gets the pitch of the camera relative to the getTargetLocation(), in degrees.

      The anti-clockwise angle from the positive Z axis through the target location to the target's horizontal plane. Any angle in degrees is valid and will automatically be normalized between 0 and 180. Defaults to 45 degrees.

      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 getTargetLocation(), in meters.

      The value cannot be negative. Serves as the minimum value for getCameraDistance(). Animations and interactions obey this limit.

      Defaults to 0.

      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 getTargetLocation(), in meters.

      The value cannot be negative. Serves as the minimum value for getCameraDistance(). Animations and interactions obey this limit.

      Defaults to 0.

      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 getTargetLocation(), in meters.

      The value must be greater than getMinCameraDistance(). Serves as the maximum value for getCameraDistance(). Animations and interactions obey this limit.

      No limit on this maximum 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 getTargetLocation(), in meters.

      The value must be greater than getMinCameraDistance(). Serves as the maximum value for getCameraDistance(). Animations and interactions obey this limit.

      No limit on this maximum 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 relative to the getTargetLocation(), in degrees.

      The value must be less than getMaxCameraHeadingOffset(). Serves as the minimum value for getCameraHeadingOffset(). Animations and interactions obey this limit.

      Defaults to -180.

      Parameters:
      minHeadingOffset - the minimum heading offset, in degrees
      Since:
      100.1.0
    • getMinCameraHeadingOffset

      public double getMinCameraHeadingOffset()
      Gets the minimum camera heading offset relative to the getTargetLocation(), in degrees.

      The value must be less than getMaxCameraHeadingOffset(). Serves as the minimum value for getCameraHeadingOffset(). Animations and interactions obey this limit.

      Defaults to -180.

      Returns:
      the minimum camera heading offset, in degrees
      Since:
      100.1.0
    • setMaxCameraHeadingOffset

      public void setMaxCameraHeadingOffset(double maxHeadingOffset)
      Sets the maximum camera heading offset relative to the getTargetLocation(), in degrees.

      The value must be greater than getMinCameraHeadingOffset(). Serves as the maximum value for getCameraHeadingOffset(). Animations and interactions obey this limit.

      Defaults to 180.

      Parameters:
      maxHeadingOffset - the maximum camera heading offset, in degrees
      Since:
      100.1.0
    • getMaxCameraHeadingOffset

      public double getMaxCameraHeadingOffset()
      Gets the maximum camera heading offset relative to the getTargetLocation(), in degrees.

      The value must be greater than getMinCameraHeadingOffset(). Serves as the maximum value for getCameraHeadingOffset(). Animations and interactions obey this limit.

      Defaults to 180.

      Returns:
      the maximum camera heading offset, in degrees
      Since:
      100.1.0
    • setMinCameraPitchOffset

      public void setMinCameraPitchOffset(double minPitchOffset)
      Sets the minimum camera pitch offset relative to the getTargetLocation(), in degrees.

      The value must be less than getMaxCameraPitchOffset() but no less than -90. Serves as the minimum value for getCameraPitchOffset(). Animations and interactions obey this limit.

      Defaults to -90.

      Parameters:
      minPitchOffset - the minimum camera pitch offset, in degrees
      Since:
      100.1.0
    • getMinCameraPitchOffset

      public double getMinCameraPitchOffset()
      Gets the minimum camera pitch offset relative to the getTargetLocation(), in degrees.

      The value must be less than getMaxCameraPitchOffset() but no less than -90. Serves as the minimum value for getCameraPitchOffset(). Animations and interactions obey this limit.

      Defaults to -90.

      Returns:
      the minimum camera pitch offset, in degrees
      Since:
      100.1.0
    • setMaxCameraPitchOffset

      public void setMaxCameraPitchOffset(double maxPitchOffset)
      Sets the maximum camera pitch offset relative to the getTargetLocation(), in degrees.

      The value must be greater than getMinCameraPitchOffset() but no greater than 90. Serves as the maximum value for getCameraPitchOffset(). Animations and interactions obey this limit.

      Defaults to 90.

      Parameters:
      maxPitchOffset - the maximum pitch offset, in degrees
      Since:
      100.1.0
    • getMaxCameraPitchOffset

      public double getMaxCameraPitchOffset()
      Gets the maximum camera pitch offset relative to the getTargetLocation(), in degrees.

      The value must be greater than getMinCameraPitchOffset() but no greater than 90. Serves as the maximum value for getCameraPitchOffset(). Animations and interactions obey this limit.

      Defaults to 90.

      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.

      True if the camera's distance to the getTargetLocation() can be changed by a user zoom interaction, false otherwise.

      When enabled, the user can change the getCameraDistance() with a zoom interaction.

      Defaults to true.

      Parameters:
      distanceInteractive - true to let 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.

      True if the camera's heading relative to the getTargetLocation() can be changed by a user horizontal pan interaction, false otherwise.

      When enabled, the user can change the getCameraHeadingOffset() with a horizontal pan interaction.

      Defaults to true.

      Parameters:
      headingOffsetInteractive - true to let 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.

      True if the camera's pitch relative to the getTargetLocation() can be changed by a user's vertical pan interaction, false otherwise.

      When enabled, the user can change the getCameraPitchOffset() with a vertical pan interaction.

      Defaults to true.

      Parameters:
      pitchOffsetInteractive - true to let a vertical pan interaction affect the camera pitch offset, otherwise false
      Since:
      100.1.0
    • isCameraDistanceInteractive

      public boolean isCameraDistanceInteractive()
      Gets whether a zoom interaction can affect the camera distance.

      True if the camera's distance to the getTargetLocation() can be changed by a user zoom interaction, false otherwise.

      When enabled, the user can change the getCameraDistance() with a zoom interaction.

      Defaults to true.

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

      public boolean isCameraHeadingOffsetInteractive()
      Gets whether a horizontal pan interaction can affect the camera heading offset.

      True if the camera's heading relative to the getTargetLocation() can be changed by a user horizontal pan interaction, false otherwise.

      When enabled, the user can change the getCameraHeadingOffset() with a horizontal pan interaction.

      Defaults to true.

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

      public boolean isCameraPitchOffsetInteractive()
      Gets whether a vertical pan interaction can affect the camera pitch offset.

      True if the camera's pitch relative to the getTargetLocation() can be changed by a user's vertical pan interaction, false otherwise.

      When enabled, the user can change the getCameraPitchOffset() with a vertical pan interaction.

      Defaults to true.

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

      public Point getTargetLocation()
      Gets the location on which the camera focuses and around which it orbits.

      The target location is the focal point of the camera managed by the orbit camera controller. The position of the camera is determined by the getCameraDistance(), getCameraHeadingOffset(), and getCameraPitchOffset() relative to this location.

      Returns:
      the target for the camera to look at and rotate around
      Since:
      100.1.0
    • addCameraDistanceChangedListener

      public void addCameraDistanceChangedListener(CameraDistanceChangedListener<OrbitLocationCameraController> 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<OrbitLocationCameraController> 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<OrbitLocationCameraController> 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<OrbitLocationCameraController> 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<OrbitLocationCameraController> 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<OrbitLocationCameraController> listener)
      Removes a camera pitch offset changed listener.
      Parameters:
      listener - the listener
      Returns:
      true if successful, otherwise false
      Since:
      100.1.0