You are reading the documentation for the version 2 of the ShapeDiver viewer API. Free support for this viewer version will be discontinued on June 1st, 2024.

Please refer to the version 3 documentation here. See also the migration guide from version 2 to version 3 here.

Interface: ArApiInterface

api.ar

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

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:

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

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

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

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

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:

ShapeDiver 3D Viewer, Copyright © 2015-2019 ShapeDiver GmbH. Documentation generated by JSDoc 3.6.5 on Tue Sep 8th 2020 using the DocStrap template.