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.
-
-
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 fromfalse
totrue
.VISIBILITY_OFF
SceneEventType visibility.off Scene has become invisible. This event is fired whenever the
scene.show
setting is changed fromtrue
tofalse
. -
<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 incontent
.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
-
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