ArcGIS Runtime SDK for macOS: AGSCamera Class Reference
ArcGIS Runtime SDK for macOS  100.5
AGSCamera Class Reference

Description

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:
 
(AGSCamera *) - moveForwardWithDistance:
 
(AGSCamera *) - moveToLocation:
 
(AGSCamera *) - moveTowardTargetPoint:distance:
 
(instancetype) - NS_UNAVAILABLE
 
(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:
 

Properties

double heading
 
AGSPointlocation
 
double pitch
 
double roll
 

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
An intialized 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
An intialized 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
An intialized camera
Since
100

§ 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.
Returns
An intialized camera
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.
Returns
An intialized camera
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.
Returns
An intialized camera
Since
100

§ 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