Your models running on ShapeDiver are hosted on one of our Geometry Backend systems. The access to triggering customizations and downloading computation results is controlled by sessions. In order to create a session from an instance of the viewer embedded in a website, you need to provide a ticket for embedding.

In our simple example we already created an instance of the Viewport and opened a Session with a model. Using a Session object you can do things such as change Parameter values and request computation results for them (aka requesting a customization), and request Exports.

The data resulting from computations of a model is available through the Outputs of the session object. Each session corresponds to a node in the scene tree. This node and its children are updated automatically depending on the data resulting from a customization.

You can open simultaneous Sessions with one or several models from a single instance of the viewer, but in most cases you will only be using one.

A Session can exist completely without a Viewport, as a Viewport can exist without a Session. For more functions and properties, please see our Documentation on Session, Parameter, Export and Output.

Credit usage of embedded sessions

Each session opened from an embedded viewer consumes at least one credit.

In case you open simultaneous sessions with one or several models from a single instance of the viewer, each individual session consumes a credit.

Each credit covers an active session duration of up to 10 minutes during which unlimited customizations (parameter changes) can happen. If a session exceeds 10 minutes of usage, another credit covering a further 10 minute active session duration is deducted as soon as the first customization happens which is not covered by the previous 10 minute period anymore. As an example:

A user opens a web page which embeds one of your models. The user engages with the model for about 5 minutes and does several parameter changes, then leaves the model unattended. After 20 minutes the user comes back and further changes parameters for about 8 minutes. This will consume 2 credits.

Please note that triggering exports consumes further credits as mentioned below.

Read more about ShapeDiver credits in the pricing page.

Parameters

Let's continue with the simple example of our last section and add something to it. The Session that we use as an example can change the length of the provided shelf from values 2 to 10. In our first case we just want to change it to 6.

You can also update multiple Parameters together and then customize the Session in the end. We will now update the length to 8 and update the color to #00ff00 (green). Notice that the customization call is only called once. Therefore, only one request is sent to our servers.

Exports

Exports can be requested easily as well.

Credit usage of exports

Each export triggered consumes a credit.

Additional CodeSandBoxes

  • Content Update
    Updating the content of an output with custom data, in this case, material data. Freezing the output not to be overwritten by parameter value changes.

  • Persistence Between Updates
    Updating simple properties like the visibility of nodes and making such changes persist across parameter value changes.

  • Persistence Between Updates (advanced)
    Updating advanced outputs like HTMLElements added to the scene and making such changes persist across parameter value changes.

  • Automatic Scene Updates
    Automatic triggering of scene updates on parameter value changes.

  • Parallel Customization
    Request multiple customizations in parallel. The results will only be returned to you, but not stored in the scene. Note: Depending on the plan you are subscribed to, your parallel customization requests will be rate limited.

  • Initial Parameter Values
    Parameter values can be provided on initialization.

  • Catching Errors
    Errors that happen during the initialization (and customization) can be caught and mapped.

Parameters

  • File Parameters
    How to use file parameters that allow using files as parameter values.

  • File Parameters - advanced
    How to use file parameters that allow using files as parameter values. In this example mime types and file endings are considered.

Exports

Outputs