@onerjs/core 8.30.9 → 8.31.1

package/Cameras/cameraMovement.d.ts

@@ -0,0 +1,150 @@
+import type { Scene } from "../scene.js";
+import { Vector3 } from "../Maths/math.vector.js";
+import type { InterpolatingBehavior } from "../Behaviors/Cameras/interpolatingBehavior.js";
+/**
+ * @experimental
+ * This class is subject to change as geospatial camera evolves.
+ *
+ * It is intended to hold all logic related to converting input pixel deltas into current frame deltas, taking speed / framerate into account
+ * to ensure smooth frame-rate-independent movement
+ */
+export declare class CameraMovement {
+    protected _cameraPosition: Vector3;
+    protected _behavior?: InterpolatingBehavior | undefined;
+    protected _scene: Scene;
+    /**
+     * Should be set by input classes to indicates whether there is active input this frame
+     * This helps us differentiate between 0 pixel delta due to no input vs user actively holding still
+     */
+    activeInput: boolean;
+    /**
+     * ------------ Speed ----------------
+     * Speed defines the amount of camera movement expected per input pixel movement
+     * -----------------------------------
+     */
+    /**
+     * Desired coordinate unit movement per input pixel when zooming
+     */
+    zoomSpeed: number;
+    /**
+     * Desired coordinate unit movement per input pixel when panning
+     */
+    panSpeed: number;
+    /**
+     * Desired radians movement per input pixel when rotating along x axis
+     */
+    rotationXSpeed: number;
+    /**
+     * Desired radians movement per input pixel when rotating along y axis
+     */
+    rotationYSpeed: number;
+    /**
+     * ----------- Speed multipliers ---------------
+     * Multipliers allow movement classes to modify the effective speed dynamically per-frame
+     * (ex: scale zoom based on distance from target)
+     * -----------------------------------
+     */
+    /**
+     * Multiplied atop zoom speed. Used to dynamically adjust zoom speed based on per-frame context (ex: zoom faster when further from target)
+     */
+    protected _zoomSpeedMultiplier: number;
+    /**
+     * Multiplied atop pan speed. Used to dynamically adjust pan speed based on per-frame context (ex: pan slowly when close to target)
+     */
+    protected _panSpeedMultiplier: number;
+    /**
+     * ---------- Inertia ----------------
+     * Inertia represents the decay factor per-frame applied to the velocity when there is no user input.
+     * 0 = No inertia, instant stop (velocity immediately becomes 0)
+     * 0.5 = Strong decay, velocity halves every frame at 60fps
+     * 0.9 = Moderate inertia, velocity retains 90% per frame at 60fps
+     * 0.95 = High inertia, smooth glide, velocity retains 95% per frame at 60fps
+     * 1 = Infinite inertia, never stops (velocity never decays)
+     * -----------------------------------
+     */
+    /**
+     * Inertia applied to the zoom velocity when there is no user input.
+     * Higher inertia === slower decay, velocity retains more of its value each frame
+     */
+    zoomInertia: number;
+    /**
+     * Inertia applied to the panning velocity when there is no user input.
+     * Higher inertia === slower decay, velocity retains more of its value each frame
+     */
+    panInertia: number;
+    /**
+     * Inertia applied to the rotation velocity when there is no user input.
+     * Higher inertia === slower decay, velocity retains more of its value each frame
+     */
+    rotationInertia: number;
+    /**
+     * ---------- Accumulated Pixel Deltas -----------
+     * Pixel inputs accumulated throughout the frame by input classes (reset each frame after processing)
+     * -----------------------------------
+     */
+    /**
+     * Accumulated pixel delta (by input classes) for zoom this frame
+     * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)
+     * Reset to zero after each frame
+     */
+    zoomAccumulatedPixels: number;
+    /**
+     * Accumulated pixel delta (by input classes) for panning this frame
+     * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)
+     * Reset to zero after each frame
+     */
+    panAccumulatedPixels: Vector3;
+    /**
+     * Accumulated pixel delta (by input classes) for rotation this frame
+     * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)
+     * Reset to zero after each frame
+     */
+    rotationAccumulatedPixels: Vector3;
+    /**
+     * ---------- Current Frame Movement Deltas -----------
+     * Deltas read on each frame by camera class in order to move the camera
+     * -----------------------------------
+     */
+    /**
+     * Zoom delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from zoomPixelDelta (taking speed into account)
+     */
+    zoomDeltaCurrentFrame: number;
+    /**
+     * Pan delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from panPixelDelta (taking speed into account)
+     */
+    panDeltaCurrentFrame: Vector3;
+    /**
+     * Rotation delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from rotationPixelDelta (taking speed into account)
+     */
+    rotationDeltaCurrentFrame: Vector3;
+    /**
+     * ---------- Velocity -----------
+     * Used to track velocity between frames for inertia calculation
+     * -----------------------------------
+     */
+    /**
+     * Zoom velocity used for inertia calculations (movement / time)
+     */
+    protected _zoomVelocity: number;
+    /**
+     * Pan velocity used for inertia calculations (movement / time)
+     */
+    private _panVelocity;
+    /**
+     * Rotation velocity used for inertia calculations (movement / time)
+     */
+    private _rotationVelocity;
+    /**
+     * Used when calculating inertial decay. Default to 60fps
+     */
+    private _prevFrameTimeMs;
+    constructor(scene: Scene, _cameraPosition: Vector3, _behavior?: InterpolatingBehavior | undefined);
+    /**
+     * When called, will take the accumulated pixel deltas set by input classes and convert them into current frame deltas, stored in currentFrameMovementDelta properties
+     * Takes speed, scaling, inertia, and framerate into account to ensure smooth movement
+     * Zeros out pixelDeltas before returning
+     */
+    computeCurrentFrameDeltas(): void;
+    get isInterpolating(): boolean;
+    private _calculateCurrentVelocity;
+}

package/Cameras/cameraMovement.js

@@ -0,0 +1,190 @@
+import { Vector3 } from "../Maths/math.vector.js";
+import { Epsilon } from "../Maths/math.constants.js";
+const FrameDurationAt60FPS = 1000 / 60;
+/**
+ * @experimental
+ * This class is subject to change as geospatial camera evolves.
+ *
+ * It is intended to hold all logic related to converting input pixel deltas into current frame deltas, taking speed / framerate into account
+ * to ensure smooth frame-rate-independent movement
+ */
+export class CameraMovement {
+    constructor(scene, _cameraPosition, _behavior) {
+        this._cameraPosition = _cameraPosition;
+        this._behavior = _behavior;
+        /**
+         * Should be set by input classes to indicates whether there is active input this frame
+         * This helps us differentiate between 0 pixel delta due to no input vs user actively holding still
+         */
+        this.activeInput = false;
+        /**
+         * ------------ Speed ----------------
+         * Speed defines the amount of camera movement expected per input pixel movement
+         * -----------------------------------
+         */
+        /**
+         * Desired coordinate unit movement per input pixel when zooming
+         */
+        this.zoomSpeed = 1;
+        /**
+         * Desired coordinate unit movement per input pixel when panning
+         */
+        this.panSpeed = 1;
+        /**
+         * Desired radians movement per input pixel when rotating along x axis
+         */
+        this.rotationXSpeed = 1;
+        /**
+         * Desired radians movement per input pixel when rotating along y axis
+         */
+        this.rotationYSpeed = 1;
+        /**
+         * ----------- Speed multipliers ---------------
+         * Multipliers allow movement classes to modify the effective speed dynamically per-frame
+         * (ex: scale zoom based on distance from target)
+         * -----------------------------------
+         */
+        /**
+         * Multiplied atop zoom speed. Used to dynamically adjust zoom speed based on per-frame context (ex: zoom faster when further from target)
+         */
+        this._zoomSpeedMultiplier = 1;
+        /**
+         * Multiplied atop pan speed. Used to dynamically adjust pan speed based on per-frame context (ex: pan slowly when close to target)
+         */
+        this._panSpeedMultiplier = 1;
+        /**
+         * ---------- Inertia ----------------
+         * Inertia represents the decay factor per-frame applied to the velocity when there is no user input.
+         * 0 = No inertia, instant stop (velocity immediately becomes 0)
+         * 0.5 = Strong decay, velocity halves every frame at 60fps
+         * 0.9 = Moderate inertia, velocity retains 90% per frame at 60fps
+         * 0.95 = High inertia, smooth glide, velocity retains 95% per frame at 60fps
+         * 1 = Infinite inertia, never stops (velocity never decays)
+         * -----------------------------------
+         */
+        /**
+         * Inertia applied to the zoom velocity when there is no user input.
+         * Higher inertia === slower decay, velocity retains more of its value each frame
+         */
+        this.zoomInertia = 0.9;
+        /**
+         * Inertia applied to the panning velocity when there is no user input.
+         * Higher inertia === slower decay, velocity retains more of its value each frame
+         */
+        this.panInertia = 0.9;
+        /**
+         * Inertia applied to the rotation velocity when there is no user input.
+         * Higher inertia === slower decay, velocity retains more of its value each frame
+         */
+        this.rotationInertia = 0.9;
+        /**
+         * ---------- Accumulated Pixel Deltas -----------
+         * Pixel inputs accumulated throughout the frame by input classes (reset each frame after processing)
+         * -----------------------------------
+         */
+        /**
+         * Accumulated pixel delta (by input classes) for zoom this frame
+         * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)
+         * Reset to zero after each frame
+         */
+        this.zoomAccumulatedPixels = 0;
+        /**
+         * Accumulated pixel delta (by input classes) for panning this frame
+         * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)
+         * Reset to zero after each frame
+         */
+        this.panAccumulatedPixels = new Vector3();
+        /**
+         * Accumulated pixel delta (by input classes) for rotation this frame
+         * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)
+         * Reset to zero after each frame
+         */
+        this.rotationAccumulatedPixels = new Vector3();
+        /**
+         * ---------- Current Frame Movement Deltas -----------
+         * Deltas read on each frame by camera class in order to move the camera
+         * -----------------------------------
+         */
+        /**
+         * Zoom delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from zoomPixelDelta (taking speed into account)
+         */
+        this.zoomDeltaCurrentFrame = 0;
+        /**
+         * Pan delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from panPixelDelta (taking speed into account)
+         */
+        this.panDeltaCurrentFrame = Vector3.Zero();
+        /**
+         * Rotation delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from rotationPixelDelta (taking speed into account)
+         */
+        this.rotationDeltaCurrentFrame = Vector3.Zero();
+        /**
+         * ---------- Velocity -----------
+         * Used to track velocity between frames for inertia calculation
+         * -----------------------------------
+         */
+        /**
+         * Zoom velocity used for inertia calculations (movement / time)
+         */
+        this._zoomVelocity = 0;
+        /**
+         * Pan velocity used for inertia calculations (movement / time)
+         */
+        this._panVelocity = new Vector3();
+        /**
+         * Rotation velocity used for inertia calculations (movement / time)
+         */
+        this._rotationVelocity = new Vector3();
+        /**
+         * Used when calculating inertial decay. Default to 60fps
+         */
+        this._prevFrameTimeMs = FrameDurationAt60FPS;
+        this._scene = scene;
+    }
+    /**
+     * When called, will take the accumulated pixel deltas set by input classes and convert them into current frame deltas, stored in currentFrameMovementDelta properties
+     * Takes speed, scaling, inertia, and framerate into account to ensure smooth movement
+     * Zeros out pixelDeltas before returning
+     */
+    computeCurrentFrameDeltas() {
+        const deltaTimeMs = this._scene.getEngine().getDeltaTime();
+        this.panDeltaCurrentFrame.setAll(0);
+        this.rotationDeltaCurrentFrame.setAll(0);
+        this.zoomDeltaCurrentFrame = 0;
+        const hasUserInput = this.panAccumulatedPixels.lengthSquared() > 0 || this.rotationAccumulatedPixels.lengthSquared() > 0 || this.zoomAccumulatedPixels !== 0;
+        if (hasUserInput && this._behavior?.isInterpolating) {
+            this._behavior.stopAllAnimations();
+        }
+        this._panVelocity.copyFromFloats(this._calculateCurrentVelocity(this._panVelocity.x, this.panAccumulatedPixels.x, this.panSpeed * this._panSpeedMultiplier, this.panInertia), this._calculateCurrentVelocity(this._panVelocity.y, this.panAccumulatedPixels.y, this.panSpeed * this._panSpeedMultiplier, this.panInertia), this._calculateCurrentVelocity(this._panVelocity.z, this.panAccumulatedPixels.z, this.panSpeed * this._panSpeedMultiplier, this.panInertia));
+        this._panVelocity.scaleToRef(deltaTimeMs, this.panDeltaCurrentFrame);
+        this._rotationVelocity.copyFromFloats(this._calculateCurrentVelocity(this._rotationVelocity.x, this.rotationAccumulatedPixels.x, this.rotationXSpeed, this.rotationInertia), this._calculateCurrentVelocity(this._rotationVelocity.y, this.rotationAccumulatedPixels.y, this.rotationYSpeed, this.rotationInertia), this._calculateCurrentVelocity(this._rotationVelocity.z, this.rotationAccumulatedPixels.z, this.rotationYSpeed, this.rotationInertia));
+        this._rotationVelocity.scaleToRef(deltaTimeMs, this.rotationDeltaCurrentFrame);
+        this._zoomVelocity = this._calculateCurrentVelocity(this._zoomVelocity, this.zoomAccumulatedPixels, this.zoomSpeed * this._zoomSpeedMultiplier, this.zoomInertia);
+        this.zoomDeltaCurrentFrame = this._zoomVelocity * deltaTimeMs;
+        this._prevFrameTimeMs = deltaTimeMs;
+        this.zoomAccumulatedPixels = 0;
+        this.panAccumulatedPixels.setAll(0);
+        this.rotationAccumulatedPixels.setAll(0);
+    }
+    get isInterpolating() {
+        return !!this._behavior?.isInterpolating;
+    }
+    _calculateCurrentVelocity(velocityRef, pixelDelta, speedFactor, inertialDecayFactor) {
+        let inputVelocity = velocityRef;
+        const deltaTimeMs = this._scene.getEngine().getDeltaTime();
+        // If we are actively recieving input or have accumulated some pixel delta since last frame, calculate inputVelocity (inertia doesn't kickin yet)
+        if (pixelDelta !== 0 || this.activeInput) {
+            const pixelsPerMs = pixelDelta / deltaTimeMs;
+            inputVelocity = pixelsPerMs * speedFactor;
+        }
+        else if (!this.activeInput && inputVelocity !== 0) {
+            // If we are not receiving input and velocity isn't already zero, apply inertial decay to decelerate velocity
+            const frameIndependentDecay = Math.pow(inertialDecayFactor, this._prevFrameTimeMs / FrameDurationAt60FPS);
+            inputVelocity *= frameIndependentDecay;
+            if (Math.abs(inputVelocity) <= Epsilon) {
+                inputVelocity = 0;
+            }
+        }
+        return inputVelocity;
+    }
+}
+//# sourceMappingURL=cameraMovement.js.map

package/Cameras/cameraMovement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cameraMovement.js","sourceRoot":"","sources":["../../../../dev/core/src/Cameras/cameraMovement.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Scene } from \"../scene\";\r\nimport { Vector3 } from \"../Maths/math.vector\";\r\nimport { Epsilon } from \"../Maths/math.constants\";\r\nimport type { InterpolatingBehavior } from \"../Behaviors/Cameras/interpolatingBehavior\";\r\n\r\nconst FrameDurationAt60FPS = 1000 / 60;\r\n/**\r\n * @experimental\r\n * This class is subject to change as geospatial camera evolves.\r\n *\r\n * It is intended to hold all logic related to converting input pixel deltas into current frame deltas, taking speed / framerate into account\r\n * to ensure smooth frame-rate-independent movement\r\n */\r\nexport class CameraMovement {\r\n    protected _scene: Scene;\r\n\r\n    /**\r\n     * Should be set by input classes to indicates whether there is active input this frame\r\n     * This helps us differentiate between 0 pixel delta due to no input vs user actively holding still\r\n     */\r\n    public activeInput: boolean = false;\r\n\r\n    /**\r\n     * ------------ Speed ----------------\r\n     * Speed defines the amount of camera movement expected per input pixel movement\r\n     * -----------------------------------\r\n     */\r\n    /**\r\n     * Desired coordinate unit movement per input pixel when zooming\r\n     */\r\n    public zoomSpeed: number = 1;\r\n    /**\r\n     * Desired coordinate unit movement per input pixel when panning\r\n     */\r\n    public panSpeed: number = 1;\r\n    /**\r\n     * Desired radians movement per input pixel when rotating along x axis\r\n     */\r\n    public rotationXSpeed: number = 1;\r\n    /**\r\n     * Desired radians movement per input pixel when rotating along y axis\r\n     */\r\n    public rotationYSpeed: number = 1;\r\n\r\n    /**\r\n     * ----------- Speed multipliers ---------------\r\n     * Multipliers allow movement classes to modify the effective speed dynamically per-frame\r\n     * (ex: scale zoom based on distance from target)\r\n     * -----------------------------------\r\n     */\r\n    /**\r\n     * Multiplied atop zoom speed. Used to dynamically adjust zoom speed based on per-frame context (ex: zoom faster when further from target)\r\n     */\r\n    protected _zoomSpeedMultiplier: number = 1;\r\n    /**\r\n     * Multiplied atop pan speed. Used to dynamically adjust pan speed based on per-frame context (ex: pan slowly when close to target)\r\n     */\r\n    protected _panSpeedMultiplier: number = 1;\r\n\r\n    /**\r\n     * ---------- Inertia ----------------\r\n     * Inertia represents the decay factor per-frame applied to the velocity when there is no user input.\r\n     * 0 = No inertia, instant stop (velocity immediately becomes 0)\r\n     * 0.5 = Strong decay, velocity halves every frame at 60fps\r\n     * 0.9 = Moderate inertia, velocity retains 90% per frame at 60fps\r\n     * 0.95 = High inertia, smooth glide, velocity retains 95% per frame at 60fps\r\n     * 1 = Infinite inertia, never stops (velocity never decays)\r\n     * -----------------------------------\r\n     */\r\n    /**\r\n     * Inertia applied to the zoom velocity when there is no user input.\r\n     * Higher inertia === slower decay, velocity retains more of its value each frame\r\n     */\r\n    public zoomInertia: number = 0.9;\r\n    /**\r\n     * Inertia applied to the panning velocity when there is no user input.\r\n     * Higher inertia === slower decay, velocity retains more of its value each frame\r\n     */\r\n    public panInertia: number = 0.9;\r\n    /**\r\n     * Inertia applied to the rotation velocity when there is no user input.\r\n     * Higher inertia === slower decay, velocity retains more of its value each frame\r\n     */\r\n    public rotationInertia: number = 0.9;\r\n\r\n    /**\r\n     * ---------- Accumulated Pixel Deltas -----------\r\n     * Pixel inputs accumulated throughout the frame by input classes (reset each frame after processing)\r\n     * -----------------------------------\r\n     */\r\n    /**\r\n     * Accumulated pixel delta (by input classes) for zoom this frame\r\n     * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)\r\n     * Reset to zero after each frame\r\n     */\r\n    public zoomAccumulatedPixels: number = 0;\r\n    /**\r\n     * Accumulated pixel delta (by input classes) for panning this frame\r\n     * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)\r\n     * Reset to zero after each frame\r\n     */\r\n    public panAccumulatedPixels: Vector3 = new Vector3();\r\n    /**\r\n     * Accumulated pixel delta (by input classes) for rotation this frame\r\n     * Read by computeCurrentFrameDeltas() function and converted into currentFrameTranslationDelta (taking speed into account)\r\n     * Reset to zero after each frame\r\n     */\r\n    public rotationAccumulatedPixels: Vector3 = new Vector3();\r\n\r\n    /**\r\n     * ---------- Current Frame Movement Deltas -----------\r\n     * Deltas read on each frame by camera class in order to move the camera\r\n     * -----------------------------------\r\n     */\r\n    /**\r\n     * Zoom delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from zoomPixelDelta (taking speed into account)\r\n     */\r\n    public zoomDeltaCurrentFrame: number = 0;\r\n    /**\r\n     * Pan delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from panPixelDelta (taking speed into account)\r\n     */\r\n    public panDeltaCurrentFrame: Vector3 = Vector3.Zero();\r\n    /**\r\n     * Rotation delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from rotationPixelDelta (taking speed into account)\r\n     */\r\n    public rotationDeltaCurrentFrame: Vector3 = Vector3.Zero();\r\n\r\n    /**\r\n     * ---------- Velocity -----------\r\n     * Used to track velocity between frames for inertia calculation\r\n     * -----------------------------------\r\n     */\r\n    /**\r\n     * Zoom velocity used for inertia calculations (movement / time)\r\n     */\r\n    protected _zoomVelocity: number = 0;\r\n    /**\r\n     * Pan velocity used for inertia calculations (movement / time)\r\n     */\r\n    private _panVelocity: Vector3 = new Vector3();\r\n    /**\r\n     * Rotation velocity used for inertia calculations (movement / time)\r\n     */\r\n    private _rotationVelocity: Vector3 = new Vector3();\r\n\r\n    /**\r\n     * Used when calculating inertial decay. Default to 60fps\r\n     */\r\n    private _prevFrameTimeMs: number = FrameDurationAt60FPS;\r\n\r\n    constructor(\r\n        scene: Scene,\r\n        protected _cameraPosition: Vector3,\r\n        protected _behavior?: InterpolatingBehavior\r\n    ) {\r\n        this._scene = scene;\r\n    }\r\n\r\n    /**\r\n     * When called, will take the accumulated pixel deltas set by input classes and convert them into current frame deltas, stored in currentFrameMovementDelta properties\r\n     * Takes speed, scaling, inertia, and framerate into account to ensure smooth movement\r\n     * Zeros out pixelDeltas before returning\r\n     */\r\n    public computeCurrentFrameDeltas(): void {\r\n        const deltaTimeMs = this._scene.getEngine().getDeltaTime();\r\n\r\n        this.panDeltaCurrentFrame.setAll(0);\r\n        this.rotationDeltaCurrentFrame.setAll(0);\r\n        this.zoomDeltaCurrentFrame = 0;\r\n\r\n        const hasUserInput = this.panAccumulatedPixels.lengthSquared() > 0 || this.rotationAccumulatedPixels.lengthSquared() > 0 || this.zoomAccumulatedPixels !== 0;\r\n\r\n        if (hasUserInput && this._behavior?.isInterpolating) {\r\n            this._behavior.stopAllAnimations();\r\n        }\r\n\r\n        this._panVelocity.copyFromFloats(\r\n            this._calculateCurrentVelocity(this._panVelocity.x, this.panAccumulatedPixels.x, this.panSpeed * this._panSpeedMultiplier, this.panInertia),\r\n            this._calculateCurrentVelocity(this._panVelocity.y, this.panAccumulatedPixels.y, this.panSpeed * this._panSpeedMultiplier, this.panInertia),\r\n            this._calculateCurrentVelocity(this._panVelocity.z, this.panAccumulatedPixels.z, this.panSpeed * this._panSpeedMultiplier, this.panInertia)\r\n        );\r\n        this._panVelocity.scaleToRef(deltaTimeMs, this.panDeltaCurrentFrame);\r\n\r\n        this._rotationVelocity.copyFromFloats(\r\n            this._calculateCurrentVelocity(this._rotationVelocity.x, this.rotationAccumulatedPixels.x, this.rotationXSpeed, this.rotationInertia),\r\n            this._calculateCurrentVelocity(this._rotationVelocity.y, this.rotationAccumulatedPixels.y, this.rotationYSpeed, this.rotationInertia),\r\n            this._calculateCurrentVelocity(this._rotationVelocity.z, this.rotationAccumulatedPixels.z, this.rotationYSpeed, this.rotationInertia)\r\n        );\r\n        this._rotationVelocity.scaleToRef(deltaTimeMs, this.rotationDeltaCurrentFrame);\r\n\r\n        this._zoomVelocity = this._calculateCurrentVelocity(this._zoomVelocity, this.zoomAccumulatedPixels, this.zoomSpeed * this._zoomSpeedMultiplier, this.zoomInertia);\r\n        this.zoomDeltaCurrentFrame = this._zoomVelocity * deltaTimeMs;\r\n\r\n        this._prevFrameTimeMs = deltaTimeMs;\r\n        this.zoomAccumulatedPixels = 0;\r\n        this.panAccumulatedPixels.setAll(0);\r\n        this.rotationAccumulatedPixels.setAll(0);\r\n    }\r\n\r\n    public get isInterpolating(): boolean {\r\n        return !!this._behavior?.isInterpolating;\r\n    }\r\n\r\n    private _calculateCurrentVelocity(velocityRef: number, pixelDelta: number, speedFactor: number, inertialDecayFactor: number): number {\r\n        let inputVelocity = velocityRef;\r\n        const deltaTimeMs = this._scene.getEngine().getDeltaTime();\r\n\r\n        // If we are actively recieving input or have accumulated some pixel delta since last frame, calculate inputVelocity (inertia doesn't kickin yet)\r\n        if (pixelDelta !== 0 || this.activeInput) {\r\n            const pixelsPerMs = pixelDelta / deltaTimeMs;\r\n            inputVelocity = pixelsPerMs * speedFactor;\r\n        } else if (!this.activeInput && inputVelocity !== 0) {\r\n            // If we are not receiving input and velocity isn't already zero, apply inertial decay to decelerate velocity\r\n            const frameIndependentDecay = Math.pow(inertialDecayFactor, this._prevFrameTimeMs / FrameDurationAt60FPS);\r\n            inputVelocity *= frameIndependentDecay;\r\n            if (Math.abs(inputVelocity) <= Epsilon) {\r\n                inputVelocity = 0;\r\n            }\r\n        }\r\n\r\n        return inputVelocity;\r\n    }\r\n}\r\n"]}

package/Cameras/geospatialCamera.d.ts

@@ -3,85 +3,89 @@ import { Vector3, Matrix } from "../Maths/math.vector.js";
 import { Camera } from "./camera.js";
 import type { Scene } from "../scene.js";
 import type { MeshPredicate } from "../Culling/ray.core.js";
-import type { Nullable } from "../types.js";
+import { GeospatialLimits } from "./Limits/geospatialLimits.js";
+import { GeospatialCameraMovement } from "./geospatialCameraMovement.js";
+import type { IVector3Like } from "../Maths/math.like.js";
 type CameraOptions = {
     planetRadius: number;
-    minAltitude?: number;
-    maxAltitude?: number;
-    restingAltitude?: number;
 };
 /**
  * @experimental
  * This camera's movements are limited to a camera orbiting a globe, and as the API evolves it will introduce conversions between cartesian coordinates and true lat/long/alt
  *
  * Please note this is marked as experimental and the API (including the constructor!) will change until we remove that flag
- *
- * Still TODO:
- * - Pitch/yaw limits, input speeds
- * - ZoomToPoint
- * - Conversion between lat/long/alt and cartesian coordinates
  */
 export declare class GeospatialCamera extends Camera {
     inputs: GeospatialCameraInputsManager;
-    /** @internal */
-    _perFrameGeocentricTranslation: Vector3;
-    /** @internal */
-    _perFrameGeocentricRotation: Vector3;
-    /** @internal */
-    _perFrameZoom: number;
     /** If supplied, will be used when picking the globe */
     pickPredicate?: MeshPredicate;
-    /**
-     * Enables rotation around a specific point, instead of default rotation around center
-     * @internal
-     */
-    _alternateRotationPt: Nullable<Vector3>;
-    /** The point on the globe that we are anchoring around. If no alternate rotation point is supplied, this will represent the center of screen*/
-    get center(): Vector3;
-    private _tempGeocentricNormal;
-    private _tempRotationAxis;
-    private _tempRotationMatrix;
-    private _tempPickingRay;
+    /** Movement controller that turns input pixelDeltas into currentFrameDeltas used by camera*/
+    readonly movement: GeospatialCameraMovement;
     private _tempPosition;
     private _viewMatrix;
     private _isViewMatrixDirty;
     private _lookAtVector;
-    private _planetRadius;
-    private _minAltitude;
-    private _maxAltitude?;
-    private _maxCameraRadius?;
-    private _restingAltitude;
-    /** Target of camera when looking along lookAtVector from current position. This does not necessarily represent a point on the globe */
-    private get _target();
+    constructor(name: string, scene: Scene, options: CameraOptions, pickPredicate?: MeshPredicate);
+    private _center;
+    /** The point on the globe that we are anchoring around. If no alternate rotation point is present, this will represent the center of screen*/
+    get center(): Vector3;
+    /**
+     * Sets the camera position to orbit around a new center point
+     * @param center The world position (ECEF) to orbit around
+     */
+    set center(center: IVector3Like);
+    private _yaw;
+    /**
+     * Gets the camera's yaw (rotation around the geocentric normal) in radians
+     */
+    get yaw(): number;
+    /**
+     * Sets the camera's yaw (rotation around the geocentric normal)
+     * @param yaw The desired yaw angle in radians (0 = north, π/2 = east)
+     */
+    set yaw(yaw: number);
+    private _pitch;
+    /**
+     * Gets the camera's pitch (angle from looking straight at globe)
+     * Pitch is measured from looking straight down at planet center:
+     * - zero pitch = looking straight at planet center (down)
+     * - positive pitch = tilting up away from planet
+     * - π/2 pitch = looking at horizon (perpendicular to geocentric normal)
+     */
+    get pitch(): number;
+    /**
+     * Sets the camera's pitch (angle from looking straight at globe)
+     * @param pitch The desired pitch angle in radians (0 = looking at planet center, π/2 = looking at horizon)
+     */
+    set pitch(pitch: number);
+    private _radius;
+    get radius(): number;
+    /**
+     * Sets the camera's distance from the current center point
+     * @param radius The desired radius
+     */
+    set radius(radius: number);
+    protected _checkLimits(): void;
+    private _tempVect;
+    private _tempEast;
+    private _tempNorth;
+    private _tempUp;
+    private _setOrientation;
     /** The point around which the camera will geocentrically rotate. Uses center (pt we are anchored to) if no alternateRotationPt is defined */
     private get _geocentricRotationPt();
-    constructor(name: string, scene: Scene, options: CameraOptions, pickPredicate?: MeshPredicate);
+    private _limits;
+    get limits(): GeospatialLimits;
     private _resetToDefault;
     /** @internal */
     _getViewMatrix(): Matrix;
     /** @internal */
     _isSynchronizedViewMatrix(): boolean;
-    /**
-     * Applies rotation correction to the camera by calculating a changeOfBasis matrix from the camera's current position to the new position
-     * and transforming the lookAt and up vectors by that matrix before updating the camera position and marking the view matrix as dirty
-     * @param newPos The camera's desired position, before correction is applied
-     */
-    private _applyRotationCorrectionAndSetPos;
-    /**
-     * When the geocentric normal has any translation change (due to dragging), we must ensure the camera remains orbiting around the world origin
-     * We thus need to perform 2 correction steps
-     * 1. Translation correction that keeps the camera at the same radius as before the drag
-     * 2. Rotation correction that keeps the camera facing the globe (so that as we pan, the globe stays centered on screen)
-     */
     private _applyGeocentricTranslation;
     /**
      * This rotation keeps the camera oriented towards the globe as it orbits around it. This is different from cameraCentricRotation which is when the camera rotates around its own axis
      */
     private _applyGeocentricRotation;
-    private _clampZoomDistance;
     private _applyZoom;
-    private _moveCameraAlongVectorByDistance;
-    private get _pickAlongLook();
     _checkInputs(): void;
     attachControl(noPreventDefault?: boolean): void;
     detachControl(): void;