@plastic-software/three 0.181.3 → 0.183.0

package/examples/jsm/exporters/GLTFExporter.js

@@ -1852,12 +1852,12 @@ class GLTFWriter {
 				! ( array instanceof Uint8Array ) ) {
 
 				console.warn( 'GLTFExporter: Attribute "skinIndex" converted to type UNSIGNED_SHORT.' );
-				modifiedAttribute = new BufferAttribute( new Uint16Array( array ), attribute.itemSize, attribute.normalized );
+				modifiedAttribute = GLTFExporter.Utils.toTypedBufferAttribute( attribute, Uint16Array );
 
 			} else if ( ( array instanceof Uint32Array || array instanceof Int32Array ) && ! attributeName.startsWith( '_' ) ) {
 
 				console.warn( `GLTFExporter: Attribute "${ attributeName }" converted to type FLOAT.` );
-				modifiedAttribute = GLTFExporter.Utils.toFloat32BufferAttribute( attribute );
+				modifiedAttribute = GLTFExporter.Utils.toTypedBufferAttribute( attribute, Float32Array );
 
 			}
 
@@ -2355,6 +2355,13 @@ class GLTFWriter {
 
 		if ( ! json.nodes ) json.nodes = [];
 
+		// Handle pivot by creating a container node
+		if ( object.pivot !== null ) {
+
+			return await this._processNodeWithPivotAsync( object );
+
+		}
+
 		const nodeDef = {};
 
 		if ( options.trs ) {
@@ -2451,6 +2458,126 @@ class GLTFWriter {
 
 	}
 
+	/**
+	 * Process Object3D node with pivot using container approach
+	 * @param {THREE.Object3D} object Object3D with pivot
+	 * @return {Promise<number>} Index of the container node
+	 */
+	async _processNodeWithPivotAsync( object ) {
+
+		const json = this.json;
+		const options = this.options;
+		const nodeMap = this.nodeMap;
+
+		const pivot = object.pivot;
+
+		// Container node: holds position + pivot offset, rotation, scale
+		// Animations will target this node
+		const containerDef = {};
+
+		const rotation = object.quaternion.toArray();
+		const position = [
+			object.position.x + pivot.x,
+			object.position.y + pivot.y,
+			object.position.z + pivot.z
+		];
+		const scale = object.scale.toArray();
+
+		if ( ! equalArray( rotation, [ 0, 0, 0, 1 ] ) ) {
+
+			containerDef.rotation = rotation;
+
+		}
+
+		if ( ! equalArray( position, [ 0, 0, 0 ] ) ) {
+
+			containerDef.translation = position;
+
+		}
+
+		if ( ! equalArray( scale, [ 1, 1, 1 ] ) ) {
+
+			containerDef.scale = scale;
+
+		}
+
+		// Store pivot in extras for round-trip reconstruction
+		containerDef.extras = { pivot: pivot.toArray() };
+
+		if ( object.name !== '' ) containerDef.name = String( object.name );
+
+		this.serializeUserData( object, containerDef );
+
+		const containerIndex = json.nodes.push( containerDef ) - 1;
+
+		// Map original object to container so animations target it
+		nodeMap.set( object, containerIndex );
+
+		// Child node: holds mesh with -pivot offset
+		const childDef = {};
+
+		const childPosition = [ - pivot.x, - pivot.y, - pivot.z ];
+
+		if ( ! equalArray( childPosition, [ 0, 0, 0 ] ) ) {
+
+			childDef.translation = childPosition;
+
+		}
+
+		if ( object.isMesh || object.isLine || object.isPoints ) {
+
+			const meshIndex = await this.processMeshAsync( object );
+
+			if ( meshIndex !== null ) childDef.mesh = meshIndex;
+
+		} else if ( object.isCamera ) {
+
+			childDef.camera = this.processCamera( object );
+
+		}
+
+		if ( object.isSkinnedMesh ) this.skins.push( object );
+
+		const childIndex = json.nodes.push( childDef ) - 1;
+
+		// Build children array for container
+		const containerChildren = [ childIndex ];
+
+		// Process object's children as children of the child node
+		if ( object.children.length > 0 ) {
+
+			const grandchildren = [];
+
+			for ( let i = 0, l = object.children.length; i < l; i ++ ) {
+
+				const child = object.children[ i ];
+
+				if ( child.visible || options.onlyVisible === false ) {
+
+					const childNodeIndex = await this.processNodeAsync( child );
+
+					if ( childNodeIndex !== null ) grandchildren.push( childNodeIndex );
+
+				}
+
+			}
+
+			if ( grandchildren.length > 0 ) childDef.children = grandchildren;
+
+		}
+
+		containerDef.children = containerChildren;
+
+		await this._invokeAllAsync( function ( ext ) {
+
+			ext.writeNode && ext.writeNode( object, containerDef );
+
+		} );
+
+		return containerIndex;
+
+	}
+
 	/**
 	 * Process Scene
 	 * @param {Scene} scene Scene to process
@@ -3538,9 +3665,9 @@ GLTFExporter.Utils = {
 
 	},
 
-	toFloat32BufferAttribute: function ( srcAttribute ) {
+	toTypedBufferAttribute: function ( srcAttribute, TypedArray ) {
 
-		const dstAttribute = new BufferAttribute( new Float32Array( srcAttribute.count * srcAttribute.itemSize ), srcAttribute.itemSize, false );
+		const dstAttribute = new BufferAttribute( new TypedArray( srcAttribute.count * srcAttribute.itemSize ), srcAttribute.itemSize, false );
 
 		if ( ! srcAttribute.normalized && ! srcAttribute.isInterleavedBufferAttribute ) {
 

package/examples/jsm/exporters/USDZExporter.js

@@ -501,7 +501,6 @@ function buildHierarchy( object, parentNode, materials, usedNames, files, option
 function buildXform( object, usedNames ) {
 
 	const name = getName( object, usedNames );
-	const transform = buildMatrix( object.matrix );
 
 	if ( object.matrix.determinant() < 0 ) {
 
@@ -514,8 +513,28 @@ function buildXform( object, usedNames ) {
 
 	const node = new USDNode( name, 'Xform' );
 
-	node.addProperty( `matrix4d xformOp:transform = ${transform}` );
-	node.addProperty( 'uniform token[] xformOpOrder = ["xformOp:transform"]' );
+	if ( object.pivot !== null ) {
+
+		// Export with pivot using separate transform ops
+		const p = object.position;
+		const q = object.quaternion;
+		const s = object.scale;
+		const piv = object.pivot;
+
+		node.addProperty( `float3 xformOp:translate = (${p.x.toPrecision( PRECISION )}, ${p.y.toPrecision( PRECISION )}, ${p.z.toPrecision( PRECISION )})` );
+		node.addProperty( `float3 xformOp:translate:pivot = (${piv.x.toPrecision( PRECISION )}, ${piv.y.toPrecision( PRECISION )}, ${piv.z.toPrecision( PRECISION )})` );
+		node.addProperty( `quatf xformOp:orient = (${q.w.toPrecision( PRECISION )}, ${q.x.toPrecision( PRECISION )}, ${q.y.toPrecision( PRECISION )}, ${q.z.toPrecision( PRECISION )})` );
+		node.addProperty( `float3 xformOp:scale = (${s.x.toPrecision( PRECISION )}, ${s.y.toPrecision( PRECISION )}, ${s.z.toPrecision( PRECISION )})` );
+		node.addProperty( 'uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:translate:pivot", "xformOp:orient", "xformOp:scale", "!invert!xformOp:translate:pivot"]' );
+
+	} else {
+
+		// Export as single transform matrix
+		const transform = buildMatrix( object.matrix );
+		node.addProperty( `matrix4d xformOp:transform = ${transform}` );
+		node.addProperty( 'uniform token[] xformOpOrder = ["xformOp:transform"]' );
+
+	}
 
 	return node;
 

package/examples/jsm/geometries/DecalGeometry.js

@@ -35,7 +35,7 @@ class DecalGeometry extends BufferGeometry {
 	 * @param {Mesh} [mesh] - The base mesh the decal should be projected on.
 	 * @param {Vector3} [position] - The position of the decal projector.
 	 * @param {Euler} [orientation] - The orientation of the decal projector.
-	 * @param {Vector3} [size] - Tje scale of the decal projector.
+	 * @param {Vector3} [size] - The scale of the decal projector.
 	 */
 	constructor( mesh = new Mesh(), position = new Vector3(), orientation = new Euler(), size = new Vector3( 1, 1, 1 ) ) {
 

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/LightProbeHelperGPU.js

@@ -2,7 +2,7 @@ import {
 	Mesh,
 	NodeMaterial,
 	SphereGeometry
-} from 'three';
+} from 'three/webgpu';
 import { float, Fn, getShIrradianceAt, normalWorld, uniformArray, uniform, vec4 } from 'three/tsl';
 
 /**

package/examples/jsm/helpers/TextureHelperGPU.js

@@ -6,7 +6,7 @@ import {
 	PlaneGeometry,
 	DoubleSide,
 	Vector3,
-} from 'three';
+} from 'three/webgpu';
 import { texture as textureNode, cubeTexture, texture3D, float, vec4, attribute } from 'three/tsl';
 import { mergeGeometries } from '../utils/BufferGeometryUtils.js';
 

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 );