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,
- 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 want to get back an API v2 object, and use a specific runtime id for the API object api: {version: 2, 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
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
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 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) 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.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.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 URLs making up the cube mapped environment map scene.render.ambientOcclusion Boolean Enable / disable ambient occlusion for rendering 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) 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.
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
-
<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 a 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, nteractions)
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
-
AnchorEventDataAdd
-
Anchor data type definition
Type:
- Object
Properties:
Name Type Argument Description location
Point3d The 3D point defining the location of the anchor
viewport
String <optional>
runtime id of the viewport reporting the anchor position
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. 'tag2d')
data
Object <optional>
optional data of the anchor object, this property is passed on from the anchor definition (e.g. a Tag2D description)
runtimeId
String <optional>
a unique runtimeId for this anchor
updateFunction
function <optional>
sets the callback to update the dom element is linked to the anchor every the projected coordinates of the anchor on the screen change. The callback that must be provided has to be of type AnchorUpdateCallback.
-
AnchorEventDataRemove
-
Anchor data type definition
Type:
- Object
Properties:
Name Type Argument Description location
Point3d The 3D point defining the location of the anchor
viewport
String <optional>
runtime id of the viewport reporting the anchor position
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. 'tag2d')
data
Object <optional>
optional data of the anchor object, this property is passed on from the anchor definition (e.g. a Tag2D description)
runtimeId
String <optional>
a unique runtimeId for this anchor
-
AnchorEventDataUpdate
-
Anchor data type definition
Type:
- Object
Properties:
Name Type Argument Description location
Point3d The 3D point defining the location of the anchor
containerX
Number <optional>
horizontal coordinate (according to the viewer container) of the 3D location of the anchor
containerY
Number <optional>
vertical coordinate (according to the viewer container) of the 3D location of the anchor
clientX
Number <optional>
horizontal coordinate (according to the current window, scrolling not considered) of the 3D location of the anchor
clientY
Number <optional>
vertical coordinate (according to the current window, scrolling not considered) of the 3D location of the anchor
pageX
Number <optional>
horizontal coordinate (according to the current window) of the 3D location of the anchor
pageY
Number <optional>
vertical coordinate (according to the current window) of the 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 2D 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. 'tag2d')
data
Object <optional>
optional data of the anchor object, this property is passed on from the anchor definition (e.g. a Tag2D description)
runtimeId
String <optional>
a unique runtimeId for this anchor
-
AnchorUpdateCallback(event)
-
Parameters:
Name Type Description event
AnchorEventDataUpdate -
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
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'.