Updating scene assets through the API

New viewer version
This article and the other ones in the Viewer category of this website concern the version 2 of the ShapeDiver viewer API. We have since released a version 3 of the viewer API which is documented in the new help center. All the information below is still relevant if you are using version 2 for legacy purposes. Keep in mind that by the end of 2022, maintenance for the version 2 will stop and no more updates or patches will be rolled out to this version. Consider reading our migration guide to version 3.

The particularity of ShapeDiver models is that they are created by a designer who includes most of the variable features of the geometry and materials directly in the 3D model. Therefore, once it is uploaded to ShapeDiver, the standard way to update the model's features is to use the model parameters.

When updating model parameters (typically using api.parameters.updateAsync()), the ShapeDiver viewer automatically reads the updated geometry and materials from the servers and updates the assets in the scene. In the process, the version property is incremented.

The scene interface of the API offers the possibility to explicitly update assets without going through the parameters interface. One should keep in mind that the parameters interface is the most convenient way to update the 3D scene. The scene interface acts at a lower level which requires a more in-depth understanding of the architecture of the viewer.

There are two cases where updating assets is required:

• When the model parameters are too restrictive and don't contain all the options that one wants to give to the end users.
• When updating asset properties which are not available to the designers uploading the models. For example, making objects selectable and draggable or defining animations can only be done with the API at the moment.

First example

Let's consider again the simple example of the previous article. It contains a single sphere geometry asset which references a single material asset.

// geometry asset
{
  name: "Sphere",
  id: "b089ece6ba096bccd3e8461f5d4029bf",
  material: "c49ed428b846ad6f9bf7440b04f2573b", // references the material below
  scenePath: "CommPlugin_1.b089ece6ba096bccd3e8461f5d4029bf",
  version: "99914b932bd37a50b983c5e7c90ae93b",
  content: [{...}] // geometry description
}
// material asset
{
  name: "Sphere",
  id: "c49ed428b846ad6f9bf7440b04f2573b",
  scenePath: "CommPlugin_1.c49ed428b846ad6f9bf7440b04f2573b",
  version: "42cf2f4bf55d11ce65077a6016a0c310",
  content: [{data: {version: "1.0", materialpreset: 1, color: "#ff0000"}, format: "material"}] // material description
}

 The material description describes which material preset is used (default - 1) and the color of the sphere (red = #ff0000).

In order to change the color of the sphere, we first need to create an update object. An update object is a partial description of an asset which contains at least the id of the asset and the properties which need to be modified. In our case, we can define the following update object:

let updateObject = {
  id: "c49ed428b846ad6f9bf7440b04f2573b",
  content: [{data: {version: "1.0", materialpreset: 1, color: "#0000ff"}, format: "material"}]
}

Then we just need to call the update function using this object:

api.scene.updateAsync(updateObject);

Persistent vs non-persistent updates

There are two functions for updating assets using the API. The example above makes use of updateAsync(). This function acts at the same level as parameter updates. It will update the required assets, but the update will be overwritten the next time the asset is updated, either through a parameter change or through another call to updateAsync().

The second function for updating assets is called updatePersistentAsync(). It performs persistent updates: they permanently override the updates made through parameter changes or regular updates made with updateAsync(). The only way to further update the persistent properties afterwards will be through another call to updatePersistentAsync() or by cancelling change.

These different behaviours are illustrated in the example below:

This model contains a single parameter controlling the color of the sphere. It can be used through the parameters interface (first color picker). The two other pickers are linked with the two update functions described above. In particular, note that:

• Changing the model parameter and doing a regular model update are interchangeable operations and can be overwritten by each other, as can be verified by alternating changes with the two first color pickers.
• After doing a persistent update, neither the model parameter nor the regular update are reflected in the asset.
• After cancelling the persistent update, the parameter and the regular update are again applied sucessfully.

A persistent update can simply be cancelled by calling another persistent update with a null value for the target properties which were previously set as persistent.

Checking persistent properties

The assets of a scene can be listed using the function:

api.scene.get(null,"CommPlugin_1");

By default, the function will only return non-persistent properties. All persistent changes will be invisible to the returned list of assets. In the case of the example from the last section, that means the color property will contain the last value set by either the model parameter or a non-persistent update. In order to display the persistent values instead, the function need to be called with a third parameter:

api.scene.get(null,"CommPlugin_1", true);

In that case, all properties which were overwritten using updatePersistentAsync() will display their persistent values. Alternatively, one can just list all persistent properties in the scene with the function

api.scene.getPersistent(null,"CommPlugin_1");