@cognite/reveal 3.0.0-alpha.2 → 3.0.0

package/packages/cad-styling/src/prioritized/types.d.ts

@@ -1,7 +1,7 @@
-/*!
- * Copyright 2021 Cognite AS
- */
-export declare type PrioritizedArea = {
-    area: THREE.Box3;
-    extraPriority: number;
-};
+/*!
+ * Copyright 2021 Cognite AS
+ */
+export declare type PrioritizedArea = {
+    area: THREE.Box3;
+    extraPriority: number;
+};

package/packages/camera-manager/index.d.ts

@@ -1,6 +1,8 @@
-/*!
- * Copyright 2021 Cognite AS
- */
-export { ComboControls } from './src/ComboControls';
-export { CameraManager } from './src/CameraManager';
-export * from './src/types';
+/*!
+ * Copyright 2021 Cognite AS
+ */
+export { DefaultCameraManager } from './src/DefaultCameraManager';
+export { CameraManagerHelper } from './src/CameraManagerHelper';
+export { CameraManager } from './src/CameraManager';
+export { ComboControls } from './src/ComboControls';
+export * from './src/types';

package/packages/camera-manager/src/CameraManager.d.ts

@@ -1,84 +1,73 @@
-/*!
- * Copyright 2021 Cognite AS
- */
-import * as THREE from 'three';
-import { ComboControls } from './ComboControls';
-import { CameraManagerCallbackData, CameraControlsOptions, CameraChangeData, ControlsState } from './types';
-export declare class CameraManager {
-    private readonly _events;
-    private readonly _controls;
-    private readonly _camera;
-    private readonly _domElement;
-    private readonly _inputHandler;
-    private readonly _raycaster;
-    private isDisposed;
-    private readonly _modelRaycastCallback;
-    private _onClick;
-    private _onWheel;
-    private static readonly DefaultAnimationDuration;
-    private static readonly DefaultMinAnimationDuration;
-    private static readonly DefaultMaxAnimationDuration;
-    private static readonly DefaultMinDistance;
-    private static readonly DefaultMinZoomDistance;
-    private static readonly DefaultMinimalTimeBetweenRaycasts;
-    private static readonly DefaultCameraControlsOptions;
-    private _cameraControlsOptions;
-    automaticNearFarPlane: boolean;
-    automaticControlsSensitivity: boolean;
-    /**
-     * Reusable buffers used by functions in Cognite3dViewer to avoid allocations.
-     */
-    private readonly _updateNearAndFarPlaneBuffers;
-    private readonly _calculateCameraFarBuffers;
-    constructor(camera: THREE.PerspectiveCamera, domElement: HTMLElement, raycastFunction: (x: number, y: number) => Promise<CameraManagerCallbackData>);
-    on(event: 'cameraChange', callback: CameraChangeData): void;
-    off(event: 'cameraChange', callback: CameraChangeData): void;
-    fitCameraToBoundingBox(box: THREE.Box3, duration?: number, radiusFactor?: number): void;
-    set cameraControlsEnabled(enabled: boolean);
-    get cameraControlsEnabled(): boolean;
-    set keyboardNavigationEnabled(enabled: boolean);
-    get keyboardNavigationEnabled(): boolean;
-    get cameraControls(): ComboControls;
-    setCameraTarget(target: THREE.Vector3, animated?: boolean): void;
-    setCameraControlsState(controlsState: ControlsState): void;
-    getCameraControlsState(): ControlsState;
-    getCameraControlsOptions(): CameraControlsOptions;
-    setCameraControlsOptions(controlsOptions: CameraControlsOptions): void;
-    moveCameraTo(position: THREE.Vector3, target: THREE.Vector3, duration?: number): void;
-    moveCameraTargetTo(target: THREE.Vector3, duration?: number): void;
-    updateCameraNearAndFar(camera: THREE.PerspectiveCamera, combinedBbox: THREE.Box3): void;
-    updateCameraControlsState(deltaTime: number): void;
-    dispose(): void;
-    private calculateAnimationStartTarget;
-    private createTweenAnimation;
-    private calculateCameraFar;
-    private calculateCameraNear;
-    /**
-     * Calculates new target when raycaster doesn't have any intersections with the model.
-     * @param cursorPosition Cursor position for desired calculations.
-     * @param cursorPosition.x
-     * @param cursorPosition.y
-     */
-    private calculateNewTargetWithoutModel;
-    /**
-     * Calculates new camera target based on cursor position.
-     * @param event MouseEvent that contains pointer location data.
-     */
-    private calculateNewTarget;
-    /**
-     * Removes controls event listeners if they are defined.
-     */
-    private teardownControls;
-    private handleMouseWheelActionChange;
-    /**
-     * Method for setting up camera controls listeners and values inside current controls class.
-     */
-    private setupControls;
-    /**
-     * Convert pixel coordinates of the cursor to [-1,1]^2 coordinates.
-     * @param pixelX
-     * @param pixelY
-     */
-    private convertPixelCoordinatesToNormalized;
-    private calculateDefaultDuration;
-}
+/*!
+ * Copyright 2022 Cognite AS
+ */
+import { CameraChangeDelegate, CameraState } from './types';
+/**
+ * Interface for manager responsible for all manipulations to the camera,
+ * including animations and modification of state. Implementations are responsible for
+ * providing a `THREE.PerspectiveCamera` instance to {@link Cognite3DViewer}. Implementations
+ * must trigger the `cameraChange`-event when camera is changed.
+ * The default implementation is {@link DefaultCameraManager}.
+ */
+export interface CameraManager {
+    /**
+     * Returns the camera used for rendering in {@link Cognite3DViewer}.
+     * Note that the camera will not be modified directly by Reveal.
+     * Implementations must trigger the `cameraChange`-event whenever the
+     * camera changes.
+     */
+    getCamera(): THREE.PerspectiveCamera;
+    /**
+     * Set camera's state. Rotation and target can't be set at the same time as they could conflict,
+     * should throw an error if both are passed with non-zero value inside state.
+     *
+     * @param state Camera state, all fields are optional.
+     * @param state.position Camera position in world space.
+     * @param state.target Camera target in world space.
+     * @param state.rotation Camera local rotation in quaternion form.
+     * @example
+     * ```js
+     * // store position, target
+     * const { position, target } = cameraManager.getCameraState();
+     * // restore position, target
+     * cameraManager.setCameraState({ position, target });
+     * ```
+     */
+    setCameraState(state: CameraState): void;
+    /**
+     * Get camera's state
+     * @returns Camera state: position, target and rotation.
+     */
+    getCameraState(): Required<CameraState>;
+    /**
+     * Subscribes to changes of the camera event. This is used by Reveal to react on changes of the camera.
+     * @param event Name of the event.
+     * @param callback Callback to be called when the event is fired.
+     */
+    on(event: 'cameraChange', callback: CameraChangeDelegate): void;
+    /**
+     * Unsubscribes from changes of the camera event.
+     * @param event Name of the event.
+     * @param callback Callback function to be unsubscribed.
+     */
+    off(event: 'cameraChange', callback: CameraChangeDelegate): void;
+    /**
+     * Moves camera to a place where the content of a bounding box is visible to the camera.
+     * @param box The bounding box in world space.
+     * @param duration The duration of the animation moving the camera.
+     * @param radiusFactor The ratio of the distance from camera to center of box and radius of the box.
+     */
+    fitCameraToBoundingBox(boundingBox: THREE.Box3, duration?: number, radiusFactor?: number): void;
+    /**
+     * Updates internal state of camera manager. Expected to update visual state of the camera
+     * as well as it's near and far planes if needed. Called in `requestAnimationFrame`-loop.
+     * Reveal performance affects frequency with which this method is called.
+     * @param deltaTime Delta time since last update in seconds.
+     * @param boundingBox Global bounding box of the model(s) and any custom objects added to the scene.
+     */
+    update(deltaTime: number, boundingBox: THREE.Box3): void;
+    /**
+     * @obvious
+     */
+    dispose(): void;
+}

package/packages/camera-manager/src/CameraManagerHelper.d.ts

@@ -0,0 +1,42 @@
+/*!
+ * Copyright 2022 Cognite AS
+ */
+import * as THREE from 'three';
+/**
+ * Helper methods for implementing a camera manager.
+ */
+export declare class CameraManagerHelper {
+    /**
+     * Reusable buffers used by updateNearAndFarPlane function to avoid allocations.
+     */
+    private static readonly _updateNearAndFarPlaneBuffers;
+    private static readonly _calculateCameraFarBuffers;
+    /**
+     * Calculates camera target based on new camera rotation.
+     * @param camera Used camera instance.
+     * @param rotation New camera rotation in quaternion form.
+     * @param currentTarget Current camera target.
+     * @returns
+     */
+    static calculateNewTargetFromRotation(camera: THREE.PerspectiveCamera, rotation: THREE.Quaternion, currentTarget: THREE.Vector3): THREE.Vector3;
+    /**
+     * Updates near and far plane of the camera based on the bounding box.
+     * @param camera Used camera instance.
+     * @param combinedBbox Bounding box of all objects on the scene.
+     */
+    static updateCameraNearAndFar(camera: THREE.PerspectiveCamera, combinedBbox: THREE.Box3): void;
+    /**
+     * Calculates camera position and target that allows to see the content of provided bounding box.
+     * @param camera Used camera instance.
+     * @param box Bounding box to be fitted.
+     * @param radiusFactor The ratio of the distance from camera to center of box and radius of the box.
+     * @returns
+     */
+    static calculateCameraStateToFitBoundingBox(camera: THREE.PerspectiveCamera, box: THREE.Box3, radiusFactor?: number): {
+        position: THREE.Vector3;
+        target: THREE.Vector3;
+    };
+    private static calculateCameraFar;
+    private static calculateCameraNear;
+    private static getBoundingBoxCorners;
+}

package/packages/camera-manager/src/ComboControls.d.ts

@@ -1,101 +1,112 @@
-/*!
- * Copyright 2021 Cognite AS
- */
-import { EventDispatcher, Vector3, PerspectiveCamera, OrthographicCamera } from 'three';
-export declare class ComboControls extends EventDispatcher {
-    enabled: boolean;
-    enableDamping: boolean;
-    dampingFactor: number;
-    dynamicTarget: boolean;
-    minDistance: number;
-    minZoomDistance: number;
-    dollyFactor: number;
-    minPolarAngle: number;
-    maxPolarAngle: number;
-    minAzimuthAngle: number;
-    maxAzimuthAngle: number;
-    panDollyMinDistanceFactor: number;
-    firstPersonRotationFactor: number;
-    pointerRotationSpeedAzimuth: number;
-    pointerRotationSpeedPolar: number;
-    enableKeyboardNavigation: boolean;
-    keyboardRotationSpeedAzimuth: number;
-    keyboardRotationSpeedPolar: number;
-    mouseFirstPersonRotationSpeed: number;
-    keyboardDollySpeed: number;
-    keyboardPanSpeed: number;
-    keyboardSpeedFactor: number;
-    pinchEpsilon: number;
-    pinchPanSpeed: number;
-    EPSILON: number;
-    dispose: () => void;
-    minZoom: number;
-    maxZoom: number;
-    orthographicCameraDollyFactor: number;
-    lookAtViewTarget: boolean;
-    useScrollTarget: boolean;
-    zoomToCursor: boolean;
-    minDeltaRatio: number;
-    maxDeltaRatio: number;
-    minDeltaDownscaleCoefficient: number;
-    maxDeltaDownscaleCoefficient: number;
-    private _temporarilyDisableDamping;
-    private readonly _camera;
-    private _firstPersonMode;
-    private readonly _reusableCamera;
-    private readonly _reusableVector3;
-    private readonly _accumulatedMouseMove;
-    private readonly _domElement;
-    private readonly _target;
-    private readonly _viewTarget;
-    private readonly _scrollTarget;
-    private readonly _targetEnd;
-    private readonly _spherical;
-    private _sphericalEnd;
-    private readonly _deltaTarget;
-    private _keyboard;
-    private readonly _offsetVector;
-    private readonly _panVector;
-    private readonly _raycaster;
-    private readonly _targetFPS;
-    private _targetFPSOverActualFPS;
-    private _isFocused;
-    constructor(camera: PerspectiveCamera | OrthographicCamera, domElement: HTMLElement);
-    update: (deltaTime: number) => boolean;
-    getState: () => {
-        target: Vector3;
-        position: Vector3;
-    };
-    setState: (position: Vector3, target: Vector3) => void;
-    setViewTarget: (target: Vector3) => void;
-    setScrollTarget: (target: Vector3) => void;
-    triggerCameraChangeEvent: () => void;
-    private calculateShortestDeltaTheta;
-    private readonly convertPixelCoordinatesToNormalized;
-    private readonly onMouseDown;
-    private readonly onMouseUp;
-    private readonly onMouseWheel;
-    private readonly onTouchStart;
-    private readonly onFocusChanged;
-    private readonly isDescendant;
-    private readonly onContextMenu;
-    private readonly rotate;
-    private readonly startMouseRotation;
-    private readonly startMousePan;
-    private readonly startTouchRotation;
-    private readonly startTouchPinch;
-    private readonly handleKeyboard;
-    private readonly rotateSpherical;
-    private readonly rotateFirstPersonMode;
-    private readonly pan;
-    private readonly dollyOrthographicCamera;
-    private readonly calculateNewRadiusAndTargetOffsetLerp;
-    private readonly clampedMap;
-    private readonly calculateNewRadiusAndTargetOffsetScrollTarget;
-    private readonly dollyWithWheelScroll;
-    private readonly dollyPerspectiveCamera;
-    private readonly dolly;
-    private readonly getDollyDeltaDistance;
-    private readonly panLeft;
-    private readonly panUp;
-}
+/*!
+ * Copyright 2021 Cognite AS
+ */
+import { EventDispatcher, Vector3, PerspectiveCamera, OrthographicCamera, Quaternion } from 'three';
+export declare class ComboControls extends EventDispatcher {
+    enabled: boolean;
+    enableDamping: boolean;
+    dampingFactor: number;
+    dynamicTarget: boolean;
+    minDistance: number;
+    minZoomDistance: number;
+    dollyFactor: number;
+    minPolarAngle: number;
+    maxPolarAngle: number;
+    minAzimuthAngle: number;
+    maxAzimuthAngle: number;
+    panDollyMinDistanceFactor: number;
+    firstPersonRotationFactor: number;
+    pointerRotationSpeedAzimuth: number;
+    pointerRotationSpeedPolar: number;
+    enableKeyboardNavigation: boolean;
+    keyboardRotationSpeedAzimuth: number;
+    keyboardRotationSpeedPolar: number;
+    mouseFirstPersonRotationSpeed: number;
+    keyboardDollySpeed: number;
+    keyboardPanSpeed: number;
+    keyboardSpeedFactor: number;
+    pinchEpsilon: number;
+    pinchPanSpeed: number;
+    EPSILON: number;
+    dispose: () => void;
+    minZoom: number;
+    maxZoom: number;
+    orthographicCameraDollyFactor: number;
+    lookAtViewTarget: boolean;
+    useScrollTarget: boolean;
+    zoomToCursor: boolean;
+    minDeltaRatio: number;
+    maxDeltaRatio: number;
+    minDeltaDownscaleCoefficient: number;
+    maxDeltaDownscaleCoefficient: number;
+    private _temporarilyDisableDamping;
+    private readonly _camera;
+    private _firstPersonMode;
+    private readonly _reusableCamera;
+    private readonly _reusableVector3;
+    private readonly _accumulatedMouseMove;
+    private readonly _domElement;
+    private readonly _target;
+    private readonly _viewTarget;
+    private readonly _scrollTarget;
+    private readonly _targetEnd;
+    private readonly _spherical;
+    private _sphericalEnd;
+    private readonly _deltaTarget;
+    private readonly _rawCameraRotation;
+    private _keyboard;
+    private readonly _offsetVector;
+    private readonly _panVector;
+    private readonly _raycaster;
+    private readonly _targetFPS;
+    private _targetFPSOverActualFPS;
+    private _isFocused;
+    constructor(camera: PerspectiveCamera | OrthographicCamera, domElement: HTMLElement);
+    update: (deltaTime: number) => boolean;
+    getState: () => {
+        target: Vector3;
+        position: Vector3;
+    };
+    setState: (position: Vector3, target: Vector3) => void;
+    /**
+     * Camera rotation to be used by the camera instead of target-based rotation.
+     * This rotation is used only when set to non-default quaternion value (not identity rotation quaternion).
+     * Externally, value is updated by `CameraManager` when `setState` method with non-zero rotation is called. Automatically
+     * resets to default value when `setState` method is called with no rotation value.
+     */
+    get cameraRawRotation(): Quaternion;
+    setViewTarget: (target: Vector3) => void;
+    setScrollTarget: (target: Vector3) => void;
+    getScrollTarget: () => Vector3;
+    triggerCameraChangeEvent: () => void;
+    private calculateShortestDeltaTheta;
+    private readonly convertPixelCoordinatesToNormalized;
+    private readonly onPointerDown;
+    private readonly onMouseDown;
+    private readonly onMouseUp;
+    private readonly onMouseWheel;
+    private readonly onTouchStart;
+    private readonly onFocusChanged;
+    private readonly isDescendant;
+    private readonly onContextMenu;
+    private readonly rotate;
+    private readonly startMouseRotation;
+    private readonly startMousePan;
+    private readonly startTouchRotation;
+    private readonly startTouchPinch;
+    private readonly handleKeyboard;
+    private readonly rotateSpherical;
+    private readonly rotateFirstPersonMode;
+    private readonly pan;
+    private readonly dollyOrthographicCamera;
+    private readonly calculateNewRadiusAndTargetOffsetLerp;
+    private readonly clampedMap;
+    private readonly calculateNewRadiusAndTargetOffsetScrollTarget;
+    private readonly dollyWithWheelScroll;
+    private readonly dollyPerspectiveCamera;
+    private readonly dolly;
+    private readonly getDollyDeltaDistance;
+    private readonly panLeft;
+    private readonly panUp;
+    private isIdentityQuaternion;
+}

package/packages/camera-manager/src/DefaultCameraManager.d.ts

@@ -0,0 +1,136 @@
+/*!
+ * Copyright 2021 Cognite AS
+ */
+import * as THREE from 'three';
+import { ComboControls } from './ComboControls';
+import { CameraControlsOptions, CameraChangeDelegate, CameraState } from './types';
+import { CameraManager } from './CameraManager';
+/**
+ * Default implementation of {@link CameraManager}. Uses target-based orbit controls combined with
+ * keyboard and mouse navigation possibility. Supports automatic update of camera near and far
+ * planes and animated change of camera position and target.
+ */
+export declare class DefaultCameraManager implements CameraManager {
+    private readonly _events;
+    private readonly _controls;
+    private readonly _camera;
+    private readonly _domElement;
+    private readonly _inputHandler;
+    private readonly _raycaster;
+    private isDisposed;
+    private _nearAndFarNeedsUpdate;
+    private readonly _modelRaycastCallback;
+    private _onClick;
+    private _onWheel;
+    private static readonly DefaultAnimationDuration;
+    private static readonly DefaultMinAnimationDuration;
+    private static readonly DefaultMaxAnimationDuration;
+    private static readonly DefaultMinDistance;
+    private static readonly DefaultMinZoomDistance;
+    private static readonly DefaultMinimalTimeBetweenRaycasts;
+    private static readonly DefaultCameraControlsOptions;
+    private _cameraControlsOptions;
+    private readonly _currentBoundingBox;
+    /**
+     * When false, camera near and far planes will not be updated automatically (defaults to true).
+     * This can be useful when you have custom content in the 3D view and need to better
+     * control the view frustum.
+     *
+     * When automatic camera near/far planes are disabled, you are responsible for setting
+     * this on your own.
+     * @example
+     * ```
+     * viewer.camera.near = 0.1;
+     * viewer.camera.far = 1000.0;
+     * viewer.camera.updateProjectionMatrix();
+     * ```
+     */
+    automaticNearFarPlane: boolean;
+    /**
+     * When false, the sensitivity of the camera controls will not be updated automatically.
+     * This can be useful to better control the sensitivity of the 3D navigation.
+     *
+     * When not set, control the sensitivity of the camera using `viewer.cameraManager.cameraControls.minDistance`
+     * and `viewer.cameraManager.cameraControls.maxDistance`.
+     */
+    automaticControlsSensitivity: boolean;
+    on(event: 'cameraChange', callback: CameraChangeDelegate): void;
+    off(event: 'cameraChange', callback: CameraChangeDelegate): void;
+    fitCameraToBoundingBox(box: THREE.Box3, duration?: number, radiusFactor?: number): void;
+    /**
+     * Gets instance of camera controls that are used by camera manager. See {@link ComboControls} for more
+     * information on all adjustable properties.
+     */
+    get cameraControls(): ComboControls;
+    /**
+     * Sets whether camera controls through mouse, touch and keyboard are enabled.
+     * This can be useful to e.g. temporarily disable navigation when manipulating other
+     * objects in the scene or when implementing a "cinematic" viewer.
+     */
+    set cameraControlsEnabled(enabled: boolean);
+    /**
+     * Gets whether camera controls through mouse, touch and keyboard are enabled.
+     */
+    get cameraControlsEnabled(): boolean;
+    /**
+     * Sets whether keyboard control of the camera is enabled/disabled.
+     */
+    set keyboardNavigationEnabled(enabled: boolean);
+    /**
+     * Whether keyboard control of the camera is enabled/disabled.
+     */
+    get keyboardNavigationEnabled(): boolean;
+    getCamera(): THREE.PerspectiveCamera;
+    /**
+     * Sets camera state. All parameters are optional. Rotation and target can't be set at the same time,
+     * if so, error will be thrown. Set rotation is preserved until next call of setCameraState with
+     * empty rotation field.
+     * @param state Camera state.
+     * **/
+    setCameraState(state: CameraState): void;
+    getCameraState(): Required<CameraState>;
+    /**
+     * Gets current camera controls options.
+     */
+    getCameraControlsOptions(): CameraControlsOptions;
+    /**
+     * Sets camera controls options to customize camera controls modes. See {@link CameraControlsOptions}.
+     * @param controlsOptions JSON object with camera controls options.
+     */
+    setCameraControlsOptions(controlsOptions: CameraControlsOptions): void;
+    update(deltaTime: number, boundingBox: THREE.Box3): void;
+    dispose(): void;
+    private moveCameraTo;
+    private moveCameraTargetTo;
+    private updateCameraNearAndFar;
+    private calculateAnimationStartTarget;
+    private createTweenAnimation;
+    /**
+     * Calculates new target when raycaster doesn't have any intersections with the model.
+     * @param cursorPosition Cursor position for desired calculations.
+     * @param cursorPosition.x
+     * @param cursorPosition.y
+     */
+    private calculateNewTargetWithoutModel;
+    /**
+     * Calculates new camera target based on cursor position.
+     * @param event MouseEvent that contains pointer location data.
+     */
+    private calculateNewTarget;
+    /**
+     * Removes controls event listeners if they are defined.
+     */
+    private teardownControls;
+    private handleMouseWheelActionChange;
+    /**
+     * Method for setting up camera controls listeners and values inside current controls class.
+     */
+    private setupControls;
+    /**
+     * Convert pixel coordinates of the cursor to [-1,1]^2 coordinates.
+     * @param pixelX
+     * @param pixelY
+     */
+    private convertPixelCoordinatesToNormalized;
+    private calculateDefaultDuration;
+}

package/packages/camera-manager/src/Keyboard.d.ts

@@ -1,17 +1,17 @@
-/*!
- * Copyright 2021 Cognite AS
- */
-export default class Keyboard {
-    private keys;
-    private _disabled;
-    get disabled(): boolean;
-    set disabled(isDisabled: boolean);
-    constructor();
-    isPressed(key: string): boolean;
-    comsumePressed(key: string): boolean;
-    private readonly addEventListeners;
-    private readonly removeEventListeners;
-    private readonly onKeydown;
-    private readonly onKeyup;
-    private readonly clearPressedKeys;
-}
+/*!
+ * Copyright 2021 Cognite AS
+ */
+export default class Keyboard {
+    private keys;
+    private _disabled;
+    get disabled(): boolean;
+    set disabled(isDisabled: boolean);
+    constructor();
+    isPressed(key: string): boolean;
+    comsumePressed(key: string): boolean;
+    private readonly addEventListeners;
+    private readonly removeEventListeners;
+    private readonly onKeydown;
+    private readonly onKeyup;
+    private readonly clearPressedKeys;
+}