ShapeDiver Viewer - AR API
The AR interface is part of the global API of the ShapeDiver Viewer.
Prerequisites for the AR interface are to use a supported device, and to run the ShapeDiver Viewer in a supported environment. Currently the ShapeDiver Viewer can be used in AR mode on all devices running iOS which support ARKit, if the viewer is run inside the ShapeDiver App or inside a client-specific App provided by ShapeDiver. Support for devices running Android and ARCore will be added in the near future.
The AR interface
- allows to switch the default viewport between orbit and AR mode
- allows to configure behavior of the viewer in AR mode by means of settings
- allows to add and remove handlers for related events
- provides access to low level functionality related to AR
- can be configured using settings with prefix
ar.
, see updateSettingAsync
Recommended reading:
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:
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).
- for ARKit (see hit test result types):
-
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:
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:
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:
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:
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.
- for ARKit (see world tracking configuration)
-
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:
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
- for ARKit this property will always be true for anchors other than image anchors
- for ARKit see plane anchor
- for ARKit (see plane alignment types)
- 'none'
- 'horizontal'
- 'vertical'
- for ARKit (see plane classification types)
- 'none'
- 'ceiling'
- 'floor'
- 'seat'
- 'table'
- 'wall'
- 'window'
- 'door'
- for ARKit see plane anchor center
- for ARKit see plane anchor extent
- for ARKit see image anchor
Properties:
Name Type Description transform
THREE.Matrix4 the anchor's 4x4 transformation matrix
isTracked
Boolean true if the transform is currently up to date
uuid
String unique id of the anchor
name
String optional name of the anchor
plane
Object optional data for a plane anchor
Properties
Name Type Description alignment
String alignment of plane, one of:
classification
String optional classification of plane, one of:
center
THREE.Vector3 center point of the plane relative to its anchor position,
extent
THREE.Vector3 estimated width and length of the detected plane,
image
Object optional data for an 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
- for ARKit see image anchor
- for ARKit (see camera tracking status)
- 'notAvailable'
- 'limited'
- 'normal'
- for ARKit (see camera tracking reason)
- '' (in case tracking is not 'limited')
- 'initializing'
- 'relocalizing'
- 'excessiveMotion'
- 'insufficientFeatures'
- for ARKit (see world mapping status)
- 'notAvailable'
- 'limited'
- 'extending'
- 'mapped'
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'
anchors
Object.<String, ARAnchor> <optional>
updated anchors, object mapping anchor uuid to anchor
tracking
String <optional>
describes position tracking quality, one of:
trackingReason
String <optional>
describes possible reasons for 'limited' position tracking quality, one of:
worldMapping
String <optional>
describes how thoroughly the currently visible part of the virtual world has already been mapped, one of:
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:
Type:
- String
-
ARHitTestResult
-
Type:
- Object
- for ARKit (see hit test result types):
- 'featurePoint'
- 'estimatedHorizontalPlane'
- 'estimatedVerticalPlane'
- 'existingPlane'
- 'existingPlaneUsingExtent'
- 'existingPlaneUsingGeometry'
Properties:
Name Type Description type
Array.<String> The kind of detected feature the search result represents. Array containing strings like one of the following:
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
- 'none' (AR functionality not available)
- 'arkit'
- 'arcore'
- for ARKit (see camera tracking status)
- 'notAvailable'
- 'limited'
- 'normal'
- for ARKit (see camera tracking reason)
- '' (in case tracking is not 'limited')
- 'initializing'
- 'relocalizing'
- 'excessiveMotion'
- 'insufficientFeatures'
- for ARKit (see world mapping status)
- 'notAvailable'
- 'limited'
- 'extending'
- 'mapped'
Properties:
Name Type Argument Description framework
String framework which provides AR functionality, one of
anchors
Object.<String, ARAnchor> <optional>
anchors currently known, object mapping anchor uuid to anchor
tracking
String <optional>
describes position tracking quality, one of:
trackingReason
String <optional>
describes possible reasons for 'limited' position tracking quality, one of:
worldMapping
String <optional>
describes how thoroughly the currently visible part of the virtual world has already been mapped, one of: