ShapeDiver 3D Viewer

You are reading the documentation of the public API of the ShapeDiver 3D viewer v2. This is the result of a complete software redesign of ShapeDiver's 3D viewer v1. It offers the following advantages over v1:

  • new API v2 making use of promises
  • support for multiple simultaneous sessions with one or several ShapeDiver models
  • drag & drop, selection, highlighting
  • advanced rendering and materials
  • advanced control of the 3D scene (geometry and lighting)
  • support for multiple viewports
  • file/blob parameter types
  • AR support soon to be there

Read more about ShapeDiver and 3D product configurators.


API v2

The new API v2 offers numerous advantages over API v1:

  • supports promises and provides direct feedback of the result of asynchronous operations
  • consistent naming convention
  • support for changing of materials, and updating/adding of geometry
  • support for drag & drop, selection, and highlighting
  • support for configuration of the 3D scene lighting
  • support for multiple viewports
  • file/blob parameter types

API v1

The API v1 has been phased out and will not be available anymore from version 2.15.0.

Questions, feedback, bugs

Don't hesitate to ask questions and provide feedback, please use our forum for this purpose. Should you find a bug, please report it in our forum or email us.

Notice for developers

The JavaScript API objects might contain additional members or functionality which are not documented here. Do not use such undocumented functionality. Such additional functionality will likely be changed or removed by us between releases or patches without further notice.

Browser support

The ShapeDiver 3D viewer v2 supports the following browsers:

  • Chrome
  • Firefox
  • Edge
  • Safari
  • Internet Explorer 11
  • Modern Smartphones and tablets, Android and iOS

External dependencies

  1. THREE.js

WebGL based library used to create and display animated 3D computer graphics on a Web browser

  1. axios

    Alternative promise based standalone HTTP-client to replace jQuery

  2. verb-nurbs - optional

    verb is a library for creating and manipulating NURBS surfaces and curves in many languages including JavaScript

Release Notes

Version Release date Notes
------ -------------- ------------------
2.0.6 2018-07-01 API v2 available
------ -------------- ------------------
2.0.7 2018-08-22 Browser testing
------ -------------- ------------------
2.0.8 2018-08-30 Parameter history API
------ -------------- ------------------
2.1.0 2018-10-12 Multiple viewports, browser tested
------ -------------- ------------------
2.2.0 2018-11-23 oauth2 support
fixed iOS texture problems
fixed rendering of transparent objects
drag/selection/hovering handler now supports touch events
------ -------------- ------------------
2.3.0 2018-12-20 improved rendering for transparent objects
gems rendering
fixes to responsive layout of viewer and controls/settings containers
iframe API reflector supports addEventListener
diverse bugfixes
------ -------------- ------------------
2.4.0 2019-01-21 export dialog bugfix
CommPlugin error message improvements
viewport resizing fix
rendering bugfixes
------ -------------- ------------------
2.5.0 2019-02-01 anchor object documentation improvements and bugfix
------ -------------- ------------------
2.6.0 2019-03-01 THREE.LineSegments and THREE.LineLoop are supported now in addition to THREE.Line
IE11 support restored
Live transformations API
Fixed crash when loading empty scene
Pass on scroll events in case zooming is disabled
Added further properties to AnchorEventData
Support for settings for multiple viewports
new setting ignoreSuperseded for CommPlugin
fix in constructor SDVApp.ParametricViewer to allow an empty container array to be passed
new camera settings for auto adjusting and revert at mouse up
glb loader now uses browser cache
Settings widget light intensity sliders max value increased to 5
CommPlugin sent export requests instead of export-cache requests
Export modal dialog did not show message to user in case of download export not resulting in a downloadable file
Material defined for SceneAsset takes precedence over materials defined in SceneAssetItems.
------ -------------- ------------------
2.7.0 2019-03-15 bugfix in implementation of scene.updatePersistentAsync: all assets were being updated unnecessarily and faded out/in
bugfix in implementation of File parameter: default value was ignored
new setting scene.material.environmentMapResolution allows to configure image resolution used for environment map
performance improvement: environment map 'default' was always being loaded, even if another one was configured for a model
performance improvement: environment map and material preset images have been optimized for lower size
API documentation updates regarding supported image types
bugfix to drag & drop of transparent objects
bugfix to draggable objects restricted to a plane: the plane origin was being updated while dragging
bugfix: shadows were always being activated on change of light intensity
------ -------------- ------------------
2.8.0 2019-04-01 - bugfix in SDVReflector: return values containing an Error object did not pass through the iframe barrier,
this has been solved by passing the error message only and recreating an error object using that message
(information about the source location of the error gets lost, but the error message is preserved)
- API documentation: added clarifications about the exact firing criterion for some events
- Performance improvement: lowered resulting build size of the viewer bundle
- new API function scene.toggleGeometry for showing or hiding geometry based on scene paths
- prevent rendering of a single frame with opacity 1 when fading in geometry
------ -------------- ------------------
2.9.0 2019-04-12 - switched to using a forked version of THREE.js
- diverse significant performance optimizations regarding THREE.js
- material presets are loaded from central library on first usage
------ -------------- ------------------
2.10.0 2019-05-02 - new and improved implementation of the controls used for parameters and settings
please note that the following dependencies are not required anymore to be separately loaded for using the controls:
-- Font Awesome ( (not used anymore)
-- JQuery ( (will be loaded on demand)
-- Spectrum color picker ( (will be loaded on demand)
-- Sortable.js ( (internalized)
- support for rendering of gems, see api.scene.GemMaterialV1
- SVG images passed as data URI are now expected to be base64 encoded using the method as described on the following line,
which adds support for Unicode characters
- methods for base64 encoding and decoding of DOMStrings are available as api.utils.btoaUTF8 and api.utils.atobUTF8
- controls and settings panel now available in fullscreen mode, add property sdv-fullscreen='true' as shown in section usage
- bugfix: changed default text anchor positioning from 'top'/'left' to 'center'/'center'
- bugfix related to anchor elements and api.scene.convertTo2D for IE11
------ -------------- ------------------
2.10.1 2019-05-06 - garbage collection improvements
- bugfix: avoid unnecessary computation of intersections, dramatically improving framerate in case of anchors
- bugfix: color for lines working again
- iOS problem fix: usage of multiple spotlights was causing shader problems
------ -------------- ------------------
2.11.0 2019-05-25 - Tag3d data type API documentation improvement
- adjustable cube map resolution for gem rendering
- support for multiple viewer instances embedded directly
- API reflector supports multiple viewers embedded using iframe
- support for using viewer headless
- update to latest version of UIkit
- prevent beauty rendering kicking in between several updates in direct succession
- fix to iframe and demo pages: opening head tag was missing
- bugfix: bumpAmplitude and pointSize settings were not working correctly
- bugfix: further performance improvement regarding adding and removing anchors
- bugfix: fullscreen mode did not work in case of iframe embedding
- bugfix: corrected depth sorting for transparent objects
- bugfixes and improvements regarding the newly implemented controls used for parameters and settings
- bugfix: pass through touch events in case rotation is disabled
------ -------------- ------------------
2.12.0 2019-05-29 - A new setting Parameter Validation allows to operate the parameter widget in a mode which asks the user to commit or cancel
changes to parameter values before sending a computation request.
- This can be activated using the settings widget, or by setting the viewer constructor parameter commitParameters, see SDVApp.ParametricViewer.
- bugfix: camera setting Top View did not get restored properly in case it was stored as default for a model
- bugfix: the camera default position and target did not get stored in case of the orthographic camera (Top View)
------ -------------- ------------------
2.13.0 2019-06-07 - Release of the ShapeDiver Viewer AR API
- The functionality for applying transformations to viewports and plugins has been extended to support an array of transformations instead of just a single one.
Refer to setTransformation, applyTransformation, getTransformation, and resetTransformation in api.scene
- bugfix: avoid additional render calls while operating in continuous rendering mode
- bugfix in api.scene.resume: activate orbit controls only if they should be according to the settings
- fixed documentation of api.getRuntimeId()
------ -------------- ------------------
2.14.0 2019-07-19 - new light API allows to define light scenes, and adds new light types
- CAUTION: changes to the light API are breaking
- controls for lights allow to configure lights from the settings panel
- added support for loading glTF 2.0 files, see SceneAssetItemFormat GLTF
- new property format for scene assets, making it easier to filter scene assets by the format of their content
- extension of the material format MaterialV2 and MaterialV3 by a line material, allowing to configure dashed lines
- CAUTION: the dashed line material is currently not supported for indexed line or line segment geometry
- CAUTION: dashed lines do not work in all browsers, e.g. IE11
- removal of unnecessary property runtimeId from ANCHOR_ADD and ANCHOR_REMOVE events
(property scenePath can be used instead to uniquely identify anchors)
- bugfix: shadows were not updated properly during live transformations
- bugfix: live transformations were stopped on hover off
- bugfix: live transformations were failing in case of assets with empty content
- bugfix: the database of preset materials contained a wrongly configured materials
- bugfix: long parameter names were causing the parameter widget to become too wide
- bugfix: setTransformation and applyTransformation did not adjust the scene (shadow camera, lights, etc)
- improved documentation of properties of anchor events (coordinate properties containerX, containerY, clientX, clientY, pageX, pageY)
------ -------------- ------------------
2.15.0 2019-09-09 - performance improvement: caching of cube textures
- api.scene.getBoundingBox now supports computation of the bounding box of the complete scene
- now supports zooming to a given bounding box
- settings panel: included link to specific help pages for each section
- light settings: various usability improvements (zoom to light handles, improve visibility of light handles, default naming of new lights and scenes)
- control panel: custom components can be registered, allowing to create simple custom user interfaces
the following component types are supported for now (see codepen example for details):
button, checkbox, checklist, color picker, dropdown, file, group, modal, slider, static html, string, vector3
- settings panel: we added tooltips providing a short explanation of individual settings
- bugfix: control and settings panels: parameter components did not scale correctly on mobile
- bugfix: light settings: Boolean property Cast shadow of directional lights did not get initialized properly
- bugfix: light settings: coordinates of direction vectors and positions could not be entered
- bugfix: light settings: the hemisphere sky color did not work as expected
- bugfix: control and settings panels: sometimes the color picker was not working properly
- bugfix: control panel: long filenames made file parameter component become wider
- bugfix: control panel: commit parameter mode did not work as expected for sliders
- bugfix: settings and control panel layout fixes in landscape mode
- CAUTION: The API v1 has been phased out and will not be maintained from version 2.15.0 onward.
------ -------------- ------------------
2.16.0 2019-09-16 - support for React: see for an example
- extended by getPlacementAnchor, resetPlacementAnchor, setPlacementAnchor
- new AR event type OBJECT_PLACEMENT
- new properties runtimeId and anchorId for AREvent
------ -------------- ------------------
2.17.0 2019-10-15 - revised camera controls for perspective and orthographic camera, including:
-- consistent behavior across different devices and model sizes
-- additional settings for camera controls (see documentation of api.updateSettingAsync)
-- new type of perspective camera controls: fps (see setting
-- automated camera movements can now be disrupted, e.g. in case user wants to move the camera while it is reverting to its default position
-- fixes to several problems which had caused the previous controls to behave strangely
-- orthographic camera controls now support resizing of the container
- CAUTION: the revised camera controls cause the following breaking changes:
-- setting became
-- previously stored values for speed of zooming, panning, and rotating are being ignored
- new option for api.scene.updateAsync, allowing to enable blur during updates
- improved documentation of gemstone material
- TypeScript interface definition of the ShapeDiver Viewer API: npm install shapediver-types (will become an @types package soon)
- interactionMode of SceneAssets may now be set at arbitrary depths of the scene tree
- added support for starting external drag operations, see api.scene.startExternalDragEvent (example)
- new event type FRAMERATE (api.scene) for measuring the framerate
- speedup of loading process (prevent unnecessary render calls)
CAUTION: breaking change: fixed return type of to return an APIResponse
- iframe embedding example using deferred loading of geometry, see section usage
- fixes and improvements to API documentation
- bugfix to api.state.setBusy
- bugfix: justification of 3D text tags was ignoring spaces at the end of strings
------ -------------- ------------------
2.18.0 2019-12-16 - optionally disable visibility tests for anchors, see new property hideable for anchors
- optionally provide a specific or simplified intersection target for testing visibility of anchors, see new property intersectionTarget for anchors
- improved edit mode for parameter controls
- added missing tooltips for viewer settings
- allow two digits for light intensity
- new texture properties wrapS and wrapT, allowing to choose between different wrapping modes
- support for export requests using parameter values different from the currently set ones (see property parameters of ExportRequestObject)
- deactivate ambient occlusion for iPadOS
- bugfix: several fixes for glTF 2.0 loader
- bugfix: clearColor/clearAlpha was being reset while dragging operations
------ -------------- ------------------
2.19.0 2020-02-05 - new constructor parameter useModelSettings allowing to switch off the usage of settings which are stored for a model
- new constructor parameter downloadExportButtonName allowing to override button caption in modal dialog for downloadable exports
- support for interactions (drag&drop, selection, hovering) when using the orthographic camera
- glTF 2.0 loader: support for extension KHR_materials_pbrSpecularGlossiness
- unification of loaders for glTF 1.0 and 2.0
- update of the camera settings widget, perspective and various orthographic views can be switched easily now
- bugfix related to setting commitParameters when using export buttons
- bugfix: anchor positions were off when moving window to screen with different device pixel ratio, or when zooming in browser
- bugfix: saving light scene was not working immediately after uploading of a model (in case there were no stored settings yet)
------ -------------- ------------------
2.19.1 2020-02-27 - bugfix: when using new constructor parameter useModelSettings set to false, restoring a light scene caused an exception
- bugfix: export buttons for exports of type shapeways were not shown
------ -------------- ------------------
2.19.2 2020-03-04 - bugfix: Status messages related to a parameter update did not include original process token and payload.
This fix allows events of type api.state.EVENTTYPE.MESSAGE to be linked to the parameter update they belong to,
by passing a payload to api.parameters.updateAsync which will be included in the token.payload property of the event.
- bugfix: some settings were not applied when given in a settings objects,
as an example this happened for and other settings which are vectors
- bugfix: environment map was not loaded in specific cases (timing issue)
- bugfix: light setting controls were always showing default values
- bugfix: background color setting control was always showing default value
------ -------------- ------------------
2.19.3 2020-03-26 - bugfix: text input maximum length was not enforced in the viewer's parameter controls
- bugfix: revertAtMouseUp was triggered on every mouseout event, this caused the camera to be reverted in unnecessary cases
- the SETTINGS_REGISTERED event was not emitted anymore if constructor setting useModelSettings was set to true
------ -------------- ------------------
------ -------------- ------------------
2.20.0 2020-05-04 - new Snap Module for snapping of objects to points and lines, please see documentation of InteractionGroup
- extended SceneAsset by a possibility to drag objects from their bounding box center (new property dragOffset)
- extended SceneAsset by a possibility to drag along further objects (new property dragAdditionalPaths)
- extended event DRAG_START by a callback allowing to define further objects to be dragged along (additionalDragPathsCallBack)
- extended MaterialV2 and MaterialV3 by an optional property side which allows to define the sidedness of meshes
- new setting scene.render.beautyRenderBlendingDuration
- bugfix: api.exports.requestAsync did not support file/blob parameters
- bugfix: obj loader was failing in case mtlUrl was defined
- bugfix: text input maximum length was not enforced in the parameter controls
- bugfix: updating viewer settings was triggering zoom extents in some cases even if settings remained unchanged
- bugfix: light controls were responding to all drag events
- bugfix: improved performance of bounding box computation
- bugfix: in case of commitParameters the Apply button was not working reliably
- bugfix: controls for grid visibility and disabling pan were not working correctly
- bugfix: version check was inefficient when using scene.updateAsync
- removed unnecessary warnings from glTF loader
------ -------------- ------------------
2.20.1 2020-05-19 - reverted feature dragAdditionalPaths which was introduced in 2.20.0
- changed feature additionalDragPathsCallBack introduced in 2.20.0 to additionalInteractionPathsCallBack
which supports selection, dragging and hovering of additional objects
- new property dragPosIntersection for DRAG_START events, which provides the ray intersection point
- new callback property resetPosition for DRAG_END events which allows to reset the position of the dragged object
- performance improvement: avoid unnecessary render calls when adding multiple assets to the scene
- bugfix: http client did not include optional authorization header
- bugfix: checklist inputs did not work anymore
- bugfix: drag plane was not chosen correctly in case of external dragging
- bugfix: dragPosStart did not take into account transformations according to the scene asset item
- bugfix: constructor parameter commitParameters did not work as expected
- bugfix: event CAMERA_END did not trigger for orthographic camera
- bugfix: resetPosition did not reset the rotation
- bugfix: iOS devices could get stuck
- snapping did not work for elements that have already been dragged
- snapping did not work with partial assets
------ -------------- ------------------
2.20.2 2020-06-19 - bugfix: Adding lights via the light controls doesn't work in full screen
- bugfix: Colour picker doesn't work in full screen mode
- bugfix: Anchors are sometimes positioned incorrectly
- bugfix: Transformation issue with rotated snapped elements
- bugfix: Lights anchor offset
------ -------------- ------------------
2.21.0 2020-08-25 - bugfix: Parameter validation - Apply button doesn't work reliably
- bugfix: The resetPosition() function from the DRAG_END event does not take rotations into account
- bugfix: resetPosition() not working with non-snapped objects
- bugfix: When the maximum of a slider is 0 then ShapeDivers shows the maximum to 100
- bugfix: Line Snapping not working reliably
- Implement tests for settings controls (comparing API with control values)
- Override properties of materials contained in glTF/glb assets
- Improve user experience for object dragging (intersection point, dragOffset)
- Scene paths can be excluded from interactions
- Retry failed network requests
------ -------------- ------------------
2.22.0 2020-09-08 - bugfix: Dragging issues with external geometry
- bugfix: bounding box calculation issues that lead to disappearing geometry
- Snapping is now configured to snap to anchors not the center of the object
- glTF loader: use default scheme for names of objects in case names are not defined


  • Version: 2.22.0
  • Build date: 2020-09-08T07:35:37.305Z
  • Branch: 2.22.0
  • Commit: d0859c3d0dda17bf00aee7546844d17ece1f2faf

ShapeDiver 3D Viewer, Copyright © 2015-2019 ShapeDiver GmbH. Documentation generated by JSDoc 3.6.5 on Tue Sep 8th 2020 using the DocStrap template.