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: 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 to a selected part of the scene or to a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformation should be applied to.

id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformation is applied to all plugins or viewports (depending on type)

matrix Transformation

The transformation 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
Promise.<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 Description
path ScenePathType

Scene path for which the bounding box should be returned

Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type BoundingBox.

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

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>

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 of a selected part of the scene or to a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformation should be returned.

id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformation is returned from all plugins or viewports (depending on type)

Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type matrix.

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 for a selected part of the scene or for a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformation should be reset.

id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformation is reset at all plugins or viewports (depending on 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 to a selected part of the scene or to a viewport.

See:
Parameters:
Name Type Description
type TransformationType

The type for which the transformation should be set to.

id String

runtime id of the plugin or the viewport, if a falsy value is provided, the transformation is set to all plugins or viewports (depending on type)

matrix Transformation

The transformation matrix

Returns:
Type Description
Promise.<APIResponse>

API response with a data array of type boolean.

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

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

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.

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

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

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 (according to the viewer container) of the 3D position

containerY Number <optional>

vertical coordinate (according to the viewer container) of the 3D position

clientX Number <optional>

horizontal coordinate (according to the current window, scrolling not considered) of the 3D position

clientY Number <optional>

vertical coordinate (according to the current window, scrolling not considered) of the 3D position

pageX Number <optional>

horizontal coordinate (according to the current window) of the 3D position

pageY Number <optional>

vertical coordinate (according to the current window) 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 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

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 paht of the environment map to use, 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.

transparency Number <optional>
0

The overall transparency of the gem. Affects the complete object uniformly.

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.

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.

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

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.

gamma Number <optional>
1.0

The gamma value affects the individual results of each tracing step.

contrast Number <optional>
1.0

The contrast value affects the individual results of each tracing step.

brightness Number <optional>
0.0

The brightness value affects the individual results of each tracing step.

InteractionEffect

Interaction Effect

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

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

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.

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

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

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.

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

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

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.

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

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 InteractionModeType <optional>
INTERACTIONMODETYPE.SUB

Allows to specify whether the complete asset or its individual subobjects are selectable/hoverable/draggable. Requires an InteractionGroup to be specified. See INTERACTIONMODETYPE for values.

dragPlaneNormal Point3d | 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.

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.

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

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.5.5 on Sat May 25th 2019 using the DocStrap template.