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.

commitParameters

commitParameters: boolean

(Platform specific) Option to enable commit-mode for parameters. This setting is used purely for UI purposes, it does not have any influence on the session itself.

commitSettings

commitSettings: boolean

(Platform specific) Option to enable commit-mode for settings. This setting is used purely for UI purposes, it does not have any influence on the session itself.

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 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

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 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

  • applySettings(response: ShapeDiverResponseDto, sections?: ISettingsSections): Promise<void>

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(): 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}

    Returns Promise<Blob>

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]: string

    Returns Promise<ITreeNode>

customizeResult

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

  • 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]: string

    Returns Promise<ShapeDiverResponseDto>

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[]

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: ShapeDiverRequestExport, loadOutputs?: boolean, maxWaitMsec?: number): Promise<ShapeDiverResponseDto>

  • Request one or multiple exports.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • body: ShapeDiverRequestExport

      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<ShapeDiverResponseDto>

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>