Interface: ArApiInterface

Methods

addEventListener(type, callback)

Add a callback to be invoked when a certain AR event occurs

Parameters:

Name	Type	Description
type	AREventType	Type of AR event to subscribe to
callback	AREventListenerCallback	Function to be called when the event fires

Returns:

Type	Description
APIResponse	API Response with an EventListenerToken object. The event listener token can be used to remove the event listener by calling removeEventListener.

getPlacementAnchor(runtimeId)

Get id of anchor currently used for object placement. Use this to check whether object has been placed yet.

Parameters:

Name	Type	Description
runtimeId	String	Runtime id of the plugin whose currently used placement anchor shall be returned (ignored for now)

Returns:

Type	Description
APIResponse	API Response containing id of currently used placement anchor, empty string in case no anchor is set

getStatus()

Get status of AR interface

Returns an object describing the status of the AR interface. This function should be used to detect whether AR functionality is available.

Returns:

Type	Description
Promise.<APIResponse>	API response with data of type ARStatusType in case AR functionality, or data set to a falsy value if AR functionality is not available.

hitTest(screenX, screenY, types)

Run a hit test, based on the latest available frame

CAUTION: Be aware that the coordinates screenX and screenY are normalized screen coordinates. The point (0,0) represents the top left corner of the screen, and the point (1,1) represents the bottom right corner. As of now the AR view in the ShapeDiver App always occupies the complete screen, and the webview on top of it occupies the complete screen as well. The coordinates need to be given with respect to the complete screen.

For ARKit refer to these documentation pages:

• ARFrame
• ARHitTestResult
• ARFrame.hitTest

Parameters:

Name	Type	Description
screenX	Number	Normalized screen X coordinate (considering the complete screen of the device).
screenY	Number	Normalized screen Y coordinate (considering the complete screen of the device).
types	String | Array.<String>	Optional. The types of hit-test result to search for. String or array of strings according to the following list: for ARKit (see hit test result types): 'featurePoint' 'estimatedHorizontalPlane' 'estimatedVerticalPlane' 'existingPlane' 'existingPlaneUsingExtent' 'existingPlaneUsingGeometry' Defaults to the setting ar.defaultHitTestType, see updateSettingAsync

Returns:

Type	Description
Promise	Promise which resolves to an array of ARHitTestResult on success (may be empty).

pauseSession()

Pause the AR session

While paused, the session doesn't track device motion or capture scene images using the device camera

For ARKit refer to these documentation pages:

• ARSession.pause

Returns:

Type	Description
Promise	Promise which resolves once the session has been paused.

registerAnchor(transform, name)

Register an anchor

Anchors should be registered for virtual objects placed in the scene, this helps tracking. When moving a virtual object, remove the existing anchor and register a new one.

Register an event listener to ANCHOR_UPDATE to receives updates to the anchor's position.

For ARKit refer to these documentation pages:

• ARAnchor
• ARSession.add

Parameters:

Name	Type	Description
transform	THREE.Matrix4	Tranformation of new anchor
name	String	Optional descriptive name to use for the anchor, not supported for ARCore

Returns:

Type	Description
Promise	Promise which resolves to a unique identifier (String) of the newly added anchor.

removeAnchor(uuid)

Remove an anchor

Use this function to remove an anchor previously added using registerAnchor

For ARKit refer to these documentation pages:

• ARAnchor
• ARSession.remove

Parameters:

Name	Type	Description
uuid	String	Unique identifier of the anchor to remove

Returns:

Type	Description
Promise	Promise which resolves to a boolean indicating whether the anchor could be removed.

removeEventListener(token)

Remove an event listener for an AR event type

Parameters:

Name	Type	Description
token	EventListenerToken	event listener token for event listener to be removed

Returns:

Type	Description
APIResponse	API Response with a Boolean data, indicating whether the event listener could be removed.

resetPlacementAnchor(runtimeId)

Reset anchor currently used for object placement.

This results in the object going back to placement mode.

Parameters:

Name	Type	Description
runtimeId	String	Runtime id of the plugin whose currently used placement anchor shall be reset (ignored for now)

Returns:

Type	Description
APIResponse	API Response containing id of previously used placement anchor, empty string in case no anchor was set

runSession(planeDetection, options)

Start running the AR session, continue running the AR session after it has been paused, reconfigure a running session, or reset tracking for a running session.

Running the AR session does not automatically switch the default viewport to AR mode. The AR session can be run in the background, without updating the default viewport based on tracking information. Synchronization of the camera has to be enabled separately, using the setting ar.enableCameraSync.

Call this function for a running AR session if you want it to be reconfigured or reset.

For ARKit refer to these documentation pages:

• ARSession.run

Parameters:

Name	Type	Description
planeDetection	String | Array.<String>	Optional. The types of planes that should be detected automatically. Defaults to no plane detection, respectively to the settings of the AR App. Array containing strings according to the following list: for ARKit (see world tracking configuration) 'horizontal' 'vertical'
options	String | Array.<String>	Optional. The options for running the session. No default options are set. Array containing strings according to the following list: for ARKit (see also run options) 'removeExistingAnchors' 'resetTracking' 'detectImages' (in this case ARKit's pure image tracking will be used, if no plane types are configured to be detected automatically)

Returns:

Type	Description
Promise	Promise which resolves once the command has been processed by the app.

setPlacementAnchor(anchorId, runtimeId)

Set id of anchor to be used for object placement.

Parameters:

Name	Type	Description
anchorId	String	Id of anchor to be used for object placement.
runtimeId	String	Runtime id of the plugin whose placement anchor shall be set (ignored for now)

Returns:

Type	Description
APIResponse	API Response containing id of previously used placement anchor, empty string in case no anchor was set

Members

<readonly> EVENTTYPE :AREventType

Enum for supported AR event types.

Type:

• AREventType

Properties:

Name	Type	Default	Description
ANCHOR_CREATE_IMAGE	AREventType	anchor.create.image	a new image anchor has been created, updates to its position will be part of ANCHOR_UPDATE events
ANCHOR_UPDATE	AREventType	anchor.update	anchor positions have been updated
OBJECT_PLACEMENT	AREventType	object.placement	placement anchor of object has changed
STATUS_TRACKING	AREventType	status.tracking	the status of tracking of the device (camera) has changed
STATUS_MAPPING	AREventType	status.mapping	the status of mapping of the virtual world has changed
STATUS_WEBVIEW_DIDAPPEAR	AREventType	status.webview.didappear	the webview contained in the native AR app did appear
STATUS_WEBVIEW_WILLDISAPPEAR	AREventType	status.webview.willdisappear	the webview contained in the native AR app will disappear

Type Definitions

ARAnchor

Type:

• Object

Properties:

Name	Type	Description
transform	THREE.Matrix4	the anchor's 4x4 transformation matrix
isTracked	Boolean	true if the transform is currently up to date for ARKit this property will always be true for anchors other than image anchors
uuid	String	unique id of the anchor
name	String	optional name of the anchor
plane	Object	optional data for a plane anchor for ARKit see plane anchor Properties Name Type Description alignment String alignment of plane, one of: for ARKit (see plane alignment types) 'none' 'horizontal' 'vertical' classification String optional classification of plane, one of: for ARKit (see plane classification types) 'none' 'ceiling' 'floor' 'seat' 'table' 'wall' 'window' 'door' center THREE.Vector3 center point of the plane relative to its anchor position, for ARKit see plane anchor center extent THREE.Vector3 estimated width and length of the detected plane, for ARKit see plane anchor extent
image	Object	optional data for an image anchor for ARKit see image anchor Properties Name Type Description name String optional name of the detected image width Number physical width of the image (width that was provided alongside the image as additional information for tracking) height Number physical height of the image (height that was provided alongside the image as additional information for tracking)

AREvent

AR event type definition

Type:

• Object

Properties:

Name	Type	Argument	Description
type	String		type of event as specified when registering an event listener
api	Object		Reference to the instance of the API object which was used to register the event listener
image	ARAnchor	<optional>	new image anchor, updates to the image anchor will be part of property 'anchors' for ARKit see image anchor
anchors	Object.<String, ARAnchor>	<optional>	updated anchors, object mapping anchor uuid to anchor
tracking	String	<optional>	describes position tracking quality, one of: for ARKit (see camera tracking status) 'notAvailable' 'limited' 'normal'
trackingReason	String	<optional>	describes possible reasons for 'limited' position tracking quality, one of: for ARKit (see camera tracking reason) '' (in case tracking is not 'limited') 'initializing' 'relocalizing' 'excessiveMotion' 'insufficientFeatures'
worldMapping	String	<optional>	describes how thoroughly the currently visible part of the virtual world has already been mapped, one of: for ARKit (see world mapping status) 'notAvailable' 'limited' 'extending' 'mapped'
runtimeId	String	<optional>	OBJECT_PLACEMENT events: Runtime id of the plugin whose placement anchor changed
anchorId	String	<optional>	OBJECT_PLACEMENT events: Anchor id of the placement anchor

AREventListenerCallback(event)

Event listener callback

Parameters:

Name	Type	Description
event	AREvent	AR event object depending on event type

AREventType

AR event type, see EVENTTYPE for values

See:

• addEventListener

Type:

• String

ARHitTestResult

Type:

• Object

Properties:

Name	Type	Description
type	Array.<String>	The kind of detected feature the search result represents. Array containing strings like one of the following: for ARKit (see hit test result types): 'featurePoint' 'estimatedHorizontalPlane' 'estimatedVerticalPlane' 'existingPlane' 'existingPlaneUsingExtent' 'existingPlaneUsingGeometry'
anchor	ARAnchor	The anchor representing the detected surface, if any.
distance	Number	The distance, in meters, from the camera to the detected surface.
worldTransform	THREE.Matrix4	The position and orientation of the hit test result relative to the world coordinate system.
localTransform	THREE.Matrix4	The position and orientation of the hit test result relative to the nearest anchor or feature point.

ARStatusType

AR status type definition

Type:

• Object

Properties:

Name	Type	Argument	Description
framework	String		framework which provides AR functionality, one of 'none' (AR functionality not available) 'arkit' 'arcore'
anchors	Object.<String, ARAnchor>	<optional>	anchors currently known, object mapping anchor uuid to anchor
tracking	String	<optional>	describes position tracking quality, one of: for ARKit (see camera tracking status) 'notAvailable' 'limited' 'normal'
trackingReason	String	<optional>	describes possible reasons for 'limited' position tracking quality, one of: for ARKit (see camera tracking reason) '' (in case tracking is not 'limited') 'initializing' 'relocalizing' 'excessiveMotion' 'insufficientFeatures'
worldMapping	String	<optional>	describes how thoroughly the currently visible part of the virtual world has already been mapped, one of: for ARKit (see world mapping status) 'notAvailable' 'limited' 'extending' 'mapped'