Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface ISessionApi

The api for sessions.

A session represents an instance of a model hosted on a ShapeDiver Geometry Backend.

Sessions are created by calling createSession.

The session contains representations of the model's parameters, outputs and exports. Each session corresponds to a node in the scene tree, which reflects the status of the outputs for the current parameter values.

On change of parameter values (aka customizations), the session makes the necessary calls to the Geometry Backend to trigger a computation of the model (if required), wait for its completion, download the resulting assets, and create an updated scene tree.

A model may define exports, whose data is not reflected in the scene tree, but can be requested by functionality of the session.

Hierarchy

  • ISessionApi

Index

Properties

Methods

Properties

automaticSceneUpdate

automaticSceneUpdate: boolean

Option to automatically update the session's scene tree node whenever a customization finishes. (default: true)

In case this is set to false, the session's scene tree node will not be automatically replaced by the node returned from customize. This can be used to plug the result of customize into other parts of the scene tree.

customizeOnParameterChange

customizeOnParameterChange: boolean

Option to trigger a call to customize whenever a parameter value is changed.

Use this with care as this might max out the rate limit for your model on the Geometry Backend.

excludeViewports

excludeViewports: string[]

The ids of the viewports in which the session's scene tree node should not be shown.

Readonly exports

exports: {}

The exports defined by the model. This object maps export ids to export definitions.

Type declaration

Readonly hasStoredSettings

hasStoredSettings: boolean

Flag to indicate if the session has stored settings. This is true if at some points settings were stored for the session.

Readonly id

id: string

The unique identifier of the session that was specified or automatically chosen on creation of the session.

Readonly jwtToken

jwtToken: undefined | string

The JWT used for authorizing API calls to the Geometry Backend.

see

setJwtToken

loadSdtf

loadSdtf: boolean

Option to load the SDTF data. The data is not loaded by default as it can be quite large. (default: false)

Readonly modelViewUrl

modelViewUrl: string

The modelViewUrl of the ShapeDiver Geometry Backend hosting the model.

Readonly node

node: ITreeNode

The node of the session in the scene tree.

Readonly outputs

outputs: {}

The outputs defined by the model. This object maps output ids to output definitions.

Type declaration

Readonly parameterDefaultValues

parameterDefaultValues: {}

The parameter values that are the defaults of the session. Changing these values does not have any affect. The values in this dictionary only reflect the defval of the parameters.

Type declaration

  • [key: string]: unknown

Readonly parameterSessionValues

parameterSessionValues: {}

The parameter values that were used in the last successful session customization. These values may not reflect the current state in the parameters if there was a change in parameters after the last customization call. Changing these values does not have any affect. The values in this dictionary only reflect the sessionValue of the parameters.

Type declaration

  • [key: string]: unknown

Readonly parameterValues

parameterValues: {}

The parameter values that are currently set in the API. These values may not reflect the current state in the scene if there was a change in parameters after the last customization call. Changing these values does not have any affect. The values in this dictionary only reflect the value of the parameters.

Type declaration

  • [key: string]: unknown

Readonly parameters

parameters: {}

The parameters defined by the model. This object maps parameter ids to parameter definitions.

Type declaration

refreshJwtToken

refreshJwtToken: undefined | (() => Promise<string>)

Optional callback which can be specified for refreshing the JWT. This will be called by the session once the JWT expires. The callback is required to provide a fresh JWT.

updateCallback

updateCallback: null | ((newNode?: ITreeNode, oldNode?: ITreeNode) => void | Promise<void>)

A callback that is executed whenever a session's node is to be replaced due to an update of the session's content. Provides the new scene tree node and the old one, so that data can be carried over. If the callback is a promise it will be awaited in the execution chain.

Optional Readonly guid

guid?: string

The geometry backend model id (guid). This identifies the model on the Geometry Backend. A jwtToken is needed for authentication.

Optional hideAttributeVisualization

hideAttributeVisualization?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideAttributeVisualizationIframe

hideAttributeVisualizationIframe?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideDataOutputs

hideDataOutputs?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideDataOutputsIframe

hideDataOutputsIframe?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideDesktopClients

hideDesktopClients?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideExports

hideExports?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideExportsIframe

hideExportsIframe?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideJsonMenu

hideJsonMenu?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideJsonMenuIframe

hideJsonMenuIframe?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideSavedStates

hideSavedStates?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional hideSavedStatesIframe

hideSavedStatesIframe?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional Readonly modelState

modelState?: ResModelState

The model state of the session. This object contains information about the model state. It is only available if a model state id was provided on session creation.

Optional parametersCommit

parametersCommit?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional parametersDisable

parametersDisable?: boolean

Configuration Settings for the model. This settings is not used within the viewer, but is passed through for usage in the platform or App Builder. If you want to change this setting, please do so on the model edit page of the ShapeDiver platform.

Optional Readonly ticket

ticket?: string

The ticket for direct embedding of the model represented by the session. This identifies the model on the Geometry Backend.

Methods

applySettings

canGoBack

  • canGoBack(): boolean

  • Check if the session's history allows to go back to a previous state of parameter values. The session history is recorded whenever customize is called.

    A further state of parameter values is recorded whenever a successful customization happens.

    see

    customize

    see

    canGoBack

    see

    canGoForward

    see

    goBack

    see

    goForward

    Returns boolean

canGoForward

  • canGoForward(): boolean

  • Check if the session's history allows to go forward to a next state of parameter values. The session history is recorded whenever customize is called.

    A further state of parameter values is recorded whenever a successful customization happens.

    see

    customize

    see

    canGoBack

    see

    canGoForward

    see

    goBack

    see

    goForward

    Returns boolean

cancelCustomization

  • cancelCustomization(): void

  • Cancel the current customization if there is one in progress. Requests that were already sent will still be received, but not further processed.

    Returns void

close

  • close(): Promise<void>

  • Close the session. This removes the node from the scene tree and closes the session with the Geometry Backend.

    throws

    {@type ShapeDiverViewerError}

    Returns Promise<void>

convertToGlTF

  • convertToGlTF(convertForAR?: boolean): Promise<Blob>

  • Convert the session into a glTF file.

    The ground plane and grid will not be included, as well as additionally added data that was added to the scene other than through a GeometryData property.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional convertForAR: boolean

      Option to convert the scene for AR. In this case some specific use cases are target to ensure the best AR performance. (default: false)

    Returns Promise<Blob>

createModelState

  • createModelState(parameterValues?: {}, omitSessionParameterValues?: boolean, image?: string | Blob | File | Promise<string> | (() => string) | (() => Promise<string>), data?: Record<string, any>, arScene?: ArrayBuffer | Blob | File | (() => Promise<ArrayBuffer>) | (() => Promise<Blob>)): Promise<string>

  • Create a new model state. This function creates a new model state on the Geometry Backend.

    For each parameter, the current state of the parameter in the session is used if no parameter value is provided. The omitSessionParameterValues flag can be used to store the model state without the current parameter values of the session. For the image property, a function that returns a data URL (() => string), a data URL (string), a Blob (Blob) or a File (File) can be provided. (Example: () => viewport.getScreenShot()) The data property can be used to provide additional data for the model state. An example for this would be a UI state object of a web application. The arScene property can be used to provide a glTF representing an AR scene of the model state. The glTF can be provided as an ArrayBuffer ('ArrayBuffer'), a function that returns an ArrayBuffer (() => ArrayBuffer), a Blob (Blob), a function that returns an Blob (() => Blob), or a File (File). (Example: () => viewport.convertToGlTF())

    Parameters

    • Optional parameterValues: {}

      The set of parameter values to use. Map from parameter id to parameter value. The current value will be used for any parameter not specified.

      • [key: string]: unknown
    • Optional omitSessionParameterValues: boolean

      If omitSessionParameterValues is set to true, the current parameter values of the session will not be stored with the model state, if no parameter value is provided. (Default: false)

    • Optional image: string | Blob | File | Promise<string> | (() => string) | (() => Promise<string>)

      The image to use for the model state. Can be a function that returns a data URL (() => string), a function of a promise of a data URL (() => Promise<string>), a data URL (string), a promise of a data URL (Promise<string>), a Blob (Blob) or a File (File).

    • Optional data: Record<string, any>

      The additional data for the model state.

    • Optional arScene: ArrayBuffer | Blob | File | (() => Promise<ArrayBuffer>) | (() => Promise<Blob>)

      The AR scene for the model state. Can be a function that returns an ArrayBuffer ('ArrayBuffer'), a function that returns an ArrayBuffer (() => ArrayBuffer), a Blob (Blob), a function that returns an Blob (() => Blob), or a File (File).

    Returns Promise<string>

    The id of the created model state.

customize

  • customize(parameterValues?: {}, force?: boolean, waitForViewportUpdate?: boolean): Promise<ITreeNode>

  • Customize the session.

    The current state of parameter values is used to request the outputs of the model from the Geometry Backend. The specific version of an output for a given set of parameter values is called output version. In case the Geometry Backend has already cached the requested output versions, it will reply immediately, otherwise a computation request for the missing output versions of the model will be triggered and awaited. Once the output versions are available, the resulting assets will be downloaded, extracted, and the resulting scene tree node will be created.

    Unless automaticSceneUpdate is set to false, the session's node will be updated and viewports will be rendered.

    Independent of automaticSceneUpdate, right before returning the following will happen:

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional parameterValues: {}

      The set of parameter values to use. Map from parameter id to parameter value. The current value will be used for any parameter not specified.

      • [key: string]: unknown
    • Optional force: boolean

      If force is set to true, the customization call will even be called if no parameters have changed. (Default: false)

    • Optional waitForViewportUpdate: boolean

      If waitForViewportUpdate is set to true, the promise will only resolve when the geometry was processed by the viewport(s) and is visible in the scene. (Default: false)

    Returns Promise<ITreeNode>

customizeParallel

  • customizeParallel(parameterValues: {}): Promise<ITreeNode>

  • Customize the session, parallel mode.

    Use this instead of customize in case you want to run several customizations in parallel, or you do not want the customization to affect the current state of the outputs or parameters. The node resulting from this call has to be manually inserted into the scene.

    Calls to this function will not update the session's node nor the outputs' nodes, and also not update IParameterApi.sessionValue of the parameters. Note that IOutputApi.updateCallback will not be called, and IOutputApi.freeze will be ignored.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • parameterValues: {}

      The set of parameter values to use. Map from parameter id to parameter value. The current value will be used for any parameter not specified.

      • [key: string]: unknown

    Returns Promise<ITreeNode>

customizeResult

  • customizeResult(parameterValues: {}): Promise<ResBase>

  • Customize the session and only receive the result of the customization call.

    Use this instead of customize in case you want to run customizations and only work with the data of the customization result

    Calls to this function will not update the session's node nor the outputs' nodes, and also not update IParameterApi.sessionValue of the parameters. Note that IOutputApi.updateCallback will not be called, and IOutputApi.freeze will be ignored.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • parameterValues: {}

      The set of parameter values to use. Map from parameter id to parameter value. The current value will be used for any parameter not specified.

      • [key: string]: unknown

    Returns Promise<ResBase>

customizeWithModelState

  • customizeWithModelState(modelState: string | ResBase): Promise<ITreeNode>

  • Customize the session with a given model state. This function creates uses the parameter values of the given model state to customize the session.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • modelState: string | ResBase

      The model state to use. This can be a model state id or a ResBase.

    Returns Promise<ITreeNode>

getExportById

  • Get an export definition by id.

    Parameters

    • id: string

      The id of the export.

    Returns null | IExportApi

getExportByName

  • Get export definitions by name. Please note that a model may define multiple exports for a given name.

    Parameters

    • name: string

      The name of the exports.

    Returns IExportApi[]

getExportByType

  • Get export definitions by type. Please note that a model may define multiple exports for a given type.

    Parameters

    • type: string

      The type of the exports.

    Returns IExportApi[]

getModelState

  • getModelState(modelStateId?: string): Promise<ResGetModelState>

  • Get the model state of the provided model state id.

    Parameters

    • Optional modelStateId: string

      The id of the model state to get. If not provided, the current model state will be returned.

    Returns Promise<ResGetModelState>

getOutputByFormat

  • Get output definitions by format of the output's current content.

    This function filters output definitions by the format of the output's current content, which depends on the current state of the output's IOutputApi.node. The results of this function may vary depending on this state.

    Parameters

    • format: string

      The format of the output's content.

    Returns IOutputApi[]

getOutputById

  • Get an output definition by id.

    Parameters

    • id: string

      The id of the output.

    Returns null | IOutputApi

getOutputByName

  • Get output definitions by name. Please note that a model may define multiple outputs for a given name.

    Parameters

    • name: string

      The name of the outputs.

    Returns IOutputApi[]

getParameterById

  • Get parameter definition by id.

    Parameters

    • id: string

      The id of the parameters.

    Returns null | IParameterApi<unknown>

getParameterByName

  • Get parameter definitions by name. Note that a model may define multiple parameters for a given name.

    Parameters

    • name: string

      The name of the parameters.

    Returns IParameterApi<unknown>[]

getParameterByType

  • Get parameter definitions by type. Note that a model may define multiple parameters for a given type.

    Parameters

    • type: string

      The type of the parameters.

    Returns IParameterApi<unknown>[]

goBack

goForward

loadCachedOutputs

  • loadCachedOutputs(outputs: {}): Promise<{}>

  • Load cached outputs to be able to insert them into the scene manually.

    Only outputs that are cached on the backend are loaded. If an output is not cached, undefined is returned instead.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • outputs: {}

      The set of outputs. Map from output id to output version.

      • [key: string]: string

    Returns Promise<{}>

requestExports

  • requestExports(body: ReqExport, loadOutputs?: boolean, maxWaitMsec?: number): Promise<ResBase>

  • Request one or multiple exports.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • body: ReqExport

      The body of the export request.

    • Optional loadOutputs: boolean

      If loadOutputs is set to true, if result of the export request contains outputs, they will be loaded into the session. (Default: false)

    • Optional maxWaitMsec: number

    Returns Promise<ResBase>

resetParameterValues

  • resetParameterValues(force?: boolean): Promise<ITreeNode>

  • Reset the parameters to their stored default values and customize the scene.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional force: boolean

      If force is set to true, the customization call will even be called if no parameters have changed. (Default: false)

    Returns Promise<ITreeNode>

resetSettings

  • Reset all or some settings of the current session and the viewports.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional sections: ISettingsSections

      specify false for those parts of the settings that should not be applied

    Returns Promise<void>

saveDefaultParameterValues

  • saveDefaultParameterValues(): Promise<boolean>

  • Save the current state of parameter values of this session as the default parameter values of the model.

    This call will throw an exception if the ticket and JWT do not grant the required permission to save parameter default values for the model.

    throws

    {@type ShapeDiverViewerError}

    Returns Promise<boolean>

saveSettings

  • saveSettings(viewportId?: string): Promise<boolean>

  • Save the 3D viewport related settings of this session to the model hosted on the Geometry Backend.

    If a viewportId is provided, the settings of that viewport will be used for saving.

    This call will throw an exception if the ticket and JWT do not grant the required permission to save viewport settings for the model.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional viewportId: string

      The optional viewport id.

    Returns Promise<boolean>

saveUiProperties

  • saveUiProperties(): Promise<boolean>

  • Save UI-related properties of parameter, output, and export definitions (displayname, order, hidden and tooltip, etc).

    This call will throw an exception if the ticket and JWT do not grant the required permissions for the model.

    throws

    {@type ShapeDiverViewerError}

    Returns Promise<boolean>

setJwtToken

  • setJwtToken(token: string): Promise<void>

  • Set a new JWT used for authorizing API calls to the Geometry Backend. If a change of the JWT would result in different parameters / exports / outputs of the model, please create a new session with that token instead.

    see

    jwtToken

    Parameters

    • token: string

    Returns Promise<void>

updateOutputs

  • updateOutputs(waitForViewportUpdate?: boolean): Promise<ITreeNode>

  • Update the current available outputs. Calling this function makes sense if you have updated one of the outputs manually by calling IOutputApi.updateOutputContent.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional waitForViewportUpdate: boolean

      If waitForViewportUpdate is set to true, the promise will only resolve when the geometry was processed by the viewport(s) and is visible in the scene. (Default: false)

    Returns Promise<ITreeNode>

uploadFileParameters

  • uploadFileParameters(values: {}): Promise<{}>

  • Upload the files that are specified in the provided values. If a file parameter is not specified in the values, the current value will be used. The ids of the uploaded files are returned in a map from parameter id to file id.

    Note: The currently set file parameters will be uploaded automatically by customize, customizeParallel, requestExports, and {@link requestExport}.

    Parameters

    • values: {}

      The set of file parameters to upload. If a parameter is not a file parameter, the current value will be used.

      • [key: string]: string | File | Blob

    Returns Promise<{}>