Migration Guide

Version 3.16 (16/04/26) - Quince

With the introduction of the new RectangleTransform feature, which is a close relative to the Gumball, existing Gumball functionality has been renamed to GumballTransform, including a renaming of the general package.

• The @shapediver/viewer.features.gumball package has been renamed to @shapediver/viewer.features.transformation-tools. All imports must be updated accordingly:

  • Gumball was renamed to GumballTransform

  • IGumball was renamed to IGumballTransform

  • IGumballEvent was renamed to ITransformationToolsEvent. The new event interface introduces two additional required fields: id (string) and type ("gumball" | "rectangleTransform") to filter for the correct events.

  • GumballEventResponseMapping was renamed to EventResponseMapping (exported from @shapediver/viewer.features.transformation-tools)

  • updateGumballTransformation() was renamed to updateTransformation(). Note: the internal transformation node ID also changed from "SD_gumball_matrix" to "SD_transformation_tools_matrix".

• The IGumball interface previously exposed all enable-flags as directly writable properties at runtime (e.g. gumball.enableRotationX = false). These properties have been removed from IGumballTransform. The settings — including enableRotation, enableScaling, enableTranslation and their per-axis variants, as well as space, scale, and restrictions — must now be passed as constructor arguments via GumballTransformSettingsOptional and can no longer be mutated on the returned instance.

• EVENTTYPE_GUMBALL has been removed and replaced by EVENTTYPE_TRANSFORMATION_TOOLS. The event type value also changed from "gumball.matrixChanged" to "transformation_tools.matrixChanged". Any addListener / removeListener calls using EVENTTYPE_GUMBALL.MATRIX_CHANGED must be updated to EVENTTYPE_TRANSFORMATION_TOOLS.MATRIX_CHANGED.

• The following Gumball-related exports have been renamed across @shapediver/viewer and @shapediver/viewer.session:

  • IGumballParameterApi → IGumballTransformParameterApi

  • IGumballParameterProps → IGumballTransformParameterProps

  • GumballParameterValue → GumballTransformParameterValue

  • IGumballParameterJsonSchema → IGumballTransformParameterJsonSchema

  • IGumballParameterPropsJsonSchema → IGumballTransformParameterPropsJsonSchema

  • isGumballParameterApi() → isGumballTransformParameterApi()

  • validateGumballParameterSettings() → validateGumballTransformParameterSettings()

• In IDrawingParameterSettings, the display property has been renamed to visualization. Any drawing tool parameter settings referencing display: { ... } must be updated to visualization: { ... }.

• createDrawingTools() previously threw a ShapeDiverViewerDrawingToolsError if an existing drawing tools instance was still open. This restriction has been lifted — multiple instances can now be active simultaneously. Code that relied on catching this error to detect singleton violations must now manage instance lifecycles explicitly.

Version 3.14 (30/10/25) - Orange

• Due to the implementation of the SelectionBox feature, multiple objects can now be hovered at once. Therefore, the IHoverEvent needed to be changed and now returns nodes instead of node.

Version 3.0 (21/05/24) - Asgard

• Due to the separation of the Viewport and the Session APIs into separate packages (hydra/headless versions) the naming of some properties in the scene tree were changed as the three.js library was removed from some packages:

  • threeJsObject was renamed to convertedObject

  • updateCallbackThreeJsObject was renamed to updateCallbackConvertedObject

• From this version on, sdTF data is not loaded anymore by default. This affect Attribute Visualization and all applications that need data from sdTF. This change was necessary as this type of data can get quite large and can therefore drastically impact the loading performance. You can enable sdTF loading either:

  • At initialization by setting the loadSdtf in the createSession properties to true

  • At runtime by setting the property loadSdtf in the SessionApi to true. In this case you can listen to the event SESSION_SDTF_DELAYED_LOADED for when the data has been loaded.

• As there was a switch from the mouse/pointer events to the pointer events, the function signature of the function restrictEventListeners has changed.

Version 2.9 (25/05/23) - Jimmy Eat World

• The properties mode, material, standardMaterial, attributeMaterial, materialVariants and effectsMaterial were removed from the PrimitiveData and added to the GeometryData

Version 2.8 (20/04/23) - Interpol

• Removal of tsyringe, classes that were previously requested via container.resolve(ExampleClass) can now be accessed via ExampleClass.instance

Version 2.2 (01/09/22) - Cleopatrick

• The events ISelectEvent, IMultiSelectEvent, IHoverEvent and IDragEvent were moved from @shapediver/viewer to @shapediver/viewer.features.interaction.

• The animations property in the IViewportApi is now a dictionary instead of an array.

Version 2.0 (27/07/22) - Arctic Monkeys

• To avoid further confusion, the naming of the Viewer component of the API was changed to Viewport on all occurrences

• Some previously exposed classes are now only exposed via their interface. The naming stayed the same with a leading I Example: AnimationTrack is now IAnimationTrack

• The API Classes now all have the postfix Api. With the previously point in mind, Session change to ISessionApi.

• The CameraApi now includes all properties that were under Camera.controls directly.

• The enum values are now separated by underscores, therefore enum names may have changed by adding additional underscores. Example: RENDERERTYPE was changed to RENDERER_TYPE
  Important other enum changes:

  • PRIMITIVETYPEHINT → SDTF_TYPEHINT

  • ATTRIBUTEVISUALIZATION → ATTRIBUTE_VISUALIZATION in package @shapediver/viewer.features.attribute-visualization

• The api Object was removed the corresponding functions and variables were moved as follows:

  • api.addListener → addListener

  • api.applySettings → SessionApi.applySettings

  • api.automaticUpdate → SessionApi.automaticSceneUpdate

  • api.closeSession → SessionApi.close

  • api.closeViewer → ViewportApi.close

  • api.convertSceneToGLTF → exists on ViewportApi and SessionApi depending on use case

  • api.createSDTFOverview → ViewportApi.createSDTFOverview

  • api.createSession → createSession

  • api.createViewer → createViewport

  • api.enableAR → ViewportApi.enableAR

  • api.globalScale → ViewportApi.arScale

  • api.globalTranslation → ViewportApi.arTranslation

  • api.globalRotation → ViewportApi.arRotation

  • api.loggingLevel → generalOptions.loggingLevel

  • api.removeListener → removeListener

  • api.sceneTree → sceneTree

  • api.sessions → sessions

  • api.showMessages → generalOptions.showMessages

  • api.update → ViewportApi.update

  • api.viewInAR → ViewportApi.viewInAR

  • api.viewableInAR → ViewportApi.viewableInAR

  • api.viewers → viewports

• AnimationTrack is now IAnimationTrack

• AnchorDataImage is now IAnchorDataImage

• AnchorDataText is now IAnchorDataText

• The AttributeVisualizationEngine now only needs a ViewportApi as input

• The default material MaterialData was renamed to MaterialStandardData

Version 1.15.0

• removed busy and blurSceneWhenBusy, you can now use the branding options when creating a viewer

Version 1.13.0

• viewableInAR only returns a boolean now, no more errors

Version 1.12.2

• import of reflect-metadata not necessary any more

• branding options changed, logo was moved into object

• the HTMLElementAnchorData was reworked, there are now HTMLElementAnchorTextData, HTMLElementAnchorImageData and HTMLElementAnchorCustomData to better fit your needs

Version 1.11.11

• updateOutputContent function signature, session.updateOutputs() now included, can be disabled via flag

Version 1.11.2

• renamed ENVIRONMENTMAP to ENVIRONMENT_MAP

• renamed ENVIRONMENTMAP_CUBE to ENVIRONMENT_MAP_CUBE

Version 1.8.0

• the CDN naming was changed from lowercase sdv to uppercase SDV

• the viewer types were restructured, there is no IStandardViewer or IAttributeViewer anymore, both are the same IViewer where the type can be set later on