AGSOrbitGeoElementCameraController Class Reference

Description

A controller which allows a scene view's camera to orbit a geo-element.

Instances of this class represent a controller which allows a scene view's camera to orbit a stationary or moving target geo-element. Interactions on the scene view will pivot the camera around the target so that the camera is always looking at the target. The camera will move to maintain a fixed relative distance from a moving target, and it can even adjust its heading, pitch, and roll based on changes to geo-element's heading, pitch, and roll.

To activate this controller, you need to set it on the scene view using the AGSSceneView::cameraController property. Programmatically setting the viewpoint on the scene view will be disabled when this controller is active.

Since

100.1

Inheritance diagram for AGSOrbitGeoElementCameraController:

Instance Methods
(instancetype)	- initWithTargetGeoElement:distance:
(id< AGSCancelable >)	- moveCameraWithDistanceDelta:headingDelta:pitchDelta:duration:completion:
(id< AGSCancelable >)	- setTargetOffsetX:targetOffsetY:targetOffsetZ:duration:completion:

Class Methods
(instancetype)	+ orbitGeoElementCameraControllerWithTargetGeoElement:distance:

Properties
BOOL	autoHeadingEnabled
BOOL	autoPitchEnabled
BOOL	autoRollEnabled
double	cameraDistance
BOOL	cameraDistanceInteractive
double	cameraHeadingOffset
BOOL	cameraHeadingOffsetInteractive
double	cameraPitchOffset
BOOL	cameraPitchOffsetInteractive
double	maxCameraDistance
double	maxCameraHeadingOffset
double	maxCameraPitchOffset
double	minCameraDistance
double	minCameraHeadingOffset
double	minCameraPitchOffset
id< AGSGeoElement >	targetGeoElement
double	targetOffsetX
double	targetOffsetY
double	targetOffsetZ
float	targetVerticalScreenFactor

Method Documentation

initWithTargetGeoElement:distance:

- (instancetype) initWithTargetGeoElement:		(id< AGSGeoElement >)	targetGeoElement
distance:		(double)	distance

Initialize the camera controller to orbit around the provided geo-element at the specified distance. When the target moves, the camera will move with the target to maintain its relative position.

An orbit camera controller is used associate camera navigation and movement with AGSGeoElement point object. This can take a point AGSGraphic or a point AGSFeature. When the controller is set on the scene view using AGSSceneView::cameraController the interaction mode will change for the active navigation model and will be focused on the input AGSGeoElement allowing the user to rotate around and zoom in an out from the object. For a moving AGSGeoElement the camera will move in synchronization with it. Position, heading, pitch and roll can be adjusted by simply changing the object with no requirement to change the camera.

Parameters

targetGeoElement	which will be the focus of the camera in the view.
distance	in meters from the targetGeoElement the camera will be placed.

Since

100.1

moveCameraWithDistanceDelta:headingDelta:pitchDelta:duration:completion:

- (id<AGSCancelable>) moveCameraWithDistanceDelta:		(double)	distanceDelta
headingDelta:		(double)	headingDelta
pitchDelta:		(double)	pitchDelta
duration:		(NSTimeInterval)	duration
completion:		(nullable void(^)(BOOL finished))	completion

Moves the camera with animation to a new offset position.

Parameters

distanceDelta	the change in distance to apply in the animation, in meters.
headingDelta	the change in heading to apply in the animation, in degrees.
pitchDelta	the change in pitch to apply in the animation, in degrees.
duration	of the animation, in seconds.
completion	block which is invoked when operation completes. The finished argument indicates whether animation finished without any user interruption.

Note

The heading and pitch delta values may be greater than 360 degrees and the angle is not normalized. For example, a heading delta of 720 will make the camera do two circles around the target within the duration time.

Returns

An operation that can be cancelled.

Since

100.1

orbitGeoElementCameraControllerWithTargetGeoElement:distance:

+ (instancetype) orbitGeoElementCameraControllerWithTargetGeoElement:		(id< AGSGeoElement >)	targetGeoElement
distance:		(double)	distance

Creates a camera controller to orbit around the provided geo-element at the specified distance. When the target moves, the camera will move with the target to maintain its relative position.

An orbit camera controller is used associate camera navigation and movement with AGSGeoElement point object. This can take the form point AGSGraphic or a point AGSFeature. When the controller is set on the scene view using AGSSceneView::cameraController the interaction mode will change for the active navigation model and will be focused on the input AGSGeoElement allowing the user to rotate around and zoom in an out from the object. For a moving AGSGeoElement the camera will move in synchronization with it. Position, heading, pitch and roll can be adjusted by simply changing the object with no requirement to change the camera.

Parameters

targetGeoElement	which will be the focus of the camera in the view.
distance	in meters from the targetGeoElement the camera will be placed.

Returns

A new camera controller.

Since

100.1

setTargetOffsetX:targetOffsetY:targetOffsetZ:duration:completion:

- (id<AGSCancelable>) setTargetOffsetX:		(double)	x
targetOffsetY:		(double)	y
targetOffsetZ:		(double)	z
duration:		(NSTimeInterval)	duration
completion:		(nullable void(^)(BOOL finished))	completion

Moves the camera with animation to focus on the target, offset by specified values. By default the camera focuses on the center of geo-element's geometry. The offsets move the focal point to a new position relative to that center.

Parameters

x	offset along x-axis, in meters.
y	offset along y-axis, in meters.
z	offset along z-axis, in meters.
duration	of the animation, in seconds.
completion	block which is invoked when operation completes. The finished argument indicates whether animation finished without any user interruption.

Returns

An operation that can be cancelled.

Since

100.1

Property Documentation

autoHeadingEnabled

- (BOOL) autoHeadingEnabled

readwritenonatomicassign

Indicates whether the camera's position changes in sync with the target's heading to keep that same cameraHeadingOffset property relative to the target's symbol. Default value is YES. If set to NO, you'll notice changes in the target's heading, otherwise the target's heading will appear constant even when it changes because the camera will re-position to offset it.

Since

100.1

autoPitchEnabled

- (BOOL) autoPitchEnabled

readwritenonatomicassign

Indicates whether the camera's position changes in sync with the target's pitch to keep that same cameraPitchOffset property relative to the target's symbol. The default value is YES. If set to NO, you'll notice changes in the target's pitch, otherwise the target's pitch will appear constant even when it changes because the camera will re-position to offset it.

Since

100.1

autoRollEnabled

- (BOOL) autoRollEnabled

readwritenonatomicassign

Indidates whether the camera's roll changes in sync with the target's roll. The default value is YES. If set to NO, you'll notice changes in the target's roll, otherwise the target's roll will appear constant even when it changes because the camera will offset it.

Since

100.1

cameraDistance

- (double) cameraDistance

readwritenonatomicassign

The distance between the camera and the target, in meters. The camera position is derived from this distance plus the camera heading and pitch offsets.

Since

100.1

cameraDistanceInteractive

- (BOOL) cameraDistanceInteractive

readwritenonatomicassign

Indicates if the camera's distance to the target can be changed by user-interaction, for example zooming.

Since

100.1

cameraHeadingOffset

- (double) cameraHeadingOffset

readwritenonatomicassign

The camera heading offset relative to the target's symbol, in degrees. It is a measure of the clockwise angle in the target symbol's horizontal plane starting directly behind the symbol. The default value is 0 degrees.

If this value is not in the range between minCameraHeadingOffset and maxCameraHeadingOffset, it will be normalized as follows:

• If cameraHeadingOffset < minCameraHeadingOffset, then 360 will be added until the new value is above minCameraHeadingOffset. If the new value is less than maxCameraHeadingOffset, it will be used. Otherwise, the value will be set to minCameraHeadingOffset.
• If cameraHeadingOffset > maxCameraHeadingOffset, then 360 will be subtracted until the new value is below maxCameraHeadingOffset. If the new value is greater than minCameraHeadingOffset, it will be used. Otherwise, the value will be set to maxCameraHeadingOffset.

See also

autoHeadingEnabled to maintain the same camera heading relative to the target's symbol even when the target's heading changes.

Since

100.1

cameraHeadingOffsetInteractive

- (BOOL) cameraHeadingOffsetInteractive

readwritenonatomicassign

Indicates if the camera's heading relative to the target can be changed by user-interaction, for example panning horizontally.

Since

100.1

cameraPitchOffset

- (double) cameraPitchOffset

readwritenonatomicassign

The camera pitch offset relative to the target's symbol, in degrees. It is a measure of the counterclockwise angle from the positive Z axis of the target's symbol to the symbol's horizontal plane. The default value is 45 degrees.

The value will be clamped to minCameraPitchOffset and maxCameraPitchOffset.

See also

autoPitchEnabled to keep the same relative pitch to the target's symbol even when the target changes its pitch.

Since

100.1

cameraPitchOffsetInteractive

- (BOOL) cameraPitchOffsetInteractive

readwritenonatomicassign

Indicates if the camera's pitch relative to the target can be changed by user-interaction, for example panning vertically.

Since

100.1

maxCameraDistance

- (double) maxCameraDistance

readwritenonatomicassign

The maximum distance from the camera to the targetGeoElement property in meters. Interactions and animations obey this limit. Serves as the max value for the cameraDistance property.

Since

100.1

maxCameraHeadingOffset

- (double) maxCameraHeadingOffset

readwritenonatomicassign

The maximum camera heading offset relative to the target's symbol, in degrees. Default value is 180. Interactions and animations obey this limit. Serves as the max value for the cameraHeadingOffset property.

Since

100.1

maxCameraPitchOffset

- (double) maxCameraPitchOffset

readwritenonatomicassign

The maximum camera pitch offset relative to the target's symbol, in degrees. Interactions and animations obey this limit. Serves as the max value for the cameraPitchOffset property.

Since

100.1

minCameraDistance

- (double) minCameraDistance

readwritenonatomicassign

The minimum distance from the camera to the targetGeoElement property in meters. Interactions and animations obey this limit. Serves as the min value for the cameraDistance property.

Since

100.1

minCameraHeadingOffset

- (double) minCameraHeadingOffset

readwritenonatomicassign

The minimum camera heading offset relative to the target's symbol, in degrees. Default value is -180. Interactions and animations obey this limit. Serves as the min value for the cameraHeadingOffset property.

Since

100.1

minCameraPitchOffset

- (double) minCameraPitchOffset

readwritenonatomicassign

The minimum camera pitch offset relative to the target's symbol, in degrees. Interactions and animations obey this limit. Serves as the min value for the cameraPitchOffset property.

Since

100.1

targetGeoElement

- (id<AGSGeoElement>) targetGeoElement

readnonatomicstrong

The geo-element that the camera should orbit.

Since

100.1

targetOffsetX

- (double) targetOffsetX

readwritenonatomicassign

Specifies an offset of the target focus point relative to the target object in the X axis in the symbol coordinate system. A non-zero value offsets the camera target from the targetGeoElement property along the X axis. Default value is 0.

Since

100.1

targetOffsetY

- (double) targetOffsetY

readwritenonatomicassign

Specifies an offset of the target focus point relative to the target object in the Y axis in the symbol coordinate system. A non-zero value offsets the camera target from the targetGeoElement property along the Y axis. Default value is 0.

Since

100.1

targetOffsetZ

- (double) targetOffsetZ

readwritenonatomicassign

Specifies an offset of the target focus point relative to the target object in the Z axis in the symbol coordinate system. A non-zero value offsets the camera target from the targetGeoElement property along the Z axis. Default value is 0.

Since

100.1

targetVerticalScreenFactor

- (float) targetVerticalScreenFactor

readwritenonatomicassign

Specifies the vertical position of the target on the screen. Allowed values range from 0 (bottom of screen) to 1 (top). Default value is 0.5. The target is centered vertically on the screen.

Since

100.1