@gnsx/three 0.185.16 → 0.186.1

package/examples/jsm/loaders/FBXLoader.js

@@ -86,6 +86,16 @@ class FBXLoader extends Loader {
 
 		super( manager );
 
+		/**
+		 * Whether to trim animation clips to the time range of their
+		 * animation stacks and shift them to start at time zero. Useful
+		 * for assets that define multiple clips on a single timeline.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.trimAnimationClips = false;
+
 	}
 
 	/**
@@ -172,7 +182,7 @@ class FBXLoader extends Loader {
 
 		const textureLoader = new TextureLoader( this.manager ).setPath( this.resourcePath || path ).setCrossOrigin( this.crossOrigin );
 
-		return new FBXTreeParser( textureLoader, this.manager ).parse( fbxTree );
+		return new FBXTreeParser( textureLoader, this.manager, this.trimAnimationClips ).parse( fbxTree );
 
 	}
 
@@ -181,10 +191,11 @@ class FBXLoader extends Loader {
 // Parse the FBXTree object returned by the BinaryParser or TextParser and return a Group
 class FBXTreeParser {
 
-	constructor( textureLoader, manager ) {
+	constructor( textureLoader, manager, trimAnimationClips ) {
 
 		this.textureLoader = textureLoader;
 		this.manager = manager;
+		this.trimAnimationClips = trimAnimationClips;
 
 	}
 
@@ -367,7 +378,7 @@ class FBXTreeParser {
 		} else { // Binary Format
 
 			const array = new Uint8Array( content );
-			return window.URL.createObjectURL( new Blob( [ array ], { type: type } ) );
+			return URL.createObjectURL( new Blob( [ array ], { type: type } ) );
 
 		}
 
@@ -1000,12 +1011,13 @@ class FBXTreeParser {
 		// without a BindPose section).
 		this.bindSkeleton( deformers.skeletons, geometryMap, modelMap );
 
-		const animations = new AnimationParser().parse();
+		const animations = new AnimationParser( this.trimAnimationClips ).parse();
 
 		// if all the models where already combined in a single group, just return that
 		if ( sceneGraph.children.length === 1 && sceneGraph.children[ 0 ].isGroup ) {
 
 			sceneGraph.children[ 0 ].animations = animations;
+			Object.assign( sceneGraph.children[ 0 ].userData, sceneGraph.userData );
 			sceneGraph = sceneGraph.children[ 0 ];
 
 		}
@@ -2614,6 +2626,12 @@ class GeometryParser {
 // parse animation data from FBXTree
 class AnimationParser {
 
+	constructor( trimAnimationClips ) {
+
+		this.trimAnimationClips = trimAnimationClips;
+
+	}
+
 	// take raw animation clips and turn them into three.js animation clips
 	parse() {
 
@@ -2912,11 +2930,14 @@ class AnimationParser {
 			}
 
 			const layer = layersMap.get( children[ 0 ].ID );
+			const rawStack = rawStacks[ nodeID ];
 
 			rawClips[ nodeID ] = {
 
-				name: rawStacks[ nodeID ].attrName,
+				name: rawStack.attrName,
 				layer: layer,
+				localStart: rawStack.LocalStart !== undefined ? convertFBXTimeToSeconds( Number( rawStack.LocalStart.value ) ) : 0,
+				localStop: rawStack.LocalStop !== undefined ? convertFBXTimeToSeconds( Number( rawStack.LocalStop.value ) ) : 0,
 
 			};
 
@@ -2937,10 +2958,65 @@ class AnimationParser {
 
 		} );
 
+		if ( this.trimAnimationClips === true && rawClip.localStop > rawClip.localStart ) {
+
+			tracks = this.trimTracks( tracks, rawClip.localStart, rawClip.localStop );
+
+		}
+
 		return new AnimationClip( rawClip.name, - 1, tracks );
 
 	}
 
+	// trims the given tracks to the time range [ startTime, endTime ] and shifts
+	// them so they start at time zero. tracks without keyframes in the range are discarded
+	trimTracks( tracks, startTime, endTime ) {
+
+		// track times are stored as float32 so compare against float32 boundaries
+		// to keep keyframes lying exactly on the range limits
+
+		const start = Math.fround( startTime );
+		const end = Math.fround( endTime );
+
+		const trimmedTracks = [];
+
+		for ( let i = 0; i < tracks.length; i ++ ) {
+
+			const track = tracks[ i ];
+			const stride = track.getValueSize();
+
+			const times = [];
+			const values = [];
+
+			for ( let j = 0; j < track.times.length; j ++ ) {
+
+				const time = track.times[ j ];
+
+				if ( time < start || time > end ) continue;
+
+				times.push( time - start );
+
+				for ( let k = 0; k < stride; k ++ ) {
+
+					values.push( track.values[ j * stride + k ] );
+
+				}
+
+			}
+
+			if ( times.length === 0 ) continue;
+
+			track.times = new Float32Array( times );
+			track.values = new Float32Array( values );
+
+			trimmedTracks.push( track );
+
+		}
+
+		return trimmedTracks;
+
+	}
+
 	generateTracks( rawTracks ) {
 
 		const tracks = [];

package/examples/jsm/loaders/GLTFGaussianSplatLoaderExtension.js

@@ -0,0 +1,330 @@
+import {
+	Group
+} from '@gnsx/three';
+
+import { GaussianSplat } from '../objects/GaussianSplat.js';
+import { SH_BAND_WORDS, createGaussianSplatGeometry, createPackedSphericalHarmonicsBand, writeColorBytesFromSH0, writeCovariance } from '../utils/GaussianSplatUtils.js';
+
+const EXTENSION_NAME = 'KHR_gaussian_splatting';
+const POINTS = 0;
+const ATTRIBUTES = {
+	POSITION: 'position'
+};
+
+/**
+ * A glTF loader plugin for `KHR_gaussian_splatting`.
+ *
+ * This plugin must be registered explicitly because {@link GaussianSplat}
+ * requires {@link WebGPURenderer}.
+ *
+ * ```js
+ * const loader = new GLTFLoader();
+ * loader.register( function ( parser ) {
+ *
+ * 	return new GLTFGaussianSplatLoaderExtension( parser );
+ *
+ * } );
+ * ```
+ *
+ * @three_import import { GLTFGaussianSplatLoaderExtension } from 'three/addons/loaders/GLTFGaussianSplatLoaderExtension.js';
+ */
+class GLTFGaussianSplatLoaderExtension {
+
+	/**
+	 * Constructs a new glTF gaussian splatting extension plugin.
+	 *
+	 * @param {GLTFParser} parser - The glTF parser.
+	 */
+	constructor( parser ) {
+
+		this.name = EXTENSION_NAME;
+		this.parser = parser;
+
+	}
+
+	/**
+	 * Loads a glTF mesh containing gaussian splat primitives.
+	 *
+	 * @param {number} meshIndex - The mesh index.
+	 * @return {?Promise<Group|GaussianSplat>} The loaded mesh or `null` when the mesh does not use this extension.
+	 */
+	loadMesh( meshIndex ) {
+
+		const parser = this.parser;
+		const meshDef = parser.json.meshes[ meshIndex ];
+		const primitives = meshDef.primitives;
+
+		if ( primitives.some( isGaussianSplatPrimitive ) === false ) return null;
+
+		if ( primitives.every( isGaussianSplatPrimitive ) === false ) {
+
+			throw new Error( 'THREE.GLTFGaussianSplatLoaderExtension: Mixed gaussian and non-gaussian mesh primitives are not supported.' );
+
+		}
+
+		return parser.loadGeometries( primitives ).then( function ( geometries ) {
+
+			const meshes = [];
+
+			for ( let i = 0, il = geometries.length; i < il; i ++ ) {
+
+				const geometry = geometries[ i ];
+				const primitive = primitives[ i ];
+
+				if ( primitive.mode !== POINTS ) {
+
+					throw new Error( 'THREE.GLTFGaussianSplatLoaderExtension: Gaussian splat primitives must use POINTS mode.' );
+
+				}
+
+				const mesh = createGaussianSplat( geometry, primitive );
+				mesh.name = parser.createUniqueName( meshDef.name || ( 'mesh_' + meshIndex ) );
+
+				assignExtrasToUserData( mesh, meshDef );
+				parser.associations.set( mesh, {
+					meshes: meshIndex,
+					primitives: i
+				} );
+
+				meshes.push( mesh );
+
+			}
+
+			if ( meshes.length === 1 ) return meshes[ 0 ];
+
+			const group = new Group();
+			assignExtrasToUserData( group, meshDef );
+			parser.associations.set( group, { meshes: meshIndex } );
+
+			for ( let i = 0, il = meshes.length; i < il; i ++ ) {
+
+				group.add( meshes[ i ] );
+
+			}
+
+			return group;
+
+		} );
+
+	}
+
+}
+
+function isGaussianSplatPrimitive( primitiveDef ) {
+
+	return primitiveDef.extensions !== undefined &&
+		primitiveDef.extensions[ EXTENSION_NAME ] !== undefined;
+
+}
+
+function createGaussianSplat( geometry, primitiveDef ) {
+
+	const extensionDef = primitiveDef.extensions[ EXTENSION_NAME ];
+
+	if ( extensionDef.kernel !== 'ellipse' ) {
+
+		throw new Error( 'THREE.GLTFGaussianSplatLoaderExtension: Unsupported KHR_gaussian_splatting kernel.' );
+
+	}
+
+	if ( extensionDef.colorSpace === undefined ) {
+
+		throw new Error( 'THREE.GLTFGaussianSplatLoaderExtension: KHR_gaussian_splatting colorSpace is required.' );
+
+	}
+
+	if ( extensionDef.projection !== undefined && extensionDef.projection !== 'perspective' ) {
+
+		console.warn( 'THREE.GLTFGaussianSplatLoaderExtension: Unsupported KHR_gaussian_splatting projection. Results may be incorrect.' );
+
+	}
+
+	if ( extensionDef.sortingMethod !== undefined && extensionDef.sortingMethod !== 'cameraDistance' ) {
+
+		console.warn( 'THREE.GLTFGaussianSplatLoaderExtension: Unsupported KHR_gaussian_splatting sortingMethod. Results may be incorrect.' );
+
+	}
+
+	const position = getGaussianSplatAttribute( geometry, primitiveDef, 'POSITION' );
+	const scale = getGaussianSplatAttribute( geometry, primitiveDef, 'KHR_gaussian_splatting:SCALE' );
+	const rotation = getGaussianSplatAttribute( geometry, primitiveDef, 'KHR_gaussian_splatting:ROTATION' );
+	const opacity = getGaussianSplatAttribute( geometry, primitiveDef, 'KHR_gaussian_splatting:OPACITY' );
+	const sh0 = getGaussianSplatAttribute( geometry, primitiveDef, 'KHR_gaussian_splatting:SH_DEGREE_0_COEF_0' );
+	const count = position.count;
+
+	if ( scale.count !== count || rotation.count !== count || opacity.count !== count || sh0.count !== count ) {
+
+		throw new Error( 'THREE.GLTFGaussianSplatLoaderExtension: KHR_gaussian_splatting attribute counts must match POSITION.' );
+
+	}
+
+	const centers = new Float32Array( count * 3 );
+	const covariances = new Float32Array( count * 6 );
+	const colors = new Uint8ClampedArray( count * 4 );
+	const sphericalHarmonics = createGLTFSphericalHarmonicsAttributes( geometry, primitiveDef, count );
+
+	for ( let i = 0; i < count; i ++ ) {
+
+		const i3 = i * 3;
+
+		centers[ i3 ] = position.getX( i );
+		centers[ i3 + 1 ] = position.getY( i );
+		centers[ i3 + 2 ] = position.getZ( i );
+
+		writeCovariance(
+			covariances,
+			i * 6,
+			scale.getX( i ),
+			scale.getY( i ),
+			scale.getZ( i ),
+			rotation.getX( i ),
+			rotation.getY( i ),
+			rotation.getZ( i ),
+			rotation.getW( i )
+		);
+
+		writeColorBytesFromSH0(
+			colors,
+			i * 4,
+			sh0.getX( i ),
+			sh0.getY( i ),
+			sh0.getZ( i ),
+			opacity.getX( i )
+		);
+
+	}
+
+	const mesh = new GaussianSplat( createGaussianSplatGeometry( centers, covariances, colors, sphericalHarmonics ) );
+
+	mesh.userData.gltfExtensions = mesh.userData.gltfExtensions || {};
+	mesh.userData.gltfExtensions[ EXTENSION_NAME ] = Object.assign( {}, extensionDef );
+
+	return mesh;
+
+}
+
+function createGLTFSphericalHarmonicsAttributes( geometry, primitiveDef, count ) {
+
+	const sphericalHarmonics = {};
+
+	for ( let degree = 1; degree <= 3; degree ++ ) {
+
+		const coefficientCount = degree * 2 + 1;
+		const attributes = [];
+
+		for ( let coefficient = 0; coefficient < coefficientCount; coefficient ++ ) {
+
+			const semantic = `KHR_gaussian_splatting:SH_DEGREE_${ degree }_COEF_${ coefficient }`;
+			const attribute = getOptionalGaussianSplatAttribute( geometry, primitiveDef, semantic );
+
+			if ( attribute !== undefined ) {
+
+				if ( attribute.count !== count || attribute.itemSize !== 3 ) {
+
+					throw new Error( `THREE.GLTFGaussianSplatLoaderExtension: Invalid ${ semantic } attribute.` );
+
+				}
+
+			}
+
+			attributes.push( attribute );
+
+		}
+
+		if ( attributes.every( attribute => attribute === undefined ) ) break;
+
+		if ( attributes.some( attribute => attribute === undefined ) ) {
+
+			throw new Error( `THREE.GLTFGaussianSplatLoaderExtension: Incomplete KHR_gaussian_splatting SH degree ${ degree } coefficients.` );
+
+		}
+
+		const band = createPackedSphericalHarmonicsBand( count, degree );
+		const target = band.bytes;
+		const byteStride = SH_BAND_WORDS[ degree ] * 4;
+
+		for ( let i = 0; i < count; i ++ ) {
+
+			for ( let coefficient = 0; coefficient < coefficientCount; coefficient ++ ) {
+
+				const attribute = attributes[ coefficient ];
+				const targetOffset = i * byteStride + coefficient * 3;
+
+				target[ targetOffset ] = attribute.getX( i ) * 128 + 128;
+				target[ targetOffset + 1 ] = attribute.getY( i ) * 128 + 128;
+				target[ targetOffset + 2 ] = attribute.getZ( i ) * 128 + 128;
+
+			}
+
+		}
+
+		sphericalHarmonics[ `sh${ degree }` ] = band.packed;
+
+	}
+
+	for ( const semantic in primitiveDef.attributes ) {
+
+		const match = semantic.match( /^KHR_gaussian_splatting:SH_DEGREE_([1-3])_COEF_/ );
+
+		if ( match !== null && sphericalHarmonics[ `sh${ match[ 1 ] }` ] === undefined ) {
+
+			throw new Error( 'THREE.GLTFGaussianSplatLoaderExtension: KHR_gaussian_splatting spherical harmonics attributes must be contiguous.' );
+
+		}
+
+	}
+
+	return sphericalHarmonics;
+
+}
+
+function getGaussianSplatAttribute( geometry, primitiveDef, semantic ) {
+
+	if ( primitiveDef.attributes[ semantic ] === undefined ) {
+
+		throw new Error( `THREE.GLTFGaussianSplatLoaderExtension: KHR_gaussian_splatting requires ${ semantic }.` );
+
+	}
+
+	const attributeName = ATTRIBUTES[ semantic ] || semantic.toLowerCase();
+	const attribute = geometry.getAttribute( attributeName );
+
+	if ( attribute === undefined ) {
+
+		throw new Error( `THREE.GLTFGaussianSplatLoaderExtension: KHR_gaussian_splatting attribute ${ semantic } was not loaded.` );
+
+	}
+
+	return attribute;
+
+}
+
+function getOptionalGaussianSplatAttribute( geometry, primitiveDef, semantic ) {
+
+	if ( primitiveDef.attributes[ semantic ] === undefined ) return undefined;
+
+	const attributeName = ATTRIBUTES[ semantic ] || semantic.toLowerCase();
+
+	return geometry.getAttribute( attributeName );
+
+}
+
+function assignExtrasToUserData( object, gltfDef ) {
+
+	if ( gltfDef.extras !== undefined ) {
+
+		if ( typeof gltfDef.extras === 'object' ) {
+
+			Object.assign( object.userData, gltfDef.extras );
+
+		} else {
+
+			console.warn( 'THREE.GLTFGaussianSplatLoaderExtension: Ignoring primitive type .extras, ' + gltfDef.extras );
+
+		}
+
+	}
+
+}
+
+export { GLTFGaussianSplatLoaderExtension };

package/examples/jsm/loaders/GLTFLoader.js

@@ -104,7 +104,8 @@ import { clone } from '../utils/SkeletonUtils.js';
  * - EXT_texture_avif
  * - EXT_texture_webp
  *
- * The following glTF 2.0 extension is supported by an external user plugin:
+ * The following glTF 2.0 extensions are supported by separately registered plugins:
+ * - KHR_gaussian_splatting
  * - [KHR_materials_variants](https://github.com/takahirox/three-gltf-extensions)
  * - [MSFT_texture_dds](https://github.com/takahirox/three-gltf-extensions)
  * - [KHR_animation_pointer](https://github.com/needle-tools/three-animation-pointer)
@@ -1786,6 +1787,9 @@ class GLTFMeshGpuInstancing {
 				}
 
 				// Add instance attributes to the geometry, excluding TRS.
+
+				let instanceGeometry = null;
+
 				for ( const attributeName in attributes ) {
 
 					if ( attributeName === '_COLOR_0' ) {
@@ -1797,7 +1801,36 @@ class GLTFMeshGpuInstancing {
 						 attributeName !== 'ROTATION' &&
 						 attributeName !== 'SCALE' ) {
 
-						mesh.geometry.setAttribute( attributeName, attributes[ attributeName ] );
+						if ( instanceGeometry === null ) {
+
+							// do a shallow clone of the goemetry so per-instance data are not shared
+
+							const source = instancedMesh.geometry;
+							instanceGeometry = new BufferGeometry();
+							instanceGeometry.name = source.name;
+
+							for ( const name in source.attributes ) instanceGeometry.setAttribute( name, source.attributes[ name ] );
+							for ( const name in source.morphAttributes ) instanceGeometry.morphAttributes[ name ] = source.morphAttributes[ name ];
+							if ( source.index !== null ) instanceGeometry.setIndex( source.index );
+
+							instanceGeometry.morphTargetsRelative = source.morphTargetsRelative;
+
+							for ( const group of source.groups ) instanceGeometry.addGroup( group.start, group.count, group.materialIndex );
+
+							if ( source.boundingBox !== null ) instanceGeometry.boundingBox = source.boundingBox.clone();
+							if ( source.boundingSphere !== null ) instanceGeometry.boundingSphere = source.boundingSphere.clone();
+
+							instanceGeometry.drawRange.start = source.drawRange.start;
+							instanceGeometry.drawRange.count = source.drawRange.count;
+
+							instanceGeometry.userData = Object.assign( {}, source.userData );
+
+							instancedMesh.geometry = instanceGeometry;
+
+						}
+
+						const attr = attributes[ attributeName ];
+						instanceGeometry.setAttribute( attributeName, new InstancedBufferAttribute( attr.array, attr.itemSize, attr.normalized ) );
 
 					}
 
@@ -2040,6 +2073,27 @@ class GLTFTextureTransformExtension {
 
 		}
 
+		if ( transform.rotation !== undefined ) {
+
+			// glTF's KHR_texture_transform order differs from three.js:
+			// glTF defines the UV transform as T * R * S
+			// three.js defines the UV transform as T * S * R
+			//
+			// To fix this, we need to override the matrix with the value computed per glTF spec
+			// We still set the other fields so that you can inspect/export the resulting object.
+
+			const c = Math.cos( texture.rotation );
+			const s = Math.sin( texture.rotation );
+
+			texture.matrix.set(
+				texture.repeat.x * c, texture.repeat.y * s, texture.offset.x,
+				- texture.repeat.x * s, texture.repeat.y * c, texture.offset.y,
+				0, 0, 1
+			);
+			texture.matrixAutoUpdate = false;
+
+		}
+
 		texture.needsUpdate = true;
 
 		return texture;
@@ -3776,6 +3830,18 @@ class GLTFParser {
 
 				}
 
+				// Convert strip/fan primitives to triangles
+
+				if ( primitive.mode === WEBGL_CONSTANTS.TRIANGLE_STRIP ) {
+
+					geometryPromise = geometryPromise.then( geometry => toTrianglesDrawMode( geometry, TriangleStripDrawMode ) );
+
+				} else if ( primitive.mode === WEBGL_CONSTANTS.TRIANGLE_FAN ) {
+
+					geometryPromise = geometryPromise.then( geometry => toTrianglesDrawMode( geometry, TriangleFanDrawMode ) );
+
+				}
+
 				// Cache this geometry
 				cache[ cacheKey ] = { primitive: primitive, promise: geometryPromise };
 
@@ -3819,7 +3885,7 @@ class GLTFParser {
 
 		pending.push( parser.loadGeometries( primitives ) );
 
-		return Promise.all( pending ).then( function ( results ) {
+		return Promise.all( pending ).then( async function ( results ) {
 
 			const materials = results.slice( 0, results.length - 1 );
 			const geometries = results[ results.length - 1 ];
@@ -3842,8 +3908,17 @@ class GLTFParser {
 						primitive.mode === WEBGL_CONSTANTS.TRIANGLE_FAN ||
 						primitive.mode === undefined ) {
 
+					const needsSkinning = meshDef.isSkinnedMesh === true;
+					const hasSkinningAttributes = geometry.hasAttribute( 'skinIndex' ) && geometry.hasAttribute( 'skinWeight' );
+
+					if ( needsSkinning && hasSkinningAttributes === false ) {
+
+						console.warn( 'THREE.GLTFLoader: Missing skinIndex or skinWeight attributes. Skinning disabled.' );
+
+					}
+
 					// .isSkinnedMesh isn't in glTF spec. See ._markDefs()
-					mesh = meshDef.isSkinnedMesh === true
+					mesh = ( needsSkinning && hasSkinningAttributes )
 						? new SkinnedMesh( geometry, material )
 						: new Mesh( geometry, material );
 
@@ -3854,16 +3929,6 @@ class GLTFParser {
 
 					}
 
-					if ( primitive.mode === WEBGL_CONSTANTS.TRIANGLE_STRIP ) {
-
-						mesh.geometry = toTrianglesDrawMode( mesh.geometry, TriangleStripDrawMode );
-
-					} else if ( primitive.mode === WEBGL_CONSTANTS.TRIANGLE_FAN ) {
-
-						mesh.geometry = toTrianglesDrawMode( mesh.geometry, TriangleFanDrawMode );
-
-					}
-
 				} else if ( primitive.mode === WEBGL_CONSTANTS.LINES ) {
 
 					mesh = new LineSegments( geometry, material );