@shapediver/viewer.viewport 3.0.0

package/src/interfaces/camera/ICameraApi.ts

@@ -0,0 +1,233 @@
+import { CAMERA_TYPE, ICameraOptions } from '@shapediver/viewer.rendering-engine.camera-engine';
+import { IBox } from '@shapediver/viewer.shared.math';
+import { vec2, vec3 } from 'gl-matrix';
+
+/**
+ * The api for a camera, please see the definitions for the [perspective camera api]{@link IPerspectiveCameraApi} and the [orthographic camera api]{@link IOrthographicCameraApi} as this is just a shared interface for both.
+ * A camera can be created by calling the corresponding method in the {@link IViewportApi}.
+ * A camera has a multitude of properties and methods that can be used to adjust the behavior.
+ */
+export interface ICameraApi {
+    // #region Properties (38)
+
+    /**
+     * The id of the camera.
+     */
+    readonly id: string;
+    /**
+     * The type of camera that is being used.
+     */
+    readonly type: CAMERA_TYPE;
+
+    /**
+     * Option to automatically adjust the camera to the size of the scene whenever a call to 
+     * {@link ISessionApi.customize} replaced {@link ISessionApi.node}.
+     * This does not happen in case {@link ISessionApi.automaticSceneUpdate} is set to false.
+     */
+    autoAdjust: boolean;
+    /**
+     * The speed of the camera for auto rotating.
+     */
+    autoRotationSpeed: number;
+    /**
+     * The standard duration for camera movements.
+     */
+    cameraMovementDuration: number;
+    /**
+     * The restrictions for the position of the camera with a cube.
+     */
+    cubePositionRestriction: { min: vec3, max: vec3 };
+    /**
+     * The restrictions for the target of the camera with a cube.
+     */
+    cubeTargetRestriction: { min: vec3, max: vec3 };
+    /**
+     * The damping factor for the camera.
+     * The dampening affects how much the camera moves even after you let it got.
+     * This smooths the usage of the camera.
+     */
+    damping: number;
+    /**
+     * The default position of the camera.
+     */
+    defaultPosition: vec3;
+    /**
+     * The default target of the camera.
+     */
+    defaultTarget: vec3;
+    /**
+     * Option to enable auto rotating.
+     */
+    enableAutoRotation: boolean;
+    /**
+     * Option to enable the rotation of the camera on the azimuth axis (left/right). (default: true)
+     */
+    enableAzimuthRotation: boolean;
+    /**
+     * Option to enable panning with key presses.
+     */
+    enableKeyPan: boolean;
+    /**
+     * Option to enable the object controls. (default: false)
+     */
+    enableObjectControls: boolean;
+    /**
+     * Option to enable panning. Panning can be done by pressing the right mouse button or three-finger touch events.
+     */
+    enablePan: boolean;
+    /**
+     * Option to enable the rotation of the camera on the polar axis (up/down). (default: true)
+     */
+    enablePolarRotation: boolean;
+    /**
+     * Option to enable rotating.
+     */
+    enableRotation: boolean;
+    /**
+     * Option to enable the turntable controls. (default: false)
+     */
+    enableTurntableControls: boolean;
+    /**
+     * Option to enable zooming. Zooming can be done with the mouse wheel or two-finger touch events.
+     */
+    enableZoom: boolean;
+    /**
+     * Option to enable / disable the movement of the camera.
+     */
+    enabled: boolean;
+    /**
+     * The speed of the camera for key panning. The higher this value, the faster you can pan.
+     */
+    keyPanSpeed: number;
+    /**
+     * The factor for applying smoothing to the camera movement.
+     * The various events that come in are blended together to ensure that extremes are not as pronounced.
+     */
+    movementSmoothness: number;
+    /**
+     * The name of the camera.
+     * Used by the platform.
+     */
+    name?: string;
+    /**
+     * The center of the object when {@link enableObjectControls} is activated. (default: [0,0,0])
+     */
+    objectControlsCenter: vec3;
+    /**
+     * Optional order property for the camera.
+     * Used by the platform.
+     */
+    order?: number;
+    /**
+     * The speed of the camera for panning. The higher this value, the faster you can pan.
+     */
+    panSpeed: number;
+    /**
+     * The current position of the camera.
+     */
+    position: vec3;
+    /**
+     * Option to animate the camera position and target to their defaults whenever the mouse/touch up event is fired.
+     */
+    revertAtMouseUp: boolean;
+    /**
+     * The standard duration for revertAtMouseUp animations.
+     */
+    revertAtMouseUpDuration: number;
+    /**
+     * The restrictions for the rotation of the camera.
+     */
+    rotationRestriction: { minPolarAngle: number, maxPolarAngle: number, minAzimuthAngle: number, maxAzimuthAngle: number };
+    /**
+     * The speed of the camera for rotating.
+     */
+    rotationSpeed: number;
+    /**
+     * The restrictions for the position of the camera with a sphere.
+     */
+    spherePositionRestriction: { center: vec3, radius: number };
+    /**
+     * The restrictions for the target of the camera with a sphere.
+     */
+    sphereTargetRestriction: { center: vec3, radius: number };
+    /**
+     * The current target of the camera.
+     */
+    target: vec3;
+    /**
+     * The center of the turntable when {@link enableTurntableControls} is activated. (default: [0,0,0])
+     */
+    turntableCenter: vec3;
+    /**
+     * The restrictions for the zooming of the camera.
+     */
+    zoomRestriction: { minDistance: number, maxDistance: number };
+    /**
+     * The speed of the camera for zooming. The higher this value, the faster you can zoom.
+     */
+    zoomSpeed: number;
+    /**
+     * The factor that is used when the {@link zoomTo} function is called.
+     * 
+     * See also {@link calculateZoomTo}
+     */
+    zoomToFactor: number;
+
+    // #endregion Properties (38)
+
+    // #region Public Methods (7)
+
+    /**
+     * Let the camera follow a path along pairs of position and target.
+     * 
+     * @param path The defined path.
+     * @param options Various options to be adjusted.
+     */
+    animate(path: { position: vec3, target: vec3 }[], options?: ICameraOptions): Promise<boolean>;
+    /**
+     * Calculate the position and target which a call to {@link zoomTo} would result in.
+     * 
+     * If no target to zoom to is provided, the current bounding box is used.
+     * If no startingPosition and startingTarget are provided, the current camera position and target are used.
+     * 
+     * @see {@link zoomToFactor}
+     * 
+     * @param zoomTarget The target to zoom to.
+     * @param startingPosition The starting position of the camera.
+     * @param startingTarget The starting target of the camera.
+     */
+    calculateZoomTo(zoomTarget?: IBox, startingPosition?: vec3, startingTarget?: vec3): { position: vec3; target: vec3; };
+    /**
+     * Projects the vector from world space into the camera's normalized device coordinate (NDC) space.
+     * 
+     * @param p The point in the scene to project.
+     */
+    project(p: vec3): vec2;
+    /**
+     * Reset / animate the camera to its default position and target.
+     * 
+     * @param options Various options to be adjusted.
+     */
+    reset(options?: ICameraOptions): Promise<boolean>;
+    /**
+     * Set / animate the camera to a specific position and target.
+     * 
+     * @param options Various options to be adjusted.
+     */
+    set(position: vec3, target: vec3, options?: ICameraOptions): Promise<boolean>;
+    /**
+     * Projects the vector from the camera's normalized device coordinate (NDC) space into world space.
+     * 
+     * @param p The point on the screen to project.
+     */
+    unproject(p: vec3): vec3;
+    /**
+     * Zoom to a specific part of the scene, or the whole scene (default).
+     * 
+     * @param zoomTarget The target to zoom to.
+     * @param options Various options to be adjusted.
+     */
+    zoomTo(zoomTarget?: IBox, options?: ICameraOptions): Promise<boolean>;
+
+    // #endregion Public Methods (7)
+}

package/src/interfaces/camera/IOrthographicCameraApi.ts

@@ -0,0 +1,18 @@
+import { ICameraApi } from './ICameraApi';
+import { ORTHOGRAPHIC_CAMERA_DIRECTION } from '@shapediver/viewer.rendering-engine.camera-engine';
+
+/**
+ * The api for an orthographic camera.
+ * An orthographic camera can be created by calling the {@link createOrthographicCamera} method.
+ * A camera has a multitude of properties and methods that can be used to adjust the behavior.
+ */
+export interface IOrthographicCameraApi extends ICameraApi {
+    // #region Properties (1)
+
+    /**
+     * The direction of the camera. (default: ORTHOGRAPHIC_CAMERA_DIRECTION.CUSTOM)
+     */
+    direction: ORTHOGRAPHIC_CAMERA_DIRECTION;
+
+    // #endregion Properties (1)
+}

package/src/interfaces/camera/IPerspectiveCameraApi.ts

@@ -0,0 +1,17 @@
+import { ICameraApi } from './ICameraApi';
+
+/**
+ * The api for a perspective camera.
+ * A perspective camera can be created by calling the {@link createPerspectiveCamera} method.
+ * A camera has a multitude of properties and methods that can be used to adjust the behavior.
+ */
+export interface IPerspectiveCameraApi extends ICameraApi {
+    // #region Properties (1)
+
+    /**
+     * The field of view for the camera.
+     */
+    fov: number;
+
+    // #endregion Properties (1)
+}

package/src/interfaces/lights/ILightApi.ts

@@ -0,0 +1,41 @@
+import { Color } from '@shapediver/viewer.shared.types';
+import { LIGHT_TYPE } from '@shapediver/viewer.rendering-engine.light-engine';
+
+/**
+ * The api for a light, please see the definitions for [ambient]{@link IAmbientLightApi}, [directional]{@link IDirectionalLightApi}, [hemisphere]{@link IHemisphereLightApi}, [point]{@link IPointLightApi} and [spot]{@link ISpotLightApi} as this is just a shared interface for all of them.
+ * A light can be created by calling the corresponding method in the [light scene]{@link ILightSceneApi}.
+ * A light has a multitude of properties and methods that can be used to adjust the behavior.
+ */
+export interface ILightApi {
+  // #region Properties (6)
+
+  /**
+   * The id of the light.
+   */
+  readonly id: string;
+  /**
+   * The type of the light.
+   */
+  readonly type: LIGHT_TYPE;
+
+  /**
+   * The color of the light.
+   */
+  color: Color;
+  /**
+   * The intensity of the light.
+   */
+  intensity: number;
+  /**
+   * The name of the light.
+   * Used by the platform.
+   */
+  name?: string;
+  /**
+   * The order of the light.
+   * Used by the platform.
+   */
+  order?: number;
+
+  // #endregion Properties (6)
+}

package/src/interfaces/lights/ILightSceneApi.ts

@@ -0,0 +1,147 @@
+import { Color } from '@shapediver/viewer.shared.types';
+import { IAmbientLightApi } from './types/IAmbientLightApi';
+import { IDirectionalLightApi } from './types/IDirectionalLightApi';
+import { IHemisphereLightApi } from './types/IHemisphereLightApi';
+import { ILightApi } from './ILightApi';
+import { IPointLightApi } from './types/IPointLightApi';
+import { ISpotLightApi } from './types/ISpotLightApi';
+import { ITreeNode } from '@shapediver/viewer.shared.node-tree';
+import { vec3 } from 'gl-matrix';
+
+/**
+ * The api for a light scene.
+ * A light scene is a collection of lights. Therefore multiple light scene can be used to switch between different lighting environments.
+ * It can be created by calling the {@link createLightScene} method.
+ */
+export interface ILightSceneApi {
+    // #region Properties (4)
+
+    /**
+     * The id of the light scene.
+     */
+    readonly id: string;
+    /**
+     * The node in which the lights are stored in the [scene tree]{@link ITree}.
+     */
+    readonly node: ITreeNode;
+
+    /**
+     * The collection of lights in the light scene.
+     */
+    lights: { [key: string]: ILightApi; };
+    /**
+     * The name of the light scene.
+     */
+    name?: string
+
+    // #endregion Properties (4)
+
+    // #region Public Methods (6)
+
+    /**
+     * Create an ambient light and add it to the light scene.
+     * 
+     * @param properties.color The color of the light.
+     * @param properties.intensity The intensity of the light. (0-Infinity, default: 0.5)
+     * @param properties.id The id of the light.
+     * @param properties.name The name of the light.
+     */
+    addAmbientLight(properties: {
+        color?: Color,
+        intensity?: number,
+        id?: string,
+        name?: string
+    }): IAmbientLightApi;
+    /**
+     * Create a directional light and add it to the light scene.
+     * 
+     * @param properties.color The color of the light.
+     * @param properties.intensity The intensity of the light. (0-Infinity, default: 0.5)
+     * @param properties.id The id of the light.
+     * @param properties.name The name of the light.
+     * @param properties.direction The direction of the light.
+     * @param properties.castShadow Option for the light to cast shadows.
+     * @param properties.shadowMapResolution The resolution of the shadow map. (default: 1024, has to be power of two)
+     * @param properties.shadowMapBias The bias of the shadow map. For more info on the shadow bias, see [here](https://digitalrune.github.io/DigitalRune-Documentation/html/3f4d959e-9c98-4a97-8d85-7a73c26145d7.htm).
+     */
+    addDirectionalLight(properties: {
+        color?: Color,
+        intensity?: number,
+        direction?: vec3,
+        castShadow?: boolean,
+        shadowMapResolution?: number,
+        shadowMapBias?: number,
+        id?: string,
+        name?: string
+    }): IDirectionalLightApi;
+    /**
+     * Create an hemisphere light and add it to the light scene.
+     * 
+     * @param properties.color The color of the light.
+     * @param properties.intensity The intensity of the light. (0-Infinity, default: 0.5)
+     * @param properties.id The id of the light.
+     * @param properties.name The name of the light.
+     * @param properties.groundColor The ground color of the light.
+     */
+    addHemisphereLight(properties: {
+        color?: Color,
+        intensity?: number,
+        groundColor?: Color,
+        id?: string,
+        name?: string
+    }): IHemisphereLightApi;
+    /**
+     * Create a point light and add it to the light scene.
+     * 
+     * @param properties.color The color of the light.
+     * @param properties.intensity The intensity of the light. (0-Infinity, default: 0.5)
+     * @param properties.id The id of the light.
+     * @param properties.name The name of the light.
+     * @param properties.position The position of the light.
+     * @param properties.distance The distance of the light.
+     * @param properties.decay The decay of the light.
+     */
+    addPointLight(properties: {
+        color?: Color,
+        intensity?: number,
+        position?: vec3,
+        distance?: number,
+        decay?: number,
+        id?: string,
+        name?: string
+    }): IPointLightApi;
+    /**
+     * Create a point light and add it to the light scene.
+     * 
+     * @param properties.color The color of the light.
+     * @param properties.intensity The intensity of the light. (0-Infinity, default: 0.5)
+     * @param properties.id The id of the light.
+     * @param properties.name The name of the light.
+     * @param properties.position The position of the light.
+     * @param properties.target The target of the light.
+     * @param properties.distance The distance of the light.
+     * @param properties.decay The decay of the light.
+     * @param properties.angle The angle of the light.
+     * @param properties.penumbra The penumbra of the light.
+     */
+    addSpotLight(properties: {
+        color?: Color,
+        intensity?: number,
+        position?: vec3,
+        target?: vec3,
+        distance?: number,
+        decay?: number,
+        angle?: number,
+        penumbra?: number,
+        id?: string,
+        name?: string
+    }): ISpotLightApi;
+    /**
+     * Remove a light from the light scene with the specified id.
+     * 
+     * @param id The id of the light to remove.
+     */
+    removeLight(id: string): boolean;
+
+    // #endregion Public Methods (6)
+}

package/src/interfaces/lights/types/IAmbientLightApi.ts

@@ -0,0 +1,7 @@
+import { ILightApi } from '../ILightApi';
+
+/**
+ * The api for an ambient light.
+ * An ambient light can be created by calling the {@link addAmbientLight} method.
+ */
+export type IAmbientLightApi = ILightApi

package/src/interfaces/lights/types/IDirectionalLightApi.ts

@@ -0,0 +1,29 @@
+import { ILightApi } from '../ILightApi';
+import { vec3 } from 'gl-matrix';
+
+/**
+ * The api for a directional light.
+ * A directional light can be created by calling the {@link addDirectionalLight} method.
+ */
+export interface IDirectionalLightApi extends ILightApi {
+    // #region Properties (4)
+
+    /**
+     * Option to cast shadows.
+     */
+    castShadow: boolean;
+    /**
+     * The direction of the light.
+     */
+    direction: vec3;
+    /**
+     * The bias of the shadow map.
+     */
+    shadowMapBias: number;
+    /** 
+     * The resolution of the shadow map.
+     */
+    shadowMapResolution: number;
+
+    // #endregion Properties (4)
+}

package/src/interfaces/lights/types/IHemisphereLightApi.ts

@@ -0,0 +1,17 @@
+import { Color } from '@shapediver/viewer.shared.types';
+import { ILightApi } from '../ILightApi';
+
+/**
+ * The api for an hemisphere light.
+ * An hemisphere light can be created by calling the {@link addHemisphereLight} method.
+ */
+export interface IHemisphereLightApi extends ILightApi {
+    // #region Properties (1)
+
+    /**
+     * The ground color of the light.
+     */
+    groundColor: Color;
+
+    // #endregion Properties (1)
+}

package/src/interfaces/lights/types/IPointLightApi.ts

@@ -0,0 +1,25 @@
+import { ILightApi } from '../ILightApi';
+import { vec3 } from 'gl-matrix';
+
+/**
+ * The api for a point light.
+ * A point light can be created by calling the {@link addPointLight} method.
+ */
+export interface IPointLightApi extends ILightApi {
+    // #region Properties (3)
+
+    /**
+     * The decay of the light.
+     */
+    decay: number;
+    /**
+     * The distance of the light.
+     */
+    distance: number;
+    /**
+     * The position of the light.
+     */
+    position: vec3;
+
+    // #endregion Properties (3)
+}

package/src/interfaces/lights/types/ISpotLightApi.ts

@@ -0,0 +1,37 @@
+import { ILightApi } from '../ILightApi';
+import { vec3 } from 'gl-matrix';
+
+/**
+ * The api for a spot light.
+ * A spot light can be created by calling the {@link addSpotLight} method.
+ */
+export interface ISpotLightApi extends ILightApi {
+    // #region Properties (6)
+
+    /**
+     * The angle of the light.
+     */
+    angle: number;
+    /**
+     * The decay of the light.
+     */
+    decay: number;
+    /**
+     * The distance of the light.
+     */
+    distance: number;
+    /**
+     * The penumbra of the light.
+     */
+    penumbra: number;
+    /**
+     * The position of the light.
+     */
+    position: vec3;
+    /**
+     * The target of the light.
+     */
+    target: vec3;
+
+    // #endregion Properties (6)
+}

package/src/main.ts

@@ -0,0 +1,85 @@
+import {
+    BUSY_MODE_DISPLAY,
+    SPINNER_POSITIONING,
+    VISIBILITY_MODE
+} from '@shapediver/viewer.rendering-engine.rendering-engine';
+import { CreationControlCenterViewport, ICreationControlCenterViewport, ViewportCreationDefinition } from '@shapediver/viewer.creation-control-center.viewport';
+import { InputValidator, Logger, SESSION_SETTINGS_MODE, ShapeDiverViewerValidationError } from '@shapediver/viewer.shared.services';
+import { IViewportApi } from './interfaces/IViewportApi';
+import { RenderingEngine as RenderingEngineThreeJs } from '@shapediver/viewer.rendering-engine.rendering-engine-threejs';
+import { showConsoleMessage } from '@shapediver/viewer.api.general';
+import { ViewportApi } from './implementation/ViewportApi';
+
+const creationControlCenterViewport: ICreationControlCenterViewport = CreationControlCenterViewport.instance;
+const inputValidator: InputValidator = InputValidator.instance;
+const logger: Logger = Logger.instance;
+
+/**
+ * The viewports that are currently being used.
+ */
+export const viewports: { [key: string]: IViewportApi; } = {};
+
+// Whenever a session or viewport is added or removed, this update is called.
+creationControlCenterViewport.updateViewports = (
+    renderingEngines: { [key: string]: RenderingEngineThreeJs; }
+) => {
+    for (const v in renderingEngines)
+        if (!viewports[v])
+            viewports[v] = new ViewportApi(renderingEngines[v]);
+
+    for (const v in viewports) {
+        if (!renderingEngines[v])
+            delete viewports[v];
+    }
+};
+
+/**
+ * Create and initialize a viewport with the provided type and canvas, 
+ * and return a viewport api object allowing to control it.
+ * 
+ * An optional identifier for the viewport can be provided. This identifier can be used to retrieve the  
+ * viewport object from {@link viewports}. In case no identifier is provided, a unique one will be generated.
+ * 
+ * By default a new viewport displays the complete scene tree. Viewports can be excluded from 
+ * displaying geometry for specific sessions by using the {@link excludeViewports} property of
+ * {@link ISessionApi}.
+ * 
+ * @param properties.visibility The visibility of the viewport.
+ * @param properties.canvas The canvas that the viewport should use. A canvas element will be created if none is provided. 
+ * @param properties.id The unique identifier to use for the viewport.
+ * @param properties.branding Optional branding options.
+ * @param properties.sessionSettingsId Optional identifier of the session to be used for loading / persisting settings of the viewport when the {@link SESSION_SETTINGS_MODE} is set to MANUAL. 
+ * @param properties.sessionSettingsMode Allows to control which session to use for loading / persisting settings of the viewport. (default: {@link SESSION_SETTINGS_MODE.FIRST}).
+ * @returns 
+ */
+export const createViewport = async (properties?: ViewportCreationDefinition): Promise<IViewportApi> => {
+    showConsoleMessage();
+
+    logger.debug(`createSession: Creating and initializing session with properties ${JSON.stringify(properties)}.`);
+    inputValidator.validateAndError('createViewport', properties, 'object', false);
+
+    const prop = Object.assign({}, properties);
+    inputValidator.validateAndError('createViewport', prop.canvas, 'HTMLCanvasElement', false);
+    inputValidator.validateAndError('createViewport', prop.id, 'string', false);
+    inputValidator.validateAndError('createViewport', prop.sessionSettingsId, 'string', false);
+    inputValidator.validateAndError('createViewport', prop.sessionSettingsMode, 'enum', false, Object.values(SESSION_SETTINGS_MODE));
+    inputValidator.validateAndError('createViewport', prop.visibility, 'enum', false, Object.values(VISIBILITY_MODE));
+
+    inputValidator.validateAndError('createViewport', prop.branding, 'object', false);
+    const branding = Object.assign({}, prop.branding);
+    if (branding.logo !== null) inputValidator.validateAndError('createViewport', branding.logo, 'string', false);
+    inputValidator.validateAndError('createViewport', branding.backgroundColor, 'string', false);
+    inputValidator.validateAndError('createViewport', branding.busyModeSpinner, 'string', false);
+    inputValidator.validateAndError('createViewport', branding.busyModeDisplay, 'enum', false, Object.values(BUSY_MODE_DISPLAY));
+    inputValidator.validateAndError('createViewport', branding.spinnerPositioning, 'enum', false, Object.values(SPINNER_POSITIONING));
+
+    prop.sessionSettingsMode = prop.sessionSettingsMode !== undefined ? prop.sessionSettingsMode : SESSION_SETTINGS_MODE.FIRST;
+
+    if (prop.sessionSettingsMode === SESSION_SETTINGS_MODE.MANUAL && !prop.sessionSettingsId)
+        throw new ShapeDiverViewerValidationError('createViewport: Input could not be validated. sessionSettingsId has to point to a valid and created session when using SESSION_SETTINGS_MODE.MANUAL', prop.sessionSettingsId, 'string');
+
+    const renderingEngine = await creationControlCenterViewport.createViewportEngine(prop);
+
+    viewports[renderingEngine.id] = new ViewportApi(renderingEngine);
+    return viewports[renderingEngine.id];
+};

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "extends": "../../tsconfig.json",
+    "include": [
+        "./**/*.ts"
+    ],
+    "compilerOptions": {
+        "rootDir": "src",
+        "outDir": "dist"
+    },
+    "exclude": [
+        "__tests__",
+        "node_modules",
+        "dist",
+        "dist-dev",
+        "dist-prod"
+    ]
+}