Skip To Content ArcGIS for Developers Sign In Dashboard

Camera Class

(Esri::ArcGISRuntime::Camera)

3D view description modeled as a virtual camera. More...

Header: #include <Camera>
Since: Esri::ArcGISRuntime 100.0

Public Functions

Camera()
Camera(double latitude, double longitude, double altitude, double heading, double pitch, double roll)
Camera(const Point &locationPoint, double heading, double pitch, double roll)
Camera(const Point &lookAtPoint, double distance, double heading, double pitch, double roll)
Camera(TransformationMatrix *transformationMatrix)
Camera(const Camera &other)
Camera(Camera &&other)
~Camera()
Camera elevate(double deltaAltitude) const
double heading() const
bool isEmpty() const
Point location() const
Camera moveForward(double distance) const
Camera moveTo(const Point &location) const
Camera moveToward(const Point &targetPoint, double distance) const
double pitch() const
double roll() const
Camera rotateAround(const Point &targetPoint, double deltaHeading, double deltaPitch, double deltaRoll) const
Camera rotateTo(double heading, double pitch, double roll) const
TransformationMatrix *transformationMatrix(QObject *parent = nullptr) const
Camera zoomToward(const Point &targetPoint, double factor) const
Camera &operator=(const Camera &other)
Camera &operator=(Camera &&other)
bool operator==(const Camera &other) const

Detailed Description

3D view description modeled as a virtual camera.

A Camera contains the spatial parameters to set a 3D view on a Scene in a SceneView: a virtual camera's location, orientation and field of view. The Viewpoint contains a camera. See the API doc for Viewpoint for details of how it uses a Camera.

Camera orientation

  • The ENU (East-North-Up) ground reference frame is used.
  • Heading is expressed in degrees of rotation around its Z axis, clockwise from north. Negative headings are allowed and heading can wrap around (i.e 361 wraps to a value of 1).
  • Pitch is expressed in degrees of rotation around its Y axis, from 0 looking straight down to 180 looking straight up towards the sky. Negative pitches are not allowed, and the 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 is expressed in degrees of rotation around its X axis, from 0 to 360, with 0 being horizontal.
  • Field of view is the vertical angular extent of a given scene as imaged by the virtual camera.
  • Distances for moveForward and moveToward are expressed in meters.

Camera transformation

A Camera object is immutable. The Camera class includes helper methods for advanced transformations of location and orientation. The result of the transformation is a new Camera object. This approach simplifies the code that chains together transformations.

Each transformation is based either solely on the camera's location and orientation, or in addition incorporates a reference to another location referred to here as lookAtPoint. This is the location that the camera is pointed at.

Transformations are applied in this order:

  • Set the camera location to (x=0, y=0, z=0) with heading, pitch, and roll all set to zero.
  • Set the camera to the new location.
  • Set the heading.
  • Set the pitch.
  • Set the roll.

Example:

Create a Camera to be used for setting the viewpoint on a SceneView:

// create a camera
const double latitude = 28.4;
const double longitude = 83.9;
const double altitude = 10010.0;
const double heading = 10.0;
const double pitch = 80.0;
const double roll = 0.0;
Camera camera(latitude, longitude, altitude, heading, pitch, roll);

// set the viewpoint
m_sceneView->setViewpointCameraAndWait(camera);

See also Viewpoint.

Member Function Documentation

Camera::Camera()

Default constructor. Creates an empty Camera.

Camera::Camera(double latitude, double longitude, double altitude, double heading, double pitch, double roll)

Constructs a camera using camera location latitude, longitude, altitude, and orientation.

  • latitude - The latitude directly below the camera.
  • longitude - The longitude directly below the camera.
  • altitude - The camera altitude.
  • heading - The camera heading.
  • pitch - The camera pitch.
  • roll - The camera roll.

See also Camera orientation and Camera transformation.

Camera::Camera(const Point &locationPoint, double heading, double pitch, double roll)

Constructs a camera using camera location (as a Point) and orientation.

  • locationPoint - The x,y,z-coordinates of camera's location.
  • heading - The camera heading.
  • pitch - The camera pitch.
  • roll - The camera roll.

See also Camera orientation and Camera transformation.

Camera::Camera(const Point &lookAtPoint, double distance, double heading, double pitch, double roll)

Constructs a camera using the location of camera's subject (as a Point) and camera orientation.

  • lookAtPoint - The x,y,z-coordinates of subject's location.
  • distance - The distance from the camera to the subject in meters.
  • heading - The camera heading.
  • pitch - The camera pitch.
  • roll - The camera roll.

The camera location is calculated such that when the camera has the specified orientation, the lookAtPoint is at the specified distance from the camera and the lookAtPoint is seen in the center of the view.

See also Camera orientation.

Camera::Camera(TransformationMatrix *transformationMatrix)

Constructs a camera using transformation matrix.

The transformation matrix describes the camera's location and the direction it is looking. Using this constructor with the location provided by ARKit/ARCore is necessary for enabling augmented reality.

This function was introduced in Esri::ArcGISRuntime 100.6.

Camera::Camera(const Camera &other)

Copy constructor from other Camera.

Camera::Camera(Camera &&other)

Move constructor from other Camera.

Camera::~Camera()

Destructor.

Camera Camera::elevate(double deltaAltitude) const

Create a new Camera with the same orientation and x,y location as this one, with altitude (z-value) changed by deltaAltitude.

double Camera::heading() const

Returns this Camera's heading.

bool Camera::isEmpty() const

Returns whether this object is empty.

Point Camera::location() const

Returns this Camera's location.

Camera Camera::moveForward(double distance) const

Create a Camera object with the same orientation as this one, but moved along its heading by distance meters.

Camera Camera::moveTo(const Point &location) const

Create a new Camera object with the same orientation as this one, moved to a new location.

Camera Camera::moveToward(const Point &targetPoint, double distance) const

Create a new Camera object with the same orientation as this one, moved toward a given targetPoint by a given distance in meters.

Note that targetPoint indicates the direction the camera should be moved. This is not the same thing as lookAtPoint, which indicates the direction that the camera should be oriented.

double Camera::pitch() const

Returns this Camera's pitch.

double Camera::roll() const

Returns this Camera's roll.

Camera Camera::rotateAround(const Point &targetPoint, double deltaHeading, double deltaPitch, double deltaRoll) const

Create a new Camera object that is rotated around a target point.

  • targetPoint - The location to rotate around.
  • deltaHeading - The change in heading.
  • deltaPitch - The change in pitch.
  • deltaRoll - The change in roll.

The result of this transformation is a new camera with the following characteristics.

  • The orientation of the camera is changed by the specified values of heading, pitch, and roll.
  • The target point remains in the same relative location in the view.
  • The camera location is the same distance from the target point.

See also Camera transformation.

Camera Camera::rotateTo(double heading, double pitch, double roll) const

Create a new Camera object with the same location as this one, with rotated orientation.

  • heading - The new absolute heading.
  • pitch - The new absolute pitch.
  • roll - The new absolute roll.

See also Camera orientation.

TransformationMatrix *Camera::transformationMatrix(QObject *parent = nullptr) const

Returns this Camera's location and orientation as a TransformationMatrix.

  • parent - The parent QObject-derived object (optional).

This returns a TransformationMatrix even when this Camera was not created using a TransformationMatrix.

This function was introduced in Esri::ArcGISRuntime 100.6.

Camera Camera::zoomToward(const Point &targetPoint, double factor) const

Create a new Camera object with the view zoomed toward a specified point.

  • targetPoint - The absolute point in space to zoom toward.
  • factor - The zoom factor.

Camera &Camera::operator=(const Camera &other)

Assignment operator from other Camera.

Camera &Camera::operator=(Camera &&other)

Move operator from other Camera.

bool Camera::operator==(const Camera &other) const

Equivalency operator.

Returns whether this object and other are equivalent.


Feedback on this topic?