@shapediver/viewer.session 3.0.0

package/src/index.ts

@@ -0,0 +1,225 @@
+import {
+    addListener,
+    generalOptions,
+    IGeneralOptions,
+    removeListener,
+    sceneTree,
+    version
+} from '@shapediver/viewer.api.general';
+import {
+    AnimationData,
+    AttributeData,
+    CustomData,
+    EventResponseMapping,
+    GeometryData,
+    HTMLElementAnchorCustomData,
+    HTMLElementAnchorData,
+    HTMLElementAnchorImageData,
+    HTMLElementAnchorTextData,
+    IAnchorDataImage,
+    IAnchorDataText,
+    IAnimationData,
+    IAnimationTrack,
+    IAttributeData,
+    ICameraEvent,
+    ICustomData,
+    IGeometryData,
+    IHTMLElementAnchorData,
+    IMapData,
+    IMaterialAbstractData,
+    IMaterialAbstractDataProperties,
+    IMaterialBasicLineData,
+    IMaterialBasicLineDataProperties,
+    IMaterialGemData,
+    IMaterialGemDataProperties,
+    IMaterialMultiPointData,
+    IMaterialMultiPointDataProperties,
+    IMaterialPointData,
+    IMaterialPointDataProperties,
+    IMaterialSpecularGlossinessData,
+    IMaterialSpecularGlossinessDataProperties,
+    IMaterialStandardData,
+    IMaterialStandardDataProperties,
+    IMaterialUnlitData,
+    IMaterialUnlitDataProperties,
+    IMaterialVariantsData,
+    IOutputEvent,
+    IParameterEvent,
+    IPrimitiveData,
+    IRenderingEvent,
+    ISceneEvent,
+    ISDTFAttributeData,
+    ISDTFAttributesData,
+    ISDTFAttributeVisualizationData,
+    ISDTFItemData,
+    ISDTFOverview,
+    ISDTFOverviewData,
+    ISessionEvent,
+    ISessionSettingsSections,
+    ISettingsSections,
+    ITaskEvent,
+    IViewportEvent,
+    IViewportSettingsSections,
+    MapData,
+    MATERIAL_ALPHA,
+    MATERIAL_SHADING,
+    MATERIAL_SIDE,
+    MATERIAL_TYPE,
+    MaterialBasicLineData,
+    MaterialGemData,
+    MaterialMultiPointData,
+    MaterialPointData,
+    MaterialSpecularGlossinessData,
+    MaterialStandardData,
+    MaterialUnlitData,
+    MaterialVariantsData,
+    PARAMETER_TYPE,
+    PARAMETER_VISUALIZATION,
+    PRIMITIVE_MODE,
+    PrimitiveData,
+    SDTF_TYPEHINT,
+    SDTFAttributeData,
+    SDTFAttributesData,
+    SDTFItemData,
+    SDTFOverviewData,
+    SdtfPrimitiveTypeGuard,
+    TASK_TYPE,
+    TEXTURE_FILTERING,
+    TEXTURE_WRAPPING
+} from '@shapediver/viewer.shared.types';
+import {
+    Box,
+    IBox,
+    IGeometry,
+    ISphere,
+    Sphere
+} from '@shapediver/viewer.shared.math';
+import { createSession, sessions } from './main';
+import {
+    EVENTTYPE,
+    EVENTTYPE_CAMERA,
+    EVENTTYPE_DRAWING_TOOLS,
+    EVENTTYPE_INTERACTION,
+    EVENTTYPE_OUTPUT,
+    EVENTTYPE_PARAMETER,
+    EVENTTYPE_RENDERING,
+    EVENTTYPE_SCENE,
+    EVENTTYPE_SESSION,
+    EVENTTYPE_TASK,
+    EVENTTYPE_VIEWPORT,
+    IDomEventListener,
+    IEvent,
+    isARError,
+    isViewerCameraError,
+    isViewerDataProcessingError,
+    isViewerDrawingToolsError,
+    isViewerEnvironmentMapError,
+    isViewerError,
+    isViewerGeometryBackendError,
+    isViewerGeometryBackendGenericError,
+    isViewerGeometryBackendRequestError,
+    isViewerGeometryBackendResponseError,
+    isViewerInteractionError,
+    isViewerLightError,
+    isViewerSessionError,
+    isViewerSettingsError,
+    isViewerUnknownError,
+    isViewerValidationError,
+    isViewerViewportError,
+    isViewerWebGLError,
+    LOGGING_LEVEL,
+    MainEventTypes,
+    SESSION_SETTINGS_MODE,
+    ShapeDiverGeometryBackendError,
+    ShapeDiverGeometryBackendRequestError,
+    ShapeDiverGeometryBackendResponseError,
+    ShapeDiverGeometryBackendResponseErrorType,
+    ShapeDiverViewerArError,
+    ShapeDiverViewerCameraError,
+    ShapeDiverViewerDataProcessingError,
+    ShapeDiverViewerDrawingToolsError,
+    ShapeDiverViewerEnvironmentMapError,
+    ShapeDiverViewerError,
+    ShapeDiverViewerErrorType,
+    ShapeDiverViewerInteractionError,
+    ShapeDiverViewerLightError,
+    ShapeDiverViewerSessionError,
+    ShapeDiverViewerSettingsError,
+    ShapeDiverViewerUnknownError,
+    ShapeDiverViewerValidationError,
+    ShapeDiverViewerViewportError,
+    ShapeDiverViewerWebGLError
+} from '@shapediver/viewer.shared.services';
+import { IExportApi } from './interfaces/IExportApi';
+import { IFileParameterApi } from './interfaces/IFileParameterApi';
+import {
+    IMaterialContentDataV1,
+    IMaterialContentDataV2,
+    IMaterialContentDataV3,
+    ITag2D,
+    ITag3D,
+    ITexture,
+    TAG3D_JUSTIFICATION
+} from '@shapediver/viewer.data-engine.shared-types';
+import { IOutputApi } from './interfaces/IOutputApi';
+import { IOutputApiData } from './interfaces/data/IOutputApiData';
+import { IParameterApi } from './interfaces/IParameterApi';
+import { ISessionApi } from './interfaces/ISessionApi';
+import { ISessionApiData } from './interfaces/data/ISessionApiData';
+import {
+    ISessionData,
+    ISessionOutputData,
+    SessionData,
+    SessionOutputData,
+    ShapeDiverResponseOutputChunk,
+    ShapeDiverResponseOutputContent
+} from '@shapediver/viewer.session-engine.session-engine';
+import {
+    ITransformation,
+    ITree,
+    ITreeNode,
+    ITreeNodeData,
+    Tree,
+    TreeNode
+} from '@shapediver/viewer.shared.node-tree';
+import { OutputApiData } from './implementation/data/OutputApiData';
+import { SessionApiData } from './implementation/data/SessionApiData';
+import { SessionCreationDefinition } from '@shapediver/viewer.creation-control-center.session';
+import {
+    ShapeDiverResponseExport,
+    ShapeDiverResponseExportContent,
+    ShapeDiverResponseExportDefinitionGroup,
+    ShapeDiverResponseExportResult,
+    ShapeDiverResponseModelComputationStatus,
+    ShapeDiverResponseParameter
+} from '@shapediver/sdk.geometry-api-sdk-v2';
+import {
+    ShapeDiverResponseExportDefinitionType as EXPORT_TYPE,
+    ShapeDiverResponseOutput,
+    ShapeDiverResponseOutputChunk as ShapeDiverResponseOutputChunkBackend,
+    ShapeDiverResponseOutputContent as ShapeDiverResponseOutputContentBackend
+} from '@shapediver/sdk.geometry-api-sdk-v2';
+
+export { IExportApi, IFileParameterApi, IOutputApi, IParameterApi, ISessionApi };
+export { ISessionApiData, SessionApiData, IOutputApiData, OutputApiData };
+
+export { createSession, sessions };
+
+export { addListener, removeListener, sceneTree, generalOptions, version, IGeneralOptions };
+
+export { SessionCreationDefinition };
+export { ITree, Tree, ITreeNode, TreeNode, ITreeNodeData };
+export { PARAMETER_TYPE, EXPORT_TYPE, PARAMETER_VISUALIZATION, TAG3D_JUSTIFICATION, LOGGING_LEVEL, PRIMITIVE_MODE, MATERIAL_SIDE, MATERIAL_ALPHA, MATERIAL_SHADING, MATERIAL_TYPE, TEXTURE_WRAPPING, TEXTURE_FILTERING, SDTF_TYPEHINT, SESSION_SETTINGS_MODE };
+export { TASK_TYPE, MainEventTypes, EVENTTYPE, EVENTTYPE_CAMERA, EVENTTYPE_OUTPUT, EVENTTYPE_PARAMETER, EVENTTYPE_RENDERING, EVENTTYPE_SCENE, EVENTTYPE_SESSION, EVENTTYPE_VIEWPORT, EVENTTYPE_INTERACTION, EVENTTYPE_DRAWING_TOOLS, EVENTTYPE_TASK };
+export { IBox, Box, ISphere, Sphere, IGeometry, ITransformation, ShapeDiverResponseOutput, ShapeDiverResponseOutputContentBackend, ShapeDiverResponseOutputChunkBackend, ShapeDiverResponseOutputContent, ShapeDiverResponseOutputChunk, IDomEventListener, IEvent };
+export { ShapeDiverResponseExport, ShapeDiverResponseExportContent, ShapeDiverResponseExportResult, ShapeDiverResponseModelComputationStatus, ShapeDiverResponseExportDefinitionGroup, ShapeDiverResponseParameter };
+
+export { EventResponseMapping, IViewportEvent, ISessionEvent, IOutputEvent, ICameraEvent, ISceneEvent, ITaskEvent, IRenderingEvent, IParameterEvent, ISettingsSections, IViewportSettingsSections, ISessionSettingsSections };
+export { IMaterialAbstractData, IMaterialAbstractDataProperties, IMaterialStandardData, MaterialStandardData, IMaterialStandardDataProperties, IMaterialUnlitData, MaterialUnlitData, IMaterialUnlitDataProperties, IMaterialPointData, MaterialPointData, IMaterialPointDataProperties, IMaterialMultiPointData, MaterialMultiPointData, IMaterialMultiPointDataProperties, IMaterialBasicLineData, MaterialBasicLineData, IMaterialBasicLineDataProperties, IMaterialSpecularGlossinessData, MaterialSpecularGlossinessData, IMaterialSpecularGlossinessDataProperties, IMaterialGemData, MaterialGemData, IMaterialGemDataProperties, IMapData, MapData, ITexture, IMaterialContentDataV1, IMaterialContentDataV2, IMaterialContentDataV3 };
+export { IAnimationData, AnimationData, IAnimationTrack, IGeometryData, IAttributeData, IPrimitiveData, IMaterialVariantsData, GeometryData, AttributeData, PrimitiveData, MaterialVariantsData };
+export { IAnchorDataImage, IAnchorDataText, ITag2D, ITag3D, IHTMLElementAnchorData, HTMLElementAnchorCustomData, HTMLElementAnchorTextData, HTMLElementAnchorImageData, HTMLElementAnchorData };
+export { ICustomData, CustomData };
+export { ISDTFOverviewData, SDTFOverviewData, ISDTFOverview, SDTFAttributesData, ISDTFAttributesData, ISDTFAttributeData, SDTFAttributeData, SDTFItemData, ISDTFItemData, ISDTFAttributeVisualizationData, SdtfPrimitiveTypeGuard };
+export { ISessionData, SessionData, ISessionOutputData, SessionOutputData };
+export { ShapeDiverViewerErrorType, ShapeDiverViewerError, ShapeDiverViewerDataProcessingError, ShapeDiverViewerEnvironmentMapError, ShapeDiverViewerWebGLError, ShapeDiverViewerSettingsError, ShapeDiverViewerSessionError, ShapeDiverViewerViewportError, ShapeDiverViewerUnknownError, ShapeDiverViewerArError, ShapeDiverViewerLightError, ShapeDiverViewerCameraError, ShapeDiverViewerValidationError, ShapeDiverViewerInteractionError, ShapeDiverViewerDrawingToolsError, ShapeDiverGeometryBackendError, ShapeDiverGeometryBackendRequestError, ShapeDiverGeometryBackendResponseError, ShapeDiverGeometryBackendResponseErrorType };
+export { isViewerError, isViewerUnknownError, isViewerDataProcessingError, isViewerEnvironmentMapError, isViewerWebGLError, isViewerSettingsError, isViewerSessionError, isViewerViewportError, isViewerLightError, isViewerCameraError, isARError, isViewerValidationError, isViewerInteractionError, isViewerDrawingToolsError, isViewerGeometryBackendError, isViewerGeometryBackendGenericError, isViewerGeometryBackendRequestError, isViewerGeometryBackendResponseError };

package/src/interfaces/IExportApi.ts

@@ -0,0 +1,29 @@
+import { ShapeDiverResponseExport } from '@shapediver/sdk.geometry-api-sdk-v2';
+
+/**
+ * The api for an export of a corresponding [session]{@link ISessionApi}.
+ * 
+ * Exports are used for outputting data which should not be visualized in the scene, 
+ * or which should not be accessible via the viewport. 
+ * 
+ * Exports are NOT computed as part of customizations (see {@link customize}). 
+ * The export can be requested by calling its {@link request} method.
+ * 
+ * Only the properties of {@link ShapeDiverResponseExportDefinition} will stay constant over the lifetime of a session.
+ * All additional properties that are added via the extension to {@link ShapeDiverResponseExport} can change according to
+ * the last export request.
+ */
+export interface IExportApi extends ShapeDiverResponseExport {
+    // #region Public Methods (1)
+
+    /**
+     * Request the export.
+     * 
+     * @param parameters Parameter values to be used for this export request. Map from parameter id to parameter value. The current value will be used for any parameter not specified.
+     * 
+     * @throws {@type ShapeDiverViewerError}
+     */
+    request(parameters?: { [key: string]: unknown }): Promise<ShapeDiverResponseExport>;
+
+    // #endregion Public Methods (1)
+}

package/src/interfaces/IFileParameterApi.ts

@@ -0,0 +1,39 @@
+import { IParameterApi } from './IParameterApi';
+
+/**
+ * The api for a file parameter of a corresponding [session]{@link ISessionApi}.
+ * 
+ * File parameters accept {@link https://developer.mozilla.org/en-US/docs/Web/API/File|File} or
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob} objects. The data 
+ * gets uploaded to the Geometry Backend prior to sending a _customization_ request. 
+ * This prior upload assigns a unique id to the data, which can be read from {@link IFileParameter.value}
+ * once the upload completed. The unique id can be used to run further customizations 
+ * using the same data, avoiding a further upload.
+ * 
+ * {@link upload} is used to trigger the prior upload, in case one is necessary. This
+ * is taken care of automatically by {@link ISessionApi.customize} and
+ * {@link ISessionApi.customizeParallel}, but can also be triggered separately
+ * beforehand.
+ */
+export interface IFileParameterApi extends IParameterApi<File | Blob | string> {
+    // #region Public Methods (2)
+
+    /**
+     * Get the filename of the file with the given id. If no id is given, the filename of the current value is returned (if available).
+     * 
+     * @param fileId - The id of the file to get the filename for.
+     * @returns The filename of the file with the given id, or the filename of the current value if no id is given. If the filename is not available, `undefined` is returned.
+     * @throws {@type ShapeDiverViewerError}
+     */
+    getFilename(fileId?: string): Promise<string | undefined>;
+    /**
+     * Upload the data (File, Blob) that is currently set to the {@link value} property.
+     * You can then use the returned id to either set it as the value of the parameter or use it in a subsequent customization.
+     * This call returns immediately in case no data is waiting to be uploaded.
+     * 
+     * @throws {@type ShapeDiverViewerError}
+     */
+    upload(): Promise<string>;
+
+    // #endregion Public Methods (2)
+}

package/src/interfaces/IOutputApi.ts

@@ -0,0 +1,85 @@
+import { ITreeNode } from '@shapediver/viewer.shared.node-tree';
+import { ShapeDiverResponseOutput } from '@shapediver/sdk.geometry-api-sdk-v2';
+import { ShapeDiverResponseOutputContent } from '@shapediver/viewer.session-engine.session-engine';
+
+/**
+ * The api for an output of a corresponding [session]{@link ISessionApi}.
+ * 
+ * Outputs represent the channels through which data is output from the model
+ * represented by a session. They are computed as part of customizations (see {@link customize}). 
+ * 
+ * Outputs contain static properties which do not
+ * depend on parameter values, these are: 
+ * 
+ *   * id
+ *   * uid
+ *   * name
+ *   * material
+ *   * chunks
+ *   * dependency
+ *   * order
+ *   * tooltip
+ *   * displayname
+ *   * hidden
+ * 
+ * The remaining properties are dynamic and may change depending on parameter values.
+ * Specifically the _content_ property refers to output assets and embedded data.
+ * 
+ * Each output has a corresponding {@link node} in the [scene tree]{@link ITree}
+ * which represents the data that got output from the model for the parameter values
+ * stored in {@link IParameterApi.sessionValue}.
+ * 
+ * An output's content can be updated manually by calling the {@link updateOutputContent} method.
+ * Using the {@link freeze} property the output's content can be frozen, which means subsequent
+ * {@link customize} calls will not update the output.
+ */
+export interface IOutputApi extends ShapeDiverResponseOutput {
+    // #region Properties (4)
+
+    /**
+     * The format of the items in the content array.
+     */
+    readonly format: string[];
+    /**
+     * The {@link node} corresponding to the output in the [scene tree]{@link ITree}.
+     */
+    readonly node?: ITreeNode;
+
+    /**
+     * The freeze flag. 
+     * When set to true, calls to the following functions will not update the output: 
+     * 
+     *   * {@link updateOutputContent}
+     *   * {@link ISessionApi.customize}
+     *   * {@link ISessionApi.updateOutputs}
+     */
+    freeze: boolean;
+    /**
+     * A callback that is executed whenever an output's {@link node} is to be replaced
+     * due to an update of the output'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.
+     */
+    updateCallback: ((newNode?: ITreeNode, oldNode?: ITreeNode) => void | Promise<void>) | null;
+
+    // #endregion Properties (4)
+
+    // #region Public Methods (1)
+
+    /**
+     * Update the output's content, effectively overriding the content which was output from the model.
+     * 
+     * This can be used to override the content which was output from the model (e.g. materials). 
+     * In case you want the override content to persist further calls to {@link ISessionApi.customize}, 
+     * await the call to this function and then set {@link freeze} to true.
+     * 
+     * @param content The new output content.
+     * @param preventUpdate Option to not update the output immediately (default: false). Use this to update
+     *                      the content of several outputs at the same time, then call {@link ISessionApi.updateOutputs}.
+     * 
+     * @throws {@type ShapeDiverViewerError}
+     */
+    updateOutputContent(content: ShapeDiverResponseOutputContent[], preventUpdate?: boolean): Promise<ITreeNode | undefined>;
+
+    // #endregion Public Methods (1)
+}

package/src/interfaces/IParameterApi.ts

@@ -0,0 +1,55 @@
+import { ShapeDiverResponseParameter } from '@shapediver/sdk.geometry-api-sdk-v2';
+
+/**
+ * The api for a parameter of a corresponding [session]{@link ISessionApi}.
+ * 
+ * Parameters represent the channels through which data can be input into the model
+ * represented by a session. 
+ * 
+ * The current value can be changed by setting the {@link value} property.
+ */
+export interface IParameterApi<T> extends ShapeDiverResponseParameter {
+    // #region Properties (2)
+
+    /**
+     * The value that corresponds to the latest successful call to {@link ISessionApi.customize}.
+     * This property will be updated immediately before {@link ISessionApi.customize} returns.
+     */
+    sessionValue: T | string;
+    /**
+     * The current value.
+     * 
+     * Validation happens immediately when setting this property. An error will be thrown in case
+     * validation fails. Use {@link isValid} to test whether a value passes validation.
+     * 
+     * In case {@link ISessionApi.automaticSceneUpdate} is true, setting the value will immediately 
+     * trigger a customization (see {@link ISessionApi.customize}).
+     */
+    value: T | string;
+
+    // #endregion Properties (2)
+
+    // #region Public Methods (4)
+
+    /**
+     * Evaluates if a given value is valid for this parameter.
+     * 
+     * @param value the value to evaluate
+     * @param throwError if true, an error is thrown if validation does not pass (default: false)
+     */
+    isValid(value: unknown, throwError?: boolean): boolean;
+    /**
+     * Resets the value to the default value.
+     */
+    resetToDefaultValue(): void;
+    /**
+     * Resets the value to {@link sessionValue}.
+     */
+    resetToSessionValue(): void;
+    /**
+     * Returns the current value as a string
+     */
+    stringify(): string;
+
+    // #endregion Public Methods (4)
+}