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

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

@@ -0,0 +1,364 @@
+import { Component } from "../Component";
+import { Perspective } from "./Perspective";
+import { Ortho } from "./Ortho";
+import { Frustum } from "./Frustum";
+import { CustomProjection } from "./CustomProjection";
+
+/**
+ * Manages viewing and projection transforms for its {@link Scene}.
+ */
+export declare class Camera extends Component {
+  /**
+   * Sets an optional matrix to premultiply into {@link Camera.matrix} matrix.
+   *
+   * This is intended to be used for stereo rendering with WebVR etc.
+   *
+   * @param {Number[]} matrix The matrix.
+   */
+  set deviceMatrix(arg: number[]);
+
+  /**
+   * Gets an optional matrix to premultiply into {@link Camera.matrix} matrix.
+   *
+   * @returns {Number[]} The matrix.
+   */
+  get deviceMatrix(): number[];
+
+  /**
+   * Sets the position of the Camera's eye.
+   *
+   * Default value is ````[0,0,10]````.
+   *
+   * @emits "eye" event on change, with the value of this property.
+   * @type {Number[]} New eye position.
+   */
+  set eye(arg: number[]);
+
+  /**
+   * Gets the position of the Camera's eye.
+   *
+   * Default vale is ````[0,0,10]````.
+   *
+   * @type {Number[]} New eye position.
+   */
+  get eye(): number[];
+
+  /**
+   * Sets the position of this Camera's point-of-interest.
+   *
+   * Default value is ````[0,0,0]````.
+   *
+   * @emits "look" event on change, with the value of this property.
+   *
+   * @param {Number[]} look Camera look position.
+   */
+  set look(arg: number[]);
+
+  /**
+   * Gets the position of this Camera's point-of-interest.
+   *
+   * Default value is ````[0,0,0]````.
+   *
+   * @returns {Number[]} Camera look position.
+   */
+  get look(): number[];
+
+  /**
+   * Sets the direction of this Camera's {@link Camera.up} vector.
+   *
+   * @emits "up" event on change, with the value of this property.
+   *
+   * @param {Number[]} up Direction of "up".
+   */
+  set up(arg: number[]);
+
+  /**
+   * Gets the direction of this Camera's {@link Camera.up} vector.
+   *
+   * @returns {Number[]} Direction of "up".
+   */
+  get up(): number[];
+
+  /**
+   * Sets the up, right and forward axis of the World coordinate system.
+   *
+   * Has format: ````[rightX, rightY, rightZ, upX, upY, upZ, forwardX, forwardY, forwardZ]````
+   *
+   * Default axis is ````[1, 0, 0, 0, 1, 0, 0, 0, 1]````
+   *
+   * @param {Number[]} axis The new Wworld coordinate axis.
+   */
+  set worldAxis(arg: number[]);
+
+  /**
+   * Gets the up, right and forward axis of the World coordinate system.
+   *
+   * Has format: ````[rightX, rightY, rightZ, upX, upY, upZ, forwardX, forwardY, forwardZ]````
+   *
+   * Default axis is ````[1, 0, 0, 0, 1, 0, 0, 0, 1]````
+   *
+   * @returns {Number[]} The current World coordinate axis.
+   */
+  get worldAxis(): number[];
+
+  /**
+   * Sets whether to lock yaw rotation to pivot about the World-space "up" axis.
+   *
+   * Fires a {@link Camera.gimbalLock:event} event on change.
+   *
+   * @params {Boolean} gimbalLock Set true to lock gimbal.
+   */
+  set gimbalLock(arg: boolean);
+
+  /**
+   * Gets whether to lock yaw rotation to pivot about the World-space "up" axis.
+   *
+   * @returns {Boolean} Returns ````true```` if gimbal is locked.
+   */
+  get gimbalLock(): boolean;
+
+  /**
+   * Sets the active projection type.
+   *
+   * Accepted values are ````"perspective"````, ````"ortho"````, ````"frustum"```` and ````"customProjection"````.
+   *
+   * Default value is ````"perspective"````.
+   *
+   * @param {String} value Identifies the active projection type.
+   */
+  set projection(arg: "perspective" | "ortho" | "frustum" | "customProjection");
+
+  /**
+   * Gets the active projection type.
+   *
+   * Possible values are ````"perspective"````, ````"ortho"````, ````"frustum"```` and ````"customProjection"````.
+   *
+   * Default value is ````"perspective"````.
+   *
+   * @returns {String} Identifies the active projection type.
+   */
+  get projection(): "perspective" | "ortho" | "frustum" | "customProjection";
+
+  /**
+   * Rotates {@link Camera.eye} about {@link Camera.look}, around the {@link Camera.up} vector
+   *
+   * @param {Number} angleInc Angle of rotation in degrees
+   */
+  orbitYaw(angleInc: number): void;
+
+  /**
+   * Rotates {@link Camera.eye} about {@link Camera.look} around the right axis (orthogonal to {@link Camera.up} and "look").
+   *
+   * @param {Number} angleInc Angle of rotation in degrees
+   */
+  orbitPitch(angleInc: number): void;
+
+  /**
+   * Rotates {@link Camera.look} about {@link Camera.eye}, around the {@link Camera.up} vector.
+   *
+   * @param {Number} angleInc Angle of rotation in degrees
+   */
+  yaw(angleInc: number): void;
+
+  /**
+   * Rotates {@link Camera.look} about {@link Camera.eye}, around the right axis (orthogonal to {@link Camera.up} and "look").
+   *
+   * @param {Number} angleInc Angle of rotation in degrees
+   */
+  pitch(angleInc: number): void;
+
+  /**
+     * Pans the Camera along its local X, Y and Z axis.
+     *
+     * @param {Number[]}pan The pan vector
+     */
+  pan(pan: number[]): void;
+
+  /**
+   * Increments/decrements the Camera's zoom factor, which is the distance between {@link Camera.eye} and {@link Camera.look}.
+   *
+   * @param {Number} delta Zoom factor increment.
+   */
+  zoom(delta: number): void;
+
+  /**
+   * Gets the direction of World-space "up".
+   *
+   * This is set by {@link Camera.worldAxis}.
+   *
+   * Default value is ````[0,1,0]````.
+   *
+   * @returns {Number[]} The "up" vector.
+   */
+  get worldUp(): number[];
+
+  /**
+   * Gets if the World-space X-axis is "up".
+   * @returns {boolean}
+   */
+  get xUp(): boolean;
+
+  /**
+   * Gets if the World-space Y-axis is "up".
+   * @returns {boolean}
+   */
+  get yUp(): boolean;
+
+  /**
+   * Gets if the World-space Z-axis is "up".
+   * @returns {boolean}
+   */
+  get zUp(): boolean;
+
+  /**
+   * Gets the direction of World-space "right".
+   *
+   * This is set by {@link Camera.worldAxis}.
+   *
+   * Default value is ````[1,0,0]````.
+   *
+   * @returns {Number[]} The "up" vector.
+   */
+  get worldRight(): number[];
+
+  /**
+   * Gets the direction of World-space "forwards".
+   *
+   * This is set by {@link Camera.worldAxis}.
+   *
+   * Default value is ````[0,0,1]````.
+   *
+   * @returns {Number[]} The "up" vector.
+   */
+  get worldForward(): number[];
+
+  /**
+   * Gets whether to prevent camera from being pitched upside down.
+   *
+   * The camera is upside down when the angle between {@link Camera.up} and {@link Camera.worldUp} is less than one degree.
+   *
+   * Default value is ````false````.
+   *
+   * @returns {Boolean} ````true```` if pitch rotation is currently constrained.
+   */
+  get constrainPitch(): boolean;
+
+  /**
+   * Sets whether to prevent camera from being pitched upside down.
+   *
+   * The camera is upside down when the angle between {@link Camera.up} and {@link Camera.worldUp} is less than one degree.
+   *
+   * Fires a {@link Camera.constrainPitch:event} event on change.
+   *
+   * Default value is ````false````.
+   *
+   * @param {Boolean} value Set ````true```` to contrain pitch rotation.
+   */
+  set constrainPitch(arg: boolean);
+
+  /**
+   * Gets distance from {@link Camera.look} to {@link Camera.eye}.
+   *
+   * @returns {Number} The distance.
+   */
+  get eyeLookDist(): boolean;
+
+  /**
+   * Gets the Camera's viewing transformation matrix.
+   *
+   * Fires a {@link Camera.matrix:event} event on change.
+   *
+   * @returns {Number[]} The viewing transform matrix.
+   */
+  get matrix(): number[];
+
+  /**
+   * Gets the Camera's viewing transformation matrix.
+   *
+   * Fires a {@link Camera.matrix:event} event on change.
+   *
+   * @returns {Number[]} The viewing transform matrix.
+   */
+  get viewMatrix(): number[];
+
+  /**
+   * The Camera's viewing normal transformation matrix.
+   *
+   * Fires a {@link Camera.matrix:event} event on change.
+   *
+   * @returns {Number[]} The viewing normal transform matrix.
+   */
+  get normalMatrix(): number[];
+
+  /**
+   * The Camera's viewing normal transformation matrix.
+   *
+   * Fires a {@link Camera.matrix:event} event on change.
+   *
+   * @returns {Number[]} The viewing normal transform matrix.
+   */
+  get viewNormalMatrix(): number[];
+
+  /**
+   * Gets the inverse of the Camera's viewing transform matrix.
+   *
+   * This has the same value as {@link Camera.normalMatrix}.
+   *
+   * @returns {Number[]} The inverse viewing transform matrix.
+   */
+  get inverseViewMatrix(): number[];
+
+  /**
+   * Gets the Camera's projection transformation projMatrix.
+   *
+   * Fires a {@link Camera.projMatrix:event} event on change.
+   *
+   * @returns {Number[]} The projection matrix.
+   */
+  get projMatrix(): number[];
+
+  /**
+   * Gets the Camera's perspective projection.
+   *
+   * The Camera uses this while {@link Camera.projection} equals ````perspective````.
+   *
+   * @returns {Perspective} The Perspective component.
+   */
+  get perspective(): Perspective;
+
+  /**
+   * Gets the Camera's orthographic projection.
+   *
+   * The Camera uses this while {@link Camera.projection} equals ````ortho````.
+   *
+   * @returns {Ortho} The Ortho component.
+   */
+  get ortho(): Ortho;
+
+  /**
+   * Gets the Camera's frustum projection.
+   *
+   * The Camera uses this while {@link Camera.projection} equals ````frustum````.
+   *
+   * @returns {Frustum} The Ortho component.
+   */
+  get frustum(): Frustum;
+
+  /**
+   * Gets the Camera's custom projection.
+   *
+   * This is used while {@link Camera.projection} equals "customProjection".
+   *
+   * @returns {CustomProjection} The custom projection.
+   */
+  get customProjection(): CustomProjection;
+
+  /**
+   * Gets the currently active projection for this Camera.
+   *
+   * The currently active project is selected with {@link Camera.projection}.
+   *
+   * @returns {Perspective|Ortho|Frustum|CustomProjection} The currently active projection is active.
+   */
+  get project(): Perspective | Ortho | Frustum | CustomProjection;
+}

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;
+}
+