Package com.esri.arcgisruntime.mapping.view

Class Camera

java.lang.Object

com.esri.arcgisruntime.mapping.view.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

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