improve fitToBox function with optional "lock to axis" argument

Author: Matthew Oxley

dist/CameraControls.d.ts

@@ -89,7 +89,7 @@ export declare class CameraControls extends EventDispatcher {
     truck(x: number, y: number, enableTransition?: boolean): Promise<void>;
     forward(distance: number, enableTransition?: boolean): Promise<void>;
     moveTo(x: number, y: number, z: number, enableTransition?: boolean): Promise<void>;
-    fitToBox(box3OrObject: _THREE.Box3 | _THREE.Object3D, enableTransition: boolean, { paddingLeft, paddingRight, paddingBottom, paddingTop }?: Partial<FitToOptions>): Promise<void[]>;
+    fitToBox(box3OrObject: _THREE.Box3 | _THREE.Object3D, enableTransition: boolean, { paddingLeft, paddingRight, paddingBottom, paddingTop }?: Partial<FitToOptions>, lock?: "front" | "back"): Promise<void[]>;
     fitTo(box3OrObject: _THREE.Box3 | _THREE.Object3D, enableTransition: boolean, fitToOptions?: Partial<FitToOptions>): Promise<void[]>;
     fitToSphere(sphereOrMesh: _THREE.Sphere | _THREE.Object3D, enableTransition: boolean): Promise<void[]>;
     setLookAt(positionX: number, positionY: number, positionZ: number, targetX: number, targetY: number, targetZ: number, enableTransition?: boolean): Promise<void>;

dist/camera-controls.js

@@ -966,7 +966,7 @@
 	                approxEquals(this._target.z, this._targetEnd.z, this.restThreshold);
 	        return this._createOnRestPromise(resolveImmediately);
 	    };
-	    CameraControls.prototype.fitToBox = function (box3OrObject, enableTransition, _a) {
+	    CameraControls.prototype.fitToBox = function (box3OrObject, enableTransition, _a, lock) {
 	        var _b = _a === void 0 ? {} : _a, _c = _b.paddingLeft, paddingLeft = _c === void 0 ? 0 : _c, _d = _b.paddingRight, paddingRight = _d === void 0 ? 0 : _d, _e = _b.paddingBottom, paddingBottom = _e === void 0 ? 0 : _e, _f = _b.paddingTop, paddingTop = _f === void 0 ? 0 : _f;
 	        var promises = [];
 	        var aabb = box3OrObject.isBox3
@@ -976,8 +976,16 @@
 	            console.warn('camera-controls: fitTo() cannot be used with an empty box. Aborting');
 	            Promise.resolve();
 	        }
-	        var theta = roundToStep(this._sphericalEnd.theta, PI_HALF);
-	        var phi = roundToStep(this._sphericalEnd.phi, PI_HALF);
+	        var theta;
+	        var phi;
+	        if (!lock) {
+	            theta = roundToStep(this._sphericalEnd.theta, PI_HALF);
+	            phi = roundToStep(this._sphericalEnd.phi, PI_HALF);
+	        }
+	        else {
+	            theta = lock === "front" ? 0 : Math.PI;
+	            phi = lock === "front" ? 0 : Math.PI;
+	        }
 	        promises.push(this.rotateTo(theta, phi, enableTransition));
 	        var normal = _v3A.setFromSpherical(this._sphericalEnd).normalize();
 	        var rotation = _quaternionA.setFromUnitVectors(normal, _AXIS_Z);

dist/camera-controls.min.js

@@ -960,7 +960,7 @@ var CameraControls = (function (_super) {
                 approxEquals(this._target.z, this._targetEnd.z, this.restThreshold);
         return this._createOnRestPromise(resolveImmediately);
     };
-    CameraControls.prototype.fitToBox = function (box3OrObject, enableTransition, _a) {
+    CameraControls.prototype.fitToBox = function (box3OrObject, enableTransition, _a, lock) {
         var _b = _a === void 0 ? {} : _a, _c = _b.paddingLeft, paddingLeft = _c === void 0 ? 0 : _c, _d = _b.paddingRight, paddingRight = _d === void 0 ? 0 : _d, _e = _b.paddingBottom, paddingBottom = _e === void 0 ? 0 : _e, _f = _b.paddingTop, paddingTop = _f === void 0 ? 0 : _f;
         var promises = [];
         var aabb = box3OrObject.isBox3
@@ -970,8 +970,16 @@ var CameraControls = (function (_super) {
             console.warn('camera-controls: fitTo() cannot be used with an empty box. Aborting');
             Promise.resolve();
         }
-        var theta = roundToStep(this._sphericalEnd.theta, PI_HALF);
-        var phi = roundToStep(this._sphericalEnd.phi, PI_HALF);
+        var theta;
+        var phi;
+        if (!lock) {
+            theta = roundToStep(this._sphericalEnd.theta, PI_HALF);
+            phi = roundToStep(this._sphericalEnd.phi, PI_HALF);
+        }
+        else {
+            theta = lock === "front" ? 0 : Math.PI;
+            phi = lock === "front" ? 0 : Math.PI;
+        }
         promises.push(this.rotateTo(theta, phi, enableTransition));
         var normal = _v3A.setFromSpherical(this._sphericalEnd).normalize();
         var rotation = _quaternionA.setFromUnitVectors(normal, _AXIS_Z);

dist/camera-controls.module.js

@@ -1280,7 +1280,7 @@ export class CameraControls extends EventDispatcher {
 		paddingRight = 0,
 		paddingBottom = 0,
 		paddingTop = 0
-	}: Partial<FitToOptions> = {} ): Promise<void[]> {
+	}: Partial<FitToOptions> = {}, lock?: "front" | "back" ): Promise<void[]> {
 
 		const promises = [];
 		const aabb = ( box3OrObject as _THREE.Box3 ).isBox3
@@ -1295,8 +1295,15 @@ export class CameraControls extends EventDispatcher {
 		}
 
 		// round to closest axis ( forward | backward | right | left | top | bottom )
-		const theta = roundToStep( this._sphericalEnd.theta, PI_HALF );
-		const phi   = roundToStep( this._sphericalEnd.phi,   PI_HALF );
+        let theta;
+        let phi;
+        if (!lock) {
+            theta = roundToStep( this._sphericalEnd.theta, PI_HALF );
+		    phi   = roundToStep( this._sphericalEnd.phi,   PI_HALF );
+        } else {
+            theta = lock === "front" ? 0 : Math.PI;
+            phi = lock === "front" ? 0 : Math.PI;
+        }
 
 		promises.push( this.rotateTo( theta, phi, enableTransition ) );