Class OrbitGeoElementCameraController


  • public final class OrbitGeoElementCameraController
    extends CameraController
    Represents a camera controller that restricts the scene view's camera to a (possibly moving) GeoElement.

    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:
    SceneView.setCameraController(CameraController)
    • Constructor Detail

      • 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.

        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 GeoElement's attributes.

        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 Detail

      • 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.

        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 center of geo-element's geometry. The offsets move the focal point to a new position relative to that center.

        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 hedingOffset < 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 hedingOffset > 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 between the camera and the target. Interactions and animations are limited by this. The default value is 0 meters.
        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 between the camera and the target. Interactions and animations are limited by this. The default value is 0 meters.
        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 between the camera and the target. Interactions and animations are limited by this. 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 between the camera and the target. Interactions and animations are limited by this. 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.
        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.
        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.
        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 whether the camera's position rotates with the target's heading. The default value is true.
        Parameters:
        autoHeadingEnabled - true to let the camera's position rotate with the target's heading, otherwise false
        Since:
        100.1.0
      • isAutoHeadingEnabled

        public boolean isAutoHeadingEnabled()
        Gets whether the camera's position rotates with the target's heading. The default value is true.
        Returns:
        true if the camera's position rotates with the target's heading, otherwise false
        Since:
        100.1.0
      • setAutoPitchEnabled

        public void setAutoPitchEnabled​(boolean autoPitchEnabled)
        Sets whether the camera's position rotates with the target's pitch. The default value is true.
        Parameters:
        autoPitchEnabled - true to let the camera's position rotate with the target's pitch, otherwise false
        Since:
        100.1.0
      • isAutoPitchEnabled

        public boolean isAutoPitchEnabled()
        Gets whether the camera's position rotates with the target's pitch. The default value is true.
        Returns:
        true if the camera's position rotates with the target's pitch, otherwise false
        Since:
        100.1.0
      • setAutoRollEnabled

        public void setAutoRollEnabled​(boolean autoRollEnabled)
        Sets whether the camera's position rotates with the target's roll. The default value is true.
        Parameters:
        autoRollEnabled - true to let the camera's position rotate with the target's roll, otherwise false
        Since:
        100.1.0
      • isAutoRollEnabled

        public boolean isAutoRollEnabled()
        Gets whether the camera's position rotates with the target's roll. The default value is true.
        Returns:
        true if the camera's position rotates with the target's roll, otherwise false
        Since:
        100.1.0
      • setTargetOffsetX

        public void setTargetOffsetX​(double targetOffsetX)
        Sets the target offset along X axis. The default value is 0.
        Parameters:
        targetOffsetX - target offset along X axis, in meters
        Since:
        100.1.0
      • getTargetOffsetX

        public double getTargetOffsetX()
        Gets the target offset along X axis. The default value is 0.
        Returns:
        the target offset along X axis, in meters
        Since:
        100.1.0
      • setTargetOffsetY

        public void setTargetOffsetY​(double targetOffsetY)
        Sets the target offset along Y axis. The default value is 0.
        Parameters:
        targetOffsetY - target offset along Y axis, in meters
        Since:
        100.1.0
      • getTargetOffsetY

        public double getTargetOffsetY()
        Gets the target offset along Y axis. The default value is 0.
        Returns:
        the target offset along Y axis, in meters
        Since:
        100.1.0
      • 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()
        Gets the target offset along Z axis. 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 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
      • 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
      • 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
      • 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