HERE iOS SDK Developer's Guide

NMAARController

Class Summary

class NMAARController

Derived from: NSObject

NMAARController is used to start and configure LiveSight functionality.

Include: NMAKit.framework/headers/NMAARController.h

Inheritance Diagrams

[For complete information, see the section Class Details]

Public Property Summary

Table 1. Public Properties
Public Properties
[readable, writable, assign] `NMAGeoCoordinates * alternativeLocation` An alternative device location to use for LiveSight
[readable, assign] `NMAARCameraParameters * cameraParameters` Advanced camera view configuration parameters
[readable, writable, weak] `id< NMAARControllerDelegate > delegate` The delegate for receiving general LiveSight event and status changes
[readable, writable, weak] `id< NMAARControllerGestureDelegate > gestureDelegate` The delegate for receiving gesture callbacks from the LiveSight camera view
[readable, assign] `BOOL isStarted` Indicates whether or not LiveSight has started
[readable, assign] `NMAGeoCoordinates * location` The last known device location or nil if the location is unknown
[readable, writable, assign] `float objectUpdateGpsDistanceThreshold` The GPS location distance threshold, in meters, used to determine when object projection is updated
[readable, assign] `NMAARPoseReading * poseReading` The latest LiveSight pose (device location and orientation)
[readable, writable, assign] `NMAARProjectionType projectionType` The projection type used to display NMAARObjects in the camera view
[readable, writable, assign] `BOOL showFrontPlaneObjectsOnly` Controls whether only front plane objects are displayed in the camera view

Instance Method Summary

Table 2. Instance Methods
Instance Method Summary
`-(void) addModelObject:( NMAARModelObject *) object` Adds an NMAARModelObject that will be displayed in the camera view
`-(void) addObject:( NMAARObject *) object` Adds an NMAARObject that will be displayed in the camera view
`-(void) addPolylineObject:( NMAARPolylineObject *) object` Adds an NMAARPolylineObject that will be displayed in the camera view
`-(void) defocusObject` Defocuses a previously focused NMAARObject in the camera view Back plane
`-(void) deselectObject` Deselects a previously selected NMAARObject in the camera view
`-(void) focusObject:( NMAARObject *) object` Focuses an NMAARObject in the camera view back plane
`-( NMAARObject *) objectAtPoint:(CGPoint) point withPress:(BOOL) press` Returns the NMAARObject at a given point if available and optionally renders the object as pressed
`-(NSArray *) objectsAtPoint:(CGPoint) point` Retrieves NMAARObjects at a specified screen point
`-(NSArray *) objectsInRect:(CGRect) rect` Retrieves NMAARObjects which intersect a specified screen rect
`-(void) pressObject:( NMAARObject *) object` Renders an NMAARObject as pressed
`-(void) removeModelObject:( NMAARModelObject *) object` Removes an NMAARModelObject from the camera view
`-(void) removeObject:( NMAARObject *) object` Removes an NMAARObject from the camera view
`-(void) removePolylineObject:( NMAARPolylineObject *) object` Removes an NMAARModelObject from the camera view
`-(void) selectObject:( NMAARObject *) object` Selects an NMAARObject in the camera view
`-(void) selectObject:( NMAARObject *) object allowInfo:(BOOL) allowInfo scale:(CGFloat) scale` Select an NMAARObject in the camera view with optional configuration
`-(void) setFrontPlaneIconSize:(CGSize) size` Sets the front plane icon size, in points, for NMAARIconObjects
`-(NSError *) start` Starts the LiveSight camera view
`-(NSError *) stopWithAnimation:(BOOL) animation` Stops the LiveSight camera view
`-(void) unpressObject:( NMAARObject *) object` Renders an NMAARObject as not pressed (the default state)

Class Details

NMAARController is used to start and configure LiveSight functionality.

When LiveSight is started it will begin to control the associated NMACompositeView and display a LiveSight camera view.

In the default projection mode (NMAARProjectionTypeNearFar), LiveSight objects are displayed in either the front plane or the back plane based on their geographical distance from the device. Objects in the front plane appear closer to the bottom of the camera view and objects in the back plane appear closer to the top of the view. Objects have different apperance and exhibit different behaviours in each plane.

Objects geographically closer to the device are placed in the front plane. Performing a pan down gesture has the visual effect of moving objects from the back plane to the front plane but the gesture is actually just changing the geocoordinates that define the boundary between the two planes and hence changing the definition of which objects are considered "near" and "far".

NMAARControllerDelegate reports LiveSight events including view changes.

Public Property Details

[readable, writable, assign] NMAGeoCoordinates * alternativeLocation

An alternative device location to use for LiveSight.

This method may be used to force LiveSight to use an alternative to the current device location during testing. The alternative location will be reflected by the location and poseReading properties.

This default value is nil, in which case the actual device location is used.

[readable, assign] NMAARCameraParameters * cameraParameters

Advanced camera view configuration parameters.

See also:

NMAARCameraParameters

[readable, writable, weak] id< NMAARControllerDelegate > delegate

The delegate for receiving general LiveSight event and status changes.

[readable, writable, weak] id< NMAARControllerGestureDelegate > gestureDelegate

The delegate for receiving gesture callbacks from the LiveSight camera view.

[readable, assign] BOOL isStarted

Indicates whether or not LiveSight has started.

[readable, assign] NMAGeoCoordinates * location

The last known device location or nil if the location is unknown.

This is a convenience method that creates a geo coordinates from the current pose reading.

[readable, writable, assign] float objectUpdateGpsDistanceThreshold

The GPS location distance threshold, in meters, used to determine when object projection is updated.

When the distance between the current GPS location the location of the last projection update is bigger than the threshold, the camera view projection of objects is updated.

The default value is 3 meters.

[readable, assign] NMAARPoseReading * poseReading

The latest LiveSight pose (device location and orientation).

Note:

NMAARControllerDelegatedidUpdatePose:::arController:didUpdatePose: is called when the pose changes.

[readable, writable, assign] NMAARProjectionType projectionType

The projection type used to display NMAARObject s in the camera view.

Attempts to set this property to NMAARProjectionTypeGlobal will be ignored.

Note:

NMAARObject instances may override this default by setting an explicit projectionType.

[readable, writable, assign] BOOL showFrontPlaneObjectsOnly

Controls whether only front plane objects are displayed in the camera view.

Front plane object have their info images visible.

Note:

Only applicable when the projection type is NMAARProjectionTypeNearFar.

Instance Method Details

-(void) addModelObject:( NMAARModelObject *) object

Adds an NMAARModelObject that will be displayed in the camera view.

Note:

Objects should not be added whilst Livesight is in a "starting" state as this may cause the main thread to block. I.e. Don't add objects after calling [ NMAARController start] until the [ NMAARControllerDelegate arControllerDidEnterCameraView:] callback has returned.

Parameters:

object
The NMAARModelObject to add to the NMAARController .

-(void) addObject:( NMAARObject *) object

Adds an NMAARObject that will be displayed in the camera view.

Note:

Parameters:

object
The NMAARObject to add to the NMAARController .

-(void) addPolylineObject:( NMAARPolylineObject *) object

Adds an NMAARPolylineObject that will be displayed in the camera view.

Note:

Parameters:

object
The NMAARPolyline to add to the NMAARController .

-(void) defocusObject

Defocuses a previously focused NMAARObject in the camera view Back plane.

Returns the object to its original position among all other objects in the camera view back plane.

Note:

Object focus only applies to the camera view back plane.

-(void) deselectObject

Deselects a previously selected NMAARObject in the camera view.

When an object is unselected, its info image (if set) expands, the front plane image is used instead of the back plane image (if item is in front plane), the item is scaled to normal size, and all opacities change to default values.

Note:

Object selection only applies to the camera view.

-(void) focusObject:( NMAARObject *) object

Focuses an NMAARObject in the camera view back plane.

Focusing brings the object in front of other items and expands its info image.

An object becomes defocused automatically if another object is focused; only one object can be in focus at a time.

Note:

Object focus only applies to the camera view back plane. An object may not be selected and focused at the same time. Focusing a selected object will deselect the object and vice versa.

Parameters:

object
The NMAARObject to focus.

-( NMAARObject *) objectAtPoint:(CGPoint) point withPress:(BOOL) press

Returns the NMAARObject at a given point if available and optionally renders the object as pressed.

This method is designed to be used in conjunction with NMAARControllerGestureDelegate to implement custom object gestures with visual feedback. Typically an object becomes pressed when a touch down event occurs on that object. Multiple objects may be in the pressed state.

Note:

Object press is only applicable in the camera view. An object can be rendered pressed regardless of its selected or focused state.

Parameters:

point
The point in the associated NMAARCompositeView at which to check for an object.
press
A BOOL indicating whether or not to press the returned object.

Returns:

The NMAARObject at the given point, or nil if no object is present.

-(NSArray *) objectsAtPoint:(CGPoint) point

Retrieves NMAARObject s at a specified screen point.

Parameters:

point
The point within the associated NMAARCompositeView at which to check for NMAARObjects.

Returns:

An array of NMAARObject s, or nil if no objects are located at the specified point.

-(NSArray *) objectsInRect:(CGRect) rect

Retrieves NMAARObject s which intersect a specified screen rect.

Parameters:

rect
The screen rect within the associated NMAARCompositeView inside which to check for NMAARObjects.

Returns:

An array of NMAARObject s, or nil if no objects intersect the specified rect.

-(void) pressObject:( NMAARObject *) object

Renders an NMAARObject as pressed.

Note:

Object press is only applicable in the camera view. An object can be rendered pressed regardless of its selected or focused state.

Parameters:

object
The NMAARObject to render as pressed.

-(void) removeModelObject:( NMAARModelObject *) object

Removes an NMAARModelObject from the camera view.

Parameters:

object
The NMAARModelObject to remove from the NMAARController .

-(void) removeObject:( NMAARObject *) object

Removes an NMAARObject from the camera view.

Parameters:

object
The NMAARObject to remove from the NMAARController .

-(void) removePolylineObject:( NMAARPolylineObject *) object

Removes an NMAARModelObject from the camera view.

Parameters:

object
The NMAARModelObject to remove from the NMAARController .

-(void) selectObject:( NMAARObject *) object

Selects an NMAARObject in the camera view.

Any object in camera view can be in the selected state regardless of its plane. Selected objects are rendered differently than "focused" objects. An object is automatically unselected if another object is selected. Only one object can be selected at a time.

When selected, the object's info image collapses and the back plane image replaces the front plane image (if the object is in the front plane). The appearance of selected and deselected objects will be configurable in future SDK releases.

Note:

Object selection only applies to the camera view.

Parameters:

object
The NMAARObject to select.

-(void) selectObject:( NMAARObject *) object allowInfo:(BOOL) allowInfo scale:(CGFloat) scale

Select an NMAARObject in the camera view with optional configuration.

When selected, the object's info image collapses, the back plane image replaces the front plane image (if the object is in the front plane) and the image is scaled (if specified).

Note:

Object selection only applies to the camera view. An object may not be selected and focused at the same time. Selecting a focused object will defocus the object and vice versa.

Parameters:

object
The NMAARObject to be marked as selected.
allowInfo
A BOOL value indicating whether the object's info image should be displayed while the object is selected.
scale
The amount to scale the object's image by when selected.

-(void) setFrontPlaneIconSize:(CGSize) size

Sets the front plane icon size, in points, for NMAARIconObjects.

Before adding icon objects to the LiveSight view, the front plane icon size should be specified here. For optimal results, only a single icon size should be used.

Note:

If the front plane icon size is not specified explicitly, it will be inferred from the first icon object added to the LiveSight view.

-(NSError *) start

Starts the LiveSight camera view.

If LiveSight is successfully started then the LiveSight camera view will be presented and NMAARDelegate::arController:arControllerDidEnterCameraView: will be called.

NMAARDelegate::arController:errorOccurred: will be called if LiveSight experiences an unrecoverable error during startup or subsequent operations.

Returns:

nil if the start up sequence is initialized, otherwise an NSError populated with an NMAARError code. The error NMAARErrorOperationNotAllowed indicates that an updated HERE license key is required. Contact your HERE representative for more information.

-(NSError *) stopWithAnimation:(BOOL) animation

Stops the LiveSight camera view.

NMAARDelegate::arController:errorOccurred: will be called with NMAARErrorStopped when exit animations have completed and LiveSight has stopped.

When LiveSight is stopped the NMACompositeView will render a solid black view.

Parameters:

animation
If YES, an exit animation is performed before stopping LiveSight. This parameter is currently ignored.

Returns:

nil if the stop request succeeded, otherwise an NSError populated with an NMAARError error code.

-(void) unpressObject:( NMAARObject *) object

Renders an NMAARObject as not pressed (the default state).

This method is designed to be used in conjunction with NMAARControllerGestureDelegate to implement custom object gestures with visual feedback. Typically any pressed objects are unpressed when a touch up event occurs anywhere on the view.

Note:

Object press is only applicable in the camera view.

Parameters:

object
The NMAARObject to render unpressed; this method has no effect if the object is not currently pressed.