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

api

ShapeDiver - Viewer API

Definition of the API v2, the default API to use when working with the ShapeDiver 3D Viewer v2. This interface describes the object returned when requesting an API v2 object from an instance of the ShapeDiver 3D Viewer v2, e.g. like so:

// container for the viewport, typically this is a <div>
var _container = document.getElementById('sdv-container-viewport');

// viewer settings (minimum example)
var _viewerSettings = {
  // container to use
  container: _container
};

// create the viewer, get back an API v2 object
var api = new SDVApp.ParametricViewer(_viewerSettings);

// further API v2 objects can be created if needed, each one having its own runtime id:
var api_other = api.getApiV2();
console.log('Runtime id of default API object', api.getRuntimeId());
console.log('Runtime id of second API object', api_other.getRuntimeId());

The API v2 provides access to the

  • 3D scene including geometry, camera, lights, and interactions,
  • plugins, e.g. for adding further instances of the ShapeDiver Communication Plugin,
  • viewports, e.g. for adding and removing viewports,
  • parameters which may have been registered by plugins,
  • AR scene settings which may be available depending on device and environment,
  • exports which may have been registered by plugins,
  • current state of the viewer, and
  • settings

Methods

addEventListener(type, callback)

Add a callback to be invoked when a certain event occurs

Parameters:
Name Type Description
type ApiEventType

Type of event to subscribe to

callback EventListenerCallback

Function to be called when the event fires

Returns:
Type Description
APIResponse

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

createAsynchronousFunctions()

Creates asynchronous functions for all synchronous functions. These functions will then return a promise with the result of the individual functions as the data property.

getRuntimeId()

Get the runtime id used for this API object. The runtime id is used by default as the namespace (= the first part of the scene path) when manipulating the scene (adding and removing assets, etc).

The runtime id can optionally be specified as a setting when creating the API object, otherwise a random one will be created.

// container for the viewer, typically this is a <div>
var _container = document.getElementById('sdv-container');

// viewer settings example, using a given API runtime id
var _viewerSettings = {
  // container to use
  container: _container,
  // we might want to use a specific runtime id for the API v2 object the constructor returns
  runtimeId: 'My_runtime_id',
};

// create the viewer, get back an API v2 object
var api = new SDVApp.ParametricViewer(_viewerSettings);
console.log(api.getRuntimeId()); // shows 'My_runtime_id'

// further API v2 objects can be created if needed:
var api_other = api.getApiV2({runtimeId: 'My_other_runtime_id'});
console.log(api_other.getRuntimeId()); // shows 'My_other_runtime_id'
Returns:
Type Description
String

runtime id used for API instance, should be unique

getSetting(key)

Provides a copy of an individual setting

See:
Parameters:
Name Type Description
key String

name of setting (e.g. 'scene.render.shadows')

Returns:
Type Description
*

a copy of the setting, undefined if not found

getSettingDefinitions()

Provides an object describing all available settings

See:
Returns:
Type Description
Object

object describing all available settings, their type, and constraints

getSettings( [keys])

Provides a copy of all or multiple settings

See:
Parameters:
Name Type Argument Description
keys Array.<String> <optional>

optional array of keys, keys which don't exist are ignored, if omitted all settings will be returned

Returns:
Type Description
Object

object containing a copy of the settings

removeEventListener(token)

Remove an event listener

Parameters:
Name Type Description
token EventListenerToken

event listener token for event listener to be removed

Returns:
Type Description
APIResponse

APIResponse with a Boolean data, indicating whether the event listener could be removed.

saveSettingsAsync()

Persistently store current state of settings. This will fail if there is no plugin providing the capability to store model settings. Instances of the CommPlugin provide this capability in case the model view session allows this.

Properties:
Name Type Argument Description
plugin String <optional>

Optional runtime id of plugin to use for storing settings. Leave undefined to automatically choose a plugin which supports storing settings.

Returns:
Type Description
Promise.<APIResponse>

APIResponse whose data property will be true or false depending on success.

updateSettingAsync(key, val)

Update an individual setting, if allowed

Name of setting Type Description
blurSceneWhenBusy Boolean Blur or don't blur the scene while a process is busy
defaultMaterial.color Color Color of the default material
defaultMaterial.bumpAmplitude Number Bump amplitude of the default material
defaultMaterial.metalness Number Metalness of the default material
defaultMaterial.roughness Number Roughness of the default material
ignoreSuperseded Boolean Ignore intermediate solutions which at the time of their arrival have already been superseded by another customization request
loggingLevel Number Level of log messages shown on the console, allowed values: -1 (none), 0 (error), 1 (warn), 2 (info), 3 (debug)
messageLoggingLevel Number Log level to be used for logging internal messages, allowed values: -1 (none), 0 (error), 1 (warn), 2 (info), 3 (debug)
ar.enableCameraSync Boolean Enable / disable synchronisation of the camera with AR tracking information. Enabling this will disable the orbit controls.
ar.enableLightingEstimation Boolean Enable / disable automatic lighting estimation. Enabling this stores the current state of the lights which will get restored once automatic lighting estimation gets disabled again.
ar.enableTouchControls Boolean Enable / disable touch controls for placement of objects in the AR scene while AR camera synchronisation is enabled.
ar.enableTouchControlRotation Boolean Enable / disable rotation of objects in the AR scene by means of touch controls. Typically this should be enabled for objects to be placed horizontally.
ar.enableAutomaticPlacement Boolean Enable / disable initial automatic placement of objects in the AR scene as soon as plane anchors get detected. Automatic placement stops once the user starts to interact.
ar.defaultHitTestType String Default type of feature to use for hit tests, used by touch controls.
scene.duration Number Set fade in / fade out duration
scene.camera.autoAdjust Boolean Enable / disable that the camera adjusts to geometry updates
scene.camera.autoRotationSpeed Number Speed of autoration, can be negative, also refer to enableAutoRotation
scene.camera.cameraMovementDuration Number Default duration of camera movements
scene.camera.damping Number How much to damp camera movements by the user
scene.camera.defaults.perspective.position Point3d, Point3dArray Default position for the perspective camera
scene.camera.defaults.perspective.target Point3d, Point3dArray Default target for the perspective camera
scene.camera.defaults.orthographic.position Point3d, Point3dArray Default position for the orthographic camera
scene.camera.defaults.orthographic.target Point3d, Point3dArray Default target for the orthographic camera
scene.camera.enableAutoRotation Boolean Enable / disable automatic rotation of the camera, also refer to autoRotationSpeed
scene.camera.enableKeyPan Boolean Enable / disable panning using the keyboard, also refer to enablePan
scene.camera.enableOrbitControls Boolean Enable / disable orbit controls
scene.camera.enablePan Boolean Enable / disable panning in general, also refer to enableKeyPan
scene.camera.enableRotation Boolean Enable / disable camera rotation
scene.camera.enableZoom Boolean Enable / disable zooming
scene.camera.fov Number Camera frustum vertical field of view angle, unit degree, interval [0,180]
scene.camera.keyPanSpeed Number Speed of panning when using the keyboard
scene.camera.restrictions.position.cube.min Point3d, Point3dArray Restriction of the camera position inside a cube, minimum corner of the cube
scene.camera.restrictions.position.cube.max Point3d, Point3dArray Restriction of the camera position inside a cube, maximum corner of the cube
scene.camera.restrictions.position.sphere.center Point3d, Point3dArray Restriction of the camera position inside a sphere, center of the sphere
scene.camera.restrictions.position.sphere.radius Number Restriction of the camera position inside a sphere, radius of the sphere
scene.camera.restrictions.target.cube.min Point3d, Point3dArray Restriction of the camera target inside a cube, minimum corner of the cube
scene.camera.restrictions.target.cube.max Point3d, Point3dArray Restriction of the camera target inside a cube, maximum corner of the cube
scene.camera.restrictions.target.sphere.center Point3d, Point3dArray Restriction of the camera target inside a sphere, center of the sphere
scene.camera.restrictions.target.sphere.radius Number Restriction of the camera target inside a sphere, radius of the sphere
scene.camera.restrictions.rotation.minPolarAngle Number Minimum polar angle of the camera position with respect to the camera target, unit degree, interval [0,180]
scene.camera.restrictions.rotation.maxPolarAngle Number Maximum polar angle of the camera position with respect to the camera target, unit degree, interval [0,180]
scene.camera.restrictions.rotation.minAzimuthAngle Number Minimum azimuth angle of the camera position with respect to the camera target, unit degree, interval [-180,180]
scene.camera.restrictions.rotation.maxAzimuthAngle Number Maximum azimuth angle of the camera position with respect to the camera target, unit degree, interval [-180,180]
scene.camera.restrictions.zoom.minDistance Number Minimum distance between camera position and target
scene.camera.restrictions.zoom.maxDistance Number Maximum distance between camera position and target
scene.camera.revertAtMouseUp Boolean Enable / disable if the camera should be reset to its default position and target on mouse up
scene.camera.revertAtMouseUpDuration Number The duration of the transition of the revertAtMouseUp
scene.camera.rotationSpeed Number Speed of camera rotation
scene.camera.panSpeed Number Speed of panning
scene.camera.type CameraType Set camera type
scene.camera.zoomExtentsFactor Number Factor to apply to the bounding box before zooming to extents
scene.camera.zoomSpeed Number Speed of zooming
scene.fullscreen Boolean Enable / disable fullscreen mode
scene.gridVisibility Boolean Show / hide the grid
scene.groundPlaneVisibility Boolean Show / hide the ground plane
scene.groundPlaneReflectionVisibility Boolean Enable / disable the reflectivity of the groundplane
scene.groundPlaneReflectionThreshold Number Allows to control the reflectivity of the groundplane
scene.lights.helper Boolean Toggles the light helpers
scene.lights.lightScene String Sets the current light scene to the light scene with this name
scene.material.default.color Color Color of the default material
scene.material.environmentMapAsBackground Boolean Show / hide the environment map in the background
scene.material.environmentMap String, String[] Name of the environment map to use, or an array of 6 image URLs making up the cube mapped environment map
scene.material.environmentMapResolution String Image resolution to be used for the named environment maps (available resolutions: '256', '512', '1024', '2048')
scene.render.ambientOcclusion Boolean Enable / disable ambient occlusion for rendering
scene.render.beautyRenderDelay Number Amount of which the beauty rendering is delayed
scene.render.clearAlpha Number Set background alpha value
scene.render.clearColor Color Set background color
scene.render.pointSize Number Set size of point objects
scene.render.shadows Boolean Enable / disable shadows for rendering
scene.show Boolean Show / hide the scene
showMessages Boolean Show or don't show user messages in the viewport(s)
See:
Parameters:
Name Type Description
key String

name of setting

val Object

new value of setting

Returns:
Type Description
Promise.<APIResponse>

APIResponse whose data property will be true if setting could be changed, false if not.

updateSettingsAsync(settings)

Update a bunch of settings according to the enumerable properties of an object, if allowed.

See:
Parameters:
Name Type Description
settings Object

object whose own properties should be used as settings

Returns:
Type Description
Promise.<APIResponse>

APIResponse whose data property will be set to a copy of the input object, whose property values are replaced by true or false depending on whether the corresponding setting could be updated.

Members

ar :module:ArApiInterface~ArApiInterface

AR interface - use this to switch between orbit and AR mode, and control details of AR mode

Type:

<readonly> EVENTTYPE :ApiEventType

Enum for supported event types.

Type:
Properties:
Name Type Default Description
SETTINGS_UPDATE ApiEventType settings.update

the value of a setting has been changed

SETTINGS_REGISTERED ApiEventType settings.registered

a settings registration request (typically triggered by initialisation of the first CommPlugin) has finished processing and settings have been updated

exports :ApiExportInterface

Export interface - use this to find out which exports have been registered by plugins, and to request exports

See:
Type:

parameters :ApiParameterInterface

Parameter interface - use this to find out which parameters have been registered by plugins, and to update their values, which in turn updates the scene

See:
Type:

plugins :ApiPluginInterface

Plugin interface - use this to register and deregister instances of plugins, ask for their status, etc

Type:

scene :ApiSceneInterface

Scene interface - use this to manage the scene (geometry, interactions)

Type:

state :ApiStateInterface

State interface - use this to observe and manage the general state of the viewer

Type:

viewports :ApiViewportsInterface

Viewports interface - use to manage the viewports

Type:

Type Definitions

AnchorEventData

Data type definition for events of type ANCHOR_ADD or ANCHOR_UPDATE (not emitted by viewer via addEventListener, use updateFunction instead) or ANCHOR_REMOVE

Type:
  • Object
Properties:
Name Type Argument Description
location Point3d

The 3D point defining the location of the anchor

containerX Number <optional>

horizontal coordinate (relative to the top-left corner of the viewer container) of the projected 3D location of the anchor

containerY Number <optional>

vertical coordinate (relative to the top-left corner of the viewer container) of the projected 3D location of the anchor

clientX Number <optional>

horizontal coordinate (relative to the top-left corner of the viewport) of the projected 3D location of the anchor

clientY Number <optional>

vertical coordinate (relative to the top-left corner of the viewport) of the projected 3D location of the anchor

pageX Number <optional>

horizontal coordinate (relative to the top-left corner of the document) of the projected 3D location of the anchor

pageY Number <optional>

vertical coordinate (relative to the top-left corner of the document) of the projected 3D location of the anchor

containerWidth Number <optional>

the width of the viewer container

containerHeight Number <optional>

the height of the viewer container

viewport String <optional>

runtime id of the viewport reporting the anchor position

hidden Boolean <optional>

true if the anchor is hidden behind other objects, false if not

overflow Boolean <optional>

true if the projected 3D anchor position is outside the viewport container

distance Number <optional>

distance between the camera and the anchor location (perspective camera only)

viewingAngle Number <optional>

the angle between the camera direction and direction from the camera origin to the anchor

scenePath ScenePathType <optional>

this specifies the path of the anchor object in the scene graph

format String <optional>

optional format description of the anchor object, this property is passed on from the anchor definition (e.g. text or image)

data Object <optional>

optional data of the anchor object, this property is passed on from the anchor definition (e.g. AnchorDataFormatText or AnchorDataFormatImage)

updateFunction function <optional>

only available in events of type ANCHOR_ADD; can be used to set a callback to receive AnchorEventData events whenever the projected 3D coordinates of the anchor location change. The callback that must be provided has to be of type AnchorUpdateCallback.

AnchorUpdateCallback(event)

Parameters:
Name Type Description
event AnchorEventData

ApiEventType

Viewer general event type, see EVENTTYPE for values

Type:
  • String

APIResponse

Every API function returns an object of this format

Type:
  • Object
Properties:
Name Type Argument Description
err Error <optional>

Error object if applicable, note that both err and data may be set.

Properties
Name Type Argument Description
data * <optional>

Optional further data explaining the error.

data * <optional>

The data resulting from the API call if applicable.

payload * <optional>

Payload which optionally may be passed to asynchronous functions.

Color

Color including alpha value defined by an array of 4 numbers between 0 and 255 [red, green, blue, alpha]. Further supported are all formats accepted by href="http://www.npmjs.com/package/tinycolor2">www.npmjs.com/package/tinycolor2 tinycolor.

Type:
  • Array.<Number> | String | Number

Event

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

token Object <optional>

optional message token created by internal processes of the ShapeDiver 3D viewer

Properties
Name Type Argument Description
id String <optional>

id of the message token, the same id is used for all messages belonging to the same process

serial Number <optional>

serial number of the message token, increases for every message belonging to the same process

payload * <optional>

payload which optionally may be passed to asynchronous functions, e.g. a token used to identify progress or status messages of asynchronous processes

progress Number <optional>

In case this is a progress event, a number describing the progress in interval [0,1]

message String <optional>

An optional status message which could be displayed to the user, e.g. if computation fails etc

messageLevel Number <optional>

Optional level of message to show to the user, one of 0 (error), 1 (warn), 2 (info), 3 (debug)

messageScope String <optional>

An optional description of the scope which the status message originates from

containerId String <optional>

Optional id of container this message relates to

scenePath ScenePathType <optional>

In case of an event related to a geometric object in the scene, this specifies the path in the scene graph

dragPosStart Point3d <optional>

In case this is a dragstart event, the starting position of a drag operation

dragPosAbs Point3d <optional>

In case this is a dragmove or dragend event, the current absolute position of the drag operation

dragPosRel Point3d <optional>

In case this is a dragmove or dragend event, the current relative position of the drag operation

hoverPos Point3d <optional>

In case this is a hover event, the ray intersection point

selectPos Point3d <optional>

In case this is a selection event, the ray intersection point

clientX Number <optional>

In case of an interaction event, the horizontal coordinate (according to the current window) of the mouse pointer when a mouse event was triggered

clientY Number <optional>

In case of an interaction event, the vertical coordinate (according to the current window) of the mouse pointer when a mouse event was triggered

anchors Array.<AnchorEventData> <optional>

In case of an anchor event, an array of AnchorEventData objects

export ApiExportInterface#ExportResult | * <optional>

data related to an export: status message, or availability message (final success)

parameter ParameterDefinition | * <optional>

data related to a parameter, depending on event type: a parameter definition, or an object mapping plugin id to updated parameter ids to updated parameter value

assets Array.<String> <optional>

object describing an update to scene assets (persistent attributes applied), for event type SUBSCENE_PUBLISHED

settings Object <optional>

data related to a settings update

Properties
Name Type Argument Description
key String <optional>

key of the setting which changed

valueNew * <optional>

new value of the setting

valueOld * <optional>

old value of the setting

EventListenerCallback(event)

Event listener callback

Parameters:
Name Type Description
event Event

event object depending on event type

EventListenerToken

Event listener token - when adding an event listener, remember this token if you wish to remove the event listener again later

Type:
  • Object

Point3d

3D point or vector defined by an object of three coordinates x,y,z

Type:
  • Object
Properties:
Name Type Argument Description
x Number <optional>

x coordinate of point or vector

y Number <optional>

y coordinate of point or vector

z Number <optional>

z coordinate of point or vector

Point3dArray

3D point or vector defined by an array of three numbers

Type:
  • Array.<Number>

ScenePathType

Scene path type - a string describing the path of an object in the 3D scene.

Scene paths are composed from the following parts in dot-separated format:

  • Runtime id of the plugin owning the object. In case of an object added via an API object, the runtime id of the API object.
  • Id of the asset which the object belongs to.
  • Further path of the object below the asset. An example scene path: CommPlugin_1.Asset_Id_1.further.path.to.object
Type:
  • String

TransitionParameters

Definition of a transition function

Type:
  • Object
Properties:
Name Type Argument Default Description
duration Number <optional>

duration of the transition in milliseconds

easing String | function <optional>
'Quartic.InOut'

In case a string S is provided, the corresponding easing function TWEEN.Easing[S] will be used if it exists. The easing function may also be passed directly, e.g. one of the many provided by Tween, see also TweenExplained, or a manually defined one.

interpolation String <optional>
'CatmullRom'

In case a string S is provided, the corresponding interpolation function TWEEN.Interpolation[S] will be used if it exists. Tween supports Linear, Bezier, and CatmullRom.

coordinates String <optional>
'cylindrical'

Defines coordinate system to use for animated camera paths. One of 'spherical' or 'cylindrical'.

ShapeDiver 3D Viewer, Copyright © 2015-2019 ShapeDiver GmbH. Documentation generated by JSDoc 3.5.5 on Fri Sep 13th 2019 using the DocStrap template.