@plastic-software/three 0.182.0 → 0.183.0

package/examples/jsm/helpers/AnimationPathHelper.js

@@ -0,0 +1,302 @@
+import {
+	BufferGeometry,
+	Float32BufferAttribute,
+	Line,
+	LineBasicMaterial,
+	Object3D,
+	Points,
+	PointsMaterial
+} from 'three';
+
+/**
+ * Visualizes the motion path of an animated object based on position keyframes
+ * from an AnimationClip.
+ *
+ * ```js
+ * const clip = model.animations[ 0 ];
+ * const helper = new AnimationPathHelper( model, clip, object );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments Object3D
+ * @three_import import { AnimationPathHelper } from 'three/addons/helpers/AnimationPathHelper.js';
+ */
+class AnimationPathHelper extends Object3D {
+
+	/**
+	 * Constructs a new animation path helper.
+	 *
+	 * @param {Object3D} root - The root object containing the animation clips.
+	 * @param {AnimationClip} clip - The animation clip containing position keyframes.
+	 * @param {Object3D} object - The specific object to show the path for.
+	 * @param {Object} [options={}] - Configuration options.
+	 * @param {number|Color|string} [options.color=0x00ff00] - The path line color.
+	 * @param {number|Color|string} [options.markerColor=0xff0000] - The keyframe marker color.
+	 * @param {number} [options.divisions=100] - Number of samples for smooth path interpolation.
+	 * @param {boolean} [options.showMarkers=true] - Whether to show markers at keyframe positions.
+	 * @param {number} [options.markerSize=5] - Size of keyframe markers in pixels.
+	 */
+	constructor( root, clip, object, options = {} ) {
+
+		super();
+
+		const {
+			color = 0x00ff00,
+			markerColor = 0xff0000,
+			divisions = 100,
+			showMarkers = true,
+			markerSize = 5
+		} = options;
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isAnimationPathHelper = true;
+
+		this.type = 'AnimationPathHelper';
+
+		/**
+		 * The root object containing the animation clips.
+		 *
+		 * @type {Object3D}
+		 */
+		this.root = root;
+
+		/**
+		 * The animation clip containing position keyframes.
+		 *
+		 * @type {AnimationClip}
+		 */
+		this.clip = clip;
+
+		/**
+		 * The object whose path is being visualized.
+		 *
+		 * @type {Object3D}
+		 */
+		this.object = object;
+
+		/**
+		 * Number of samples for smooth path interpolation.
+		 *
+		 * @type {number}
+		 * @default 100
+		 */
+		this.divisions = divisions;
+
+		/**
+		 * The position track for the object.
+		 *
+		 * @type {KeyframeTrack|null}
+		 * @private
+		 */
+		this._track = this._findTrackForObject( object );
+
+		if ( this._track === null ) {
+
+			console.warn( 'AnimationPathHelper: No position track found for object', object.name );
+			return;
+
+		}
+
+		// Create line for path
+		const lineGeometry = new BufferGeometry();
+		const lineMaterial = new LineBasicMaterial( {
+			color: color,
+			toneMapped: false
+		} );
+
+		/**
+		 * The line representing the animation path.
+		 *
+		 * @type {Line}
+		 */
+		this.line = new Line( lineGeometry, lineMaterial );
+		this.add( this.line );
+
+		// Create points for keyframe markers
+		if ( showMarkers ) {
+
+			const pointsGeometry = new BufferGeometry();
+			const pointsMaterial = new PointsMaterial( {
+				color: markerColor,
+				size: markerSize,
+				sizeAttenuation: false,
+				toneMapped: false
+			} );
+
+			/**
+			 * Points marking keyframe positions.
+			 *
+			 * @type {Points|null}
+			 */
+			this.points = new Points( pointsGeometry, pointsMaterial );
+			this.add( this.points );
+
+		} else {
+
+			this.points = null;
+
+		}
+
+		// Sync matrix with object's parent
+		this.matrixAutoUpdate = false;
+
+		this._updateGeometry();
+
+	}
+
+	/**
+	 * Finds the position track for the given object.
+	 *
+	 * @private
+	 * @param {Object3D} object - The object to find the track for.
+	 * @returns {KeyframeTrack|null} The position track, or null if not found.
+	 */
+	_findTrackForObject( object ) {
+
+		const targetName = object.uuid + '.position';
+
+		for ( const track of this.clip.tracks ) {
+
+			if ( track.name === targetName && track.getValueSize() === 3 ) {
+
+				return track;
+
+			}
+
+		}
+
+		return null;
+
+	}
+
+	/**
+	 * Samples the track at regular intervals.
+	 *
+	 * @private
+	 * @returns {Float32Array} Array of sampled positions.
+	 */
+	_sampleTrack() {
+
+		const track = this._track;
+		const interpolant = track.createInterpolant();
+		const duration = this.clip.duration;
+		const positions = [];
+
+		for ( let i = 0; i <= this.divisions; i ++ ) {
+
+			const t = ( i / this.divisions ) * duration;
+			const result = interpolant.evaluate( t );
+			positions.push( result[ 0 ], result[ 1 ], result[ 2 ] );
+
+		}
+
+		return new Float32Array( positions );
+
+	}
+
+	/**
+	 * Updates the geometry with sampled path data.
+	 *
+	 * @private
+	 */
+	_updateGeometry() {
+
+		if ( this._track === null ) return;
+
+		// Update line geometry
+		const sampledPositions = this._sampleTrack();
+		this.line.geometry.setAttribute( 'position', new Float32BufferAttribute( sampledPositions, 3 ) );
+		this.line.geometry.computeBoundingSphere();
+
+		// Update keyframe markers
+		if ( this.points !== null ) {
+
+			this.points.geometry.setAttribute( 'position', new Float32BufferAttribute( new Float32Array( this._track.values ), 3 ) );
+			this.points.geometry.computeBoundingSphere();
+
+		}
+
+	}
+
+	/**
+	 * Updates the helper's transform to match the object's parent.
+	 *
+	 * @param {boolean} force - Force matrix update.
+	 */
+	updateMatrixWorld( force ) {
+
+		// Position the helper at the object's parent so the path appears in correct local space
+		if ( this.object && this.object.parent ) {
+
+			this.object.parent.updateWorldMatrix( true, false );
+			this.matrix.copy( this.object.parent.matrixWorld );
+
+		} else {
+
+			this.matrix.identity();
+
+		}
+
+		this.matrixWorld.copy( this.matrix );
+
+		// Update children
+		for ( let i = 0; i < this.children.length; i ++ ) {
+
+			this.children[ i ].updateMatrixWorld( force );
+
+		}
+
+	}
+
+	/**
+	 * Sets the path line color.
+	 *
+	 * @param {number|Color|string} color - The new color.
+	 */
+	setColor( color ) {
+
+		if ( this.line ) this.line.material.color.set( color );
+
+	}
+
+	/**
+	 * Sets the keyframe marker color.
+	 *
+	 * @param {number|Color|string} color - The new color.
+	 */
+	setMarkerColor( color ) {
+
+		if ( this.points ) this.points.material.color.set( color );
+
+	}
+
+	/**
+	 * Frees the GPU-related resources allocated by this instance.
+	 */
+	dispose() {
+
+		if ( this.line ) {
+
+			this.line.geometry.dispose();
+			this.line.material.dispose();
+
+		}
+
+		if ( this.points ) {
+
+			this.points.geometry.dispose();
+			this.points.material.dispose();
+
+		}
+
+	}
+
+}
+
+export { AnimationPathHelper };

package/examples/jsm/helpers/ViewHelper.js

@@ -65,6 +65,20 @@ class ViewHelper extends Object3D {
 		 */
 		this.center = new Vector3();
 
+		/**
+		 * Controls the position of the helper in the viewport.
+		 * Use `top`/`bottom` for vertical positioning and `left`/`right` for horizontal.
+		 * If `left` is `null`, `right` is used. If `top` is `null`, `bottom` is used.
+		 *
+		 * @type {{top: number|null, right: number, bottom: number, left: number|null}}
+		 */
+		this.location = {
+			top: null,
+			right: 0,
+			bottom: 0,
+			left: null
+		};
+
 		const color1 = new Color( '#ff4466' );
 		const color2 = new Color( '#88ff44' );
 		const color3 = new Color( '#4488ff' );
@@ -142,8 +156,8 @@ class ViewHelper extends Object3D {
 		const turnRate = 2 * Math.PI; // turn rate in angles per second
 
 		/**
-		 * Renders the helper in a separate view in the bottom-right corner
-		 * of the viewport.
+		 * Renders the helper in a separate view in the viewport.
+		 * Position is controlled by the `location` property.
 		 *
 		 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
 		 */
@@ -157,8 +171,31 @@ class ViewHelper extends Object3D {
 
 			//
 
-			const x = domElement.offsetWidth - dim;
-			const y = renderer.isWebGPURenderer ? domElement.offsetHeight - dim : 0;
+			const location = this.location;
+
+			let x, y;
+
+			if ( location.left !== null ) {
+
+				x = location.left;
+
+			} else {
+
+				x = domElement.offsetWidth - dim - location.right;
+
+			}
+
+			if ( location.top !== null ) {
+
+				// Position from top
+				y = renderer.isWebGPURenderer ? location.top : domElement.offsetHeight - dim - location.top;
+
+			} else {
+
+				// Position from bottom
+				y = renderer.isWebGPURenderer ? domElement.offsetHeight - dim - location.bottom : location.bottom;
+
+			}
 
 			renderer.clearDepth();
 
@@ -191,10 +228,32 @@ class ViewHelper extends Object3D {
 			if ( this.animating === true ) return false;
 
 			const rect = domElement.getBoundingClientRect();
-			const offsetX = rect.left + ( domElement.offsetWidth - dim );
-			const offsetY = rect.top + ( domElement.offsetHeight - dim );
-			mouse.x = ( ( event.clientX - offsetX ) / ( rect.right - offsetX ) ) * 2 - 1;
-			mouse.y = - ( ( event.clientY - offsetY ) / ( rect.bottom - offsetY ) ) * 2 + 1;
+			const location = this.location;
+
+			let offsetX, offsetY;
+
+			if ( location.left !== null ) {
+
+				offsetX = rect.left + location.left;
+
+			} else {
+
+				offsetX = rect.left + domElement.offsetWidth - dim - location.right;
+
+			}
+
+			if ( location.top !== null ) {
+
+				offsetY = rect.top + location.top;
+
+			} else {
+
+				offsetY = rect.top + domElement.offsetHeight - dim - location.bottom;
+
+			}
+
+			mouse.x = ( ( event.clientX - offsetX ) / dim ) * 2 - 1;
+			mouse.y = - ( ( event.clientY - offsetY ) / dim ) * 2 + 1;
 
 			raycaster.setFromCamera( mouse, orthoCamera );
 

package/examples/jsm/inspector/Inspector.js

@@ -110,7 +110,7 @@ class Inspector extends RendererInspector {
 
 	}
 
-	resolveConsole( type, message ) {
+	resolveConsole( type, message, stackTrace = null ) {
 
 		switch ( type ) {
 
@@ -126,7 +126,15 @@ class Inspector extends RendererInspector {
 
 				this.console.addMessage( 'warn', message );
 
-				console.warn( message );
+				if ( stackTrace && stackTrace.isStackTrace ) {
+
+					console.warn( stackTrace.getError( message ) );
+
+				} else {
+
+					console.warn( message );
+
+				}
 
 				break;
 
@@ -134,7 +142,15 @@ class Inspector extends RendererInspector {
 
 				this.console.addMessage( 'error', message );
 
-				console.error( message );
+				if ( stackTrace && stackTrace.isStackTrace ) {
+
+					console.error( stackTrace.getError( message ) );
+
+				} else {
+
+					console.error( message );
+
+				}
 
 				break;
 
@@ -182,10 +198,10 @@ class Inspector extends RendererInspector {
 
 			if ( this.isAvailable ) {
 
-				renderer.backend.trackTimestamp = true;
-
 				renderer.init().then( () => {
 
+					renderer.backend.trackTimestamp = true;
+
 					if ( renderer.hasFeature( 'timestamp-query' ) !== true ) {
 
 						this.console.addMessage( 'error', 'THREE.Inspector: GPU Timestamp Queries not available.' );

package/examples/jsm/inspector/tabs/Console.js

@@ -33,8 +33,14 @@ class Console extends Tab {
 
 		} );
 
-		const filtersGroup = document.createElement( 'div' );
-		filtersGroup.className = 'console-filters-group';
+		const copyButton = document.createElement( 'button' );
+		copyButton.className = 'console-copy-button';
+		copyButton.title = 'Copy all';
+		copyButton.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>';
+		copyButton.addEventListener( 'click', () => this.copyAll( copyButton ) );
+
+		const buttonsGroup = document.createElement( 'div' );
+		buttonsGroup.className = 'console-buttons-group';
 
 		Object.keys( this.filters ).forEach( type => {
 
@@ -53,11 +59,11 @@ class Console extends Tab {
 			label.appendChild( checkbox );
 			label.appendChild( checkmark );
 			label.append( type.charAt( 0 ).toUpperCase() + type.slice( 1 ) );
-			filtersGroup.appendChild( label );
+			buttonsGroup.appendChild( label );
 
 		} );
 
-		filtersGroup.addEventListener( 'change', ( e ) => {
+		buttonsGroup.addEventListener( 'change', ( e ) => {
 
 			const type = e.target.dataset.type;
 			if ( type in this.filters ) {
@@ -69,8 +75,10 @@ class Console extends Tab {
 
 		} );
 
+		buttonsGroup.appendChild( copyButton );
+
 		header.appendChild( filterInput );
-		header.appendChild( filtersGroup );
+		header.appendChild( buttonsGroup );
 		this.content.appendChild( header );
 
 	}
@@ -92,6 +100,32 @@ class Console extends Tab {
 
 	}
 
+	copyAll( button ) {
+
+		const win = this.logContainer.ownerDocument.defaultView;
+		const selection = win.getSelection();
+		const selectedText = selection.toString();
+		const textInConsole = selectedText && this.logContainer.contains( selection.anchorNode );
+
+		let text;
+		if ( textInConsole ) {
+
+			text = selectedText;
+
+		} else {
+
+			const messages = this.logContainer.querySelectorAll( '.log-message:not(.hidden)' );
+			text = Array.from( messages ).map( msg => msg.dataset.rawText ).join( '\n' );
+
+		}
+
+		navigator.clipboard.writeText( text );
+
+		button.classList.add( 'copied' );
+		setTimeout( () => button.classList.remove( 'copied' ), 350 );
+
+	}
+
 	_getIcon( type, subType ) {
 
 		let icon;

package/examples/jsm/inspector/tabs/Parameters.js

@@ -13,6 +13,8 @@ class ParametersGroup {
 
 		this.paramList = new Item( name );
 
+		this.objects = [];
+
 	}
 
 	close() {
@@ -93,6 +95,15 @@ class ParametersGroup {
 
 		};
 
+
+		this._registerParameter( object, property, editor, subItem );
+
+	}
+
+	_registerParameter( object, property, editor, subItem ) {
+
+		this.objects.push( { object: object, key: property, editor: editor, subItem: subItem } );
+
 	}
 
 	addFolder( name ) {
@@ -291,6 +302,8 @@ class ParametersGroup {
 
 		};
 
+		this._registerParameter( object, property, editor, subItem );
+
 		return editor;
 
 	}
@@ -315,6 +328,8 @@ class Parameters extends Tab {
 
 		this.paramList = paramList;
 
+		this.groups = [];
+
 	}
 
 	createGroup( name ) {
@@ -322,6 +337,7 @@ class Parameters extends Tab {
 		const group = new ParametersGroup( this, name );
 
 		this.paramList.add( group.paramList );
+		this.groups.push( group );
 
 		return group;
 

package/examples/jsm/inspector/ui/Style.js

@@ -1057,7 +1057,7 @@ export class Style {
 	justify-content: space-between;
 }
 
-.console-filters-group {
+.console-buttons-group {
 	display: flex;
 	gap: 20px;
 }
@@ -1074,6 +1074,28 @@ export class Style {
 	border-radius: 15px;
 }
 
+.console-copy-button {
+	background: transparent;
+	border: none;
+	color: var(--text-secondary);
+	cursor: pointer;
+	padding: 4px;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	border-radius: 4px;
+	transition: color 0.2s, background-color 0.2s;
+}
+
+.console-copy-button:hover {
+	color: var(--text-primary);
+	background-color: var(--profiler-hover);
+}
+
+.console-copy-button.copied {
+	color: var(--color-green);
+}
+
 #console-log {
 	display: flex;
 	flex-direction: column;
@@ -1081,6 +1103,8 @@ export class Style {
 	padding: 10px;
 	overflow-y: auto;
 	flex-grow: 1;
+	user-select: text;
+	-webkit-user-select: text;
 }
 
 .log-message {