@combeenation/3d-viewer 4.0.1-alpha1 → 4.2.0

package/src/api/classes/viewer.ts

@@ -276,7 +276,7 @@ export class Viewer extends EventBroadcaster {
 		if( this.scene.meshes.length === 0 ) {
 			throw new Error( 'There are currently no meshes on the scene.' );
 		}
-		this.scene.render();  // XXX: workaround for BoundingBox not respecting render loop
+		this.scene.render();  // CB-6062: workaround for BoundingBox not respecting render loop
 		const bbName = '__bounding_box__';
 		
 		const { max, min } = this.scene.meshes.filter( mesh => {
@@ -302,57 +302,26 @@ export class Viewer extends EventBroadcaster {
 		return boundingBox;
 	}
 
-	/**
-	 * Focuses the camera to see every visible mesh in scene and tries to optimize wheel precision and panning.
-	 */
 	public async autofocusActiveCamera( settings?: AutofocusSettings ) {
+		// first check some preconditions
 		const activeCamera = this.scene.activeCamera;
-		if( !activeCamera ) {
-			throw new Error( 'No active camera found when using autofocus feature.' );
+		if ( !activeCamera ) {
+			throw new Error("No active camera found when using autofocus feature.");
 		}
-		if( activeCamera instanceof ArcRotateCamera ) {
-			// calculate some values
-			const boundingBox = await this.calculateBoundingBox();
-			const size = boundingBox.getBoundingInfo().maximum.subtract( boundingBox.getBoundingInfo().minimum );
-			let radius = size.length() * (settings?.radiusFactor ?? 1.5);
-			if( !isFinite( radius ) ) {
-				radius = 1;
-			}
-			// use helper camera to get some default values
-			const helperCamera = new ArcRotateCamera(
-				'__helper_camera__',
-				Math.PI / -2,
-				Math.PI / 2,
-				radius,
-				Vector3.Zero(),
-				this.scene
-			);
-			helperCamera.useFramingBehavior = true;
-			helperCamera.setTarget( boundingBox );
-			// translate values from helper to active camera
-			activeCamera.setTarget( Mesh.Center( [boundingBox] ) );
-			activeCamera.alpha = helperCamera.alpha;
-			activeCamera.beta = helperCamera.beta;
-			activeCamera.minZ = helperCamera.minZ;
-			activeCamera.maxZ = helperCamera.maxZ;
-			activeCamera.radius = helperCamera.radius;
-			activeCamera.lowerRadiusLimit = helperCamera.lowerRadiusLimit;
-			activeCamera.upperRadiusLimit = helperCamera.upperRadiusLimit;
-			if( settings?.adjustWheelPrecision !== false ) {
-				activeCamera.wheelPrecision = helperCamera.wheelPrecision;
-			}
-			if( settings?.adjustPanningSensibility !== false ) {
-				activeCamera.panningSensibility = helperCamera.panningSensibility;
-			}
-			if( settings?.adjustPinchPrecision !== false ) {
-				activeCamera.pinchPrecision = helperCamera.pinchPrecision;
-			}
-			// remove the helper camera
-			helperCamera.dispose();
-		} else {
+		if ( !( activeCamera instanceof ArcRotateCamera ) ) {
 			const cameraClsName = activeCamera.getClassName();
 			throw new Error( `Camera of type "${cameraClsName}" is not implemented yet to use autofocus feature.` );
 		}
+
+		// get bounding box of all visible meshes, this is the base for the autofocus algorithm
+		const boundingBox = await this.calculateBoundingBox();
+
+		// focus the helper camera and set the calculated camera data to the real camera
+		const helperCamera = this.getFocusedHelperCamera( boundingBox, settings )
+		await this.applyFocusedHelperCameraData( activeCamera, helperCamera, settings )
+
+		// remove the helper camera
+		helperCamera.dispose();
 	}
 
 	/**
@@ -485,4 +454,72 @@ export class Viewer extends EventBroadcaster {
 		return instances;
 	}
 
+	/**
+	 * Help function for focusing a helper camera exactly onto the given bounding box
+	 */
+	private getFocusedHelperCamera(boundingBox: Mesh, settings?: AutofocusSettings): ArcRotateCamera {
+		// use helper camera to get some default values and set the values of the real camera accordingly
+		const helperCamera = new ArcRotateCamera(
+			"__helper_camera__",
+			0, // camera angles will be overwritten after the target has been set
+			0,
+			0, // radius will be calculated, so we can set to 0 here
+			Vector3.Zero(),
+			this.scene
+		);
+		// this is required for automatically calculating the `lowerRadiusLimit`, so that we don't "dive" into meshes
+		// see https://doc.babylonjs.com/divingDeeper/behaviors/cameraBehaviors#framing-behavior
+		helperCamera.useFramingBehavior = true;
+
+		// `minZ` is the camera distance beyond which the mesh will be clipped
+		// this should be very low, but can't be zero
+		// a good value seems to be 1% of the bounding box size (= radius), whereas the value shouldn't go above 1, which is also the default value
+		const radius = boundingBox.getBoundingInfo().boundingSphere.radius;
+		helperCamera.minZ = Math.min(radius/100, 1);
+
+		// set desired camera data, these won't be changed by the autofocus function!
+		// default values should focus the element exactly from the front (= XY Plane)
+		helperCamera.setTarget(boundingBox, true);
+		helperCamera.alpha = ( settings?.alpha ?? - 90 ) * ( Math.PI / 180 );
+		helperCamera.beta = ( settings?.beta ?? 90 ) * ( Math.PI / 180 );
+
+		// finally zoom to the bounding box
+		// also apply a zoom factor, this adjusts the borders around the model in the viewport
+		helperCamera.zoomOnFactor = settings?.radiusFactor || 1;
+		helperCamera.zoomOn( [boundingBox], true );
+
+		return helperCamera;
+	}
+
+	/**
+	 * Help function for applying the relevant data of the focused helper camera to the real camera
+	 */
+	private async applyFocusedHelperCameraData(activeCamera: ArcRotateCamera, helperCamera: ArcRotateCamera, settings?: AutofocusSettings) {
+		// limits
+		activeCamera.minZ = helperCamera.minZ;
+		activeCamera.maxZ = helperCamera.maxZ;
+		activeCamera.lowerRadiusLimit = helperCamera.lowerRadiusLimit;
+		activeCamera.upperRadiusLimit = helperCamera.upperRadiusLimit;
+
+		// additional settings
+		if( settings?.adjustWheelPrecision !== false ) {
+			activeCamera.wheelPrecision = helperCamera.wheelPrecision;
+		}
+		if( settings?.adjustPanningSensibility !== false ) {
+			activeCamera.panningSensibility = helperCamera.panningSensibility;
+		}
+		if( settings?.adjustPinchPrecision !== false ) {
+			activeCamera.pinchPrecision = helperCamera.pinchPrecision;
+		}
+
+		// finally move the camera
+		// do this at last, so that all camera settings are already considered
+		const newCameraPosition: PlacementDefinition = {
+			alpha: helperCamera.alpha,
+			beta: helperCamera.beta,
+			radius: helperCamera.radius,
+			target: helperCamera.target
+		}
+		await this.animationManager.animateToPlacement(activeCamera, newCameraPosition, settings?.animation)
+	}
 }

package/src/api/classes/viewerLight.ts

@@ -14,8 +14,7 @@ import {
 	enableNodeWithParents,
 	getRootNode,
 	injectNodeMetadata,
-	moveTransformNode,
-	rotateTransformNode
+	transformTransformNode
 } from './../util/babylonHelper';
 import { DottedPath } from './dottedPath';
 import { Parameter } from './parameter';
@@ -128,37 +127,42 @@ export class ViewerLight extends VariantParameterizable {
 				set( light.light, 'intensity', Parameter.parseNumber( newValue ) );
 			}
 		] );
-		this._parameterObservers.set( Parameter.POSITION, [
+		this._parameterObservers.set( Parameter.SCALING, [
 			async ( light: ViewerLight, oldValue: ParameterValue, newValue: ParameterValue ) => {
 				// we have to deal just with root nodes here due to relative impacts in a node tree
 				const rootNode = getRootNode( light.light );
 				if( rootNode instanceof TransformNode ) {
-					moveTransformNode( rootNode, Parameter.parseVector( newValue ) );
+					transformTransformNode( rootNode, {
+						scaling: Parameter.parseScaling( newValue ),
+						position: Parameter.parseVector( light.inheritedParameters[Parameter.POSITION] || '(0, 0, 0)' ),
+						rotation: Parameter.parseRotation( light.inheritedParameters[Parameter.ROTATION] || '(0, 0, 0)' )
+					} );
 				}
 			}
 		] );
-		this._parameterObservers.set( Parameter.ROTATION, [
+		this._parameterObservers.set( Parameter.POSITION, [
 			async ( light: ViewerLight, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				// The current implementation (rotating around coordinates 0,0,0) implicitly mutates the position of a node.
-				// Since a user expects the rotation after the positioning, we have to manually fire the position observers.
-				// Without calling these observers, the pivot and the position of a node is initially the same before rotating,
-				// so there is no rotation happening at all.
-				if( Parameter.POSITION in light.inheritedParameters ) {
-					await light.commitParameter( Parameter.POSITION, light.inheritedParameters[Parameter.POSITION] );
-				}
 				// we have to deal just with root nodes here due to relative impacts in a node tree
 				const rootNode = getRootNode( light.light );
 				if( rootNode instanceof TransformNode ) {
-					rotateTransformNode( rootNode, Parameter.parseRotation( newValue ) );
+					transformTransformNode( rootNode, {
+						scaling: Parameter.parseVector( light.inheritedParameters[Parameter.SCALING] || '(1, 1, 1)' ),
+						position: Parameter.parseVector( newValue ),
+						rotation: Parameter.parseRotation( light.inheritedParameters[Parameter.ROTATION] || '(0, 0, 0)' )
+					} );
 				}
 			}
 		] );
-		this._parameterObservers.set( Parameter.SCALING, [
+		this._parameterObservers.set( Parameter.ROTATION, [
 			async ( light: ViewerLight, oldValue: ParameterValue, newValue: ParameterValue ) => {
 				// we have to deal just with root nodes here due to relative impacts in a node tree
 				const rootNode = getRootNode( light.light );
 				if( rootNode instanceof TransformNode ) {
-					rootNode.scaling = Parameter.parseScaling( newValue );
+					transformTransformNode( rootNode, {
+						scaling: Parameter.parseVector( light.inheritedParameters[Parameter.SCALING] || '(1, 1, 1)' ),
+						position: Parameter.parseVector( light.inheritedParameters[Parameter.POSITION] || '(0, 0, 0)' ),
+						rotation: Parameter.parseRotation( newValue )
+					} );
 				}
 			}
 		] );

package/src/api/util/babylonHelper.ts

@@ -216,13 +216,24 @@ const disableNodeWithParents = function( node: Node ) {
 };
 
 /**
- * Attention: this function mutates the position of a node. Keep in mind that there are dependencies to other
- * functions moving nodes around.
+ * Applies a {@link TransformationDefinition} consecutively to ensure dependencies in positioning etc.
  * @param node
- * @param rotation
+ * @param transformation
  */
-const rotateTransformNode = function( node: TransformNode, rotation: Vector3 ): TransformNode {
-	// remember absolute rotation and reset it before translating
+const transformTransformNode = function( node: TransformNode, transformation: TransformationDefinition ) {
+	// scaling
+	if( !has( node.metadata, 'scaling.initial' ) ) {
+		injectNodeMetadata( node, { 'scaling.initial': node.scaling }, false );
+	}
+	const initialScaling = get( node.metadata, 'scaling.initial' ) as Vector3;
+	node.scaling = initialScaling.multiply( transformation.scaling );
+	// position
+	if( !has( node.metadata, 'position.initial' ) ) {
+		injectNodeMetadata( node, { 'position.initial': node.absolutePosition.clone() }, false );
+	}
+	const initialPosition = get( node.metadata, 'position.initial' ) as Vector3;
+	node.setAbsolutePosition( initialPosition.add( transformation.position ).multiply( transformation.scaling ) );
+	// rotation
 	if( !has( node.metadata, 'rotation.initial' ) ) {
 		let rotationQuaternion = node.rotationQuaternion;
 		if( !rotationQuaternion ) {
@@ -230,43 +241,12 @@ const rotateTransformNode = function( node: TransformNode, rotation: Vector3 ):
 		}
 		injectNodeMetadata( node, { 'rotation.initial': rotationQuaternion.asArray() }, false );
 	}
-	if( !has( node.metadata, 'rotation.position' ) || get( node.metadata, 'position.dirty' ) ) {
-		let rotationPosition = node.absolutePosition.clone();
-		if( has( node.metadata, 'rotation.offset' ) ) {
-			rotationPosition = rotationPosition.subtract( get( node.metadata, 'rotation.offset' ) as Vector3 );
-		}
-		injectNodeMetadata( node, { 'rotation.position': rotationPosition }, false );
-		injectNodeMetadata( node, { 'position.dirty': false }, false );
-	}
-	node.setAbsolutePosition( get( node.metadata, 'rotation.position' ) );
-	node.rotationQuaternion = Quaternion.FromArray( get( node.metadata, 'rotation.initial' ) as [] );
-	node.rotateAround( Vector3.Zero(), Axis.X, rotation.x );
-	node.rotateAround( Vector3.Zero(), Axis.Y, rotation.y );
-	node.rotateAround( Vector3.Zero(), Axis.Z, rotation.z );
+	const initialRotationQuaternion = Quaternion.FromArray( get( node.metadata, 'rotation.initial' ) as [] );
+	node.rotationQuaternion = initialRotationQuaternion;
+	node.rotateAround( Vector3.Zero(), Axis.X, transformation.rotation.x );
+	node.rotateAround( Vector3.Zero(), Axis.Y, transformation.rotation.y );
+	node.rotateAround( Vector3.Zero(), Axis.Z, transformation.rotation.z );
 	node.computeWorldMatrix( true );
-	const rotationOffset = node.absolutePosition.subtract( get( node.metadata, 'rotation.position' ) as Vector3 );
-	injectNodeMetadata( node, { 'rotation.offset': rotationOffset }, false );
-	return node;
-};
-
-/**
- * Attention: this function mutates the position of a node. Keep in mind that there are dependencies to other
- * functions moving nodes around.
- * @param node
- * @param distance
- */
-const moveTransformNode = function( node: TransformNode, distance: Vector3 ): TransformNode {
-	// remember absolute position and reset it before translating
-	if( !has( node.metadata, 'position.initial' ) ) {
-		injectNodeMetadata( node, { 'position.initial': node.absolutePosition.clone() }, false );
-	}
-	let position = get( node.metadata, 'position.initial' ) as Vector3;
-	if( has( node.metadata, 'rotation.offset' ) ) {
-		position = position.add( get( node.metadata, 'rotation.offset' ) as Vector3 );
-	}
-	node.setAbsolutePosition( position.add( distance ) );
-	injectNodeMetadata( node, { 'position.dirty': true }, false );
-	return node;
 };
 
 /**
@@ -538,8 +518,7 @@ export {
 	deactivateTransformNode,
 	enableNodeWithParents,
 	disableNodeWithParents,
-	rotateTransformNode,
-	moveTransformNode,
+	transformTransformNode,
 	setMaterial,
 	setSourceNodeMaterial,
 	setMaterialColor,

package/src/api/util/globalTypes.ts

@@ -79,6 +79,12 @@ type ElementDefinition = {
 	paintables?: PaintableDefinitions
 };
 
+type TransformationDefinition = {
+	scaling: Vector3,
+	position: Vector3,
+	rotation: Vector3
+};
+
 type StructureJson = {
 	/**
 	 * `scene` describes the visualisation of the Babylon `scene` such as the incidence of light and camera position. If a
@@ -227,7 +233,13 @@ type AutofocusSettings = {
 	radiusFactor?: number,
 	adjustWheelPrecision?: boolean,
 	adjustPanningSensibility?: boolean,
-	adjustPinchPrecision?: boolean
+	adjustPinchPrecision?: boolean,
+	/** Desired horizontal camera angle, this won't be overwritten by the autofocus function */
+	alpha?: number;
+	/** Desired vertical camera angle, this won't be overwritten by the autofocus function */
+	beta?: number;
+	/** Optional animation for the focusing camera movement */
+	animation?: string | AnimationDefinition
 };
 
 type LightDefinitions = {

package/src/pagesconfig.json

@@ -40,11 +40,15 @@
         },
         {
           "title": "ViewerLights",
-          "source": "./doc/ViewerLights.md"
+          "source": "./doc/documentation/ViewerLights.md"
         },
         {
           "title": "Paintables",
           "source": "./doc/documentation/Paintables.md"
+        },
+        {
+          "title": "Transformation Parameters",
+          "source": "./doc/documentation/Transformation-Parameters.md"
         }
       ]
     },