Viewer 2 - Migration Guide

From June 21st, 2024, free support and maintenance for the version 2 of the viewer will be discontinued. Models embedded with this version of the viewer will keep working as always, but no new bug fixes will be filed, and no new support discussions will be handled on the forum or through private Business support.

Our team will, however, provide help and implementation services at our standard hourly rate, as part of our professional services offer. Read more about our professional services here.

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

• 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);

Viewer 3

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

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

Viewer 3

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

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

Viewer 3

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

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

Viewer 3

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.