Model States

This feature allows you to save and share the state of ShapeDiver models. Each state is assigned a unique ID, enabling you to recall it later or share it on social media. Model states are already available in App Builder and will be available on the Platform shortly.

Data Saved

Parameter key-value pairs: The current parameter values.

Untyped JSON object: Optional data for storing additional state (e.g., UI state).

Screenshot image: Optional image for social media sharing (OpenGraph tags).

AR scene ID: Optional link to an AR scene (a glTF and a usdz asset), allowing for fast 3D preview.

Additional API Features

Please see ShapeDiver Geometry Backend API v2 - Model States.

Get the state’s data based on a model state ID.
Access the (optional) image linked to a state based on a model state ID.
Access the (optional) glTF and usdz asset linked to a state based on a model state ID.

Usage

If you already created a model state, you can

use its ID when creating a session (specify the model state ID in the initial settings). This applies the model state to the session's default parameter values. You can also
customize an existing session with a model state.

Additionally, the Viewer API includes a function to create a new model state. This function allows you to create a new model state on the Geometry Backend, which includes parameter values, images, and additional data. The available properties are:

parameterValues (optional): Map of parameter IDs to values. Defaults to the session’s current values if not provided.
omitSessionParameterValues (optional): If set to true, the model state is stored without the current session values unless specified (default: false).
image (optional): Provide an image as a data URL, Blob, File, or function that generates one.
data (optional): Add any additional custom data (e.g., UI state).
arScene (optional): Attach a glTF file representing the state of the 3D scene.

The returned string is the ID of the model state that can be used to retrieve it at a later point.

Examples

Create a session and apply an existing model state as an option.

TYPESCRIPT

const session = await SDV.createSession({
    // other properties
    modelStateId: 'MODEL_STATE_ID'
});

Customize a session with a model state.

TYPESCRIPT

// this can be either a model state id or the model state object
await session.customizeWithModelState(modelState);

Create a new model state.

CODE

// create a new model state, please see additional options in the API documentation
await session.createModelState()

Create a new model state with a screenshot and a glTF of the current scene.

TYPESCRIPT

await session.createModelState(
  {}, // the parameter object
  false, // if the session values should be omitted
  () => viewport.getScreenshot(), // function that creates a screenshot
  undefined, // any object
  async () => await viewport.convertToGlTF() // function that creates the glTF
)

Applying model states to other models

Model states are linked to the model they were created for. However, they can be applied to other models, allowing you to deploy updated versions without losing access to model states created for previous versions of your models. Parameter values are, by default, applied loosely, matching parameters by id or name. If no matching parameter is found for a parameter value stored in a model state, it is ignored. When using the API, it is possible to force strict matching, causing an error if no matching parameter is found.

Caveat: Applying the values of file parameters across models is not available yet.

Lifetime

Model states have a lifetime of 6 months. If a model state hasn’t been used for 6 months, it will be cleaned up.