Class Camera


  • public final class Camera
    extends java.lang.Object
    Represents an immutable camera object. A Camera has a location, heading and pitch.
    • Location - the 3D point in space where the Camera is located. The Camera cannot be located at heights below the BaseSurface.
    • Heading - a value from 0 to 360. Represents the angle clockwise from north in an ENU (East, North, Up Ground reference frames). Negative headings are allowed and heading can wrap around (i.e 361 wraps to a value of 1).
    • Pitch - a value from 0 to 180. Represents the angle applied to the camera when rotating around its y-axis in an ENU. 0 is looking straight down towards the center of the earth, 180 looking straight up (sky). Negative pitches are not allowed and values do not wrap around. If the behavior of a negative pitch is required, then the corresponding transformation with positive pitch can be set instead. For example, if heading:0 pitch:-20 roll:0 is required then heading:180 pitch:20 roll:180 can be used instead.
    • Roll - a value from 0 to 360. Represents the angle applied to the camera when rotating around its x-axis in an ENU. 0 is "horizontal".
    A Camera can be created based on location, heading and pitch values. For example:
     Camera camera = new Camera(new Point(0, 0, 2000000, SpatialReferences.getWgs84()), 90, 45, 0);
     

    A Camera can be created from an existing Camera by using methods such as elevate(double), moveToward(com.esri.arcgisruntime.geometry.Point, double) and rotateAround(com.esri.arcgisruntime.geometry.Point, double, double, double). A Camera has no direct 2D concepts like scale and rotation. However, scale is approximated and is accurate when looking straight down at the ArcGISScene.

    A Camera can be created from a TransformationMatrix. For example:

     Camera camera = new Camera(new TransformationMatrix(1.0, 3.0, 0.5, -2.0, 2.0, -12.0- 9.0));
     
    Since:
    100.0.0
    • Constructor Summary

      Constructors 
      Constructor Description
      Camera​(double latitude, double longitude, double altitude, double heading, double pitch, double roll)
      Creates a camera with the given arguments.
      Camera​(Point location, double heading, double pitch, double roll)
      Creates a camera with the given arguments.
      Camera​(Point lookAtPoint, double distance, double heading, double pitch, double roll)
      Creates a camera based on a point to look at.
      Camera​(TransformationMatrix transformationMatrix)
      Creates a camera from an instance of TransformationMatrix.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Camera elevate​(double deltaAltitude)
      Creates a copy of the camera with the altitude adjusted.
      double getHeading()
      Gets the camera's heading.
      Point getLocation()
      Gets the camera's location.
      double getPitch()
      Gets the camera's pitch.
      double getRoll()
      Gets the camera's roll.
      TransformationMatrix getTransformationMatrix()
      Gets the camera's TransformationMatrix.
      Camera moveForward​(double distance)
      Creates a copy of the camera with the location moved by a given distance in the direction the camera is facing.
      Camera moveTo​(Point location)
      Creates a copy of the camera with the location changed.
      Camera moveToward​(Point targetPoint, double distance)
      Creates a copy of the camera with the location moved in the direction of a target point by a given distance.
      Camera rotateAround​(Point targetPoint, double deltaHeading, double deltaPitch, double deltaRoll)
      Creates a copy of the camera rotated around the given target point by the given delta angles in degrees.
      Camera rotateTo​(double heading, double pitch, double roll)
      Creates a copy of the camera with the heading, pitch and roll changed to the absolute given angles in degrees.
      Camera zoomToward​(Point targetPoint, double factor)
      Creates a copy of the camera with the location moved in the direction of a target point by a given zoom factor.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Camera

        public Camera​(double latitude,
                      double longitude,
                      double altitude,
                      double heading,
                      double pitch,
                      double roll)
        Creates a camera with the given arguments.
        Parameters:
        latitude - the latitude; may be negative
        longitude - the longitude; may be negative
        altitude - the height in meters; may be negative
        heading - the heading in degrees; may be negative
        pitch - the pitch in degrees; may not be negative
        roll - the roll in degrees
        Since:
        100.0.0
      • Camera

        public Camera​(Point location,
                      double heading,
                      double pitch,
                      double roll)
        Creates a camera with the given arguments.
        Parameters:
        location - the position
        heading - the heading in degrees; may be negative
        pitch - the pitch in degrees; may not be negative
        roll - the roll in degrees
        Throws:
        java.lang.IllegalArgumentException - if location is null
        Since:
        100.0.0
      • Camera

        public Camera​(Point lookAtPoint,
                      double distance,
                      double heading,
                      double pitch,
                      double roll)
        Creates a camera based on a point to look at. Note: the given values may mean that the point is not visible on screen; you can check its visibility using SceneView.locationToScreen.
        Parameters:
        lookAtPoint - A point geometry containing the location for the camera to look at
        distance - The distance of the camera from the look at point, in meters; may not be negative
        heading - the absolute heading, i.e. not relative to the lookAtPoint, in degrees; may be negative
        pitch - the pitch in degrees; may not be negative
        roll - the roll in degrees
        Throws:
        java.lang.IllegalArgumentException - if lookAtPoint is null
        Since:
        100.0.0
      • Camera

        public Camera​(TransformationMatrix transformationMatrix)
        Creates a camera from an instance of TransformationMatrix. The TransformationMatrix describes the camera's location and direction it is looking. On Android, using this constructor with the location provided by ARCore is necessary for enabling augmented reality.
        Parameters:
        transformationMatrix - the TransformationMatrix used to create the camera
        Since:
        100.6.0
    • Method Detail

      • getLocation

        public Point getLocation()
        Gets the camera's location.
        Returns:
        the location of the camera
        Since:
        100.0.0
      • getPitch

        public double getPitch()
        Gets the camera's pitch.
        Returns:
        the pitch in degrees
        Since:
        100.0.0
      • getHeading

        public double getHeading()
        Gets the camera's heading.
        Returns:
        the heading
        Since:
        100.0.0
      • getRoll

        public double getRoll()
        Gets the camera's roll.
        Returns:
        the roll
        Since:
        100.0.0
      • getTransformationMatrix

        public TransformationMatrix getTransformationMatrix()
        Gets the camera's TransformationMatrix.
        Returns:
        the TransformationMatrix representation of the camera's location and rotation
        Since:
        100.6.0
      • elevate

        public Camera elevate​(double deltaAltitude)
        Creates a copy of the camera with the altitude adjusted.
        Parameters:
        deltaAltitude - in meters; can be positive or negative, however the Camera will only move as low as the BaseSurface allows.
        Returns:
        a new camera
        Since:
        100.0.0
      • moveForward

        public Camera moveForward​(double distance)
        Creates a copy of the camera with the location moved by a given distance in the direction the camera is facing.
        Parameters:
        distance - in meters; may not be negative
        Returns:
        a new Camera
        Since:
        100.0.0
      • moveToward

        public Camera moveToward​(Point targetPoint,
                                 double distance)
        Creates a copy of the camera with the location moved in the direction of a target point by a given distance.
        Parameters:
        targetPoint - location to move towards
        distance - distance to move (in meters); may not be negative
        Returns:
        a new camera
        Since:
        100.0.0
      • rotateAround

        public Camera rotateAround​(Point targetPoint,
                                   double deltaHeading,
                                   double deltaPitch,
                                   double deltaRoll)
        Creates a copy of the camera rotated around the given target point by the given delta angles in degrees. The targetPoint will not change on the screen if it was on the screen to begin with. The distance between the previous Camera location the targetPoint will be the same as between the new Camera Location and the targetPoint.
        Parameters:
        targetPoint - the point to rotate around
        deltaHeading - the heading change; may be negative
        deltaPitch - the pitch change; may be negative
        deltaRoll - the roll change
        Returns:
        a new camera
        Throws:
        java.lang.IllegalArgumentException - if targetPoint is null
        Since:
        100.0.0
      • rotateTo

        public Camera rotateTo​(double heading,
                               double pitch,
                               double roll)
        Creates a copy of the camera with the heading, pitch and roll changed to the absolute given angles in degrees.
        Parameters:
        heading - the new heading; may be negative
        pitch - the new pitch; may not be negative
        roll - the new roll
        Returns:
        a new camera
        Since:
        100.0.0
      • moveTo

        public Camera moveTo​(Point location)
        Creates a copy of the camera with the location changed.
        Parameters:
        location - the new location
        Returns:
        a new camera
        Throws:
        java.lang.IllegalArgumentException - if location is null
        Since:
        100.0.0
      • zoomToward

        public Camera zoomToward​(Point targetPoint,
                                 double factor)
        Creates a copy of the camera with the location moved in the direction of a target point by a given zoom factor.
        Parameters:
        targetPoint - the target point to zoom towards
        factor - a factor of the distance between the current Camera Location and the targetPoint. E.g. a factor of 2 will divide that distance in half. Negative values will have no effect.
        Returns:
        a new camera
        Throws:
        java.lang.IllegalArgumentException - if target point is null
        Since:
        100.0.0