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
| Public Properties |
|---|
| [readable, writable, assign] An alternative device location to use for LiveSight |
| [readable, assign] Advanced camera view configuration parameters |
| [readable, writable, weak] The delegate for receiving general LiveSight event and status changes |
| [readable, writable, weak] The delegate for receiving gesture callbacks from the LiveSight camera view |
| [readable, assign] Indicates whether or not LiveSight has started |
| [readable, assign] The last known device location or nil if the location is unknown |
| [readable, writable, assign] The GPS location distance threshold, in meters, used to determine when object projection is updated |
| [readable, assign] The latest LiveSight pose (device location and orientation) |
| [readable, writable, assign] The projection type used to display NMAARObjects in the camera view |
| [readable, writable, assign] Controls whether only front plane objects are displayed in the camera view |
Instance Method Summary
| Instance Method Summary |
|---|
| Adds an NMAARModelObject that will be displayed in the camera view |
| Adds an NMAARObject that will be displayed in the camera view |
| Adds an NMAARPolylineObject that will be displayed in the camera view |
| Defocuses a previously focused NMAARObject in the camera view Back plane |
| Deselects a previously selected NMAARObject in the camera view |
| Focuses an NMAARObject in the camera view back plane |
| |
| Returns the NMAARObject at a given point if available and optionally renders the object as pressed |
| Retrieves NMAARObjects at a specified screen point |
| Retrieves NMAARObjects which intersect a specified screen rect |
| Renders an NMAARObject as pressed |
| Removes an NMAARModelObject from the camera view |
| Removes an NMAARObject from the camera view |
| Removes an NMAARModelObject from the camera view |
| Selects an NMAARObject in the camera view |
| Select an NMAARObject in the camera view with optional configuration |
| Sets the front plane icon size, in points, for NMAARIconObjects |
| Starts the LiveSight camera view |
| Stops the LiveSight camera view |
| Renders an NMAARObject as not pressed (the default state) |
Class Method Summary
| Class Methods |
|---|
| |
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:
[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).
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.
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.
Only applicable when the projection type is NMAARProjectionTypeNearFar.
Instance Method Details
-(void) addModelObject:(nonnull NMAARModelObject *) object
Adds an NMAARModelObject that will be displayed in the camera view.
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:
-
objectThe NMAARModelObject to add to the
NMAARController.
-(void) addObject:(nonnull NMAARObject *) object
Adds an NMAARObject that will be displayed in the camera view.
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:
-
objectThe NMAARObject to add to the
NMAARController.
-(void) addPolylineObject:(nonnull NMAARPolylineObject *) object
Adds an NMAARPolylineObject that will be displayed in the camera view.
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:
-
objectThe 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.
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.
Object selection only applies to the camera view.
-(void) focusObject:(nonnull 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.
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:
-
objectThe NMAARObject to focus.
-(nonnull instancetype) init
Instances of this class should not be initialized directly
-(nullable 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.
Object press is only applicable in the camera view. An object can be rendered pressed regardless of its selected or focused state.
Parameters:
-
pointThe point in the associated NMAARCompositeView at which to check for an object.
-
pressA BOOL indicating whether or not to press the returned object.
Returns:
The NMAARObject at the given point, or nil if no object is present.
-(nullable NSArray< NMAARObject * > *) objectsAtPoint:(CGPoint) point
Retrieves NMAARObject s at a specified screen point.
Parameters:
-
pointThe 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.
-(nullable NSArray< NMAARObject * > *) objectsInRect:(CGRect) rect
Retrieves NMAARObject s which intersect a specified screen rect.
Parameters:
-
rectThe 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:(nonnull 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.
Object press is only applicable in the camera view. An object can be rendered pressed regardless of its selected or focused state.
Parameters:
-
objectThe NMAARObject to render as pressed.
-(void) removeModelObject:(nonnull NMAARModelObject *) object
Removes an NMAARModelObject from the camera view.
Parameters:
-
objectThe NMAARModelObject to remove from the
NMAARController.
-(void) removeObject:(nonnull NMAARObject *) object
Removes an NMAARObject from the camera view.
Parameters:
-
objectThe NMAARObject to remove from the
NMAARController.
-(void) removePolylineObject:(nonnull NMAARPolylineObject *) object
Removes an NMAARModelObject from the camera view.
Parameters:
-
objectThe NMAARModelObject to remove from the
NMAARController.
-(void) selectObject:(nonnull 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.
Object selection only applies to the camera view.
Parameters:
-
objectThe NMAARObject to select.
-(void) selectObject:(nonnull 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).
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:
-
objectThe NMAARObject to be marked as selected.
-
allowInfoA BOOL value indicating whether the object's info image should be displayed while the object is selected.
-
scaleThe 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.
If the front plane icon size is not specified explicitly, it will be inferred from the first icon object added to the LiveSight view.
-(nullable 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.
-(nullable 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:
-
animationIf 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:(nonnull 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.
Object press is only applicable in the camera view.
Parameters:
-
objectThe NMAARObject to render unpressed; this method has no effect if the object is not currently pressed.
Class Method Details
+(nonnull instancetype) new
Instances of this class should not be initialized directly