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
A camera controller that supports orbital camera navigation around a stationary or moving GeoElement.

This camera controller is used to associate camera navigation and movement with GeoElement objects, such as Graphic, Feature, and DynamicEntity. When this controller is set on the scene view, the interaction mode allows the user to rotate around and zoom in and out from the target GeoElement. If the object is moving, the camera moves in synchronization with it and the camera position, heading, pitch, and roll automatically adjusts. If the GeoElement geometry is a polyline or a polygon, the camera will focus on its center point. Once you have applied this camera controller to a SceneView, you cannot change the target GeoElement nor the viewpoint of the scene view.

Since:
100.1.0
See Also:

  • Constructor Details

    • OrbitGeoElementCameraController

      public OrbitGeoElementCameraController(GeoElement targetGeoElement, double cameraDistance)
      Creates an OrbitGeoElementCameraController using a distance to the specified GeoElement.

      This camera controller is used to associate camera navigation and movement with GeoElement objects, such as Graphic, Feature, and DynamicEntity. When the controller is set on the scene view, using SceneView.setCameraController(CameraController), the interaction mode allows the user to rotate around and zoom in and out from the object. For a moving object, the camera will move in synchronization with it and the camera position, heading, pitch, and roll will automatically adjust. If the GeoElement geometry is a polyline or a polygon, the camera will focus on its center point.

      Parameters:
      targetGeoElement - the GeoElement that will be the focus of the camera in the scene view
      cameraDistance - the distance in meters that the camera will be positioned from the GeoElement
      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 of the orbit camera controller.

      The target GeoElement 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, you must use a Renderer and the GeoElement attributes.

      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)
      Animates the camera to a new position relative to the target.
      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)
      Animates the camera to a new position using the target offsets of the camera.

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

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

      The default value is 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 target, in meters.

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

      The default value is 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 target, in meters.

      There is no limit on the maximum distance. Animations and interactions are bounded by this limit.

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

      There is no limit on the maximum distance. Animations and interactions are bounded by this limit.

      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 target's GeoElement, in degrees.

      Any angle, positive or negative, will be wrapped to a clockwise angle between 0 and 360. The value must be less than getMaxCameraHeadingOffset(). Animations and interactions are bounded by this limit.

      The default value is -180.

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

    • getMinCameraHeadingOffset

      public double getMinCameraHeadingOffset()
      Gets the minimum camera heading offset relative to the target's GeoElement, in degrees.

      Any angle, positive or negative, will be wrapped to a clockwise angle between 0 and 360. The value must be less than getMaxCameraHeadingOffset(). Animations and interactions are bounded by this limit.

      The default value is -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 target's GeoElement, in degrees.

      Any angle, positive or negative, will be wrapped to a clockwise angle between 0 and 360. The value must be greater than getMinCameraHeadingOffset(). Animations and interactions are bounded by this limit.

      The default value is 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 target's GeoElement, in degrees.

      Any angle, positive or negative, will be wrapped to a clockwise angle between 0 and 360. Animations and interactions are bounded by this limit.

      The default value is 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 target's GeoElement, in degrees.

      The angle must be between -90 and getMaxCameraPitchOffset(). Animations and interactions are bounded by this limit.

      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 target's GeoElement, in degrees.

      The angle must be between -90 and getMaxCameraPitchOffset(). Animations and interactions are bounded by this limit.

      The default value is -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 target's GeoElement, in degrees.

      Animations and interactions are bounded by this limit.

      The default value is 90.

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

    • getMaxCameraPitchOffset

      public double getMaxCameraPitchOffset()
      Gets the maximum camera pitch offset relative to the target's GeoElement, in degrees.

      The angle must be between getMinCameraPitchOffset() and 90. Animations and interactions are bounded by this limit.

      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.

      If set to true, the user can interactively change the distance between the camera and the target object.

      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.

      If true, the user can interactively change the distance between the camera and the target object.

      The default value is true.

      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.

      If true, the user can interactively change the relative heading between the camera and the target object.

      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.

      If true, the user can interactively change the relative heading between the camera and the target object.

      The default value is true.

      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.

      If true, the user can interactively change the relative pitch between the camera and the target object.

      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.

      If true, the user can interactively change the relative pitch between the camera and the target object.

      The default value is true.

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

    • setAutoHeadingEnabled

      public void setAutoHeadingEnabled(boolean autoHeadingEnabled)
      Sets the camera auto-heading offset update property.

      If set to true, the camera will maintain its heading offset when the target's heading changes. Otherwise, the camera position is not affected by the target's heading.

      The default value is true.

      If you have applied a renderer to the target GeoElement, you can use the renderer's setHeadingExpression to control its heading.

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

    • isAutoHeadingEnabled

      public boolean isAutoHeadingEnabled()
      Gets the camera auto-heading offset update property.

      If true, the camera will maintain its heading offset when the target's heading changes. Otherwise, the camera position is not affected by the target's heading.

      The default value is true.

      If you have applied a renderer to the target GeoElement, you can use the renderer's setHeadingExpression to control its heading.

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

    • setAutoPitchEnabled

      public void setAutoPitchEnabled(boolean autoPitchEnabled)
      Sets the camera pitch update property. If set to true the camera pitch offset is updated with the target's pitch.

      If true, the camera will maintain its pitch offset when the target's pitch changes. Otherwise, the camera position is not affected by the target's pitch.

      The default value is true.

      If you have applied a renderer to the target GeoElement, you can use the renderer's setPitchExpression to control its pitch.

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

    • isAutoPitchEnabled

      public boolean isAutoPitchEnabled()
      Gets the camera pitch update property.

      If true, the camera will maintain its pitch offset when the target's pitch changes. Otherwise, the camera position is not affected by the target's pitch.

      The default value is true.

      If you have applied a renderer to the target GeoElement, you can use the renderer's setPitchExpression to control its pitch.

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

    • setAutoRollEnabled

      public void setAutoRollEnabled(boolean autoRollEnabled)
      Sets the camera roll update property. If set to true the camera roll offset is updated with the target's roll.

      If true, the camera will maintain its roll offset when the target's roll changes. Otherwise, the camera position is not affected by the target's roll.

      The default value is true.

      If you have applied a renderer to the target GeoElement, you can use the renderer's setRollExpression to control its roll.

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

    • isAutoRollEnabled

      public boolean isAutoRollEnabled()
      Gets the camera roll update property. True if the camera roll offset is updated with the target's roll, false otherwise.

      If true, the camera will maintain its roll offset when the target's roll changes. Otherwise, the camera position is not affected by the target's roll.

      The default value is true.

      If you have applied a renderer to the target GeoElement, you can use the renderer's setRollExpression to control its roll.

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

    • setTargetOffsetX

      public void setTargetOffsetX(double targetOffsetX)
      Sets the offset of the target focus point relative to the getTargetGeoElement() along its X axis in the symbol coordinate system.

      By default, the camera focuses on the center point of the OrbitGeoElementCameraController.getTargetGeoElement() geometry.

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

    • getTargetOffsetX

      public double getTargetOffsetX()
      Gets the offset of the target focus point relative to the getTargetGeoElement() along its X axis in the symbol coordinate system.

      By default, the camera focuses on the center point of the OrbitGeoElementCameraController.getTargetGeoElement() geometry.

      The default value is 0.

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

    • setTargetOffsetY

      public void setTargetOffsetY(double targetOffsetY)
      Sets the offset of the target focus point relative to the getTargetGeoElement() along its Y axis in the symbol coordinate system.

      By default, the camera focuses on the center point of the OrbitGeoElementCameraController.getTargetGeoElement() geometry.

      The default value is 0.

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

    • getTargetOffsetY

      public double getTargetOffsetY()
      Gets the offset of the target focus point relative to the getTargetGeoElement() along its Y axis in the symbol coordinate system.

      By default, the camera focuses on the center point of the OrbitGeoElementCameraController.getTargetGeoElement() geometry.

      The default value is 0.

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

    • setTargetOffsetZ

      public void setTargetOffsetZ(double targetOffsetZ)
      Sets the offset of the target focus point relative to the getTargetGeoElement() along its Z axis in the symbol coordinate system.

      By default, the camera focuses on the center point of the OrbitGeoElementCameraController.getTargetGeoElement() geometry.

      Parameters:
      targetOffsetZ - target offset along z-axis, in meters
      Since:
      100.1.0

    • getTargetOffsetZ

      public double getTargetOffsetZ()
      Gets the offset of the target focus point relative to the getTargetGeoElement() along its Z axis in the symbol coordinate system.

      By default, the camera focuses on the center point of the OrbitGeoElementCameraController.getTargetGeoElement() geometry.

      The default value is 0.

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

    • setTargetVerticalScreenFactor

      public void setTargetVerticalScreenFactor(float verticalFactor)
      Sets the target screen vertical factor of the orbit camera controller.

      Controls the vertical position of the target on the screen. Allowed values are 0 (bottom of screen) to 1 (top).

      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 target screen vertical factor of the orbit camera controller.

      Controls the vertical position of the target on the screen. Allowed values are 0 (bottom of screen) to 1 (top).

      The default value is 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