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:

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
AGSPoint *	location
double	pitch
double	roll
AGSTransformationMatrix *	transformationMatrix

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

latitude	component of the camera's coordinates.
longitude	component of the camera's coordinates.
altitude	the camera's height in meters from the sea level, may be negative.
heading	in degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitch	in degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
roll	in 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

locationPoint	specifying the camera's coordinates.
heading	in degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitch	in degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
roll	in 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

lookAtPoint	coordinates of the location for the camera to look at.
distance	of the camera from the look at point, in meters; may not be negative.
heading	in degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitch	in degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
roll	in 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

transformationMatrix

The 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

deltaAltitude

that 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

latitude	component of the camera's coordinates.
longitude	component of the camera's coordinates.
altitude	the camera's height in meters from the sea level, may be negative.
heading	in degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitch	in degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
roll	in 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

locationPoint	specifying the camera's coordinates.
heading	in degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitch	in degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
roll	in 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

lookAtPoint	coordinates of the location for the camera to look at.
distance	of the camera from the look at point, in meters; may not be negative.
heading	in degrees, may be negative. This is the angle, clockwise, from North in an ENU.
pitch	in degrees, may not be negative. This is the angle of rotation around the Y-axis in an ENU.
roll	in 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

transformationMatrix

The 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

other

camera 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

distance

to 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

location

for 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

targetPoint	location to move towards.
distance	to 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

targetPoint	to rotate around.
deltaHeading	the heading change in degrees, may be negative.
deltaPitch	the pitch change in degrees, may be negative.
deltaRoll	the 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

heading	for the new camera.
pitch	for the new camera.
roll	for 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

targetPoint	location to move towards.
factor	specifiying 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