@xeokit/xeokit-sdk 2.2.4 → 2.2.5-beta-2

package/types/viewer/scene/camera/CameraFlightAnimation.d.ts

@@ -0,0 +1,167 @@
+import { Component } from "../Component";
+
+/**
+ * Jumps or flies the {@link Scene}'s {@link Camera} to a given target.
+ */
+export declare class CameraFlightAnimation extends Component {
+  /**
+   * Sets the flight duration, in seconds, when calling {@link CameraFlightAnimation#flyTo}.
+   *
+   * Stops any flight currently in progress.
+   *
+   * default value is ````0.5````.
+   *
+   * @param {Number} value New duration value.
+   */
+  set duration(arg: number);
+
+  /**
+   * Gets the flight duration, in seconds, when calling {@link CameraFlightAnimation#flyTo}.
+   *
+   * default value is ````0.5````.
+   *
+   * @returns {Number} New duration value.
+   */
+  get duration(): number;
+
+  /**
+   * Sets if, when CameraFlightAnimation is flying to a boundary, it will always adjust the distance between the
+   * {@link Camera#eye} and {@link Camera#look} so as to ensure that the target boundary is always filling the view volume.
+   *
+   * When false, the eye will remain at its current distance from the look position.
+   *
+   * Default value is ````true````.
+   *
+   * @param {Boolean} value Set ````true```` to activate this behaviour.
+   */
+  set fit(arg: boolean);
+
+  /**
+   * Gets if, when CameraFlightAnimation is flying to a boundary, it will always adjust the distance between the
+   * {@link Camera#eye} and {@link Camera#look} so as to ensure that the target boundary is always filling the view volume.
+   *
+   * When false, the eye will remain at its current distance from the look position.
+   *
+   * Default value is ````true````.
+   *
+   * @returns {Boolean} value Set ````true```` to activate this behaviour.
+   */
+  get fit(): boolean;
+
+  /**
+   * Sets how much of the perspective field-of-view, in degrees, that a target {@link Entity#aabb} should
+   * fill the canvas when calling {@link CameraFlightAnimation#flyTo} or {@link CameraFlightAnimation#jumpTo}.
+   *
+   * Default value is ````45````.
+   *
+   * @param {Number} value New FOV value.
+   */
+  set fitFOV(arg: number);
+
+  /**
+   * Gets how much of the perspective field-of-view, in degrees, that a target {@link Entity#aabb} should
+   * fill the canvas when calling {@link CameraFlightAnimation#flyTo} or {@link CameraFlightAnimation#jumpTo}.
+   *
+   * Default value is ````45````.
+   *
+   * @returns {Number} Current FOV value.
+   */
+  get fitFOV(): number;
+
+  /**
+   * Sets if this CameraFlightAnimation to point the {@link Camera}
+   * in the direction that it is travelling when flying to a target after calling {@link CameraFlightAnimation#flyTo}.
+   *
+   * Default value is ````true````.
+   *
+   * @param {Boolean} value Set ````true```` to activate trailing behaviour.
+   */
+  set trail(arg: boolean);
+
+  /**
+   * Gets if this CameraFlightAnimation points the {@link Camera}
+   * in the direction that it is travelling when flying to a target after calling {@link CameraFlightAnimation#flyTo}.
+   *
+   * Default value is ````true````.
+   *
+   * @returns {Boolean} True if trailing behaviour is active.
+   */
+  get trail(): boolean;
+
+  /**
+   * Flies the {@link Camera} to a target.
+   *
+   *  * When the target is a boundary, the {@link Camera} will fly towards the target and stop when the target fills most of the canvas.
+   *  * When the target is an explicit {@link Camera} position, given as ````eye````, ````look```` and ````up````, then CameraFlightAnimation will interpolate the {@link Camera} to that target and stop there.
+   *
+   * @param {Object|Component} [params=Scene] Either a parameters object or a {@link Component} subtype that has
+   * an AABB. Defaults to the {@link Scene}, which causes the {@link Camera} to fit the Scene in view.
+   * @param {Number} [params.arc=0] Factor in range ````[0..1]```` indicating how much the {@link Camera#eye} position
+   * will swing away from its {@link Camera#look} position as it flies to the target.
+   * @param {Number|String|Component} [params.component] ID or instance of a component to fly to. Defaults to the entire {@link Scene}.
+   * @param {Number[]} [params.aabb] World-space axis-aligned bounding box (AABB) target to fly to.
+   * @param {Number[]} [params.eye] Position to fly the eye position to.
+   * @param {Number[]} [params.look] Position to fly the look position to.
+   * @param {Number[]} [params.up] Position to fly the up vector to.
+   * @param {String} [params.projection] Projection type to transition into as we fly. Can be any of the values of {@link Camera.projection}.
+   * @param {Boolean} [params.fit=true] Whether to fit the target to the view volume. Overrides {@link CameraFlightAnimation#fit}.
+   * @param {Number} [params.fitFOV] How much of field-of-view, in degrees, that a target {@link Entity} or its AABB should
+   * fill the canvas on arrival. Overrides {@link CameraFlightAnimation#fitFOV}.
+   * @param {Number} [params.duration] Flight duration in seconds.  Overrides {@link CameraFlightAnimation#duration}.
+   * @param {Number} [params.orthoScale] Animate the Camera's orthographic scale to this target value. See {@link Ortho#scale}.
+   * @param {Function} [callback] Callback fired on arrival.
+   * @param {Object} [scope] Optional scope for callback.
+   */
+  flyTo(params?: {
+    arc?: number
+    component?: number | string | Component
+    aabb?: number[];
+    eye?: number[];
+    look?: number[];
+    up?: number[];
+    projection?: string;
+    fit?: boolean
+    fitFOV?: number;
+    duration?: number;
+    orthoScale?: number;
+  } | Component, callback?: ()=> void, scope?: any): void;
+
+  /**
+   * Jumps the {@link Scene}'s {@link Camera} to the given target.
+   *
+   * * When the target is a boundary, this CameraFlightAnimation will position the {@link Camera} at where the target fills most of the canvas.
+   * * When the target is an explicit {@link Camera} position, given as ````eye````, ````look```` and ````up```` vectors, then this CameraFlightAnimation will jump the {@link Camera} to that target.
+   *
+   * @param {*|Component} params  Either a parameters object or a {@link Component} subtype that has a World-space AABB.
+   * @param {Number} [params.arc=0]  Factor in range [0..1] indicating how much the {@link Camera#eye} will swing away from its {@link Camera#look} as it flies to the target.
+   * @param {Number|String|Component} [params.component] ID or instance of a component to fly to.
+   * @param {Number[]} [params.aabb]  World-space axis-aligned bounding box (AABB) target to fly to.
+   * @param {Number[]} [params.eye] Position to fly the eye position to.
+   * @param {Number[]} [params.look]  Position to fly the look position to.
+   * @param {Number[]} [params.up] Position to fly the up vector to.
+   * @param {String} [params.projection] Projection type to transition into. Can be any of the values of {@link Camera.projection}.
+   * @param {Number} [params.fitFOV] How much of field-of-view, in degrees, that a target {@link Entity} or its AABB should fill the canvas on arrival. Overrides {@link CameraFlightAnimation#fitFOV}.
+   * @param {Boolean} [params.fit] Whether to fit the target to the view volume. Overrides {@link CameraFlightAnimation#fit}.
+   */
+  jumpTo(params: {
+    arc?: number;
+    component?: number | string | Component;
+    aabb?: number[];
+    eye?: number[];
+    look?: number[];
+    up?: number[];
+    projection?: "perspective" | "ortho" | "frustum" | "customProjection",
+    fitFOV?: number;
+    fit?: boolean;
+  } | Component): void;
+
+  /**
+   * Stops an earlier flyTo, fires arrival callback.
+   */
+  stop(): void;
+
+  /**
+   * Cancels an earlier flyTo without calling the arrival callback.
+   */
+  cancel(): void;
+}

package/types/viewer/scene/camera/CameraPath.d.ts

@@ -0,0 +1,28 @@
+import { Component } from "../Component";
+
+export declare type Frame = {
+  t: number;
+  eye: number[];
+  look: number[];
+  up: number[];
+};
+
+export declare type CameraPathConfiguration = {
+  /** Optional ID, unique among all components in the parent {@link Scene}, generated automatically when omitted. */
+  id?: string;
+  /** Initial sequence of frames. */
+  frames: Frame[];
+};
+
+/**
+ * Defines a sequence of frames along which a {@link CameraPathAnimation} can animate a {@link Camera}.
+ *
+ */
+export declare class CameraPath extends Component {
+    /**
+     * @constructor
+     * @param {Component} [owner]  Owner component. When destroyed, the owner will destroy this CameraPath as well.
+     * @param {CameraPathConfiguration} [cfg] Configuration
+     */
+    constructor(owner?: Component, cfg?: CameraPathConfiguration);
+}

package/types/viewer/scene/camera/CameraPathAnimation.d.ts

@@ -0,0 +1,95 @@
+import { Component } from "../Component";
+import { CameraPath } from "./CameraPath";
+
+export declare type CameraPathAnimationConfiguration = {
+  playingRate: number;
+  /** A {@link CameraPath} that defines the path of a {@link Camera} */
+  cameraPath: CameraPath;
+};
+
+/**
+ * Animates the {@link Scene}'s's {@link Camera} along a {@link CameraPath}.
+ */
+export declare class CameraPathAnimation extends Component {
+    /**
+     * @constructor
+     * @param {Component} [owner]  Owner component. When destroyed, the owner will destroy this CameraPathAnimation as well.
+     * @param {CameraPathAnimationConfiguration} [cfg] Configuration
+     */
+    constructor(owner?: Component, cfg?: CameraPathAnimationConfiguration);
+
+    /**
+     * Sets the {@link CameraPath} animated by this CameraPathAnimation.
+     *
+     @param {CameraPath} value The new CameraPath.
+     */
+    set cameraPath(arg: CameraPath);
+
+    /**
+     * Gets the {@link CameraPath} animated by this CameraPathAnimation.
+     *
+     @returns {CameraPath} The CameraPath.
+     */
+    get cameraPath(): CameraPath;
+
+    /**
+     * Sets the rate at which the CameraPathAnimation animates the {@link Camera} along the {@link CameraPath}.
+     *
+     *  @param {Number} value The amount of progress per second.
+     */
+    set rate(arg: number);
+
+    /**
+     * Gets the rate at which the CameraPathAnimation animates the {@link Camera} along the {@link CameraPath}.
+     *
+     * @returns {*|number} The current playing rate.
+     */
+    get rate(): number;
+
+    /**
+     * Begins animating the {@link Camera} along CameraPathAnimation's {@link CameraPath} from the beginning.
+     */
+    play(): void;
+
+    /**
+     * Begins animating the {@link Camera} along CameraPathAnimation's {@link CameraPath} from the given time.
+     *
+     * @param {Number} t Time instant.
+     */
+    playToT(t: number): void;
+
+    /**
+     * Animates the {@link Camera} along CameraPathAnimation's {@link CameraPath} to the given frame.
+     *
+     * @param {Number} frameIdx Index of the frame to play to.
+     */
+    playToFrame(frameIdx: number): void;
+
+    /**
+     * Flies the {@link Camera} directly to the given frame on the CameraPathAnimation's {@link CameraPath}.
+     *
+     * @param {Number} frameIdx Index of the frame to play to.
+     * @param {Function} [ok] Callback to fire when playing is complete.
+     */
+    flyToFrame(frameIdx: number, ok?: ()=> void): void;
+
+    /**
+     * Scrubs the {@link Camera} to the given time on the CameraPathAnimation's {@link CameraPath}.
+     *
+     * @param {Number} t Time instant.
+     */
+    scrubToT(t: number): void;
+
+    /**
+     * Scrubs the {@link Camera} to the given frame on the CameraPathAnimation's {@link CameraPath}.
+     *
+     * @param {Number} frameIdx Index of the frame to scrub to.
+     */
+    scrubToFrame(frameIdx: number): void;
+
+    /**
+     * Stops playing this CameraPathAnimation.
+     */
+    stop(): void;
+}
+

package/types/viewer/scene/camera/CustomProjection.d.ts

@@ -0,0 +1,57 @@
+import { Component } from "../Component";
+import { Camera } from "../Camera";
+
+/**
+ * Defines a custom projection for a {@link Camera} as a custom 4x4 matrix..
+ */
+export declare class CustomProjection extends Component {
+  /**
+   * The Camera this CustomProjection belongs to.
+   */
+  camera: Camera;
+
+  /**
+   * Sets the CustomProjection's projection transform matrix.
+   *
+   * Fires a "matrix" event on change.
+
+    * Default value is ````[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]````.
+    *
+    * @param {Number[]} matrix New value for the CustomProjection's matrix.
+    */
+  set matrix(arg: number[]);
+
+  /**
+   * Gets the CustomProjection's projection transform matrix.
+   *
+   * Default value is ````[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]````.
+   *
+   * @return {Number[]} New value for the CustomProjection's matrix.
+   */
+  get matrix(): number[];
+
+  /**
+   * Gets the inverse of {@link CustomProjection#matrix}.
+   *
+   * @returns {Number[]} The inverse of {@link CustomProjection#matrix}.
+   */
+  get inverseMatrix(): number[];
+
+  /**
+   * Gets the transpose of {@link CustomProjection#matrix}.
+   *
+   * @returns {Number[]} The transpose of {@link CustomProjection#matrix}.
+   */
+  get transposedMatrix(): number[];
+
+  /**
+   * Un-projects the given Canvas-space coordinates, using this CustomProjection.
+   *
+   * @param {Number[]} canvasPos Inputs 2D Canvas-space coordinates.
+   * @param {Number} screenZ Inputs Screen-space Z coordinate.
+   * @param {Number[]} screenPos Outputs 3D Screen/Clip-space coordinates.
+   * @param {Number[]} viewPos Outputs un-projected 3D View-space coordinates.
+   * @param {Number[]} worldPos Outputs un-projected 3D World-space coordinates.
+   */
+  unproject(canvasPos: number[], screenZ: number, screenPos: number[], viewPos: number[], worldPos: number[]): number[];
+}

package/types/viewer/scene/camera/Frustum.d.ts

@@ -0,0 +1,166 @@
+import { Component } from "../Component";
+import { Camera } from "../Camera";
+
+/**
+ * Defines its {@link Camera}'s perspective projection as a frustum-shaped view volume.
+ */
+export declare class Frustum extends Component {
+  /**
+   * The Camera this Frustum belongs to.
+   *
+   * @property camera
+   * @type {Camera}
+   * @final
+   */
+  camera: Camera;
+
+  /**
+   * Sets the position of the Frustum's left plane on the View-space X-axis.
+   *
+   * Fires a {@link Frustum#left:emits} emits on change.
+   *
+   * @param {Number} value New left frustum plane position.
+   */
+  set left(arg: number);
+
+  /**
+   * Gets the position of the Frustum's left plane on the View-space X-axis.
+   *
+   * @return {Number} Left frustum plane position.
+   */
+  get left(): number;
+
+  /**
+   * Sets the position of the Frustum's right plane on the View-space X-axis.
+   *
+   * Fires a {@link Frustum#right:emits} emits on change.
+   *
+   * @param {Number} value New right frustum plane position.
+   */
+  set right(arg: number);
+
+  /**
+   * Gets the position of the Frustum's right plane on the View-space X-axis.
+   *
+   * Fires a {@link Frustum#right:emits} emits on change.
+   *
+   * @return {Number} Right frustum plane position.
+   */
+  get right(): number;
+
+  /**
+   * Sets the position of the Frustum's bottom plane on the View-space Y-axis.
+   *
+   * Fires a {@link Frustum#bottom:emits} emits on change.
+   *
+   * @emits {"bottom"} event with the value of this property whenever it changes.
+   *
+   * @param {Number} value New bottom frustum plane position.
+   */
+  set bottom(arg: number);
+
+  /**
+   * Gets the position of the Frustum's bottom plane on the View-space Y-axis.
+   *
+   * Fires a {@link Frustum#bottom:emits} emits on change.
+   *
+   * @return {Number} Bottom frustum plane position.
+   */
+  get bottom(): number;
+
+  /**
+   * Sets the position of the Frustum's top plane on the View-space Y-axis.
+   *
+   * Fires a {@link Frustum#top:emits} emits on change.
+   *
+   * @param {Number} value New top frustum plane position.
+   */
+  set top(arg: number);
+
+  /**
+   * Gets the position of the Frustum's top plane on the View-space Y-axis.
+   *
+   * Fires a {@link Frustum#top:emits} emits on change.
+   *
+   * @return {Number} Top frustum plane position.
+   */
+  get top(): number;
+
+  /**
+   * Sets the position of the Frustum's near plane on the positive View-space Z-axis.
+   *
+   * Fires a {@link Frustum#near:emits} emits on change.
+   *
+   * Default value is ````0.1````.
+   *
+   * @param {Number} value New Frustum near plane position.
+   */
+  set near(arg: number);
+
+  /**
+   * Gets the position of the Frustum's near plane on the positive View-space Z-axis.
+   *
+   * Fires a {@link Frustum#near:emits} emits on change.
+   *
+   * Default value is ````0.1````.
+   *
+   * @return {Number} Near frustum plane position.
+   */
+  get near(): number;
+
+  /**
+   * Sets the position of the Frustum's far plane on the positive View-space Z-axis.
+   *
+   * Fires a {@link Frustum#far:emits} emits on change.
+   *
+   * Default value is ````10000.0````.
+   *
+   * @param {Number} value New far frustum plane position.
+   */
+  set far(arg: number);
+
+  /**
+   * Gets the position of the Frustum's far plane on the positive View-space Z-axis.
+   *
+   * Default value is ````10000.0````.
+   *
+   * @return {Number} Far frustum plane position.
+   */
+  get far(): number;
+
+  /**
+   * Gets the Frustum's projection transform matrix.
+   *
+   * Fires a {@link Frustum#matrix:emits} emits on change.
+   *
+   * Default value is ````[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]````.
+   *
+   * @returns {Number[]} The Frustum's projection matrix matrix.
+   */
+  get matrix(): number[];
+
+  /**
+   * Gets the inverse of {@link Frustum#matrix}.
+   *
+   * @returns {Number[]} The inverse orthographic projection matrix.
+   */
+  get inverseMatrix(): number[];
+
+  /**
+   * Gets the transpose of {@link Frustum#matrix}.
+   *
+   * @returns {Number[]} The transpose of {@link Frustum#matrix}.
+   */
+  get transposedMatrix(): number[];
+
+  /**
+   * Un-projects the given Canvas-space coordinates, using this Frustum projection.
+   *
+   * @param {Number[]} canvasPos Inputs 2D Canvas-space coordinates.
+   * @param {Number} screenZ Inputs Screen-space Z coordinate.
+   * @param {Number[]} screenPos Outputs 3D Screen/Clip-space coordinates.
+   * @param {Number[]} viewPos Outputs un-projected 3D View-space coordinates.
+   * @param {Number[]} worldPos Outputs un-projected 3D World-space coordinates.
+   */
+  unproject(canvasPos: number[], screenZ: number, screenPos: number[], viewPos: number[], worldPos: number[]): number[];
+}

package/types/viewer/scene/camera/Ortho.d.ts

@@ -0,0 +1,115 @@
+import { Component } from "../Component";
+import { Camera } from "../Camera";
+
+/**
+ * Defines its {@link Camera}'s orthographic projection as a box-shaped view volume.
+ */
+export declare class Ortho extends Component {
+  /**
+   * The Camera this Ortho belongs to.
+   *
+   * @property camera
+   * @type {Camera}
+   * @final
+   */
+  camera: Camera;
+
+  /**
+   * Sets scale factor for this Ortho's extents on X and Y axis.
+   *
+   * Clamps to minimum value of ````0.01```.
+   *
+   * Fires a "scale" event on change.
+   *
+   * Default value is ````1.0````
+   * @param {Number} value New scale value.
+   */
+  set scale(arg: number);
+
+  /**
+   * Gets scale factor for this Ortho's extents on X and Y axis.
+   *
+   * Clamps to minimum value of ````0.01```.
+   *
+   * Default value is ````1.0````
+   *
+   * @returns {Number} New Ortho scale value.
+   */
+  get scale(): number;
+
+  /**
+   * Sets the position of the Ortho's near plane on the positive View-space Z-axis.
+   *
+   * Fires a "near" emits on change.
+   *
+   * Default value is ````0.1````.
+   *
+   * @param {Number} value New Ortho near plane position.
+   */
+  set near(arg: number);
+
+  /**
+   * Gets the position of the Ortho's near plane on the positive View-space Z-axis.
+   *
+   * Default value is ````0.1````.
+   *
+   * @returns {Number} New Ortho near plane position.
+   */
+  get near(): number;
+
+  /**
+   * Sets the position of the Ortho's far plane on the positive View-space Z-axis.
+   *
+   * Fires a "far" event on change.
+   *
+   * Default value is ````2000.0````.
+   *
+   * @param {Number} value New far ortho plane position.
+   */
+  set far(arg: number);
+
+  /**
+   * Gets the position of the Ortho's far plane on the positive View-space Z-axis.
+   *
+   * Default value is ````10000.0````.
+   *
+   * @returns {Number} New far ortho plane position.
+   */
+  get far(): number;
+
+  /**
+   * Gets the Ortho's projection transform matrix.
+   *
+   * Fires a "matrix" event on change.
+   *
+   * Default value is ````[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]````.
+   *
+   * @returns {Number[]} The Ortho's projection matrix.
+   */
+  get matrix(): number[];
+
+  /**
+   * Gets the inverse of {@link Ortho#matrix}.
+   *
+   * @returns {Number[]} The inverse of {@link Ortho#matrix}.
+   */
+  get inverseMatrix(): number[];
+
+  /**
+   * Gets the transpose of {@link Ortho#matrix}.
+   *
+   * @returns {Number[]} The transpose of {@link Ortho#matrix}.
+   */
+  get transposedMatrix(): number[];
+
+  /**
+   * Un-projects the given Canvas-space coordinates, using this Ortho projection.
+   *
+   * @param {Number[]} canvasPos Inputs 2D Canvas-space coordinates.
+   * @param {Number} screenZ Inputs Screen-space Z coordinate.
+   * @param {Number[]} screenPos Outputs 3D Screen/Clip-space coordinates.
+   * @param {Number[]} viewPos Outputs un-projected 3D View-space coordinates.
+   * @param {Number[]} worldPos Outputs un-projected 3D World-space coordinates.
+   */
+  unproject(canvasPos: number[], screenZ: number, screenPos: number[], viewPos: number[], worldPos: number[]): number[];
+}