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

  • 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

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

const api = new SDVApp.ParametricViewer(settings);
TYPESCRIPT

Viewer 3

const viewer = await SDV.api.createViewer({ 
  canvas: document.getElementById('canvas'), 
  id: 'myViewer'
});

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

As you can see, in Viewer 3, there are now two objects that are created. A Viewer-Object and a Session-Object. Either one can be created first, and one can be created without the other. You can also create multiple Viewer-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

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

Viewer 3

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

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

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

Viewer 3

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

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

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

Viewer 3

session.outputs["outputId"]
CODE

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.