Skip to main content
Skip table of contents

Viewer 2 - Migration Guide

This guide is targeted at users that already used our Viewer 2 and want to upgrade to Viewer 3. If you are just looking for the documentation on Viewer 2, please click here.

Reason to Upgrade

  • completely reworked Viewer

  • everything is written 100% in TypeScript

  • can be integrated via npm

  • continuous support (Viewer 2 will only be supported until the end of 2023)

  • legacy features and new features

  • direct access to the scene tree

  • and much more to come…


Migration

Installation

For Viewer 2, it was only possible to use the Viewer via a CDN. Now, you can chose between using it via CDN or via NPM. Please view the Installation Guide for further details.

Initial Setup

The initial setup was simplified and refactored to be tailored to our users needs. Compare the initialization of a sessions for both viewer below.

Viewer 2

TYPESCRIPT
const settings = {
  container: document.getElementById('sdv-container'); ,
  ticket: "53af6cbde9e2308f1851ffd0895cbd7b13328cf2bddefbe8a93f2faf9949d2bee5185ee07a5de7ba0e918fed48e07386d21157c53f1665c65e66349edd421d6c3340934b4e2a7ee388422ac4e2ad0230825b7d6f01f3b44c83d62582fa329aa6607217c99968e8c4a13d1acb08083076819db788fadf-6a161aeaf69fff37bcf1ba53679be40e",
  modelViewUrl: "eu-central-1",
  showControlsInitial: true,
  showSettingsInitial: false,
};

const api = new SDVApp.ParametricViewer(settings);

Viewer 3

TYPESCRIPT
const viewport = await SDV.createViewport({ 
  canvas: document.getElementById('canvas'), 
  id: 'myViewport'
});

const session = await SDV.createSession({
  ticket: '53af6cbde9e2308f1851ffd0895cbd7b13328cf2bddefbe8a93f2faf9949d2bee5185ee07a5de7ba0e918fed48e07386d21157c53f1665c65e66349edd421d6c3340934b4e2a7ee388422ac4e2ad0230825b7d6f01f3b44c83d62582fa329aa6607217c99968e8c4a13d1acb08083076819db788fadf-6a161aeaf69fff37bcf1ba53679be40e',
  modelViewUrl: 'https://sdeuc1.eu-central-1.shapediver.com',
  id: 'mySession'
});

As you can see, in Viewer 3, there are now two objects that are created. A Viewport-Object and a Session-Object. Either one can be created first, and one can be created without the other. You can also create multiple Viewport-Objects and multiple Session-Objects.

Parameters

The way how parameters are updated should now be much clearer. We tried to simplify the process to makes things more convenient for you. In both examples, we update a parameter with the id parameterId with a newValue.

Viewer 2

TYPESCRIPT
await api.parameters.updateAsync({id: "parameterId", value: newValue});

Viewer 3

CODE
session.parameters["parameterId"].value = newValue;
await session.customize();

In Viewer 3, you can now store parameters in a separate variable to have easier access to them. Additionally, by separating the customization call and the updating of the value, you can decide at what point you want to tell the server about parameter updates much more easily.

The session also has different ways of getting the parameter. In this example, we use the dictionary, which is created with the ids. The functions getParameterById, getParameterByName and getParameterByType let you search for your parameter in whichever way you want.

Exports

For exports, the approach to use is very similar. Again we can use the id as a key for the dictionary, or we can use the helper functions getExportById, getExportByName and getExportByType. Requesting an export is still a simple process.

Viewer 2

TYPESCRIPT
await api.exports.requestAsync({id: "exportId"});

Viewer 3

CODE
await session.exports["exportId"].request();

Outputs

The outputs that are created are evaluated a bit differently then we did it previously. They are actually now called outputs and are not obscured anymore in some data. To get all the data of an output, simply get the output with the helper functions getOutputById and getOutputByName or use the id for dictionary access.

Viewer 2

TYPESCRIPT
api.scene.getData({ id: "outputId"})

Viewer 3

CODE
session.outputs["outputId"]

The output will contain all data available for it. Under the content property, you can find all the data that is available.

Further Examples

For further information about Sessionsand Viewers, please view the linked tutorials. There you’ll see how what else you can do.

Additionally, we created the same example in Viewer 2 and Viewer 3. This example creates UI elements from the parameters and exports provided. When something is changed, the parameter is updated.

The Viewer 2 example can be seen here, and the Viewer 3 example can be seen here.

Note: Please note that the options showControlsInitial and showSettingsInitial are not possible any more. If you want to create your own UI, please have a look at this example.

Additional Notes

  • The interactions from Viewer 2 to Viewer 3 were completely reworked and changed. Please see our help pages for more information on this.

  • The function toggleGeometry was replaced by the visible property of nodes. Please view or detailed node documentation and our general documentation on the scene tree.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.