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

Figure 1. Public inheritance diagram for NMAARController

[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] NMAGeoCoordinatesalternativeLocation

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] NMAARCameraParameterscameraParameters

Advanced camera view configuration parameters.

See also:

NMAARCameraParameters

[readable, writable, weak] id< NMAARControllerDelegatedelegate

The delegate for receiving general LiveSight event and status changes.

[readable, writable, weak] id< NMAARControllerGestureDelegategestureDelegate

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

[readable, assign] BOOL isStarted

Indicates whether or not LiveSight has started.

[readable, assign] NMAGeoCoordinateslocation

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] NMAARPoseReadingposeReading

The latest LiveSight pose (device location and orientation).

Note:

Method 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:

-(void) addObject:( NMAARObject *) object

Adds an NMAARObject 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:

-(void) addPolylineObject:( NMAARPolylineObject *) object

Adds an NMAARPolylineObject 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:

-(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:

-( 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.

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:

-(void) removeModelObject:( NMAARModelObject *) object

Removes an NMAARModelObject from the camera view.

Parameters:

-(void) removeObject:( NMAARObject *) object

Removes an NMAARObject from the camera view.

Parameters:

-(void) removePolylineObject:( NMAARPolylineObject *) object

Removes an NMAARModelObject from the camera view.

Parameters:

-(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:

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

Select an NMAARObject in the camera view with optional configuration.

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 given time.

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.