ArcGIS Runtime SDK for iOS: AGSCamera Class Reference
ArcGIS Runtime SDK for iOS  100.15
AGSCamera Class Reference

Description

A camera to represent 3D viewpoints of a scene.

Instances of this class represent a camera used to specify 3D viewpoints for AGSSceneView. It defines the perspective of a scene.

A Camera object can be thought of as a physical camera that one would look through to see a viewable extent and perspective of the Earth. Depending on how you hold the camera and how far away from the ground will determine what you can see. These positions of holding the camera represent the various properties that you can set on the camera. A camera has a location, heading, and a pitch.

  • Location - the 3D point in space where the Camera is located. The Camera cannot be located at heights below the AGSScene::baseSurface.
  • Heading - a value from 0 to 360. Represents the angle clockwise from north in a 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 a ENU. 0 is looking straight down towards the center of the planet, 180 looking straight up (sky). Negative pitches are not allowed and values do not wrap around.

A camera can be created from scratch by specifying location, heading and pitch values. It is immutable which means once it is created it cannot be modified. For convenience, you can produce new cameras by applying offset values to an existing camera.

Since
100
Inheritance diagram for AGSCamera:
AGSObject

Instance Methods

(AGSCamera *) - elevateWithDeltaAltitude:
 
(instancetype) - initWithLatitude:longitude:altitude:heading:pitch:roll:
 
(instancetype) - initWithLocation:heading:pitch:roll:
 
(instancetype) - initWithLookAtPoint:distance:heading:pitch:roll:
 
(instancetype) - initWithTransformationMatrix:
 
(BOOL) - isEqualToCamera:
 
(AGSCamera *) - moveForwardWithDistance:
 
(AGSCamera *) - moveToLocation:
 
(AGSCamera *) - moveTowardTargetPoint:distance:
 
(AGSCamera *) - rotateAroundTargetPoint:deltaHeading:deltaPitch:deltaRoll:
 
(AGSCamera *) - rotateToHeading:pitch:roll:
 
(AGSCamera *) - zoomTowardTargetPoint:factor:
 

Class Methods

(instancetype) + cameraWithLatitude:longitude:altitude:heading:pitch:roll:
 
(instancetype) + cameraWithLocation:heading:pitch:roll:
 
(instancetype) + cameraWithLookAtPoint:distance:heading:pitch:roll:
 
(instancetype) + cameraWithTransformationMatrix:
 

Properties

double heading
 
AGSPointlocation
 
double pitch
 
double roll
 
AGSTransformationMatrixtransformationMatrix
 

Method Documentation

◆ cameraWithLatitude:longitude:altitude:heading:pitch:roll:

+ (instancetype) cameraWithLatitude: (double)  latitude
longitude: (double)  longitude
altitude: (double)  altitude
heading: (double)  heading
pitch: (double)  pitch
roll: (double)  roll 

Initialize a new camera based on the provided arguments.

Parameters
latitudecomponent of the camera's coordinates.
longitudecomponent of the camera's coordinates.
altitudethe camera's height in meters from the sea level, may be negative.
headingin degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitchin degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
rollin degrees. This is the angle of rotation around the X-axis in an ENU.
Returns
A new camera.
Since
100

◆ cameraWithLocation:heading:pitch:roll:

+ (instancetype) cameraWithLocation: (AGSPoint *)  locationPoint
heading: (double)  heading
pitch: (double)  pitch
roll: (double)  roll 

Initialize a new camera based on the provided arguments.

Parameters
locationPointspecifying the camera's coordinates.
headingin degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitchin degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
rollin degrees. This is the angle of rotation around the X-axis in an ENU.
Returns
A new camera.
Since
100

◆ cameraWithLookAtPoint:distance:heading:pitch:roll:

+ (instancetype) cameraWithLookAtPoint: (AGSPoint *)  lookAtPoint
distance: (double)  distance
heading: (double)  heading
pitch: (double)  pitch
roll: (double)  roll 

Initialize a new camera based on the provided arguments and a location to look at.

Note
the given lookAtPoint may not be always visible on screen. You can check its visibility using locationToScreen: (AGSSceneViewCommon).
Parameters
lookAtPointcoordinates of the location for the camera to look at.
distanceof the camera from the look at point, in meters; may not be negative.
headingin degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitchin degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
rollin degrees. This is the angle of rotation around the X-axis in an ENU.
Returns
A new camera.
Since
100

◆ cameraWithTransformationMatrix:

+ (instancetype) cameraWithTransformationMatrix: (AGSTransformationMatrix *)  transformationMatrix

Initialize a new camera based on the transformation matrix.

Parameters
transformationMatrixThe AGSTransformationMatrix used to create the camera. The transformationMatrix 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.
Returns
A new camera.
Since
100.6

◆ elevateWithDeltaAltitude:

- (AGSCamera*) elevateWithDeltaAltitude: (double)  deltaAltitude

Creates a new camera that is based on the current camera after adjusting its elevation.

Parameters
deltaAltitudethat elevation change in meters; can be positive or negative, however the camera will only move as low as the AGSScene::baseSurface allows.
Returns
A new camera.
Since
100

◆ initWithLatitude:longitude:altitude:heading:pitch:roll:

- (instancetype) initWithLatitude: (double)  latitude
longitude: (double)  longitude
altitude: (double)  altitude
heading: (double)  heading
pitch: (double)  pitch
roll: (double)  roll 

Initialize a new camera based on the provided arguments.

Parameters
latitudecomponent of the camera's coordinates.
longitudecomponent of the camera's coordinates.
altitudethe camera's height in meters from the sea level, may be negative.
headingin degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitchin degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
rollin degrees. This is the angle of rotation around the X-axis in an ENU.
Since
100

◆ initWithLocation:heading:pitch:roll:

- (instancetype) initWithLocation: (AGSPoint *)  locationPoint
heading: (double)  heading
pitch: (double)  pitch
roll: (double)  roll 

Initialize a new camera based on the provided arguments.

Parameters
locationPointspecifying the camera's coordinates.
headingin degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitchin degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
rollin degrees. This is the angle of rotation around the X-axis in an ENU.
Since
100

◆ initWithLookAtPoint:distance:heading:pitch:roll:

- (instancetype) initWithLookAtPoint: (AGSPoint *)  lookAtPoint
distance: (double)  distance
heading: (double)  heading
pitch: (double)  pitch
roll: (double)  roll 

Initialize a new camera based on the provided arguments and a location to look at.

Note
the given lookAtPoint may not be always visible on screen. You can check its visibility using locationToScreen: (AGSSceneViewCommon).
Parameters
lookAtPointcoordinates of the location for the camera to look at.
distanceof the camera from the look at point, in meters; may not be negative.
headingin degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitchin degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
rollin degrees. This is the angle of rotation around the X-axis in an ENU.
Since
100

◆ initWithTransformationMatrix:

- (instancetype) initWithTransformationMatrix: (AGSTransformationMatrix *)  transformationMatrix

Initialize a new camera based on the transformation matrix.

Parameters
transformationMatrixThe AGSTransformationMatrix used to create the camera. The transformationMatrix 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.
Since
100.6

◆ isEqualToCamera:

- (BOOL) isEqualToCamera: (AGSCamera *)  other

Compares whether two cameras are equal.

Parameters
othercamera to compare this one to.
Returns
YES if the cameras are equal.
Since
100.6

◆ moveForwardWithDistance:

- (AGSCamera*) moveForwardWithDistance: (double)  distance

Creates a new camera that is based on the current camera after moving its location in the direction the camera is facing.

Parameters
distanceto move in meters, may not be negative.
Returns
A new camera.
Since
100

◆ moveToLocation:

- (AGSCamera*) moveToLocation: (AGSPoint *)  location

Create a new camera that is based on the current camera after changing its location.

Parameters
locationfor the new camera.
Returns
A new camera.
Since
100

◆ moveTowardTargetPoint:distance:

- (AGSCamera*) moveTowardTargetPoint: (AGSPoint *)  targetPoint
distance: (double)  distance 

Create a new camera that is based on the current camera after moving its location in the direction of the given target point.

Parameters
targetPointlocation to move towards.
distanceto move in meters, may not be negative.
Returns
A new camera.
Since
100

◆ rotateAroundTargetPoint:deltaHeading:deltaPitch:deltaRoll:

- (AGSCamera*) rotateAroundTargetPoint: (AGSPoint *)  targetPoint
deltaHeading: (double)  deltaHeading
deltaPitch: (double)  deltaPitch
deltaRoll: (double)  deltaRoll 

Create a new camera that is based on the current camera after rotating around the target point. The target point will not change on the screen if it was on the screen to begin with. The distance between the previous camera location and the target point will be the same as between the new camera location and the target point.

Parameters
targetPointto rotate around.
deltaHeadingthe heading change in degrees, may be negative.
deltaPitchthe pitch change in degrees, may be negative.
deltaRollthe roll change in degrees.
Returns
A new camera.
Since
100

◆ rotateToHeading:pitch:roll:

- (AGSCamera*) rotateToHeading: (double)  heading
pitch: (double)  pitch
roll: (double)  roll 

Create a new camera that is based on the current camera after changing its heading, pitch, and roll.

Parameters
headingfor the new camera.
pitchfor the new camera.
rollfor the new camera.
Returns
A new camera.
Since
100

◆ zoomTowardTargetPoint:factor:

- (AGSCamera*) zoomTowardTargetPoint: (AGSPoint *)  targetPoint
factor: (double)  factor 

Create a new camera that is based on the current camera after moving its location in the direction of the given target point by the specified zoom factor.

Parameters
targetPointlocation to move towards.
factorspecifiying how much to move the new camera based on the distance between the current camera location and the target point. For e.g. a factor of 2 will divide that distance in half for the new camera. Negative values will have no effect.
Returns
A new camera.
Since
100

Property Documentation

◆ heading

- (double) heading
readnonatomicassign

The camera's heading in degrees. This is the angle, clockwise, from North in an ENU. Value ranges from 0 to 360 degrees. The heading property can be thought of as a rotation value assuming that you were having the lens of the camera pointing directly at the ground. As you adjust the heading from 0 to 360 degrees, you would rotate (aka. spin) the camera in a counter-clockwise fashion.

Since
100

◆ location

- (AGSPoint*) location
readnonatomicstrong

The camera's location in space. It can be thought of as the physical position on/above the Earth that the camera is sitting when you look though it. If the Z value of the point is 0, that would mean the camera is sitting directly on the surface of the Earth, otherwise the value is assumed to signify meters above sea level.

Since
100

◆ pitch

- (double) pitch
readnonatomicassign

The camera's pitch in degrees. This is the angle of rotation around the Y-axis in an ENU. Value ranges from 0 to 180 degrees, where 0 is looking straight down (center of the earth) and 180 looking straight up (towards outer space).

Since
100

◆ roll

- (double) roll
readnonatomicassign

The camera's roll in degrees. This is the angle of rotation around the X-axis in an ENU. Value ranges from 0 to 360 degrees, where 0 is horizontal.

Since
100

◆ transformationMatrix

- (AGSTransformationMatrix*) transformationMatrix
readnonatomicstrong

The camera's AGSTransformationMatrix. It does not matter if the camera was created with a transformationMatrix, the camera's location and orientation will be converted into an AGSTransformationMatrix.

Since
100.6