This version of the ShapeDiver viewer is no longer supported.

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

ShapeDiver 3D Viewer

Interface: ApiSceneInterface

api.scene

ShapeDiver Viewer - Scene API

The scene interface is part of the global API.

  • provides access to the camera and lights of the scene
  • allows to add, update, and remove assets in the scene
  • allows to define the interaction behavior of the geometry in the scene (hovering, selection, dragging)
  • allows to add and remove handlers for related events

Methods

addEventListener(type, callback)

Add a global event listener to the scene

Parameters:
Name Type Description
type SceneEventType

Type of event type to subscribe to. A scene path may be dot-appended to limit the subscription to parts of the scene.
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.

applyTransformation(type, id, matrix)

Applies a 4x4 transformation matrix or an array of matrices to a plugin or a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformations should be applied.
id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformations are applied to all plugins or viewports (depending on type)
matrix Transformation | Array.<Transformation>

The transformation matrix or an array of transformation matrices. In case of an array the matrices are premultiplied in the given order to the existing matrix.
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type boolean.

convertTo2D(position)

Converts the given 3D coordinates into various 2D coordinates

See:
Parameters:
Name Type Description
position Point3d

The 3D point to convert
Returns:
Type Description
APIResponse

API response with a data array of type 2DCoordinateSummary A summary of the different 2D coordinates, array of summaries in case of multiple viewports, null on error

get( [filter] [, namespace] [, blnScene])

Retrieve assets from the scene

Returns scene assets corresponding to given filter criteria. Depending on the value of blnScene the returned assets describe their original state, or their original state with persistent attributes applied.

Parameters:
Name Type Argument Default Description
filter SceneAssetFilter <optional>

Optional partial asset description whose properties are used as filter criteria. Most commonly, the id or name will be defined.
namespace String <optional>

By default the assets belonging to the namespace of the instance of this API will be returned. If you want to request assets owned by a plugin, specify its runtime id here.
blnScene Boolean <optional>
 false

If true use assets with persistent attributes applied, if false (default) use the original assets without persistent attributes applied.
Returns:
Type Description
APIResponse

API response with a data array of type SceneAsset. Contains a full description of the assets fulfilling the filter criteria. Returned data array may be empty.

getBoundingBox( [path])

Returns the bounding box of the visible objects at or below the provided path.

Parameters:
Name Type Argument Description
path ScenePathType <optional>

Scene path for which the bounding box should be returned, omit or pass empty string to return the bounding box of the complete scene
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type BoundingBox.

getContainer()

Returns the container(s) of the viewport(s).

Returns:
Type Description
HTMLElement

HTMLElement either as a single HTMLElement or an array of HTMLElement, depending on the number of viewports
| Array.<HTMLElement>

getData( [filter] [, namespace])

Retrieves generic data assets from the scene, optionally limited according to the given filters.

Parameters:
Name Type Argument Description
filter SceneAssetFilter <optional>

Optional partial asset description whose properties are used as filter criteria. Properties 'name' and 'id' will be used only, other properties will be ignored.
namespace String <optional>

By default all data assets in the scene will be returned. If you want to limit the request to data assets of a specific owner (e.g. this API instance), specify the owner's runtime id here.
Returns:
Type Description
APIResponse

API response with a data array of type ModelDataItem. Contains all data assets fulfilling the filter criteria.

getInteractionGroups()

Returns all currently defined interaction groups.

Returns:
Type Description
APIResponse

APIResponse with a list of interaction groups

getPersistent( [filter] [, namespace])

Retrieve the persistent attributes of assets.

Parameters:
Name Type Argument Description
filter SceneAssetFilter <optional>

Optional partial asset description whose properties are used as filter criteria. Most commonly, the id or name will be defined. Be aware that this filter is applied to the assets without persistent attributes applied.
namespace String <optional>

By default the persistent attributes of assets belonging to the namespace of the instance of this API will be returned. If you want to request persistent attributes of assets owned by a plugin, specify its runtime id here.
Returns:
Type Description
Array.<SceneAsset>

API response with a data array of type SceneAsset. Contains persistent attributes of assets fulfilling the given filter criteria.

getScreenshot()

Deprecated:
  • This function is deprecated, please use getScreenshotAsync instead. Get screenshot as a png data URI. Returns a screenshot of the viewer WebGL canvas (without any control elements) as a data URI using the png image format.
Returns:
Type Description
String

Data URI representing the png screeshot image (data:image/png;base64,...). Array of data URIs in case of multiple viewports.
| Array.<String>

getScreenshotAsync()

Get screenshot as a png data URI.

Returns a screenshot of the viewer WebGL canvas (without any control elements) as a data URI using the png image format.

Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type Data URI representing the png screeshot image (data:image/png;base64,...). Array of data URIs in case of multiple viewports.

getSelected()

Get scene paths of selected objects.

Returns:
Type Description
Array.<ScenePathType>

Array of scene paths of selected objects.

getTransformation(type, id)

Gets the 4x4 transformation matrix or the array of matrices currently configured for a plugin or a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformations should be returned.
id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformations are returned for all plugins or viewports (depending on type)
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type matrix.

getViewportRuntimeId( [runtimeId])

Returns the runtime id of the viewport(s).

Parameters:
Name Type Argument Description
runtimeId string <optional>

Optional runtimeId of a specific viewport
Returns:
Type Description
string

string, either as a single string or an array of string, depending on the number of viewports
| Array.<string>

pause()

Pauses the rendering until resume is called.

removeAsync( [filter] [, namespace] [, payload])

Remove assets from the scene according to the given filter criteria.

Parameters:
Name Type Argument Description
filter SceneAssetFilter <optional>

Optional partial asset description whose properties are used as filter criteria. Most commonly, the id or name will be defined.
namespace String <optional>

By default the assets belonging to the namespace of the instance of this API will be removed. If you want to remove assets owned by a plugin, specify its runtime id here.
payload * <optional>

Payload which will be passed through to the response and events related to a call of this function
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type SceneAsset. Contains a full description of the removed assets before removal, persistent attributes applied.

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.

render()

Renders the scene

Except in rare cases (e.g. after updating canvas textures) there is no need to call this, as rendering will be called automatically.

resetTransformation(type, id)

Resets the 4x4 transformation matrix or the array of matrices for a plugin or a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformations should be reset.
id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformations will be reset for all plugins or viewports (depending on the type).
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type boolean.

resume()

Resumes the rendering if it was paused by pause.

setLiveTransformation(liveTransformations [, viewports] [, duration])

Applies rotation, scaling or translation for different objects in different time frames.

// live transformation for 3 objects

// object 1 (PATH_1) is translated 300 unit in the x direction in 2500 ms
// and the translated 300 unit in the oposite direction to its starting point (repeat 1, yoyo true)

// object 1 also starts to rotate after 1000 ms around the z-axis and around a pivot
// the rotation will not finish as the overall duration of 5000 ms will be exceeded (1000 ms delay + 5000 ms duration)

// object 1 will be reset to its previous position as reset is set to true

// object 2 (PATH_2) and object 3 (PATH_3) inherit all transformations of object 1, as it is its parent
// these objects additionally perform a scaling operation

api.scene.setLiveTransformation(
     [
       {
         scenePaths: ['PATH_1'],
         transformations: [
           {
             delay: 0,
             duration: 2500,
             type: 'translation',
             easing: 'Quadratic.In',
             translationVector: { x: 300, y: 0, z: 0 },
             repeat: 1,
             yoyo: true
           },
           {
             delay: 1000,
             duration: 5000,
             type: 'rotation',
             rotationAxis: { x: 0, y: 0, z: 1 },
             rotationDegree: -360,
             pivot: { x: 100, y: 0, z: 0 }
           }
         ],
         reset: true
       },
       {
         scenePaths: ['PATH_2', 'PATH_3'],
         transformations: [
           {
             delay: 0,
             duration: 2500,
             type: 'scaling',
             scalingVector: { x: 1, y: 1, z: 2 },
             parent: 'PATH_1',
             repeat: 1,
             yoyo: true
           },
         ],
         reset: true
       },
     ], null, 5000
   );
Parameters:
Name Type Argument Description
liveTransformations Array.<LiveTransformationObject>

an array of LiveTransformationObject
viewports Array.<String> <optional>

the runtime ids of the viewports to which to apply the transformations, if nothing is provided it is applied to all viewports
duration Number <optional>

the maximum duration of the live transformations, the individual durations of the transformations will be ignored it they are longer
Returns:
Type Description
APIResponse

API response with data of type LiveTransformationResponse

setTransformation(type, id, matrix)

Sets a 4x4 transformation matrix or an array of transformation matrices for a plugin or a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformations should be set.
id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformations are set for all plugins or viewports (depending on the type).
matrix Transformation | Array.<Transformation>

The transformation matrix or an array of transformation matrices
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type boolean.

startContinuousRendering()

Starts continously rendering the scene until stopContinuousRendering is called.

startExternalDragEvent(path [, eventType])

Start an external drag event for an object with a certain path. This function is designed to provide support when something is dragged into the viewer. This function is called beforehand with the path of the to-be-dragged object and listens for mousemove or touchmove events inside the viewer. The to-be-dragged object should ideally be hidden (see toggleGeometry), as it will automatically be shown as soon as the dragging starts.

If there is a mouseup or touchend event before a mousemove or touchmove event, this process is cancelled automatically.

Parameters:
Name Type Argument Default Description
path ScenePathType

The scene path to the object that is to be dragged
eventType string <optional>
 'mouse'

The event type that is expected to be listened to. Either mouse or touch
Returns:
Type Description
APIResponse

APIResponse with a Boolean indicating whether the path was stored for dragging.

stopContinuousRendering()

Stops continously rendering the scene if startContinuousRendering was called.

toggleGeometry( [show] [, hide])

Show or hide geometry based on its scene path.

Parameters:
Name Type Argument Description
show Array.<ScenePathType> <optional>

Optional list of scene paths of objects which should be shown
hide Array.<ScenePathType> <optional>

Optional list of scene paths of objects which should be hidden
Returns:
Type Description
APIResponse

APIResponse with a Boolean data, indicating whether the operation succeeded

updateAsync(assets [, namespace] [, payload] [, options])

Add and update assets (typically geometry) in the scene.

By default, the assets added through instances of this API live in their own namespace within the scene (one namespace per API instance, defined by its runtime id). To access and update the assets provided by a plugin, please specify the plugin runtime id as namespace.

Note: Scene updates take place asynchronously. For each runtime id only one scene update can be active simultaneously. Should a scene update be triggered while a previous one is still going on, the previous scene update will get superseded and not included in the scene.

Parameters:
Name Type Argument Description
assets Array.<SceneAsset>

The assets which should be added to or updated in the scene. Missing information will default to the corresponding data currently in the scene.
namespace String <optional>

By default assets belonging to the namespace of the instance of this API will be updated/added. If the asset to be updated/added is owned by a plugin, specify its runtime id here.
payload * <optional>

Payload which will be passed through to the response and events related to a call of this function
options Object <optional>

Addition options for this update call

Properties
Name Type Argument Default Description
busy boolean <optional>
 false

Wether the viewer should go into busy mode and blur the scene while the scene is updated
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type SceneAsset. Contains a full description of the added/updated assets as shown in the scene after the update, persistent attributes applied.

updateInteractionGroups(groups)

Add or change an interaction group definition

Interaction groups define the behaviour of their members for hovering, selection and dragging.

Parameters:
Name Type Description
groups InteractionGroup | Array.<InteractionGroup>
Returns:
Type Description
APIResponse

APIResponse with a Boolean indicating whether the interaction groups could be updated.

updatePersistentAsync(assets [, namespace] [, payload])

Define persistent attributes for scene assets which will survive and override regular updates.

By default, the assets added through instances of this API live in their own namespace within the scene (one namespace per API instance, defined by its runtime id). To access and update the assets provided by a plugin, please specify the plugin runtime id.

Parameters:
Name Type Argument Description
assets Array.<SceneAsset>

Any information in these asset definitions will supersede information included in updates by the respective plugin. To remove a persistent attribute, set its value to null. The 'id' attribute needs to be set in any case. The 'duration' attribute will not be set persistently, but used for the actual scene update due to changing the persistent attributes.
namespace String <optional>

By default persistent attributes of assets belonging to the namespace of the instance of this API will be updated/added. If the asset to be updated/added is owned by a plugin, specify its runtime id here.
payload * <optional>

Payload which will be passed through to the response and events related to a call of this function
Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type SceneAsset. Contains a full description of the currently configured persistent attributes of the updated assets.

updateSelected( [select] [, deselect])

Update selection status of objects.

Parameters:
Name Type Argument Description
select Array.<ScenePathType> <optional>

Optional list of scene paths of objects which should be selected (please note that there might be further selected objects after this update, which had already been selected)
deselect Array.<ScenePathType> <optional>

Optional list of scene paths of objects which should be deselected
Returns:
Type Description
Boolean

true if selection status could be set for all specified scene paths, false if at least one error occured.

updateShadowMap()

Updates the shadow map if needed. Normally, all updates should be covered.

Members

<readonly> EVENTTYPE :SceneEventType

Enum for supported scene event types.

Type:
Properties:
Name Type Default Description
ANCHOR_ADD SceneEventType anchor.add

anchor objects have been added to the scene
ANCHOR_REMOVE SceneEventType anchor.remove

anchor objects have been removed from the scene
DRAG_START SceneEventType drag.start

dragging of an object started
DRAG_MOVE SceneEventType drag.move

continuously fired during dragging of an object
DRAG_END SceneEventType drag.end

dragging of an object ended
FRAMERATE SceneEventType framerate

framerate events every second (if rendering)
HOVER_ON SceneEventType hover.on

pointing device has entered a hoverable object
HOVER_OVER SceneEventType hover.over

continuously fired during hovering of an object
HOVER_OFF SceneEventType hover.off

pointing device has left a hoverable object
RENDER_INFO SceneEventType render.info

rendering info after context creation
RENDER_BEAUTY_START SceneEventType render.beauty.start

beauty rendering has started
RENDER_BEAUTY_CANCEL SceneEventType render.beauty.cancel

beauty rendering has been cancelled
RENDER_BEAUTY_END SceneEventType render.beauty.end

beauty rendering has ended
SELECT_ON SceneEventType select.on

object has been selected
SELECT_OFF SceneEventType select.off

object has been unselected
SUBSCENE_PUBLISHED SceneEventType subscene.published

A subscene, including data it may contain, has become visible in the viewer after a parameter update or the initial scene loading. This event is fired before fading in of the new subscene has been finished.
VISIBILITY_ON SceneEventType visibility.on

Scene has become visible. This event is fired whenever the scene.show setting is changed from false to true.
VISIBILITY_OFF SceneEventType visibility.off

Scene has become invisible. This event is fired whenever the scene.show setting is changed from true to false.

<readonly> FORMAT :SceneAssetItemFormat

Enum for supported scene asset item formats.

See:
Type:
Properties:
Name Type Default Description
GLB SceneAssetItemFormat glb

property href of the SceneAssetItem points to a glb file (binary glTF 1.0)
GLTF SceneAssetItemFormat gltf

property href of the SceneAssetItem points to a glTF 2.0 file. Binary glTF is supported. For now there is no support for gltf extensions, animations, multiple uv coords, and emissive textures.
OBJ SceneAssetItemFormat obj

property data of the SceneAssetItem contains an ObjMeshReference which points to a Wavefront OBJ file (supports meshes only, no lines, curves, or surfaces)
THREE SceneAssetItemFormat three

property data of the SceneAssetItem contains a ThreeGeometryReference which allows to directly add Mesh, Line, LineLoop, LineSegments, or Points objects to the scene.
DATA SceneAssetItemFormat data

property data of the SceneAssetItem contains generic data (will not be displayed in the scene, but can be requested using getData)
MATERIAL SceneAssetItemFormat material

property data of the SceneAssetItem contains a standard material definition or gem material definition
TAG2D SceneAssetItemFormat tag2d

property data of the SceneAssetItem contains an array of Tag2d definitions
TAG3D SceneAssetItemFormat tag3d

property data of the SceneAssetItem contains an array of Tag3d definitions
ANCHOR SceneAssetItemFormat anchor

property data of the SceneAssetItem contains an array of anchor definitions

<readonly> INTERACTIONMODETYPE :InteractionModeType

Enum for supported interaction modes. Allows to specify whether a complete asset or its individual subobjects should become selectable/hoverable/draggable. This enum is used for property interactionMode of the SceneAsset

Type:
Properties:
Name Type Default Description
GLOBAL InteractionModeType global

object and subobjects are globally selectable/hoverable/draggable, i.e. all of them at the same time
SUB InteractionModeType sub

object and subobjects are individually selectable/hoverable/draggable

<readonly> LIVETRANSFORMATIONTYPE :LiveTransformationType

Enum for supported live transformation types.

Type:
Properties:
Name Type Default Description
ROTATION LiveTransformationType rotation

the transformation is a rotation
TRANSLATION LiveTransformationType translation

the transformation is a translation
SCALING LiveTransformationType scaling

the transformation is a scaling

<readonly> MATERIALTYPE :MaterialType

Enum for supported material types.

Type:
Properties:
Name Type Default Description
STANDARD MaterialType standard

identifier for the standard material
GEM MaterialType gem

identifier for the gem material

<readonly> SELECTIONMODETYPE :SelectionModeType

Enum for supported selection modes. Allows to specify whether a single or multiple objects within an InteractionGroup are selectable.

Type:
Properties:
Name Type Default Description
SINGLE SelectionModeType single

A single object of the InteractionGroup can be selected, all objects of the group are deselected on a click which does not hit an object of the group.
MULTIPLE SelectionModeType multiple

Selection status of objects belonging to the InteractionGroup is toggled by clicking on them, selection status does not change on a click which does not hit an object of the group.

<readonly> TRANSFORMATIONTYPE :TransformationType

Enum for supported transformation types. Allows to specify whether a transformation matrix should be applied to the geometry of a plugin or the geometry within a viewport.

Type:
Properties:
Name Type Default Description
PLUGIN TransformationType plugin

the transformation is applied to the geometry of a plugin
VIEWPORT TransformationType viewport

the transformation is applied to the geometry in a specific viewport

Type Definitions

2DCoordinateSummary

Properties:
Name Type Argument Description
containerX Number <optional>

horizontal coordinate (relative to the top-left corner of the viewer container) of the 3D position
containerY Number <optional>

vertical coordinate (relative to the top-left corner of the viewer container) of the 3D position
clientX Number <optional>

horizontal coordinate (relative to the top-left corner of the viewport) of the 3D position
clientY Number <optional>

vertical coordinate (relative to the top-left corner of the viewport) of the 3D position
pageX Number <optional>

horizontal coordinate (relative to the top-left corner of the document) of the 3D position
pageY Number <optional>

vertical coordinate (relative to the top-left corner of the document) of the 3D position

Anchor

Anchor definition - used to specify the data of a SceneAssetItem in case its format is ANCHOR.

Anchors allow to attach DOM elements to projected 3D locations of the scene. Whenever the camera moves and projected 3D location changes, the viewer emits events which report the updated position of the projected 3D location, such that the DOM element's position can be updated. The viewer provides some predefined types of anchors to simplify usage of basic anchored DOM elements. When using one of these types, the DOM elements are created and managed by the viewer.

Type:
  • Object
Properties:
Name Type Argument Default Description
version String

Always '1.0'
location Point3d

The 3D point defining the location of the anchor
viewports Array.<String> <optional>

optional array of viewport runtime ids, for which the anchors shall report their position, defaults to all viewports
format String <optional>

optional format description of the anchor object, this property will be passed on to events related to the anchor, predefined formats include text and image
data Object <optional>

optional data of the anchor object, this property will be passed on to events related to the anchor, predefined objects include AnchorDataFormatText and AnchorDataFormatImage
hideable Boolean <optional>
 true

optional boolean on wheter the anchor is hideable. Not attempting to hide the anchor improves the performance, as visibility checks take time.
intersectionTarget BoundingBox | ScenePathType | Array.<ScenePathType> <optional>
 null

optional intersection target. This target is used for the visibility test. As intersecting with the whole scene takes time, specifying a target to intersect againt improves the performance. Can be a BoundingBox, a ScenePathType or an array of ScenePathType.

AnchorDataFormatImage

Anchor data object for format 'image'

Displays an image at the anchor location

Type:
  • Object
Properties:
Name Type Argument Default Description
src String

source URL of image
hidden Boolean <optional>
 true

if it can be hidden by other objects
positioning.horizontal String <optional>
 center

left, middle, right
positioning.vertical String <optional>
 center

bottom, middle, top
height Number | String

image height be given in px, or percentage of current div (will not be set if undefined)
width Number | String

image width in px, or percentage of current div (will not be set if undefined)
alt String

alternative text, if image display fails

AnchorDataFormatTag2D

Anchor data object for format 'tag2d'

(legacy support, use format 'text' instead)

Type:
  • Object
Properties:
Name Type Argument Default Description
color Color <optional>
 'black'

text color to use
text String

text to display at projected 3D location

AnchorDataFormatText

Anchor data object for format 'text'

Displays text at the anchor location

Type:
  • Object
Properties:
Name Type Argument Default Description
color Color <optional>
 'black'

text color to use
text String

text to display at projected 3D location
hidden Boolean <optional>
 true

if it can be hidden by other objects
positioning.horizontal String <optional>
 center

left, center, right
positioning.vertical String <optional>
 center

bottom, center, top
textAlign String <optional>
 left

left, center, right

BoundingBox

Properties:
Name Type Argument Description
min Point3dArray <optional>

Minimum coordinates of the axis-aligned bounding box.
max Point3dArray <optional>

Maximum coordinates of the axis-aligned bounding box.

CubeTexture

Cube Texture type definition Panorama maps can be converted to 6 cube maps via this tool.

See:
Type:
  • Object
Properties:
Name Type Argument Description
href String | Array.<String> <optional>

Link to the path of the environment map to use (map names = 'px.jpg', 'nx.jpg', 'pz.jpg', 'nz.jpg', 'py.jpg', 'ny.jpg'), or an array of 6 image URLs making up the cube mapped environment map.

GemMaterialV1

Gem Material version 1.0 type definition - used to specify the data of a SceneAssetItem in case its format is MATERIAL.

See:
Type:
  • Object
Properties:
Name Type Argument Default Description
version String

must be set to "1.0"
materialType MaterialType

must be set to MaterialType.GEM
colorTransferBegin Color <optional>
 'white'

The main color of the gem.
colorTransferEnd Color <optional>
 'white'

An additional color to add tone to the gem in the depth of the tracing.
depth Number <optional>
 8

The depth of the pseudo-raytracing. This value defines how many steps are taken in the raytracing process. A higher value decreases the performance, but increases the details in the stone. [min: 0, max: 20, default: 8]
transparency Number <optional>
 0

The overall transparency of the gem. Affects the complete object uniformly. [min: 0, max: 1, default: 1]
tracingTransparency Number <optional>
 0

As the amount of transparency can vary on a per face basis in the tracing calculations, this value serves as a scaling factor for this transparency. [min: 0, max: 1, default: 1]
refractionIndex Number <optional>
 2.4

The refraction index of the object. There are various resources online to find the right refraction indices for different types of stones like here. [min: 0, max: 4, default: 2.4]
dispersion Number <optional>
 0

The amount of dispersion. The larger this value is, the more areas are affected. If the dispersion is set to 0, no dispersion is calculated (improves the performance). [min: 0, max: 1, default: 0]
environmenttexture CubeTexture <optional>
 ''

The environment map for this material. If non is applied, the environment map of the scene is used.
impuritytexture CubeTexture <optional>
 ''

The impurity map of this material. This map affects the probability of the ray progressing through the stone. Only the red color channel is used.
impurityScale Number <optional>
 1.0

The impurity scale affects the application of the impurity map to the probability. [min: 0, max: 1, default: 1]
gamma Number <optional>
 1.0

The gamma value affects the individual results of each tracing step. [min: 0, max: 10, default: 1]
contrast Number <optional>
 1.0

The contrast value affects the individual results of each tracing step. [min: 0, max: 10, default: 1]
brightness Number <optional>
 0.0

The brightness value affects the individual results of each tracing step. [min: -1, max: 1, default: 0]

InteractionEffect

Interaction Effect

Defines the effect used on the active and passive objects of an InteractionGroup during an interaction event.

This can be either defined via the name of a default effect, or the actual implementation of effects. Some checks have to be made to ensure that this is an object with a material and that highlighting should be enabled. Note: With this function a lot of freedom is possible, it is in your interest to use it wisely.

Example in which the material color get multiplied with the color provided via the options and then reset to the original color.

const effect = {
  apply: function (object, options) {
    if (!object.material || object.noHighlight) return;
    object.material.originalColor = object.material.color.clone();
    object.material.color.multiply(options.color);
  },
  remove: function (object, options) {
    if (!object.material || object.noHighlight) return;
    object.material.color = object.material.originalColor.clone();
    delete object.material.originalColor;
  },
  options: {
    color: new THREE.Color(0xff0000)
  }
};
Type:
  • Object
Properties:
Name Type Argument Default Description
name String <optional>
 'colorHighlight'

The name of a predefined effect type to use. Currently 'colorHighlight' and 'opacityHighlight' are supported.
options Object <optional>

Options for the effect

Properties
Name Type Argument Default Description
color Color <optional>
 'red'

Color for the 'colorHighlight' effect
opacity Number <optional>
 0.5

Opacity value between 0 and 1 for the 'opacityHighlight' effect
apply function <optional>

the function to apply a highlight
remove function <optional>

the function to remove a highlight

InteractionGroup

Interaction Group

This type defines the interaction behaviour of a group of objects within the scene. SceneAssets can be assigned to InteractionGroups by means of the property interactionGroup of the SceneAsset.

For an expansion of the Interactions that allow snapping to points and lines see the Snap Module.

Type:
  • Object
Properties:
Name Type Argument Default Description
id String

Id of the interaction group
hoverable Boolean <optional>
 false

Will the group objects react if the user hovers over them with the mouse?
hoverEffect Object <optional>

Effects used for hovering events

Properties
Name Type Argument Description
active InteractionEffect <optional>

Effect used for the hovering object
passive InteractionEffect <optional>

Effect used for the other (non hovering) objects in the group
selectable Boolean <optional>
 false

Will the group objects be selectable?
selectionEffect Object <optional>

Effect used for selection events

Properties
Name Type Argument Description
active InteractionEffect <optional>

Effect used for selected objects
passive InteractionEffect <optional>

Effect used for non-selected objects
selectionMode SelectionModeType <optional>
 'single'

Allows to specify whether single or multiple objects belonging to the group are selectable, see SELECTIONMODETYPE for values
draggable Boolean <optional>
 false

Will the group objects be draggable?
dragEffect Object <optional>

Effect used for dragging events

Properties
Name Type Argument Description
active InteractionEffect <optional>

Effect used for dragged objects
passive InteractionEffect <optional>

Effect used for not currently dragged objects

InteractionModeType

Interaction mode type definition, used to define whether a complete asset or its subobjects should become selectable, hoverable, or draggable, see INTERACTIONMODETYPE for values

Type:
  • String

LineMaterial

Line material description

See:
Type:
  • Object
Properties:
Name Type Argument Default Description
type String <optional>
 'basic'

the type of line, can be 'basic' or 'dashed' (dashed line material currently not supported for indexed line or line segment geometry)
lineWidth Number <optional>
 1

the line width (not well supported)
dashSize Number <optional>
 3

the dash size for lines of type 'dashed'
gapSize Number <optional>
 1

the gap size for lines of type 'dashed'
scale Number <optional>
 1

the scale for lines of type 'dashed'

LiveTransformationType

Live Transformation type, see LIVETRANSFORMATIONTYPE for values

Type:
  • String

MaterialType

Material type definition, see MATERIALTYPE for values

Type:
  • String

MaterialV1

Material version 1.0 type definition - used to specify the data of a SceneAssetItem in case its format is MATERIAL.

Supported MIME types for images: image/jpeg, image/png, image/gif, image/bmp, image/svg+xml. There are some limitations on using SVG images, preferably render the SVG into a canvas yourself and specify the canvas instead (this is only available in the texture type definition used by MaterialV3)

See:
Type:
  • Object
Properties:
Name Type Argument Description
version String

must be set to "1.0"
ambient Color <optional>

Ambient color. CAUTION: This property is ignored, it has been superseded.
diffuse Color

Main material color
emission Color <optional>

Emissive (light) color of the material, essentially a solid color unaffected by other lighting. Default is black. CAUTION: This property is ignored, it has been superseded.
specular Color <optional>

Specular color of the material. Default is a Color set to 0x111111 (very dark grey). CAUTION: This property is ignored, it has been superseded by environment maps.
shine Number <optional>

How shiny the specular highlight is; a higher value gives a sharper highlight. Default is 30.
transparency Number <optional>

Float in the range of 0.0 - 1.0 indicating how transparent the material is. A value of 0.0 indicates fully opaque, 1.0 is fully transparent. If transparencytexture is also provided, both values are multiplied.
bitmaptexture String <optional>

URL to the color map, can be a data URI. Default is null. The texture map color is modulated by the main material color.
bumptexture String <optional>

URL to the bump map. Can be a data URI. The black and white values map to the perceived depth in relation to the lights. Bump doesn't actually affect the geometry of the object, only the lighting.
transparencytexture String <optional>

Url to an image which will be used as a transparency texture. Can be a data URI.

MaterialV2

Material version 2.0 type definition - used to specify the data of a SceneAssetItem in case its format is MATERIAL.

Supported MIME types for images: image/jpeg, image/png, image/gif, image/bmp, image/svg+xml. There are some limitations on using SVG images, preferably render the SVG into a canvas yourself and specify the canvas instead (this is only available in the texture type definition used by MaterialV3).

See:
Type:
  • Object
Properties:
Name Type Argument Description
version String

must be set to "2.0"
color Color

Main material color
side String <optional>

Which side of the object to display. Options: 'front' - the front side, 'back' - the back side, '' - both sides; Default: both sides
metalness Number <optional>

How much the material is like a metal. Non-metallic materials such as wood or stone use 0.0, metallic use 1.0, with nothing (usually) in between. Default is 0.5. A value between 0.0 and 1.0 could be used for a rusty metal look. If metalnesstexture is also provided, both values are multiplied.
roughness Number <optional>

How rough the material appears. 0.0 means a smooth mirror reflection, 1.0 means fully diffuse. Default is 0.5. If roughnesstexture is also provided, both values are multiplied.
transparency Number <optional>

Float in the range of 0.0 - 1.0 indicating how transparent the material is. A value of 0.0 indicates fully opaque, 1.0 is fully transparent. If transparencytexture is also provided, both values are multiplied.
alphaThreshold Number <optional>

Sets the alpha value to be used when running an alpha test. The material will not be renderered if the opacity is lower than this value. Default is 0.
bitmaptexture String <optional>

URL to the color map, can be a data URI. Default is null. The texture map color is modulated by the material color.
metalnesstexture String <optional>

URL to the metalness map, can be a data URI. The blue channel of this texture is used to alter the metalness of the material.
roughnesstexture String <optional>

URL to the roughness map, can be a data URI. The green channel of this texture is used to alter the roughness of the material.
bumptexture String <optional>

URL to the bump map. Can be a data URI. The black and white values map to the perceived depth in relation to the lights. Bump doesn't actually affect the geometry of the object, only the lighting. If a normal map is defined this will be ignored.
normaltexture String <optional>

URL to the normal map. Can be a data URI. The RGB values affect the surface normal for each pixel fragment and change the way the color is lit. Normal maps do not change the actual shape of the surface, only the lighting.
transparencytexture String <optional>

URL to the alpha map, which is a grayscale texture that controls the opacity across the surface (black: fully transparent; white: fully opaque). Default is null.
line LineMaterial <optional>

the definition for a line material

MaterialV3

Material version 3.0 type definition - used to specify the data of a SceneAssetItem in case its format is MATERIAL.

See:
Type:
  • Object
Properties:
Name Type Argument Description
version String

must be set to "3.0"
color Color

Material color
side String <optional>

Which side of the object to display. Options: 'front' - the front side, 'back' - the back side, '' - both sides; Default: both sides
metalness Number <optional>

How much the material is like a metal. Non-metallic materials such as wood or stone use 0.0, metallic use 1.0, with nothing (usually) in between. Default is 0.5. A value between 0.0 and 1.0 could be used for a rusty metal look. If metalnesstexture is also provided, both values are multiplied.
roughness Number <optional>

How rough the material appears. 0.0 means a smooth mirror reflection, 1.0 means fully diffuse. Default is 0.5. If roughnesstexture is also provided, both values are multiplied.
transparency Number <optional>

Float in the range of 0.0 - 1.0 indicating how transparent the material is. A value of 0.0 indicates fully opaque, 1.0 is fully transparent. If transparencytexture is also provided, both values are multiplied.
alphaThreshold Number <optional>

Sets the alpha value to be used when running an alpha test. The material will not be renderered if the opacity is lower than this value. Default is 0.
shadowOpacity Number <optional>

The adjustement for the opacity of the shadow. Default is 1.
lightReflectivity Number <optional>

The amount the light is reflected in metal-like surfaces. Default is 1.
threeDNoise ThreeDNoise <optional>

The options for the 3D Noise effect that can optionally be turned on using its opacity.
bitmaptexture Texture <optional>

Color texture definition. The texture map color is modulated by the material color.
metalnesstexture Texture <optional>

Metalness texture definition. The blue channel of this texture is used to alter the metalness of the material.
roughnesstexture Texture <optional>

Roughness texture definition. The green channel of this texture is used to alter the roughness of the material.
bumptexture Texture <optional>

Bump texture definition. The black and white values map to the perceived depth in relation to the lights. Bump doesn't actually affect the geometry of the object, only the lighting. If a normal map is defined this will be ignored.
normaltexture Texture <optional>

Normal texture definition. The RGB values affect the surface normal for each pixel fragment and change the way the color is lit. Normal maps do not change the actual shape of the surface, only the lighting.
transparencytexture Texture <optional>

Transparency texture definition. They greyscale level of this texture controls the opacity across the surface (black: fully transparent; white: fully opaque).
line LineMaterial <optional>

the definition for a line material

ModelDataItem

Scene data item - generic data attached to the scene

Type:
  • Object
Properties:
Name Type Description
name String

name of the data item
id String

unique id of the data item
plugin String

plugin runtime id this item belongs to
data *

the data

ObjMeshReference

OBJ reference - used to specify the data of a SceneAssetItem in case its format is OBJ.

Type:
  • Object
Properties:
Name Type Argument Default Description
objUrl String

A string containing the path/URL of the .obj file.
mtlUrl String <optional>

A string containing the path/URL of the .mtl file. If a material asset is assigned, too, the mtlUrl is still prioritized. Therefore, remove the mtlUrl to switch to the material asset.
path String <optional>

Set base path for resolving references. If set this path will be prepended to each loaded and found reference.
texturePath String <optional>

If set this path will be prepended found texture reference. If not set and setPath is, it will be used as texture base path.
side String <optional>
 'double'

The sidedness to use for the mesh, one of 'front', 'back', 'double'

SceneAsset

Scene asset

This definition describes an asset containing geometry and/or material items.

If an asset contains no material items, it may instead link to another asset which does. This makes it possible to replace geometry and materials separately - if a material is replaced, that change is reflected in all the geometry objects which link to it.

All properties can be optional depending on the context.

If the API returns an asset, it usually includes all properties.

For geometry updates using updateAsync one can send only the properties which need to be changed, along with the id of the object to be changed.

See:
Type:
  • Object
Properties:
Name Type Argument Default Description
id String

The unique id of this asset. Ids of existing assets can be retrieved using get. This id should be remembered to reference the asset later, e.g. to update or remove it.
name String <optional>

The human readable name of the asset
group String <optional>

If provided, defines a logical group which this asset belongs to. The group can be used as a filter in calls to get.
material String <optional>

Id of the material asset to be used for the geometry defined by this asset. Can be ommited if this asset contains its own materials (see property content), or if the geometry in this asset has embedded materials. Takes precedence over materials defined in content.
version String <optional>

Unique version id of this asset. If the same asset is provided again later with the same version id, caching might improve performance. A random version id will be created if none is specified.
bbmin Point3dArray <optional>

Minimum coordinates of the axis-aligned bounding box of the geometry in this asset. If not provided, this will be computed. Not used for material assets. Set this to null when updating geometry and you don't know the updated bounding box, which will cause the bounding box to be recomputed in the viewer. If you don't do this, the previous bounding box information will persist.
bbmax Point3dArray <optional>

Maximum coordinates of the axis-aligned bounding box of the geometry in this asset. If not provided, this will be computed. Not used for material assets. Set this to null when updating geometry and you don't know the updated bounding box, which will cause the bounding box to be recomputed in the viewer. If you don't do this, the previous bounding box information will persist.
content Array.<SceneAssetItem>

Items of this asset - the geometries and materials to be added to the scene. Materials
format String

In case all items of the content array share the same format, this will be reflected here. In case several formats are part of the content array, this will be set to mixed. In case the content array is empty, this will be set to unknown.
duration Number <optional>

Duration of transition in msec for fading in and out, defaults to 500 for replacements and 0 for addition and removal.
interactionGroup String <optional>

Specifies the id of the InteractionGroup to which this asset belongs.
interactionMode Number | InteractionModeType <optional>
 INTERACTIONMODETYPE.SUB

Allows to specify whether the complete asset, an individual level or its individual subobjects are selectable/hoverable/draggable. Provide a number to specify at which level of the scene path the interaction shall happen (0 - SceneAsset, 1 - SceneAssetItem, 2 - transformations of SceneAssetItem, etc). Requires an InteractionGroup to be specified. See INTERACTIONMODETYPE for values.
dragPlaneNormal Point3d | Point3dArray | Array.<Point3d> | Array.<Point3dArray> <optional>

Optional normal to the plane which should be used for dragging. If not specified, dragging will happen in a plane normal to the viewing direction. Requires an InteractionGroup to be specified. The dragPlane is prioritized over the dragPlaneNormal.
dragPlane Object | Array.<Object> <optional>

Optional normal to the plane and distance to the origin which should be used for dragging. If not specified, dragging will happen in a plane normal to the viewing direction. Requires an InteractionGroup to be specified. The dragPlane is prioritized over the dragPlaneNormal.
dragOffset Point3d | Point3dArray <optional>

Optional offset which is used while the object is being dragged. Per default the intersection point at the start of the interaction is used. Requires an InteractionGroup to be specified.
addEventListener function <optional>

When the API returns an asset, it adds this function to allow registering to events limited to this specific object (scene path). Refer to the documentation of the global addEventListener function.
status_collect string <optional>

Status of collecting results for the output version.
status_computation string <optional>

Status of the computation which resulted in the output version.
msg string <optional>

In case computation of the output version (temporarily) failed: Optional message to the user, explaining what went wrong. #SS-928 allow to specify a global transformation for the complete asset here

SceneAssetFilter

Scene asset filter - used to define filter criteria for retrieving information about assets in the scene

Type:
  • Object
Properties:
Name Type Argument Description
id String <optional>

Unique id of the asset.
name String <optional>

Human readable name of the asset.
group String <optional>

Logical group the asset belongs to.
material String <optional>

Id of the material asset to be used for the geometry defined by this asset.
version String <optional>

Unique version id of this asset.
duration Number <optional>

Duration of transition in msec for fading in and out.
interactionGroup String <optional>

Id of the InteractionGroup to which this asset belongs.

SceneAssetItem

Scene asset item - each SceneAsset can have multiple items

See:
Type:
  • Object
Properties:
Name Type Argument Description
format SceneAssetItemFormat

one of the supported scene asset item formats
href String <optional>

Link to the geometry data. Either this property or the 'data' property must be provided.
data Array.<Anchor> | Array.<Tag2d> | Array.<Tag3d> | MaterialV1 | MaterialV2 | MaterialV3 | GemMaterialV1 | ObjMeshReference | ThreeGeometryReference | * <optional>

Data as defined by the 'format' property.
transformations Array.<Transformation> <optional>

Optional property defining the transformation matrices to be used for displaying instances of this output. If this property exists it must contain at least one transformation. CAUTION: These transformations are only applied to asset items whose format is GLB, OBJ, and THREE.

SceneAssetItemFormat

Scene asset item format, see FORMAT for values

See:
Type:
  • String

SceneEventType

Scene event type, see EVENTTYPE for values

See:
Type:
  • String

SelectionModeType

Selection type, see SELECTIONMODETYPE for values

See:
Type:
  • String

Tag2d

2d text tag definition - used to specify the data of a SceneAssetItem in case its format is TAG2D.

Type:
  • Object
Properties:
Name Type Description
version String

Always '1.0'
color Color

[r,g,b,a] array of numbers between 0-255
text String

The text of the 2d tag
location Object

The point defining the location of the 2d tag

Properties
Name Type Description
X Number
Y Number
Z Number

Tag3d

3d text tag definition - used to specify the data of a SceneAssetItem in case its format is TAG3D.

Type:
  • Object
Properties:
Name Type Description
version String

Always '1.0'
justification String

One of ['BL','BC','BR','ML','MC','MR','TL','TC','TR'], meaning Bottom/Middle/Top for vertical justification and Left/Center/Right for horizontal justification within the text tags coordinate system
color Color

[r,g,b,a] array of numbers between 0-255, or other valid color definition
size Number

Text size in model units
text String

The text for the tag
location Object

The plane (the coordinate system) defining the 3d tag's position and orientation in the scene

Properties
Name Type Description
origin Object

Origin of the plane

Properties
Name Type Description
X Number
Y Number
Z Number
normal Object

Z-axis of the plane, perpendicular to the X-axis and the Y-axis

Properties
Name Type Description
X Number
Y Number
Z Number
xAxis Object

X-axis of the plane, aligned left to right with the text

Properties
Name Type Description
X Number
Y Number
Z Number
yAxis Object

Y-axis of the plane, aligned bottom to top with the text

Properties
Name Type Description
X Number
Y Number
Z Number

Texture

Texture type definition

See:
Type:
  • Object
Properties:
Name Type Argument Description
href String <optional>

Link to the bitmap to be used as texture, can be a data URI. Either href or canvas must be specified. Supported MIME types: image/jpeg, image/png, image/gif, image/bmp, image/svg+xml. There are some limitations on using SVG images, preferably render the SVG into a canvas yourself and specify the canvas instead.
canvas Object <optional>

Canvas to be used as texture. Either href or canvas must be specified.
offset Array.<Number> <optional>

Offset used on uv coordinates for this texture, in each direction U and V. CAUTION: This updates the texture coordinates, be aware of this when using several textures for one mesh.
repeat Array.<Number> <optional>

How many times the texture is repeated across the surface, in each direction U and V. CAUTION: This updates the texture coordinates, be aware of this when using several textures for one mesh.
rotation Number <optional>

How much the texture is rotated around the center point, in radians. Positive values are counter-clockwise. Default is 0. CAUTION: This updates the texture coordinates, be aware of this when using several textures for one mesh.
center Array.<Number> <optional>

The point around which rotation occurs. A value of (0.5, 0.5) corresponds to the center of the texture. Default is (0, 0), the lower left. CAUTION: This updates the texture coordinates, be aware of this when using several textures for one mesh.
wrapS Number <optional>

wrapS Wrapping Mode, corresponds to the U in UV mapping therefore the horizontal mapping mode. Possible values: 0 (RepeatWrapping, default), 1 (ClampToEdgeWrapping), 2 (MirroredRepeatWrapping)
wrapT Number <optional>

wrapT Wrapping Mode, corresponds to the V in UV mapping therefore the vertical mapping mode. Possible values: 0 (RepeatWrapping, default), 1 (ClampToEdgeWrapping), 2 (MirroredRepeatWrapping)

ThreeDNoise

3D Noise description

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

The opacity of this effect, where a value of 0 disables this effect (default: 0.0)
noiseID Number <optional>

The ID for the noise function that is used (range: 0-3, default: 0)
scale Number <optional>

The scale of the noise (default: 1.0)
distance Number <optional>

The amount the noise fades with distance (default: 0.0)

ThreeGeometryReference

THREE geometry reference - used to specify the data of a SceneAssetItem in case its format is THREE.

Type:
  • Object
Properties:
Name Type Description
threeObject THREE.Mesh | THREE.Line | THREE.Points

A THREE object, Mesh, Line, or Points are supported

Transformation

Transformation matrix - Array containing the 16 elements of a 4x4 matrix in row-major format, or a THREE.Matrix4.

Type:
  • Array.<Number> | THREE.Matrix4

TransformationType

Transformation type, see TRANSFORMATIONTYPE for values

Type:
  • String
ShapeDiver 3D Viewer, Copyright © 2015-2019 ShapeDiver GmbH. Documentation generated by JSDoc 3.6.6 on Tue Jun 21st 2022 using the DocStrap template.