feat: cameraControls.lerp position or spherical (#586)

* CameraControls.lerp
* return type
* undeprecate

Author: abernier

examples/basic.html

@@ -38,7 +38,8 @@
 	<button onclick="cameraControls.normalizeRotations().setTarget( 3, 0, -3, true )">look at ( 3, 0, -3 )</button>
 	<button onclick="cameraControls.normalizeRotations().setLookAt( 1, 2, 3, 1, 1, 0, true )">move to ( 1, 2, 3 ), look at ( 1, 1, 0 )</button>
 	<br>
-	<button onclick="cameraControls.normalizeRotations().lerpLookAt( - 2, 0, 0, 1, 1, 0, 0, 2, 5, - 1, 0, 0, Math.random(), true )">move to somewhere between ( -2, 0, 0 ) -> ( 1, 1, 0 ) and ( 0, 2, 5 ) -> ( -1, 0, 0 )</button>
+	<button onclick="cameraControls.normalizeRotations().lerp( { target: [1, 1, 0], position: [ - 2, 0, 0 ] }, { target: [ -1, 0, 0 ], position: [ 0, 2, 5]}, Math.random(), true )">move to somewhere between position/target: ( -2, 0, 0 ) -> ( 1, 1, 0 ) and ( 0, 2, 5 ) -> ( -1, 0, 0 )</button>
+	<button onclick="cameraControls.lerp( { target: [ 1, 1, 0 ], spherical: [ 2, 0, -Math.PI/2 ]}, { target: [ -1, 0, 0 ], spherical: [ 7, Math.PI, Math.PI/2 ]}, Math.random(), true )">move to somewhere inside a hemisphere of a radius ∈ [2..7] centered at a point located between ( 1, 1, 0 ) and ( -1, 0, 0 )</button>
 	<br>
 	<button onclick="cameraControls.normalizeRotations().reset( true )">reset</button>
 	<button onclick="cameraControls.saveState()">saveState</button>

src/CameraControls.ts

@@ -12,6 +12,7 @@ import {
 	CameraControlsEventMap,
 	isPerspectiveCamera,
 	isOrthographicCamera,
+	CameraControlsLerpState,
 } from './types';
 import {
 	PI_2,
@@ -2111,28 +2112,16 @@ export class CameraControls extends EventDispatcher {
 	}
 
 	/**
-	 * Similar to setLookAt, but it interpolates between two states.
-	 * @param positionAX
-	 * @param positionAY
-	 * @param positionAZ
-	 * @param targetAX
-	 * @param targetAY
-	 * @param targetAZ
-	 * @param positionBX
-	 * @param positionBY
-	 * @param positionBZ
-	 * @param targetBX
-	 * @param targetBY
-	 * @param targetBZ
+	 * Interpolates between two states.
+	 * @param stateA
+	 * @param stateB
 	 * @param t
 	 * @param enableTransition
 	 * @category Methods
 	 */
-	lerpLookAt(
-		positionAX: number, positionAY: number, positionAZ: number,
-		targetAX: number, targetAY: number, targetAZ: number,
-		positionBX: number, positionBY: number, positionBZ: number,
-		targetBX: number, targetBY: number, targetBZ: number,
+	lerp(
+		stateA: CameraControlsLerpState,
+		stateB: CameraControlsLerpState,
 		t: number,
 		enableTransition: boolean = false,
 	): Promise<void> {
@@ -2143,13 +2132,29 @@ export class CameraControls extends EventDispatcher {
 		this._lastDollyDirection = DOLLY_DIRECTION.NONE;
 		this._changedDolly = 0;
 
-		const targetA = _v3A.set( targetAX, targetAY, targetAZ );
-		const positionA = _v3B.set( positionAX, positionAY, positionAZ );
-		_sphericalA.setFromVector3( positionA.sub( targetA ).applyQuaternion( this._yAxisUpSpace ) );
+		const targetA = _v3A.set( ...stateA.target );
+		if ( 'spherical' in stateA ) {
+
+			_sphericalA.set( ...stateA.spherical );
+
+		} else {
+
+			const positionA = _v3B.set( ...stateA.position );
+			_sphericalA.setFromVector3( positionA.sub( targetA ).applyQuaternion( this._yAxisUpSpace ) );
+
+		}
+
+		const targetB = _v3C.set( ...stateB.target );
+		if ( 'spherical' in stateB ) {
+
+			_sphericalB.set( ...stateB.spherical );
+
+		} else {
+
+			const positionB = _v3B.set( ...stateB.position );
+			_sphericalB.setFromVector3( positionB.sub( targetB ).applyQuaternion( this._yAxisUpSpace ) );
 
-		const targetB = _v3C.set( targetBX, targetBY, targetBZ );
-		const positionB = _v3B.set( positionBX, positionBY, positionBZ );
-		_sphericalB.setFromVector3( positionB.sub( targetB ).applyQuaternion( this._yAxisUpSpace ) );
+		}
 
 		this._targetEnd.copy( targetA.lerp( targetB, t ) ); // tricky
 
@@ -2183,6 +2188,49 @@ export class CameraControls extends EventDispatcher {
 
 	}
 
+	/**
+	 * Similar to setLookAt, but it interpolates between two states.
+	 * @param positionAX
+	 * @param positionAY
+	 * @param positionAZ
+	 * @param targetAX
+	 * @param targetAY
+	 * @param targetAZ
+	 * @param positionBX
+	 * @param positionBY
+	 * @param positionBZ
+	 * @param targetBX
+	 * @param targetBY
+	 * @param targetBZ
+	 * @param t
+	 * @param enableTransition
+	 * @category Methods
+	 */
+	lerpLookAt(
+		positionAX: number, positionAY: number, positionAZ: number,
+		targetAX: number, targetAY: number, targetAZ: number,
+		positionBX: number, positionBY: number, positionBZ: number,
+		targetBX: number, targetBY: number, targetBZ: number,
+		t: number,
+		enableTransition: boolean = false,
+	): Promise<void> {
+
+		return this.lerp(
+			{
+				position: [ positionAX, positionAY, positionAZ ],
+				target: [ targetAX, targetAY, targetAZ ],
+			},
+			{
+				position: [ positionBX, positionBY, positionBZ ],
+				target: [ targetBX, targetBY, targetBZ ],
+			},
+			t,
+			enableTransition,
+
+		);
+
+	}
+
 	/**
 	 * Set angle and distance by given position.
 	 * An alias of `setLookAt()`, without target change. Thus keep gazing at the current target

src/types.ts

@@ -137,3 +137,11 @@ export function isOrthographicCamera( camera: _THREE.Camera ): camera is _THREE.
 	return ( camera as _THREE.OrthographicCamera  ).isOrthographicCamera;
 
 }
+
+export type CameraControlsLerpState = {
+	target: [number, number, number]
+} & ( {
+	spherical: Parameters<_THREE.Spherical["set"]>
+} | {
+	position: [number, number, number]
+} );