three
Version:
JavaScript 3D library
4,666 lines • 112 kB
JavaScript
import {
AnimationClip,
BoxGeometry,
BufferAttribute,
BufferGeometry,
CapsuleGeometry,
ClampToEdgeWrapping,
Color,
ConeGeometry,
CylinderGeometry,
DirectionalLight,
Euler,
Group,
LoaderUtils,
Matrix4,
Mesh,
MeshPhysicalMaterial,
MirroredRepeatWrapping,
NoColorSpace,
Object3D,
OrthographicCamera,
PerspectiveCamera,
PointLight,
Quaternion,
QuaternionKeyframeTrack,
RectAreaLight,
RepeatWrapping,
ShapeUtils,
SkinnedMesh,
Skeleton,
Bone,
SphereGeometry,
SpotLight,
SRGBColorSpace,
Texture,
Vector2,
Vector3,
VectorKeyframeTrack
} from 'three';
// Pre-compiled regex patterns for performance
const VARIANT_PATH_REGEX = /^(.+?)\/\{(\w+)=(\w+)\}\/(.+)$/;
// Spec types (must match USDCParser)
const SpecType = {
Unknown: 0,
Attribute: 1,
Connection: 2,
Expression: 3,
Mapper: 4,
MapperArg: 5,
Prim: 6,
PseudoRoot: 7,
Relationship: 8,
RelationshipTarget: 9,
Variant: 10,
VariantSet: 11
};
// UsdGeomCamera fallback values (OpenUSD schema)
const USD_CAMERA_DEFAULTS = {
projection: 'perspective',
clippingRange: [ 1, 1000000 ],
horizontalAperture: 20.955,
verticalAperture: 15.2908,
horizontalApertureOffset: 0,
verticalApertureOffset: 0,
focalLength: 50,
focusDistance: 0,
fStop: 0
};
/**
* USDComposer handles scene composition from parsed USD data.
* This includes reference resolution, variant selection, transform handling,
* and building the Three.js scene graph.
*
* Works with specsByPath format from USDCParser.
*/
class USDComposer {
constructor( manager = null ) {
this.textureCache = {};
this.skinnedMeshes = [];
this.manager = manager;
this.texturePromises = [];
}
/**
* Compose a Three.js scene from parsed USD data.
* @param {Object} parsedData - Data from USDCParser or USDAParser
* @param {Object} assets - Dictionary of referenced assets (specsByPath or blob URLs)
* @param {Object} variantSelections - External variant selections
* @param {string} basePath - Base path for resolving relative references
* @returns {Group} Three.js scene graph
*/
compose( parsedData, assets = {}, variantSelections = {}, basePath = '' ) {
this.specsByPath = parsedData.specsByPath;
this.assets = assets;
this.externalVariantSelections = variantSelections;
this.basePath = basePath;
this.skinnedMeshes = [];
this.skeletons = {};
this.texturePromises = [];
// Build indexes for O(1) lookups
this._buildIndexes();
// Get FPS from root spec
const rootSpec = this.specsByPath[ '/' ];
const rootFields = rootSpec ? rootSpec.fields : {};
this.fps = rootFields.timeCodesPerSecond || rootFields.framesPerSecond || 24;
const group = new Group();
this._buildHierarchy( group, '/' );
// Bind skeletons to skinned meshes
this._bindSkeletons();
// Expose skeleton on the root group so that AnimationMixer's
// PropertyBinding.findNode resolves bone names before scene objects.
// Without this, Xform prims that share a name with a skeleton joint
// would be animated instead of the bone.
const skeletonPaths = Object.keys( this.skeletons );
if ( skeletonPaths.length === 1 ) {
group.skeleton = this.skeletons[ skeletonPaths[ 0 ] ].skeleton;
}
// Build animations
group.animations = this._buildAnimations();
// Handle metersPerUnit scaling
const metersPerUnit = rootFields.metersPerUnit;
if ( metersPerUnit !== undefined && metersPerUnit !== 1 ) {
group.scale.setScalar( metersPerUnit );
}
// Handle Z-up to Y-up conversion
if ( rootSpec && rootSpec.fields && rootSpec.fields.upAxis === 'Z' ) {
group.rotation.x = - Math.PI / 2;
}
return group;
}
/**
* Apply USD transforms to a Three.js object.
* Handles xformOpOrder with proper matrix composition.
* USD uses row-vector convention, Three.js uses column-vector.
*/
applyTransform( obj, fields, attrs = {} ) {
const data = { ...fields, ...attrs };
const xformOpOrder = data[ 'xformOpOrder' ];
// If we have xformOpOrder, apply transforms using matrices
if ( xformOpOrder && xformOpOrder.length > 0 ) {
const matrix = new Matrix4();
const tempMatrix = new Matrix4();
// Track scale for handling negative scale with rotation
let scaleValues = null;
// Iterate FORWARD for Three.js column-vector convention
for ( let i = 0; i < xformOpOrder.length; i ++ ) {
const op = xformOpOrder[ i ];
const isInverse = op.startsWith( '!invert!' );
const opName = isInverse ? op.slice( 8 ) : op;
if ( opName === 'xformOp:transform' ) {
const m = data[ 'xformOp:transform' ];
if ( m && m.length === 16 ) {
tempMatrix.set(
m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
);
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:translate' ) {
const t = data[ 'xformOp:translate' ];
if ( t ) {
tempMatrix.makeTranslation( t[ 0 ], t[ 1 ], t[ 2 ] );
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:translate:pivot' ) {
const t = data[ 'xformOp:translate:pivot' ];
if ( t ) {
tempMatrix.makeTranslation( t[ 0 ], t[ 1 ], t[ 2 ] );
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:scale' ) {
const s = data[ 'xformOp:scale' ];
if ( s ) {
if ( Array.isArray( s ) ) {
tempMatrix.makeScale( s[ 0 ], s[ 1 ], s[ 2 ] );
scaleValues = [ s[ 0 ], s[ 1 ], s[ 2 ] ];
} else {
tempMatrix.makeScale( s, s, s );
scaleValues = [ s, s, s ];
}
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:rotateXYZ' ) {
const r = data[ 'xformOp:rotateXYZ' ];
if ( r ) {
// USD rotateXYZ: matrix = Rx * Ry * Rz
// Three.js Euler 'ZYX' order produces same result
const euler = new Euler(
r[ 0 ] * Math.PI / 180,
r[ 1 ] * Math.PI / 180,
r[ 2 ] * Math.PI / 180,
'ZYX'
);
tempMatrix.makeRotationFromEuler( euler );
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:rotateX' ) {
const r = data[ 'xformOp:rotateX' ];
if ( r !== undefined ) {
tempMatrix.makeRotationX( r * Math.PI / 180 );
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:rotateY' ) {
const r = data[ 'xformOp:rotateY' ];
if ( r !== undefined ) {
tempMatrix.makeRotationY( r * Math.PI / 180 );
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:rotateZ' ) {
const r = data[ 'xformOp:rotateZ' ];
if ( r !== undefined ) {
tempMatrix.makeRotationZ( r * Math.PI / 180 );
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
} else if ( opName === 'xformOp:orient' ) {
const q = data[ 'xformOp:orient' ];
if ( q && q.length === 4 ) {
const quat = new Quaternion( q[ 0 ], q[ 1 ], q[ 2 ], q[ 3 ] );
tempMatrix.makeRotationFromQuaternion( quat );
if ( isInverse ) tempMatrix.invert();
matrix.multiply( tempMatrix );
}
}
}
obj.matrix.copy( matrix );
obj.matrix.decompose( obj.position, obj.quaternion, obj.scale );
// Fix for negative scale: decompose() may absorb negative scale into quaternion
// Restore original scale signs to keep animation consistent
if ( scaleValues ) {
const negX = scaleValues[ 0 ] < 0;
const negY = scaleValues[ 1 ] < 0;
const negZ = scaleValues[ 2 ] < 0;
const negCount = ( negX ? 1 : 0 ) + ( negY ? 1 : 0 ) + ( negZ ? 1 : 0 );
// decompose() absorbs pairs of negative scales into rotation
// For [-1,-1,-1] → [-1,1,1], Y and Z were absorbed, flip quat.y and quat.w
if ( negCount === 3 ) {
obj.scale.set( scaleValues[ 0 ], scaleValues[ 1 ], scaleValues[ 2 ] );
obj.quaternion.set(
obj.quaternion.x,
- obj.quaternion.y,
obj.quaternion.z,
- obj.quaternion.w
);
}
}
return;
}
// Fallback: handle individual transform ops without order
if ( data[ 'xformOp:translate' ] ) {
const t = data[ 'xformOp:translate' ];
obj.position.set( t[ 0 ], t[ 1 ], t[ 2 ] );
}
if ( data[ 'xformOp:translate:pivot' ] ) {
const p = data[ 'xformOp:translate:pivot' ];
obj.pivot = new Vector3( p[ 0 ], p[ 1 ], p[ 2 ] );
}
if ( data[ 'xformOp:scale' ] ) {
const s = data[ 'xformOp:scale' ];
if ( Array.isArray( s ) ) {
obj.scale.set( s[ 0 ], s[ 1 ], s[ 2 ] );
} else {
obj.scale.set( s, s, s );
}
}
if ( data[ 'xformOp:rotateXYZ' ] ) {
const r = data[ 'xformOp:rotateXYZ' ];
obj.rotation.set(
r[ 0 ] * Math.PI / 180,
r[ 1 ] * Math.PI / 180,
r[ 2 ] * Math.PI / 180
);
}
if ( data[ 'xformOp:orient' ] ) {
const q = data[ 'xformOp:orient' ];
if ( q.length === 4 ) {
obj.quaternion.set( q[ 0 ], q[ 1 ], q[ 2 ], q[ 3 ] );
}
}
}
/**
* Build indexes for efficient lookups.
* Called once during compose() to avoid O(n) scans per lookup.
*/
_buildIndexes() {
// childrenByPath: parentPath -> [childName1, childName2, ...]
this.childrenByPath = new Map();
// attributesByPrimPath: primPath -> Map(attrName -> attrSpec)
this.attributesByPrimPath = new Map();
// materialsByRoot: rootPath -> [materialPath1, materialPath2, ...]
this.materialsByRoot = new Map();
// shadersByMaterialPath: materialPath -> [shaderPath1, shaderPath2, ...]
this.shadersByMaterialPath = new Map();
// geomSubsetsByMeshPath: meshPath -> [subsetPath1, subsetPath2, ...]
this.geomSubsetsByMeshPath = new Map();
for ( const path in this.specsByPath ) {
const spec = this.specsByPath[ path ];
if ( spec.specType === SpecType.Prim ) {
// Build parent-child index
const lastSlash = path.lastIndexOf( '/' );
if ( lastSlash > 0 ) {
const parentPath = path.slice( 0, lastSlash );
const childName = path.slice( lastSlash + 1 );
if ( ! this.childrenByPath.has( parentPath ) ) {
this.childrenByPath.set( parentPath, [] );
}
this.childrenByPath.get( parentPath ).push( { name: childName, path: path } );
} else if ( lastSlash === 0 && path.length > 1 ) {
// Direct child of root
const childName = path.slice( 1 );
if ( ! this.childrenByPath.has( '/' ) ) {
this.childrenByPath.set( '/', [] );
}
this.childrenByPath.get( '/' ).push( { name: childName, path: path } );
}
const typeName = spec.fields.typeName;
// Build material index
if ( typeName === 'Material' ) {
const parts = path.split( '/' );
const rootPath = parts.length > 1 ? '/' + parts[ 1 ] : '/';
if ( ! this.materialsByRoot.has( rootPath ) ) {
this.materialsByRoot.set( rootPath, [] );
}
this.materialsByRoot.get( rootPath ).push( path );
}
// Build shader index (shaders are children or descendants of materials)
if ( typeName === 'Shader' && lastSlash > 0 ) {
// Walk up ancestors to find the nearest Material prim.
// Shaders may be direct children of a Material, or nested
// inside a NodeGraph (common with MaterialX materials).
let ancestorPath = path.slice( 0, lastSlash );
while ( ancestorPath.length > 0 ) {
const ancestorSpec = this.specsByPath[ ancestorPath ];
if ( ancestorSpec && ancestorSpec.specType === SpecType.Prim && ancestorSpec.fields.typeName === 'Material' ) {
if ( ! this.shadersByMaterialPath.has( ancestorPath ) ) {
this.shadersByMaterialPath.set( ancestorPath, [] );
}
this.shadersByMaterialPath.get( ancestorPath ).push( path );
break;
}
const slash = ancestorPath.lastIndexOf( '/' );
if ( slash <= 0 ) break;
ancestorPath = ancestorPath.slice( 0, slash );
}
}
// Build GeomSubset index (subsets are children of meshes)
if ( typeName === 'GeomSubset' && lastSlash > 0 ) {
const meshPath = path.slice( 0, lastSlash );
if ( ! this.geomSubsetsByMeshPath.has( meshPath ) ) {
this.geomSubsetsByMeshPath.set( meshPath, [] );
}
this.geomSubsetsByMeshPath.get( meshPath ).push( path );
}
} else if ( spec.specType === SpecType.Attribute || spec.specType === SpecType.Relationship ) {
// Build attribute index
const dotIndex = path.lastIndexOf( '.' );
if ( dotIndex > 0 ) {
const primPath = path.slice( 0, dotIndex );
const attrName = path.slice( dotIndex + 1 );
if ( ! this.attributesByPrimPath.has( primPath ) ) {
this.attributesByPrimPath.set( primPath, new Map() );
}
this.attributesByPrimPath.get( primPath ).set( attrName, spec );
}
}
}
}
/**
* Check if a path is a direct child of parentPath.
*/
_isDirectChild( parentPath, path, prefix ) {
if ( ! path.startsWith( prefix ) ) return false;
const remainder = path.slice( prefix.length );
if ( remainder.length === 0 ) return false;
// Check for variant paths or simple names
if ( remainder.startsWith( '{' ) ) {
return false; // Variant paths are not direct children
}
return ! remainder.includes( '/' );
}
/**
* Build the scene hierarchy recursively.
* Uses childrenByPath index for O(1) child lookup instead of O(n) iteration.
*/
_buildHierarchy( parent, parentPath ) {
// Collect children from parentPath and any active variant paths
const childEntries = [];
const seenPaths = new Set();
// Get direct children using the index
const directChildren = this.childrenByPath.get( parentPath );
if ( directChildren ) {
for ( const child of directChildren ) {
if ( ! seenPaths.has( child.path ) ) {
seenPaths.add( child.path );
childEntries.push( child );
}
}
}
// Also get children from active variant paths
const variantPaths = this._getVariantPaths( parentPath );
for ( const vp of variantPaths ) {
const variantChildren = this.childrenByPath.get( vp );
if ( variantChildren ) {
for ( const child of variantChildren ) {
if ( ! seenPaths.has( child.path ) ) {
seenPaths.add( child.path );
childEntries.push( child );
}
}
}
}
// Process each child
for ( const { name, path } of childEntries ) {
const spec = this.specsByPath[ path ];
if ( ! spec || spec.specType !== SpecType.Prim ) continue;
const typeName = spec.fields.typeName;
// Check for references/payloads
const refValues = this._getReferences( spec );
if ( refValues.length > 0 ) {
// Get local variant selections from this prim
const localVariants = this._getLocalVariantSelections( spec.fields );
// Resolve all references
const resolvedGroups = [];
for ( const refValue of refValues ) {
const referencedGroup = this._resolveReference( refValue, localVariants );
if ( referencedGroup ) resolvedGroups.push( referencedGroup );
}
if ( resolvedGroups.length > 0 ) {
const attrs = this._getAttributes( path );
// Single reference with single mesh: use optimized path
// This handles the USDZExporter pattern: Xform references geometry file
if ( resolvedGroups.length === 1 ) {
const singleMesh = this._findSingleMesh( resolvedGroups[ 0 ] );
if ( singleMesh && ( typeName === 'Xform' || ! typeName ) ) {
// Merge the mesh into this prim
singleMesh.name = name;
this.applyTransform( singleMesh, spec.fields, attrs );
// Apply material binding from the referencing prim if present
this._applyMaterialBinding( singleMesh, path );
parent.add( singleMesh );
// Still build local children (overrides)
this._buildHierarchy( singleMesh, path );
continue;
}
}
// Create a container for the referenced content
const obj = new Object3D();
obj.name = name;
this.applyTransform( obj, spec.fields, attrs );
// Add all children from all resolved references
for ( const referencedGroup of resolvedGroups ) {
while ( referencedGroup.children.length > 0 ) {
obj.add( referencedGroup.children[ 0 ] );
}
}
parent.add( obj );
// Still build local children (overrides)
this._buildHierarchy( obj, path );
continue;
}
}
// Build appropriate object based on type
if ( typeName === 'SkelRoot' ) {
// Skeletal root - treat as transform but track for skeleton binding
const obj = new Object3D();
obj.name = name;
obj.userData.isSkelRoot = true;
const attrs = this._getAttributes( path );
this.applyTransform( obj, spec.fields, attrs );
parent.add( obj );
this._buildHierarchy( obj, path );
} else if ( typeName === 'Skeleton' ) {
// Build skeleton and store it
const skeleton = this._buildSkeleton( path );
if ( skeleton ) {
this.skeletons[ path ] = skeleton;
}
// Recursively build children (may contain SkelAnimation)
this._buildHierarchy( parent, path );
} else if ( typeName === 'SkelAnimation' ) {
// Skip - animations are processed separately in _buildAnimations
} else if ( typeName === 'Mesh' ) {
const obj = this._buildMesh( path, spec );
if ( obj ) {
parent.add( obj );
this._buildHierarchy( obj, path );
}
} else if ( typeName === 'Camera' ) {
const obj = this._buildCamera( path );
obj.name = name;
const attrs = this._getAttributes( path );
this.applyTransform( obj, spec.fields, attrs );
parent.add( obj );
this._buildHierarchy( obj, path );
} else if ( typeName === 'DistantLight' || typeName === 'SphereLight' || typeName === 'RectLight' || typeName === 'DiskLight' ) {
const obj = this._buildLight( path, typeName );
obj.name = name;
const attrs = this._getAttributes( path );
this.applyTransform( obj, spec.fields, attrs );
parent.add( obj );
this._buildHierarchy( obj, path );
} else if ( typeName === 'Cube' || typeName === 'Sphere' || typeName === 'Cylinder' || typeName === 'Cone' || typeName === 'Capsule' ) {
const obj = this._buildGeomPrimitive( path, spec, typeName );
if ( obj ) {
parent.add( obj );
this._buildHierarchy( obj, path );
}
} else if ( typeName === 'Material' || typeName === 'Shader' || typeName === 'GeomSubset' ) {
// Skip materials/shaders/subsets, they're referenced by meshes
} else {
// Transform node, group, or unknown type
const obj = new Object3D();
obj.name = name;
const attrs = this._getAttributes( path );
this.applyTransform( obj, spec.fields, attrs );
parent.add( obj );
this._buildHierarchy( obj, path );
}
}
}
/**
* Get variant paths for a parent path based on variant selections.
*/
_getVariantPaths( parentPath ) {
const parentSpec = this.specsByPath[ parentPath ];
const variantSetChildren = parentSpec?.fields?.variantSetChildren;
const variantPaths = [];
if ( ! variantSetChildren || variantSetChildren.length === 0 ) {
return variantPaths;
}
for ( const variantSetName of variantSetChildren ) {
// External selections take priority
let selectedVariant = this.externalVariantSelections[ variantSetName ] || null;
// Fall back to file's internal selection
if ( ! selectedVariant ) {
const variantSelection = parentSpec.fields.variantSelection;
selectedVariant = variantSelection ? variantSelection[ variantSetName ] : null;
}
// Fall back to first variant child
if ( ! selectedVariant ) {
const variantSetPath = parentPath + '/{' + variantSetName + '=}';
const variantSetSpec = this.specsByPath[ variantSetPath ];
if ( variantSetSpec?.fields?.variantChildren ) {
selectedVariant = variantSetSpec.fields.variantChildren[ 0 ];
}
}
if ( selectedVariant ) {
const variantPath = parentPath + '/{' + variantSetName + '=' + selectedVariant + '}';
variantPaths.push( variantPath );
}
}
return variantPaths;
}
/**
* Resolve a file path relative to basePath.
*/
_resolveFilePath( refPath ) {
let cleanPath = refPath;
// Remove ./ prefix
if ( cleanPath.startsWith( './' ) ) {
cleanPath = cleanPath.slice( 2 );
}
if ( ! this.basePath ) return cleanPath;
// LoaderUtils.resolveURL expects basePath to end with a separator;
// the USDZ flow passes the zip-internal directory name without one.
const base = this.basePath.endsWith( '/' ) ? this.basePath : this.basePath + '/';
return LoaderUtils.resolveURL( cleanPath, base );
}
/**
* Resolve a USD reference and return the composed content.
* @param {string} refValue - Reference value like "@./path/to/file.usdc@"
* @param {Object} localVariants - Variant selections to apply
* @returns {Group|null} Composed content or null
*/
_resolveReference( refValue, localVariants = {} ) {
if ( ! refValue ) return null;
const match = refValue.match( /@([^@]+)@(?:<([^>]+)>)?/ );
if ( ! match ) return null;
const filePath = match[ 1 ];
const primPath = match[ 2 ]; // e.g., "/Geometry"
const resolvedPath = this._resolveFilePath( filePath );
// Merge variant selections - external takes priority, then local
const mergedVariants = { ...localVariants, ...this.externalVariantSelections };
// Look up pre-parsed data in assets
const referencedData = this.assets[ resolvedPath ];
if ( ! referencedData ) return null;
// If it's specsByPath data, compose it
if ( referencedData.specsByPath ) {
const composer = new USDComposer( this.manager );
const newBasePath = this._getBasePath( resolvedPath );
const composedGroup = composer.compose( referencedData, this.assets, mergedVariants, newBasePath );
// If a primPath is specified, find and return just that subtree
if ( primPath ) {
const primName = primPath.split( '/' ).pop();
// Find the direct child with this name (not a deep search)
// This is important because there may be multiple objects with the same name
let targetObject = null;
for ( const child of composedGroup.children ) {
if ( child.name === primName ) {
targetObject = child;
break;
}
}
if ( targetObject ) {
// Detach from parent for re-parenting
composedGroup.remove( targetObject );
// Wrap in a group to maintain consistent return type
const wrapper = new Group();
wrapper.add( targetObject );
return wrapper;
}
}
return composedGroup;
}
// If it's already a Three.js Group (legacy support), clone it
if ( referencedData.isGroup || referencedData.isObject3D ) {
return referencedData.clone();
}
return null;
}
/**
* Find a single mesh in the group's shallow hierarchy.
* Only returns a mesh if it's at depth 0 or 1, not deeply nested.
* This preserves transforms in complex hierarchies like Kitchen Set
* while supporting USDZExporter round-trip (Xform > Xform > Mesh pattern).
*/
_findSingleMesh( group ) {
// Check direct children first
for ( const child of group.children ) {
if ( child.isMesh ) {
group.remove( child );
return child;
}
}
// Check grandchildren (USDZExporter pattern: Xform > Geometry > Mesh)
// Only if there's exactly one child with exactly one grandchild
if ( group.children.length === 1 ) {
const child = group.children[ 0 ];
if ( child.children && child.children.length === 1 ) {
const grandchild = child.children[ 0 ];
if ( grandchild.isMesh && ! this._hasNonIdentityTransform( child ) ) {
// Safe to merge - intermediate has identity transform
child.remove( grandchild );
return grandchild;
}
}
}
return null;
}
/**
* Check if an object has a non-identity local transform.
*/
_hasNonIdentityTransform( obj ) {
const pos = obj.position;
const rot = obj.rotation;
const scale = obj.scale;
const hasPosition = pos.x !== 0 || pos.y !== 0 || pos.z !== 0;
const hasRotation = rot.x !== 0 || rot.y !== 0 || rot.z !== 0;
const hasScale = scale.x !== 1 || scale.y !== 1 || scale.z !== 1;
return hasPosition || hasRotation || hasScale;
}
/**
* Get the base path (directory) from a file path.
*/
_getBasePath( filePath ) {
const lastSlash = filePath.lastIndexOf( '/' );
return lastSlash >= 0 ? filePath.slice( 0, lastSlash ) : '';
}
/**
* Extract variant selections from a spec's fields.
*/
_getLocalVariantSelections( fields ) {
const variants = {};
if ( fields.variantSelection ) {
for ( const key in fields.variantSelection ) {
variants[ key ] = fields.variantSelection[ key ];
}
}
return variants;
}
/**
* Get all reference values from a prim spec.
* @returns {string[]} Array of reference strings like "@path@" or "@path@<prim>"
*/
_getReferences( spec ) {
const results = [];
if ( spec.fields.references && spec.fields.references.length > 0 ) {
const ref = spec.fields.references[ 0 ];
if ( typeof ref === 'string' ) {
// Extract all @...@ references (handles both single and array values)
const matches = ref.matchAll( /@([^@]+)@(?:<([^>]+)>)?/g );
for ( const match of matches ) {
results.push( match[ 0 ] );
}
} else if ( ref.assetPath ) {
results.push( '@' + ref.assetPath + '@' );
}
}
if ( results.length === 0 && spec.fields.payload ) {
const payload = spec.fields.payload;
if ( typeof payload === 'string' ) results.push( payload );
else if ( payload.assetPath ) results.push( '@' + payload.assetPath + '@' );
}
return results;
}
/**
* Resolve an attribute's authored value, following connections before using
* local fallback values.
*/
_resolveAttributeValue( path, visited = new Set() ) {
const cleanPath = String( path ).replace( /<|>/g, '' );
if ( visited.has( cleanPath ) ) return undefined;
const fields = this.specsByPath[ cleanPath ]?.fields;
if ( ! fields ) return undefined;
const nextVisited = new Set( visited );
nextVisited.add( cleanPath );
if ( fields.connectionPaths ) {
for ( const connectionPath of fields.connectionPaths ) {
const value = this._resolveAttributeValue( connectionPath, nextVisited );
if ( value !== undefined ) return value;
}
}
if ( fields.default !== undefined ) return fields.default;
const { times, values } = fields.timeSamples || {};
if ( times && values && times.length > 0 ) {
// Find time 0, or use the first available time (rest pose).
const index = times.indexOf( 0 );
return values[ index >= 0 ? index : 0 ];
}
return undefined;
}
/**
* Get attributes for a path from attribute specs.
*/
_getAttributes( path ) {
const attrs = {};
this._collectAttributesFromPath( path, attrs );
// Collect overrides from sibling variants (when path is inside a variant)
const variantMatch = path.match( VARIANT_PATH_REGEX );
if ( variantMatch ) {
const basePath = variantMatch[ 1 ];
const relativePath = variantMatch[ 4 ];
const variantPaths = this._getVariantPaths( basePath );
for ( const vp of variantPaths ) {
if ( path.startsWith( vp ) ) continue;
const overridePath = vp + '/' + relativePath;
this._collectAttributesFromPath( overridePath, attrs );
}
} else {
// Check for variant overrides at ancestor levels
const parts = path.split( '/' );
for ( let i = 1; i < parts.length - 1; i ++ ) {
const ancestorPath = parts.slice( 0, i + 1 ).join( '/' );
const relativePath = parts.slice( i + 1 ).join( '/' );
const variantPaths = this._getVariantPaths( ancestorPath );
for ( const vp of variantPaths ) {
const overridePath = vp + '/' + relativePath;
this._collectAttributesFromPath( overridePath, attrs );
}
}
}
return attrs;
}
_collectAttributesFromPath( path, attrs ) {
// Use the attribute index for O(1) lookup instead of O(n) iteration
const attrMap = this.attributesByPrimPath.get( path );
if ( ! attrMap ) return;
for ( const [ attrName, attrSpec ] of attrMap ) {
const value = this._resolveAttributeValue( path + '.' + attrName );
if ( value !== undefined ) {
attrs[ attrName ] = value;
}
if ( attrSpec.fields?.elementSize !== undefined ) {
attrs[ attrName + ':elementSize' ] = attrSpec.fields.elementSize;
}
if ( attrName.startsWith( 'primvars:' ) && attrSpec.fields?.typeName !== undefined ) {
attrs[ attrName + ':typeName' ] = attrSpec.fields.typeName;
}
}
}
/**
* Build a mesh from a USD geometric primitive (Cube, Sphere, Cylinder, Cone, Capsule).
*/
_buildGeomPrimitive( path, spec, typeName ) {
const attrs = this._getAttributes( path );
const name = path.split( '/' ).pop();
let geometry;
switch ( typeName ) {
case 'Cube': {
const size = attrs[ 'size' ] || 2;
geometry = new BoxGeometry( size, size, size );
break;
}
case 'Sphere': {
const radius = attrs[ 'radius' ] || 1;
geometry = new SphereGeometry( radius, 32, 16 );
break;
}
case 'Cylinder': {
const height = attrs[ 'height' ] || 2;
const radius = attrs[ 'radius' ] || 1;
geometry = new CylinderGeometry( radius, radius, height, 32 );
break;
}
case 'Cone': {
const height = attrs[ 'height' ] || 2;
const radius = attrs[ 'radius' ] || 1;
geometry = new ConeGeometry( radius, height, 32 );
break;
}
case 'Capsule': {
const height = attrs[ 'height' ] || 1;
const radius = attrs[ 'radius' ] || 0.5;
geometry = new CapsuleGeometry( radius, height, 16, 32 );
break;
}
}
// USD defaults axis to "Z", Three.js uses Y
const axis = attrs[ 'axis' ] || 'Z';
if ( axis === 'X' ) {
geometry.rotateZ( - Math.PI / 2 );
} else if ( axis === 'Z' ) {
geometry.rotateX( Math.PI / 2 );
}
const material = this._buildMaterial( path, spec.fields );
const mesh = new Mesh( geometry, material );
mesh.name = name;
this.applyTransform( mesh, spec.fields, attrs );
return mesh;
}
/**
* Build a mesh from a Mesh spec.
*/
_buildMesh( path, spec ) {
const attrs = this._getAttributes( path );
// Check for skinning data
const jointIndices = attrs[ 'primvars:skel:jointIndices' ];
const jointWeights = attrs[ 'primvars:skel:jointWeights' ];
const hasSkinning = jointIndices && jointWeights &&
jointIndices.length > 0 && jointWeights.length > 0;
// Collect GeomSubsets for multi-material support
const geomSubsets = this._getGeomSubsets( path );
let geometry, material;
if ( geomSubsets.length > 0 ) {
geometry = this._buildGeometryWithSubsets( attrs, geomSubsets, hasSkinning );
const meshMaterialPath = this._getMaterialPath( path, spec.fields );
material = geomSubsets.map( subset => {
const matPath = subset.materialPath || meshMaterialPath;
return this._buildMaterialForPath( matPath );
} );
} else {
geometry = this._buildGeometry( path, attrs, hasSkinning );
material = this._buildMaterial( path, spec.fields );
}
const displayColor = attrs[ 'primvars:displayColor' ];
if ( displayColor && displayColor.length >= 3 ) {
const applyDisplayColor = ( mat ) => {
if ( mat.color && mat.color.r === 1 && mat.color.g === 1 && mat.color.b === 1 && ! mat.map ) {
mat.color.setRGB( displayColor[ 0 ], displayColor[ 1 ], displayColor[ 2 ], SRGBColorSpace );
}
};
if ( Array.isArray( material ) ) {
material.forEach( applyDisplayColor );
} else {
applyDisplayColor( material );
}
}
const displayOpacity = attrs[ 'primvars:displayOpacity' ];
if ( displayOpacity && displayOpacity.length === 1 && geomSubsets.length === 0 ) {
const opacity = displayOpacity[ 0 ];
const applyDisplayOpacity = ( mat ) => {
if ( opacity < 1 && mat.opacity === 1 && mat.transparent === false ) {
mat.opacity = opacity;
mat.transparent = true;
}
};
if ( Array.isArray( material ) ) {
material.forEach( applyDisplayOpacity );
} else {
applyDisplayOpacity( material );
}
}
let mesh;
if ( hasSkinning ) {
mesh = new SkinnedMesh( geometry, material );
// Find skeleton path from skel:skeleton relationship
let skelBindingSpec = this.specsByPath[ path + '.skel:skeleton' ];
if ( ! skelBindingSpec ) {
skelBindingSpec = this.specsByPath[ path + '.rel skel:skeleton' ];
}
let skeletonPath = null;
if ( skelBindingSpec ) {
if ( skelBindingSpec.fields.targetPaths && skelBindingSpec.fields.targetPaths.length > 0 ) {
skeletonPath = skelBindingSpec.fields.targetPaths[ 0 ];
} else if ( skelBindingSpec.fields.default ) {
skeletonPath = skelBindingSpec.fields.default.replace( /<|>/g, '' );
}
}
// Get per-mesh joint mapping
const localJoints = attrs[ 'skel:joints' ];
// Get geomBindTransform if present
const geomBindTransform = attrs[ 'primvars:skel:geomBindTransform' ];
this.skinnedMeshes.push( { mesh, skeletonPath, path, localJoints, geomBindTransform } );
} else {
mesh = new Mesh( geometry, material );
}
mesh.name = path.split( '/' ).pop();
this.applyTransform( mesh, spec.fields, attrs );
return mesh;
}
/**
* Build a camera from a Camera spec.
*/
_buildCamera( path ) {
const attrs = this._getAttributes( path );
const projectionToken = attrs[ 'projection' ];
const projection = typeof projectionToken === 'string'
? projectionToken.toLowerCase()
: USD_CAMERA_DEFAULTS.projection;
const clippingRange = attrs[ 'clippingRange' ] || USD_CAMERA_DEFAULTS.clippingRange;
const near = Math.max(
Number.EPSILON,
this._parseNumber( clippingRange[ 0 ], USD_CAMERA_DEFAULTS.clippingRange[ 0 ] )
);
const far = Math.max(
near + Number.EPSILON,
this._parseNumber( clippingRange[ 1 ], USD_CAMERA_DEFAULTS.clippingRange[ 1 ] )
);
const horizontalAperture = this._parseNumber(
attrs[ 'horizontalAperture' ],
USD_CAMERA_DEFAULTS.horizontalAperture
);
const verticalAperture = this._parseNumber(
attrs[ 'verticalAperture' ],
USD_CAMERA_DEFAULTS.verticalAperture
);
const horizontalApertureOffset = this._parseNumber(
attrs[ 'horizontalApertureOffset' ],
USD_CAMERA_DEFAULTS.horizontalApertureOffset
);
const verticalApertureOffset = this._parseNumber(
attrs[ 'verticalApertureOffset' ],
USD_CAMERA_DEFAULTS.verticalApertureOffset
);
const focalLength = this._parseNumber( attrs[ 'focalLength' ], USD_CAMERA_DEFAULTS.focalLength );
const focusDistance = this._parseNumber( attrs[ 'focusDistance' ], USD_CAMERA_DEFAULTS.focusDistance );
const fStop = this._parseNumber( attrs[ 'fStop' ], USD_CAMERA_DEFAULTS.fStop );
let camera;
if ( projection === 'orthographic' ) {
// USD orthographic apertures are in tenths of a world unit.
const width = horizontalAperture / 10;
const height = verticalAperture / 10;
const offsetX = horizontalApertureOffset / 10;
const offsetY = verticalApertureOffset / 10;
camera = new OrthographicCamera(
offsetX - width * 0.5,
offsetX + width * 0.5,
offsetY + height * 0.5,
offsetY - height * 0.5,
near,
far
);
} else {
const safeVerticalAperture = Math.max( Number.EPSILON, verticalAperture );
const safeFocalLength = Math.max( Number.EPSILON, focalLength );
const aspect = horizontalAperture / safeVerticalAperture;
const fov = 2 * Math.atan( safeVerticalAperture / ( 2 * safeFocalLength ) ) * 180 / Math.PI;
camera = new PerspectiveCamera( fov, aspect, near, far );
camera.filmGauge = Math.max( horizontalAperture, verticalAperture );
camera.filmOffset = horizontalApertureOffset;
camera.focus = focusDistance;
camera.setFocalLength( safeFocalLength );
if ( verticalApertureOffset !== 0 ) {
// Three.js supports only horizontal film offset directly.
camera.userData.verticalApertureOffset = verticalApertureOffset;
}
}
camera.userData.fStop = fStop;
camera.userData.usdProjection = projection;
return camera;
}
/**
* Build a light from a UsdLux light spec.
*/
_buildLight( path, typeName ) {
const attrs = this._getAttributes( path );
const intensity = this._parseNumber( attrs[ 'inputs:intensity' ], 1 );
const baseColor = attrs[ 'inputs:color' ] || [ 1, 1, 1 ];
const enableColorTemperature = attrs[ 'inputs:enableColorTemperature' ] === true;
const colorTemperature = this._parseNumber( attrs[ 'inputs:colorTemperature' ], 6500 );
const color = new Color( baseColor[ 0 ], baseColor[ 1 ], baseColor[ 2 ] );
if ( enableColorTemperature ) {
const temp = this._colorTemperature( colorTemperature );
color.multiply( temp );
}
let light;
switch ( typeName ) {
case 'DistantLight':
light = new DirectionalLight( color, intensity );
break;
case 'SphereLight': {
const coneAngle = this._parseNumber( attrs[ 'shaping:cone:angle' ], 0 );
if ( coneAngle > 0 ) {
const angle = coneAngle * Math.PI / 180;
const softness = this._parseNumber( attrs[ 'shaping:cone:softness' ], 0 );
light = new SpotLight( color, intensity, 0, angle, softness );
} else {
light = new PointLight( color, intensity );
}
break;
}
case 'RectLight': {
const width = this._parseNumber( attrs[ 'inputs:width' ], 1 );
const height = this._parseNumber( attrs[ 'inputs:height' ], 1 );
light = new RectAreaLight( color, intensity, width, height );
break;
}
case 'DiskLight': {
const radius = this._parseNumber( attrs[ 'inputs:radius' ], 0.5 );
const side = radius * 2;
light = new RectAreaLight( color, intensity, side, side );
break;
}
}
return light;
}
/**
* Convert a color temperature in Kelvin to an RGB Color.
* Based on Tanner Helland's algorithm.
*/
_colorTemperature( kelvin ) {
const temp = kelvin / 100;
let r, g, b;
if ( temp <= 66 ) {
r = 1;
g = 0.39008157876901960784 * Math.log( temp ) - 0.63184144378862745098;
} else {
r = 1.29293618606274509804 * Math.pow( temp - 60, - 0.1332047592 );
g = 1.12989086089529411765 * Math.pow( temp - 60, - 0.0755148492 );
}
if ( temp >= 66 ) {
b = 1;
} else if ( temp <= 19 ) {
b = 0;
} else {
b = 0.54320678911019607843 * Math.log( temp - 10 ) - 1.19625408914;
}
return new Color(
Math.min( Math.max( r, 0 ), 1 ),
Math.min( Math.max( g, 0 ), 1 ),
Math.min( Math.max( b, 0 ), 1 )
);
}
_parseNumber( value, fallback ) {
const n = Number( value );
return Number.isFinite( n ) ? n : fallback;
}
_getGeomSubsets( meshPath ) {
const subsets = [];
const subsetPaths = this.geomSubsetsByMeshPath.get( meshPath );
if ( ! subsetPaths ) return subsets;
for ( const p of subsetPaths ) {
const attrs = this._getAttributes( p );
const indices = attrs[ 'indices' ];
if ( ! indices || indices.length === 0 ) continue;
// Get material binding - check direct path and variant paths
const materialPath = this._getMaterialBindingTarget( p );
subsets.push( {
name: p.split( '/' ).pop(),
indices: indices,
materialPath: materialPath
} );
}
return subsets;
}
/**
* Get the material binding relationship for a prim, including overrides from
* active variants.
*/
_getMaterialBindingSpec( primPath ) {
const attrName = 'material:binding';
const directPath = primPath + '.' + attrName;
let bindingSpec = this.specsByPath[ directPath ] || null;
// A variant on any ancestor may override this prim's relationship.
const parts = primPath.split( '/' );
for ( let i = 1; i < parts.length; i ++ ) {
const ancestorPath = parts.slice( 0, i + 1 ).join( '/' );
const relativePath = parts.slice( i + 1 ).join( '/' );
const variantPaths = this._getVariantPaths( ancestorPath );
for ( const vp of variantPaths ) {
const overridePath = relativePath ? vp + '/' + relativePath + '.' + attrName : vp + '.' + attrName;
const overrideSpec = this.specsByPath[ overridePath ];
if ( overrideSpec?.fields?.targetPaths?.length > 0 ) {
bindingSpec = overrideSpec;
}
}
}
return bindingSpec;
}
/**
* Get the resolved material binding target for a prim. Material bindings are
* inherited, and an ancestor marked strongerThanDescendants takes precedence
* over bindings authored on its descendants.
*/
_getMaterialBindingTarget( primPath ) {
const parts = primPath.split( '/' ).filter( Boolean );
let resolvedBinding = null;
for ( let i = 0; i < parts.length; i ++ ) {
const ancestorPath = '/' + parts.slice( 0, i + 1 ).join( '/' );
const bindingSpec = this._getMaterialBindingSpec( ancestorPath );
if ( ! bindingSpec?.fields?.targetPaths?.length ) continue;
if ( ! resolvedBinding || resolvedBinding.fields?.bindMaterialAs !== 'strongerThanDescendants' ) {
resolvedBinding = bindingSpec;
}
}
return resolvedBinding?.fields.targetPaths[ 0 ] || null;
}
_buildGeometry( path, fields, hasSkinning = false ) {
const geometry = new BufferGeometry();
const points = fields[ 'points' ];
if ( ! points || points.length === 0 ) return geometry;
const faceVertexIndices = fields[ 'faceVertexIndices' ];
const faceVertexCounts = fields[ 'faceVertexCounts' ];
// Parse polygon holes (Arnold format: [holeFaceIdx, parentFaceIdx, ...])
const polygonHoles = fields[ 'primvars:arnold:polygon_holes' ];
const holeMap = this._buildHoleMap( polygonHoles );
// Compute triangulation pattern once using actual vertex positions
// This pattern will be reused for normals, UVs, etc.
let indices = faceVertexIndices;
let triPattern = null;
if ( faceVertexCounts && faceVertexCounts.length > 0 ) {
const result = this._triangulateIndicesWithPattern( faceVertexIndices, faceVertexCounts, points, holeMap );
indices = result.indices;
triPattern = result.pattern;
}
let positions = points;
if ( indices && indices.length > 0 ) {
positions = this._expandAttribute( points, indices, 3 );
}
geometry.setAttribute( 'position', new BufferAttribute( new Float32Array( positions ), 3 ) );
const normals = fields[ 'normals' ] || fields[ 'primvars:normals' ];
const normalIndicesRaw = fields[ 'normals:indices' ] || fields[ 'primvars:normals:indices' ];
if ( normals && normals.length > 0 ) {
let normalData = normals;
if ( normalIndicesRaw && normalIndicesRaw.length > 0 && triPattern ) {
// Indexed normals - apply triangulation pattern to indices
const triangulatedNormalIndices = this._applyTriangulationPattern( normalIndicesRaw, triPattern );
normalData = this._expandAttribute( normals, triangulatedNormalIndices, 3 );
} else if ( normals.length === points.length ) {
// Per-vertex normals
if ( indices && indices.length > 0 ) {
normalData = this._expandAttribute( normals, indices, 3 );
}
} else if ( triPattern ) {
// Per-face-vertex normals (no separate indices) - use same triangulation pattern
const normalIndices = this._applyTriangulationPattern(
Array.from( { length: normals.length / 3 }, ( _, i ) => i ),
triPattern
);
normalData = this._expandAttribute( normals, normalIndices, 3 );
}
geometry.setAttribute( 'normal', new BufferAttribute( new Float32Array( normalData ), 3 ) );
} else {
// Compute vertex normals from the original indexed topology where
// vertices are shared, then expand them like positions.
const vertexNormals = this._computeVertexNormals( points, indices );
geometry.setAttribute( 'normal', new BufferAttribute( new Float32Array(
this._expandAttribute( vertexNormals, indices, 3 )
), 3 ) );
}
const { uvs, uvIndices } = this._findUVPrimvar( fields );
const numFaceVertices = faceVertexIndices ? faceVertexIndices.length : 0;
if ( uvs && uvs.length > 0 ) {
let uvData = uvs;
if ( uvIndices && uvIndices.length > 0 && triPattern ) {
const triangulatedUvIndices = this._applyTriangulationPattern( uvIndices, triPattern );
uvData = this._expandAttribute( uvs, triangulatedUvIndices, 2 );
} else if ( indices && uvs.length / 2 === points.length / 3 ) {
uvData = this._expandAttribute( uvs, indices, 2 );
} else if ( triPattern && uvs.length / 2 === numFaceVertices ) {
// Per-face-vertex UVs (faceVarying, no separate indices)
const uvIndicesFromPattern = this._applyTriangulationPattern(
Array.from( { length: numFaceVertices }, ( _, i ) => i ),
triPattern
);
uvData = this._expandAttribute( uvs, uvIndicesFromPattern, 2 );
}
geometry.setAttribute( 'uv', new BufferAttribute( new Float32Array( uvData ), 2 ) );
}
// Second UV set (st1) for lightmaps/AO
const { uvs2, uv2Indices } = this._findUV2Primvar( fields );
if ( uvs2 && uvs2.length > 0 ) {
let uv2Data = uvs2;
if ( uv2Indices && uv2Indices.length > 0 && triPattern ) {
const triangulatedUv2Indices = this._applyTriangulationPattern( uv2Indices, triPattern );
uv2Data = this._expandAttribute( uvs2, triangulatedUv2Indices, 2 );
} else if ( indices && uvs2.length / 2 === points.length / 3 ) {
uv2Data = this._expandAttribute( uvs2, indices, 2 );
} else if ( triPattern && uvs2.length / 2 === numFaceVertices ) {
// Per-face-vertex UV2 (faceVarying, no separate indices)
const uv2IndicesFromPattern = this._applyTriangulationPattern(
Array.from( { length: numFaceVertices }, ( _, i ) => i ),
triPattern
);
uv2Data = this._expandAttribute( uvs2, uv2IndicesFromPattern, 2 );
}
geometry.setAttribute( 'uv1', new BufferAttribute( new Float32Array( uv2Data ), 2 ) );
}
// Add skinning attributes
if ( hasSkinning ) {
const jointIndices = fields[ 'primvars:skel:jointIndices' ];
const jointWeights = fields[ 'primvars:skel:jointWeights' ];
const elementSize = fields[ 'primvars:skel:jointIndices:elementSize' ] || 4;
if ( jointIndices && jointWeights ) {
const numVertices = positions.length / 3;
let skinIndexData, skinWeightData;
if ( indices && indices.length > 0 ) {
skinIndexData = this._expandAttribute( jointIndices, indices, elementSize );
skinWeightData = this._expandAttribute( jointWeights, indices, elementSize );
} else {
skinIndexData = jointIndices;
skinWeightData = jointWeights;
}
const skinIndices = new Uint16Array( numVertices * 4 );
const skinWeights = new Float32Array( numVertices * 4 );
this._selectTopWeights( skinIndexData, skinWeightData, elementSize, numVertices, skinIndices, skinWeights );
geometry.setAttribute( 'skinIndex', new BufferAttribute( skinIndices, 4 ) );
geometry.setAttribute( 'skinWeight', new BufferAttribute( skinWeights, 4 ) );
}
}
return geometry;
}
_buildGeometryWithSubsets( fields, geomSubsets, hasSkinning = false ) {
const geometry = new BufferGeometry();
const points = fields[ 'points' ];
if ( ! points || points.length === 0 ) return geometry;
const faceVertexIndices = fields[ 'faceVertexIndices' ];
const faceVertexCounts = fields[ 'faceVertexCounts' ];
if ( ! faceVertexCounts || faceVertexCounts.length === 0 ) return geometry;
const polygonHoles = fields[ 'primvars:arnold:polygon_holes' ];
const holeMap = this._buildHoleMap( polygonHoles );
const holeFaces = holeMap.holeFaces;
const parentToHoles = holeMap.parentToHoles;
const { uvs, uvIndices } = this._findUVPrimvar( fields );
const { uvs2, uv2Indices } = this._findUV2Primvar( fields );
const normals = fields[ 'normals' ] || fields[ 'primvars:normals' ];
const normalIndicesRaw = fields[ 'normals:indices' ] || fields[ 'primvars:normals:indices' ];
const jointIndices = hasSkinning ? fields[ 'primvars:skel:jointIndices' ] : null;
const jointWeights = hasSkinning ? fields[ 'primvars:skel:jointWeights' ] : null;
const elementSize = fields[ 'primvars:skel:jointIndices:elementSize' ] || 4;
// Build face-to-triangle mapping (accounting for holes)
const faceTriangleOffset = [];
let triangleCount = 0;
for ( let i = 0; i < faceVertexCounts.length; i ++ ) {
faceTriangleOffset.push( triangleCount );
// Skip hole faces - they're triangulated with their parent
if ( holeFaces.has( i ) ) continue;
const count = faceVertexCounts[ i ];
const holes = parentToHoles.get( i );
if ( holes && holes.length > 0 ) {
// For faces with holes, count triangles based on total vertices
// Earcut produces (total_vertices - 2) triangles for any polygon including holes
let totalVerts = count;
for ( const holeIdx of holes ) {
totalVerts += faceVertexCounts[ holeIdx ];
}
triangleCount += totalVerts - 2;
} else if ( count >= 3 ) {
triangleCount += count - 2;
}
}
const triangleToSubset = new Int32Array( triangleCount ).fill( - 1 );
for ( let si = 0; si < geomSubsets.length; si ++ ) {
const subset = geomSubsets[ si ];
for ( let i = 0; i < subset.indices.length; i ++ ) {
const faceIdx = subset.indices[ i ];
if ( faceIdx >= faceVertexCounts.length ) continue;
const triStart = faceTriangleOffset[ faceIdx ];
const triCount = faceVertexCounts[ faceIdx ] - 2;
for ( let t = 0; t < triCount; t ++ ) {
triangleToSubset[ triStart + t ] = si;
}
}
}
// Sort triangles by subset
const sortedTriangles = [];
for ( let tri = 0; tri < triangleCount; tri ++ ) {
sortedTriangles.push( { original: tri, subset: triangleToSubset[ tri ] } );
}
sortedTriangles.sort( ( a, b ) => a.subset - b.subset );
const groups = [];
let currentSubset = sortedTriangles.length > 0 ? sortedTriangles[ 0 ].subset : - 1;
let groupStart = 0;
for ( let i = 0; i < sortedTriangles.length; i ++ ) {
if ( sortedTriangles[ i ].subset !== currentSubset ) {
if ( currentSubset >= 0 ) {
groups.push( {
start: groupStart * 3,
count: ( i - groupStart ) * 3,
materialIndex: currentSubset
} );
}
currentSubset = sortedTriangles[ i ].subset;
groupStart = i;
}
}
if ( currentSubset >= 0 && sortedTriangles.length > groupStart ) {
groups.push( {
start: groupStart * 3,
count: ( sortedTriangles.length - groupStart ) * 3,
materialIndex: currentSubset
} );
}
for ( const group of groups ) {
geometry.addGroup( group.start, group.count, group.materialIndex );
}
// Triangulate original data using consistent pattern
const { indices: origIndices, pattern: triPattern } = this._triangulateIndicesWithPattern( faceVertexIndices, faceVertexCounts, points, holeMap );
const numFaceVertices = faceVertexCounts.reduce( ( a, b ) => a + b, 0 );
const faceVaryingIdentity = ( uvs && ! uvIndices && uvs.length / 2 === numFaceVertices ) ||
( uvs2 && ! uv2Indices && uvs2.length / 2 === numFaceVertices )
? this._applyTriangulationPattern( Array.from( { length: numFaceVertices }, ( _, i ) => i ), triPattern )
: null;
const origUvIndices = uvIndices
? this._applyTriangulationPattern( uvIndices, triPattern )
: ( uvs && uvs.length / 2 === numFaceVertices ? faceVaryingIdentity : null );
const origUv2Indices = uv2Indices
? this._applyTriangulationPattern( uv2Indices, triPattern )
: ( uvs2 && uvs2.length / 2 === numFaceVertices ? faceVaryingIdentity : null );
const hasIndexedNormals = normals && normalIndicesRaw && normalIndicesRaw.length > 0;
const hasFaceVaryingNormals = normals && normals.length / 3 === numFaceVertices;
const origNormalIndices = hasIndexedNormals
? this._applyTriangulationPattern( normalIndicesRaw, triPattern )
: ( hasFaceVaryingNormals
? this._applyTriangulationPattern( Array.from( { length: numFaceVertices }, ( _, i ) => i ), triPattern )
: null );
// When no normals are provided, compute vertex normals from
// the indexed topology so that shared vertices produce averaged normals.
const vertexNormals = ( ! normals && origIndices.length > 0 )
? this._computeVertexNormals( points, origIndices )
: null;
// Build reordered vertex data
const vertexCount = triangleCount * 3;
const positions = new Float32Array( vertexCount * 3 );
const uvData = uvs ? new Float32Array( vertexCount * 2 ) : null;
const uv1Data = uvs2 ? new Float32Array( vertexCount * 2 ) : null;
const normalData = ( normals || vertexNormals ) ? new Float32Array( vertexCount * 3 ) : null;
const skinSrcIndices = jointIndices ? new Uint16Array( vertexCount * elementSize ) : null;
const skinSrcWeights = jointWeights ? new Float32Array( vertexCount * elementSize ) : null;
for ( let i = 0; i < sortedTriangles.length; i ++ ) {
const origTri = sortedTriangles[ i ].original;
for ( let v = 0; v < 3; v ++ ) {
const origIdx = origTri * 3 + v;
const newIdx = i * 3 + v;
const pointIdx = origIndices[ origIdx ];
positions[ newIdx * 3 ] = points[ pointIdx * 3 ];
positions[ newIdx * 3 + 1 ] = points[ pointIdx * 3 + 1 ];
positions[ newIdx * 3 + 2 ] = points[ pointIdx * 3 + 2 ];
if ( uvData && uvs ) {
if ( origUvIndices ) {
const uvIdx = origUvIndices[ origIdx ];
uvData[ newIdx * 2 ] = uvs[ uvIdx * 2 ];
uvData[ newIdx * 2 + 1 ] = uvs[ uvIdx * 2 + 1 ];
} else if ( uvs.length / 2 === points.length / 3 ) {
uvData[ newIdx * 2 ] = uvs[ pointIdx * 2 ];
uvData[ newIdx * 2 + 1 ] = uvs[ pointIdx * 2 + 1 ];
}
}
if ( uv1Data && uvs2 ) {
if ( origUv2Indices ) {
const uv2Idx = origUv2Indices[ origIdx ];
uv1Data[ newIdx * 2 ] = uvs2[ uv2Idx * 2 ];
uv1Data[ newIdx * 2 + 1 ] = uvs2[ uv2Idx * 2 + 1 ];
} else if ( uvs2.length / 2 === points.length / 3 ) {
uv1Data[ newIdx * 2 ] = uvs2[ pointIdx * 2 ];
uv1Data[ newIdx * 2 + 1 ] = uvs2[ pointIdx * 2 + 1 ];
}
}
if ( normalData ) {
if ( normals && origNormalIndices ) {
const normalIdx = origNormalIndices[ origIdx ];
normalData[ newIdx * 3 ] = normals[ normalIdx * 3 ];
normalData[ newIdx * 3 + 1 ] = normals[ normalIdx * 3 + 1 ];
normalData[ newIdx * 3 + 2 ] = normals[ normalIdx * 3 + 2 ];
} else if ( normals && normals.length === points.length ) {
normalData[ newIdx * 3 ] = normals[ pointIdx * 3 ];
normalData[ newIdx * 3 + 1 ] = normals[ pointIdx * 3 + 1 ];
normalData[ newIdx * 3 + 2 ] = normals[ pointIdx * 3 + 2 ];
} else if ( vertexNormals ) {
normalData[ newIdx * 3 ] = vertexNormals[ pointIdx * 3 ];
normalData[ newIdx * 3 + 1 ] = vertexNormals[ pointIdx * 3 + 1 ];
normalData[ newIdx * 3 + 2 ] = vertexNormals[ pointIdx * 3 + 2 ];
}
}
if ( skinSrcIndices && skinSrcWeights && jointIndices && jointWeights ) {
for ( let j = 0; j < elementSize; j ++ ) {
skinSrcIndices[ newIdx * elementSize + j ] = jointIndices[ pointIdx * elementSize + j ] || 0;
skinSrcWeights[ newIdx * elementSize + j ] = jointWeights[ pointIdx * elementSize + j ] || 0;
}
}
}
}
geometry.setAttribute( 'position', new BufferAttribute( positions, 3 ) );
if ( uvData ) {
geometry.setAttribute( 'uv', new BufferAttribute( uvData, 2 ) );
}
if ( uv1Data ) {
geometry.setAttribute( 'uv1', new BufferAttribute( uv1Data, 2 ) );
}
geometry.setAttribute( 'normal', new BufferAttribute( normalData, 3 ) );
if ( skinSrcIndices && skinSrcWeights ) {
const skinIndexData = new Uint16Array( vertexCount * 4 );
const skinWeightData = new Float32Array( vertexCount * 4 );
this._selectTopWeights( skinSrcIndices, skinSrcWeights, elementSize, vertexCount, skinIndexData, skinWeightData );
geometry.setAttribute( 'skinIndex', new BufferAttribute( skinIndexData, 4 ) );
geometry.setAttribute( 'skinWeight', new BufferAttribute( skinWeightData, 4 ) );
}
return geometry;
}
_selectTopWeights( srcIndices, srcWeights, elementSize, numVertices, dstIndices, dstWeights ) {
if ( elementSize <= 4 ) {
for ( let i = 0; i < numVertices; i ++ ) {
for ( let j = 0; j < 4; j ++ ) {
if ( j < elementSize ) {
dstIndices[ i * 4 + j ] = srcIndices[ i * elementSize + j ] || 0;
dstWeights[ i * 4 + j ] = srcWeights[ i * elementSize + j ] || 0;
} else {
dstIndices[ i * 4 + j ] = 0;
dstWeights[ i * 4 + j ] = 0;
}
}
}
return;
}
// When elementSize > 4, find the 4 largest weights per vertex
// using a partial selection sort (4 iterations of O(elementSize)).
const order = new Uint32Array( elementSize );
for ( let i = 0; i < numVertices; i ++ ) {
const base = i * elementSize;
for ( let j = 0; j < elementSize; j ++ ) order[ j ] = j;
for ( let k = 0; k < 4; k ++ ) {
let maxIdx = k;
let maxW = srcWeights[ base + order[ k ] ] || 0;
for ( let j = k + 1; j < elementSize; j ++ ) {
const w = srcWeights[ base + order[ j ] ] || 0;
if ( w > maxW ) {
maxW = w;
maxIdx = j;
}
}
if ( maxIdx !== k ) {
const tmp = order[ k ];
order[ k ] = order[ maxIdx ];
order[ maxIdx ] = tmp;
}
}
let total = 0;
for ( let j = 0; j < 4; j ++ ) {
total += srcWeights[ base + order[ j ] ] || 0;
}
for ( let j = 0; j < 4; j ++ ) {
const s = order[ j ];
if ( total > 0 ) {
dstIndices[ i * 4 + j ] = srcIndices[ base + s ] || 0;
dstWeights[ i * 4 + j ] = ( srcWeights[ base + s ] || 0 ) / total;
} else {
dstIndices[ i * 4 + j ] = 0;
dstWeights[ i * 4 + j ] = 0;
}
}
}
}
_findUVPrimvar( fields ) {
for ( const key in fields ) {
if ( ! key.startsWith( 'primvars:' ) ) continue;
if ( key.endsWith( ':typeName' ) || key.endsWith( ':elementSize' ) || key.endsWith( ':indices' ) ) continue;
if ( key.includes( 'skel:' ) ) continue;
const typeName = fields[ key + ':typeName' ];
if ( typeName && typeName.includes( 'texCoord' ) ) {
return {
uvs: fields[ key ],
uvIndices: fields[ key + ':indices' ]
};
}
}
const uvs = fields[ 'primvars:st' ] || fields[ 'primvars:UVMap' ];
const uvIndices = fields[ 'primvars:st:indices' ];
return { uvs, uvIndices };
}
_findUV2Primvar( fields ) {
const uvs2 = fields[ 'primvars:st1' ];
const uv2Indices = fields[ 'primvars:st1:indices' ];
return { uvs2, uv2Indices };
}
_buildHoleMap( polygonHoles ) {
// polygonHoles is in Arnold format: [holeFaceIdx, parentFaceIdx, holeFaceIdx, parentFaceIdx, ...]
// Returns a map: parentFaceIdx -> [holeFaceIdx1, holeFaceIdx2, ...]
// Also returns a set of hole face indices to skip during triangulation
if ( ! polygonHoles || polygonHoles.length === 0 ) {
return { parentToHoles: new Map(), holeFaces: new Set() };
}
const parentToHoles = new Map();
const holeFaces = new Set();
for ( let i = 0; i < polygonHoles.length; i += 2 ) {
const holeFaceIdx = polygonHoles[ i ];
const parentFaceIdx = polygonHoles[ i + 1 ];
holeFaces.add( holeFaceIdx );
if ( ! parentToHoles.has( parentFaceIdx ) ) {
parentToHoles.set( parentFaceIdx, [] );
}
parentToHoles.get( parentFaceIdx ).push( holeFaceIdx );
}
return { parentToHoles, holeFaces };
}
_triangulateIndicesWithPattern( indices, counts, points = null, holeMap = null ) {
const triangulated = [];
const pattern = []; // Stores face-local indices for each triangle vertex
// Build face offset lookup for accessing hole face data
const faceOffsets = [];
let offsetAccum = 0;
for ( let i = 0; i < counts.length; i ++ ) {
faceOffsets.push( offsetAccum );
offsetAccum += counts[ i ];
}
const parentToHoles = holeMap?.parentToHoles || new Map();
const holeFaces = holeMap?.holeFaces || new Set();
let offset = 0;
for ( let i = 0; i < counts.length; i ++ ) {
const count = counts[ i ];
// Skip faces that are holes - they will be triangulated with their parent
if ( holeFaces.has( i ) ) {
offset += count;
continue;
}
// Check if this face has holes
const holes = parentToHoles.get( i );
if ( holes && holes.length > 0 && points && points.length > 0 ) {
// Triangulate face with holes using vertex -> face-vertex mapping
const vertexToFaceVertex = new Map();
const faceIndices = [];
for ( let j = 0; j < count; j ++ ) {
const vertIdx = indices[ offset + j ];
faceIndices.push( vertIdx );
vertexToFaceVertex.set( vertIdx, offset + j );
}
const holeContours = [];
for ( const holeFaceIdx of holes ) {
const holeOffset = faceOffsets[ holeFaceIdx ];
const holeCount = counts[ holeFaceIdx ];
const holeIndices = [];
for ( let j = 0; j < holeCount; j ++ ) {
const vertIdx = indices[ holeOffset + j ];
holeIndices.push( vertIdx );
vertexToFaceVertex.set( vertIdx, holeOffset + j );
}
holeContours.push( holeIndices );
}
const triangles = this._triangulateNGonWithHoles( faceIndices, holeContours, points );
for ( const tri of triangles ) {
triangulated.push( tri[ 0 ], tri[ 1 ], tri[ 2 ] );
pattern.push(
vertexToFaceVertex.get( tri[ 0 ] ),
vertexToFaceVertex.get( tri[ 1 ] ),
vertexToFaceVertex.get( tri[ 2 ] )
);
}
} else if ( count === 3 ) {
triangulated.push(
indices[ offset ],
indices[ offset + 1 ],
indices[ offset + 2 ]
);
pattern.push( offset, offset + 1, offset + 2 );
} else if ( count === 4 ) {
triangulated.push(
indices[ offset ],
indices[ offset + 1 ],
indices[ offset + 2 ],
indices[ offset ],
indices[ offset + 2 ],
indices[ offset + 3 ]
);
pattern.push(
offset, offset + 1, offset + 2,
offset, offset + 2, offset + 3
);
} else if ( count > 4 ) {
// Use ear-clipping for complex n-gons if we have vertex positions
if ( points && points.length > 0 ) {
const faceIndices = [];
for ( let j = 0; j < count; j ++ ) {
faceIndices.push( indices[ offset + j ] );
}
const triangles = this._triangulateNGon( faceIndices, points );
for ( const tri of triangles ) {
triangulated.push( tri[ 0 ], tri[ 1 ], tri[ 2 ] );
// Find local indices within the face
pattern.push(
offset + faceIndices.indexOf( tri[ 0 ] ),
offset + faceIndices.indexOf( tri[ 1 ] ),
offset + faceIndices.indexOf( tri[ 2 ] )
);
}
} else {
// Fallback to fan triangulation
for ( let j = 1; j < count - 1; j ++ ) {
triangulated.push(
indices[ offset ],
indices[ offset + j ],
indices[ offset + j + 1 ]
);
pattern.push( offset, offset + j, offset + j + 1 );
}
}
}
offset += count;
}
return { indices: triangulated, pattern };
}
_applyTriangulationPattern( indices, pattern ) {
const result = [];
for ( let i = 0; i < pattern.length; i ++ ) {
result.push( indices[ pattern[ i ] ] );
}
return result;
}
_triangulateNGon( faceIndices, points ) {
// Project 3D polygon to 2D for triangulation using Newell's method for normal
const contour2D = [];
const contour3D = [];
for ( const idx of faceIndices ) {
contour3D.push( new Vector3(
points[ idx * 3 ],
points[ idx * 3 + 1 ],
points[ idx * 3 + 2 ]
) );
}
// Calculate polygon normal using Newell's method
const normal = new Vector3();
for ( let i = 0; i < contour3D.length; i ++ ) {
const curr = contour3D[ i ];
const next = contour3D[ ( i + 1 ) % contour3D.length ];
normal.x += ( curr.y - next.y ) * ( curr.z + next.z );
normal.y += ( curr.z - next.z ) * ( curr.x + next.x );
normal.z += ( curr.x - next.x ) * ( curr.y + next.y );
}
normal.normalize();
// Create tangent basis for projection
const tangent = new Vector3();
const bitangent = new Vector3();
if ( Math.abs( normal.y ) > 0.9 ) {
tangent.set( 1, 0, 0 );
} else {
tangent.set( 0, 1, 0 );
}
bitangent.crossVectors( normal, tangent ).normalize();
tangent.crossVectors( bitangent, normal ).normalize();
// Project to 2D
for ( const p of contour3D ) {
contour2D.push( new Vector2( p.dot( tangent ), p.dot( bitangent ) ) );
}
// Triangulate using ShapeUtils
const triangles = ShapeUtils.triangulateShape( contour2D, [] );
// Map back to original indices
const result = [];
for ( const tri of triangles ) {
result.push( [
faceIndices[ tri[ 0 ] ],
faceIndices[ tri[ 1 ] ],
faceIndices[ tri[ 2 ] ]
] );
}
return result;
}
_triangulateNGonWithHoles( outerIndices, holeContours, points ) {
// Project 3D polygon with holes to 2D for triangulation
const outer3D = [];
for ( const idx of outerIndices ) {
outer3D.push( new Vector3(
points[ idx * 3 ],
points[ idx * 3 + 1 ],
points[ idx * 3 + 2 ]
) );
}
// Calculate polygon normal using Newell's method
const normal = new Vector3();
for ( let i = 0; i < outer3D.length; i ++ ) {
const curr = outer3D[ i ];
const next = outer3D[ ( i + 1 ) % outer3D.length ];
normal.x += ( curr.y - next.y ) * ( curr.z + next.z );
normal.y += ( curr.z - next.z ) * ( curr.x + next.x );
normal.z += ( curr.x - next.x ) * ( curr.y + next.y );
}
normal.normalize();
// Create tangent basis for projection
const tangent = new Vector3();
const bitangent = new Vector3();
if ( Math.abs( normal.y ) > 0.9 ) {
tangent.set( 1, 0, 0 );
} else {
tangent.set( 0, 1, 0 );
}
bitangent.crossVectors( normal, tangent ).normalize();
tangent.crossVectors( bitangent, normal ).normalize();
// Project outer contour to 2D
const outer2D = [];
for ( const p of outer3D ) {
outer2D.push( new Vector2( p.dot( tangent ), p.dot( bitangent ) ) );
}
// Project hole contours to 2D
const holes2D = [];
for ( const holeIndices of holeContours ) {
const hole2D = [];
for ( const idx of holeIndices ) {
const p = new Vector3(
points[ idx * 3 ],
points[ idx * 3 + 1 ],
points[ idx * 3 + 2 ]
);
hole2D.push( new Vector2( p.dot( tangent ), p.dot( bitangent ) ) );
}
holes2D.push( hole2D );
}
// Build combined index array: outer contour followed by all holes
const allIndices = [ ...outerIndices ];
for ( const holeIndices of holeContours ) {
allIndices.push( ...holeIndices );
}
// Triangulate using ShapeUtils with holes
const triangles = ShapeUtils.triangulateShape( outer2D, holes2D );
// Map back to original vertex indices
const result = [];
for ( const tri of triangles ) {
result.push( [
allIndices[ tri[ 0 ] ],
allIndices[ tri[ 1 ] ],
allIndices[ tri[ 2 ] ]
] );
}
return result;
}
_triangulateIndices( indices, counts ) {
const triangulated = [];
let offset = 0;
for ( let i = 0; i < counts.length; i ++ ) {
const count = counts[ i ];
if ( count === 3 ) {
triangulated.push(
indices[ offset ],
indices[ offset + 1 ],
indices[ offset + 2 ]
);
} else if ( count === 4 ) {
triangulated.push(
indices[ offset ],
indices[ offset + 1 ],
indices[ offset + 2 ],
indices[ offset ],
indices[ offset + 2 ],
indices[ offset + 3 ]
);
} else if ( count > 4 ) {
// Fan triangulation for n-gons
for ( let j = 1; j < count - 1; j ++ ) {
triangulated.push(
indices[ offset ],
indices[ offset + j ],
indices[ offset + j + 1 ]
);
}
}
offset += count;
}
return triangulated;
}
_expandAttribute( data, indices, itemSize ) {
const expanded = new Array( indices.length * itemSize );
for ( let i = 0; i < indices.length; i ++ ) {
const srcIdx = indices[ i ];
for ( let j = 0; j < itemSize; j ++ ) {
expanded[ i * itemSize + j ] = data[ srcIdx * itemSize + j ];
}
}
return expanded;
}
/**
* Compute per-vertex normals from indexed triangle data.
* Accumulates area-weighted face normals at each shared vertex and normalizes.
*/
_computeVertexNormals( points, indices ) {
const numVertices = points.length / 3;
const normals = new Float32Array( numVertices * 3 );
for ( let i = 0; i < indices.length; i += 3 ) {
const a = indices[ i ];
const b = indices[ i + 1 ];
const c = indices[ i + 2 ];
const ax = points[ a * 3 ], ay = points[ a * 3 + 1 ], az = points[ a * 3 + 2 ];
const bx = points[ b * 3 ], by = points[ b * 3 + 1 ], bz = points[ b * 3 + 2 ];
const cx = points[ c * 3 ], cy = points[ c * 3 + 1 ], cz = points[ c * 3 + 2 ];
const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
const nx = e1y * e2z - e1z * e2y;
const ny = e1z * e2x - e1x * e2z;
const nz = e1x * e2y - e1y * e2x;
normals[ a * 3 ] += nx; normals[ a * 3 + 1 ] += ny; normals[ a * 3 + 2 ] += nz;
normals[ b * 3 ] += nx; normals[ b * 3 + 1 ] += ny; normals[ b * 3 + 2 ] += nz;
normals[ c * 3 ] += nx; normals[ c * 3 + 1 ] += ny; normals[ c * 3 + 2 ] += nz;
}
for ( let i = 0; i < numVertices; i ++ ) {
const x = normals[ i * 3 ], y = normals[ i * 3 + 1 ], z = normals[ i * 3 + 2 ];
const len = Math.sqrt( x * x + y * y + z * z );
if ( len > 0 ) {
normals[ i * 3 ] /= len;
normals[ i * 3 + 1 ] /= len;
normals[ i * 3 + 2 ] /= len;
}
}
return normals;
}
/**
* Get the material path for a mesh, checking various binding sources.
*/
_getMaterialPath( meshPath, fields ) {
let materialPath = null;
const materialBinding = fields[ 'material:binding' ];
if ( materialBinding ) {
materialPath = Array.isArray( materialBinding ) ? materialBinding[ 0 ] : materialBinding;
}
// Use variant-aware lookup if no direct binding in fields
if ( ! materialPath ) {
materialPath = this._getMaterialBindingTarget( meshPath );
}
return materialPath;
}
_buildMaterial( meshPath, fields ) {
const material = new MeshPhysicalMaterial();
let materialPath = null;
const materialBinding = fields[ 'material:binding' ];
if ( materialBinding ) {
materialPath = Array.isArray( materialBinding ) ? materialBinding[ 0 ] : materialBinding;
}
// Use variant-aware lookup if no direct binding in fields
if ( ! materialPath ) {
materialPath = this._getMaterialBindingTarget( meshPath );
}
if ( ! materialPath ) {
const materialPaths = [];
const prefix = meshPath + '/';
for ( const path in this.specsByPath ) {
if ( ! path.startsWith( prefix ) ) continue;
if ( ! path.endsWith( '.material:binding' ) ) continue;
const bindingSpec = this.specsByPath[ path ];
if ( ! bindingSpec ) continue;
const targetPaths = bindingSpec.fields.targetPaths;
if ( targetPaths && targetPaths.length > 0 ) {
materialPaths.push( targetPaths[ 0 ] );
}
}
if ( materialPaths.length > 0 ) {
materialPath = this._pickBestMaterial( materialPaths );
}
}
if ( ! materialPath ) {
// Use material index for O(1) lookup instead of O(n) iteration
const meshParts = meshPath.split( '/' );
const rootPath = '/' + meshParts[ 1 ];
const materialsInRoot = this.materialsByRoot.get( rootPath );
if ( materialsInRoot ) {
for ( const path of materialsInRoot ) {
if ( path.startsWith( rootPath + '/Looks/' ) ||
path.startsWith( rootPath + '/Materials/' ) ) {
materialPath = path;
break;
}
}
}
}
if ( materialPath ) {
this._applyMaterial( material, materialPath );
}
return material;
}
_buildMaterialForPath( materialPath ) {
const material = new MeshPhysicalMaterial();
if ( materialPath ) {
this._applyMaterial( material, materialPath );
}
return material;
}
/**
* Apply material binding from a prim path to a mesh.
* Used when merging referenced geometry into a prim that has material binding.
*/
_applyMaterialBinding( mesh, primPath ) {
let materialPath = this._getMaterialBindingTarget( primPath );
if ( ! materialPath ) return;
// Clean the material path
materialPath = String( materialPath ).replace( /^<|>$/g, '' );
// Build and apply the material
const material = new MeshPhysicalMaterial();
this._applyMaterial( material, materialPath );
mesh.material = material;
}
_pickBestMaterial( materialPaths ) {
for ( const materialPath of materialPaths ) {
const shaderPaths = this.shadersByMaterialPath.get( materialPath );
if ( ! shaderPaths ) continue;
for ( const path of shaderPaths ) {
const attrs = this._getAttributes( path );
if ( attrs[ 'info:id' ] === 'UsdUVTexture' && attrs[ 'inputs:file' ] ) {
return materialPath;
}
}
}
return materialPaths[ 0 ];
}
_applyMaterial( material, materialPath ) {
const materialSpec = this.specsByPath[ materialPath ];
if ( ! materialSpec ) return;
const shaderPaths = this.shadersByMaterialPath.get( materialPath );
if ( ! shaderPaths ) return;
for ( const path of shaderPaths ) {
const spec = this.specsByPath[ path ];
if ( ! spec ) continue;
const shaderAttrs = this._getAttributes( path );
const infoId = shaderAttrs[ 'info:id' ] || spec.fields[ 'info:id' ];
if ( infoId === 'UsdPreviewSurface' || infoId === 'ND_UsdPreviewSurface_surfaceshader' ) {
this._applyPreviewSurface( material, path );
} else if ( infoId === 'arnold:openpbr_surface' ) {
this._applyOpenPBRSurface( material, path );
}
}
}
/**
* Shared helper for applying texture or value from shader attribute.
* Reduces duplication between _applyPreviewSurface and _applyOpenPBRSurface.
*/
_applyTextureOrValue( material, shaderPath, fields, attrName, textureProperty, colorSpace, valueCallback, textureGetter ) {
const attrPath = shaderPath + '.' + attrName;
const spec = this.specsByPath[ attrPath ];
if ( spec && spec.fields.connectionPaths && spec.fields.connectionPaths.length > 0 ) {
// For OpenPBR, try all connection paths; for PreviewSurface, just the first
const paths = textureGetter === this._getTextureFromOpenPBRConnection
? spec.fields.connectionPaths
: [ spec.fields.connectionPaths[ 0 ] ];
for ( const connPath of paths ) {
const texture = textureGetter.call( this, connPath );
if ( texture ) {
texture.colorSpace = colorSpace;
material[ textureProperty ] = texture;
return true;
}
}
}
if ( fields[ attrName ] !== undefined && valueCallback ) {
valueCallback( fields[ attrName ] );
}
return false;
}
_applyPreviewSurface( material, shaderPath ) {
const fields = this._getAttributes( shaderPath );
const applyTexture = ( attrName, textureProperty, colorSpace, valueCallback ) => {
return this._applyTextureOrValue(
material, shaderPath, fields, attrName, textureProperty, colorSpace, valueCallback,
this._getTextureFromConnection
);
};
const getAttrSpec = ( attrName ) => {
const attrPath = shaderPath + '.' + attrName;
return this.specsByPath[ attrPath ];
};
// Diffuse color / base color map
applyTexture(
'inputs:diffuseColor',
'map',
SRGBColorSpace,
( color ) => {
if ( Array.isArray( color ) && color.length >= 3 ) {
material.color.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], SRGBColorSpace );
}
}
);
// Apply UsdUVTexture scale to diffuse color (output = texture * scale + bias)
if ( material.map && material.map.userData.scale ) {
const scale = material.map.userData.scale;
if ( Array.isArray( scale ) && scale.length >= 3 ) {
material.color.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], SRGBColorSpace );
}
}
// Emissive
applyTexture(
'inputs:emissiveColor',
'emissiveMap',
SRGBColorSpace,
( color ) => {
if ( Array.isArray( color ) && color.length >= 3 ) {
material.emissive.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], SRGBColorSpace );
}
}
);
if ( material.emissiveMap ) {
if ( material.emissiveMap.userData.scale ) {
const scale = material.emissiveMap.userData.scale;
if ( Array.isArray( scale ) && scale.length >= 3 ) {
material.emissive.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], SRGBColorSpace );
}
} else {
material.emissive.set( 0xffffff );
}
}
// Normal map
applyTexture( 'inputs:normal', 'normalMap', NoColorSpace, null );
// Apply normal map scale from UsdUVTexture scale input
if ( material.normalMap && material.normalMap.userData.scale ) {
const scale = material.normalMap.userData.scale;
// UsdUVTexture scale is float4 (r,g,b,a), use first two components for normalScale
material.normalScale = new Vector2( scale[ 0 ], scale[ 1 ] );
}
// Roughness
const hasRoughnessMap = applyTexture(
'inputs:roughness',
'roughnessMap',
NoColorSpace,
( value ) => {
material.roughness = value;
}
);
if ( hasRoughnessMap ) {
material.roughness = 1.0;
}
// Metallic
const hasMetalnessMap = applyTexture(
'inputs:metallic',
'metalnessMap',
NoColorSpace,
( value ) => {
material.metalness = value;
}
);
if ( hasMetalnessMap ) {
material.metalness = 1.0;
}
// Occlusion
applyTexture( 'inputs:occlusion', 'aoMap', NoColorSpace, null );
// IOR
if ( fields[ 'inputs:ior' ] !== undefined ) {
material.ior = fields[ 'inputs:ior' ];
}
// Specular color
applyTexture(
'inputs:specularColor',
'specularColorMap',
SRGBColorSpace,
( color ) => {
if ( Array.isArray( color ) && color.length >= 3 ) {
material.specularColor.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], SRGBColorSpace );
}
}
);
// Apply UsdUVTexture scale to specular color
if ( material.specularColorMap && material.specularColorMap.userData.scale ) {
const scale = material.specularColorMap.userData.scale;
if ( Array.isArray( scale ) && scale.length >= 3 ) {
material.specularColor.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], SRGBColorSpace );
}
}
// Clearcoat
if ( fields[ 'inputs:clearcoat' ] !== undefined ) {
material.clearcoat = fields[ 'inputs:clearcoat' ];
}
// Clearcoat roughness
if ( fields[ 'inputs:clearcoatRoughness' ] !== undefined ) {
material.clearcoatRoughness = fields[ 'inputs:clearcoatRoughness' ];
}
// Opacity and opacity modes
const opacityThreshold = fields[ 'inputs:opacityThreshold' ] !== undefined ? fields[ 'inputs:opacityThreshold' ] : 0.0;
// Check if opacity is connected to a texture (e.g., diffuse texture's alpha)
const opacitySpec = getAttrSpec( 'inputs:opacity' );
const hasOpacityConnection = opacitySpec?.fields?.connectionPaths?.length > 0;
if ( hasOpacityConnection ) {
// Opacity from texture alpha - use the diffuse map's alpha channel
if ( opacityThreshold > 0 ) {
// Alpha cutoff mode
material.alphaTest = opacityThreshold;
material.transparent = false;
} else {
// Alpha blend mode
material.transparent = true;
}
} else {
// Direct opacity value
const opacity = fields[ 'inputs:opacity' ] !== undefined ? fields[ 'inputs:opacity' ] : 1.0;
if ( opacity < 1.0 ) {
material.transparent = true;
material.opacity = opacity;
}
}
}
_applyOpenPBRSurface( material, shaderPath ) {
const fields = this._getAttributes( shaderPath );
const applyTexture = ( attrName, textureProperty, colorSpace, valueCallback ) => {
return this._applyTextureOrValue(
material, shaderPath, fields, attrName, textureProperty, colorSpace, valueCallback,
this._getTextureFromOpenPBRConnection
);
};
// Base color (diffuse)
applyTexture(
'inputs:base_color',
'map',
SRGBColorSpace,
( color ) => {
if ( Array.isArray( color ) && color.length >= 3 ) {
material.color.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], SRGBColorSpace );
}
}
);
// Apply UsdUVTexture scale to base color
if ( material.map && material.map.userData.scale ) {
const scale = material.map.userData.scale;
if ( Array.isArray( scale ) && scale.length >= 3 ) {
material.color.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], SRGBColorSpace );
}
}
// Base metalness
applyTexture(
'inputs:base_metalness',
'metalnessMap',
NoColorSpace,
( value ) => {
if ( typeof value === 'number' ) {
material.metalness = value;
}
}
);
// Specular roughness
applyTexture(
'inputs:specular_roughness',
'roughnessMap',
NoColorSpace,
( value ) => {
if ( typeof value === 'number' ) {
material.roughness = value;
}
}
);
// Emission color
const hasEmissionMap = applyTexture(
'inputs:emission_color',
'emissiveMap',
SRGBColorSpace,
( color ) => {
if ( Array.isArray( color ) && color.length >= 3 ) {
material.emissive.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], SRGBColorSpace );
}
}
);
// Emission luminance/weight - multiply emissive by this factor
const emissionLuminance = fields[ 'inputs:emission_luminance' ];
if ( emissionLuminance !== undefined && emissionLuminance > 0 ) {
if ( hasEmissionMap ) {
material.emissiveIntensity = emissionLuminance;
} else {
// Scale the emissive color by luminance
material.emissive.multiplyScalar( emissionLuminance );
}
}
// Transmission (transparency)
const transmissionWeight = fields[ 'inputs:transmission_weight' ];
if ( transmissionWeight !== undefined && transmissionWeight > 0 ) {
material.transmission = transmissionWeight;
const transmissionDepth = fields[ 'inputs:transmission_depth' ];
if ( transmissionDepth !== undefined ) {
material.thickness = transmissionDepth;
}
const transmissionColor = fields[ 'inputs:transmission_color' ];
if ( transmissionColor !== undefined && Array.isArray( transmissionColor ) ) {
material.attenuationColor.setRGB( transmissionColor[ 0 ], transmissionColor[ 1 ], transmissionColor[ 2 ] );
material.attenuationDistance = transmissionDepth || 1.0;
}
}
// Geometry opacity (overall surface opacity)
const geometryOpacity = fields[ 'inputs:geometry_opacity' ];
if ( geometryOpacity !== undefined && geometryOpacity < 1.0 ) {
material.opacity = geometryOpacity;
material.transparent = true;
}
// Specular IOR
const specularIOR = fields[ 'inputs:specular_ior' ];
if ( specularIOR !== undefined ) {
material.ior = specularIOR;
}
// Coat (clearcoat)
const coatWeight = fields[ 'inputs:coat_weight' ];
if ( coatWeight !== undefined && coatWeight > 0 ) {
material.clearcoat = coatWeight;
const coatRoughness = fields[ 'inputs:coat_roughness' ];
if ( coatRoughness !== undefined ) {
material.clearcoatRoughness = coatRoughness;
}
}
// Thin film (iridescence)
const thinFilmWeight = fields[ 'inputs:thin_film_weight' ];
if ( thinFilmWeight !== undefined && thinFilmWeight > 0 ) {
material.iridescence = thinFilmWeight;
const thinFilmIOR = fields[ 'inputs:thin_film_ior' ];
if ( thinFilmIOR !== undefined ) {
material.iridescenceIOR = thinFilmIOR;
}
const thinFilmThickness = fields[ 'inputs:thin_film_thickness' ];
if ( thinFilmThickness !== undefined ) {
// OpenPBR uses micrometers, Three.js uses nanometers
const thicknessNm = thinFilmThickness * 1000;
material.iridescenceThicknessRange = [ thicknessNm, thicknessNm ];
}
}
// Specular
const specularWeight = fields[ 'inputs:specular_weight' ];
if ( specularWeight !== undefined ) {
material.specularIntensity = specularWeight;
}
const specularColor = fields[ 'inputs:specular_color' ];
if ( specularColor !== undefined && Array.isArray( specularColor ) ) {
material.specularColor.setRGB( specularColor[ 0 ], specularColor[ 1 ], specularColor[ 2 ] );
}
// Anisotropy
const anisotropy = fields[ 'inputs:specular_roughness_anisotropy' ];
if ( anisotropy !== undefined && anisotropy > 0 ) {
material.anisotropy = anisotropy;
}
// Geometry normal (normal map)
applyTexture(
'inputs:geometry_normal',
'normalMap',
NoColorSpace,
null
);
}
_getTextureFromOpenPBRConnection( connPath ) {
// connPath is like /Material/NodeGraph.outputs:baseColor or /Material/Shader.outputs:out
const cleanPath = connPath.replace( /<|>/g, '' );
const shaderPath = cleanPath.split( '.' )[ 0 ];
const shaderSpec = this.specsByPath[ shaderPath ];
if ( ! shaderSpec ) return null;
const attrs = this._getAttributes( shaderPath );
const infoId = attrs[ 'info:id' ] || shaderSpec.fields[ 'info:id' ];
const typeName = shaderSpec.fields.typeName;
// Handle NodeGraph - follow output connection to internal shader
if ( typeName === 'NodeGraph' ) {
// Get the output attribute that's connected
const outputName = cleanPath.split( '.' )[ 1 ]; // e.g., "outputs:baseColor"
const outputAttrPath = shaderPath + '.' + outputName;
const outputSpec = this.specsByPath[ outputAttrPath ];
if ( outputSpec?.fields?.connectionPaths?.length > 0 ) {
// Follow the internal connection
return this._getTextureFromOpenPBRConnection( outputSpec.fields.connectionPaths[ 0 ] );
}
return null;
}
// Handle arnold:image - Arnold's texture node
if ( infoId === 'arnold:image' ) {
const filePath = attrs[ 'inputs:filename' ];
if ( ! filePath ) return null;
return this._loadTextureFromPath( filePath );
}
// Handle MaterialX image nodes (ND_image_color4, ND_image_color3, etc.)
if ( infoId && infoId.startsWith( 'ND_image_' ) ) {
const filePath = attrs[ 'inputs:file' ];
if ( ! filePath ) return null;
return this._loadTextureFromPath( filePath );
}
// Handle Maya file texture - follow the inColor connection to the actual image
if ( infoId === 'MayaND_fileTexture_color4' ) {
const inColorPath = shaderPath + '.inputs:inColor';
const inColorSpec = this.specsByPath[ inColorPath ];
if ( inColorSpec?.fields?.connectionPaths?.length > 0 ) {
return this._getTextureFromOpenPBRConnection( inColorSpec.fields.connectionPaths[ 0 ] );
}
return null;
}
// Handle color conversion nodes - follow the input connection
if ( infoId && infoId.startsWith( 'ND_convert_' ) ) {
const inPath = shaderPath + '.inputs:in';
const inSpec = this.specsByPath[ inPath ];
if ( inSpec?.fields?.connectionPaths?.length > 0 ) {
return this._getTextureFromOpenPBRConnection( inSpec.fields.connectionPaths[ 0 ] );
}
return null;
}
// Handle Arnold bump2d - follow the bump_map input
if ( infoId === 'arnold:bump2d' ) {
const bumpMapPath = shaderPath + '.inputs:bump_map';
const bumpMapSpec = this.specsByPath[ bumpMapPath ];
if ( bumpMapSpec?.fields?.connectionPaths?.length > 0 ) {
return this._getTextureFromOpenPBRConnection( bumpMapSpec.fields.connectionPaths[ 0 ] );
}
return null;
}
// Handle Arnold color_correct - follow the input connection
if ( infoId === 'arnold:color_correct' ) {
const inputPath = shaderPath + '.inputs:input';
const inputSpec = this.specsByPath[ inputPath ];
if ( inputSpec?.fields?.connectionPaths?.length > 0 ) {
return this._getTextureFromOpenPBRConnection( inputSpec.fields.connectionPaths[ 0 ] );
}
return null;
}
// Handle nested shader paths (e.g., /Material/file2/cc.outputs:a)
// Check if parent path is an image node
const parentPath = shaderPath.substring( 0, shaderPath.lastIndexOf( '/' ) );
if ( parentPath ) {
const parentSpec = this.specsByPath[ parentPath ];
if ( parentSpec ) {
const parentAttrs = this._getAttributes( parentPath );
const parentInfoId = parentAttrs[ 'info:id' ] || parentSpec.fields[ 'info:id' ];
if ( parentInfoId === 'arnold:image' ) {
const filePath = parentAttrs[ 'inputs:filename' ];
if ( filePath ) return this._loadTextureFromPath( filePath );
}
}
}
return null;
}
_loadTextureFromPath( filePath ) {
if ( ! filePath ) return null;
// Check cache first
if ( this.textureCache[ filePath ] ) {
return this.textureCache[ filePath ];
}
const texture = this._loadTexture( filePath, null, null );
if ( texture ) {
this.textureCache[ filePath ] = texture;
}
return texture;
}
_getTextureFromConnection( connPath ) {
// connPath is like /Material/Shader.outputs:rgb
const shaderPath = connPath.split( '.' )[ 0 ];
const shaderSpec = this.specsByPath[ shaderPath ];
if ( ! shaderSpec ) return null;
const attrs = this._getAttributes( shaderPath );
const infoId = attrs[ 'info:id' ] || shaderSpec.fields[ 'info:id' ];
if ( infoId !== 'UsdUVTexture' ) return null;
const filePath = attrs[ 'inputs:file' ];
if ( ! filePath ) return null;
// Check for UsdTransform2d connection via inputs:st and trace to PrimvarReader
let transformAttrs = null;
let uvChannel = 0; // Default to first UV set
const stAttrPath = shaderPath + '.inputs:st';
const stAttrSpec = this.specsByPath[ stAttrPath ];
if ( stAttrSpec?.fields?.connectionPaths?.length > 0 ) {
const stConnPath = stAttrSpec.fields.connectionPaths[ 0 ];
const stPath = stConnPath.replace( /<|>/g, '' ).split( '.' )[ 0 ];
const stSpec = this.specsByPath[ stPath ];
if ( stSpec ) {
const stAttrs = this._getAttributes( stPath );
const stInfoId = stAttrs[ 'info:id' ] || stSpec.fields[ 'info:id' ];
if ( stInfoId === 'UsdTransform2d' ) {
transformAttrs = stAttrs;
// Trace to PrimvarReader to find UV set
const inAttrPath = stPath + '.inputs:in';
const inAttrSpec = this.specsByPath[ inAttrPath ];
if ( inAttrSpec?.fields?.connectionPaths?.length > 0 ) {
const inConnPath = inAttrSpec.fields.connectionPaths[ 0 ];
const primvarPath = inConnPath.replace( /<|>/g, '' ).split( '.' )[ 0 ];
const primvarAttrs = this._getAttributes( primvarPath );
// Check varname to determine UV channel
const varname = primvarAttrs[ 'inputs:varname' ];
if ( varname === 'st1' ) uvChannel = 1;
else if ( varname === 'st2' ) uvChannel = 2;
}
} else if ( stInfoId === 'UsdPrimvarReader_float2' ) {
// Direct connection to PrimvarReader
const varname = stAttrs[ 'inputs:varname' ];
if ( varname === 'st1' ) uvChannel = 1;
else if ( varname === 'st2' ) uvChannel = 2;
}
}
}
// Extract scale and bias for texture value modification
const scale = attrs[ 'inputs:scale' ];
const bias = attrs[ 'inputs:bias' ];
// Create cache key that includes scale/bias if present
let cacheKey = filePath;
if ( scale ) cacheKey += ':s' + scale.join( ',' );
if ( bias ) cacheKey += ':b' + bias.join( ',' );
if ( this.textureCache[ cacheKey ] ) {
return this.textureCache[ cacheKey ];
}
const texture = this._loadTexture( filePath, attrs, transformAttrs );
if ( texture ) {
// Store scale/bias and UV channel in userData
if ( scale ) texture.userData.scale = scale;
if ( bias ) texture.userData.bias = bias;
if ( uvChannel !== 0 ) texture.channel = uvChannel;
this.textureCache[ cacheKey ] = texture;
}
return texture;
}
_applyTextureTransforms( texture, attrs ) {
if ( ! attrs ) return;
const scale = attrs[ 'inputs:scale' ];
if ( scale && Array.isArray( scale ) && scale.length >= 2 ) {
texture.repeat.set( scale[ 0 ], scale[ 1 ] );
}
const translation = attrs[ 'inputs:translation' ];
if ( translation && Array.isArray( translation ) && translation.length >= 2 ) {
texture.offset.set( translation[ 0 ], translation[ 1 ] );
}
const rotation = attrs[ 'inputs:rotation' ];
if ( typeof rotation === 'number' ) {
texture.rotation = rotation * Math.PI / 180;
}
}
_loadTexture( filePath, textureAttrs, transformAttrs ) {
let cleanPath = filePath;
if ( cleanPath.startsWith( '@' ) ) cleanPath = cleanPath.slice( 1 );
if ( cleanPath.endsWith( '@' ) ) cleanPath = cleanPath.slice( 0, - 1 );
// Resolve relative to basePath first
const resolvedPath = this._resolveFilePath( cleanPath );
let assetData = this.assets[ resolvedPath ];
// Fallback to unresolved path
if ( ! assetData ) {
assetData = this.assets[ cleanPath ];
}
// Last resort: search by basename
if ( ! assetData ) {
const baseName = cleanPath.split( '/' ).pop();
for ( const key in this.assets ) {
if ( key.endsWith( baseName ) || key.endsWith( '/' + baseName ) ) {
return this._createTextureFromData( this.assets[ key ], textureAttrs, transformAttrs );
}
}
// Standalone .usd/.usda/.usdc files don't pre-load assets; treat the
// resolved path as a URL relative to basePath so the browser fetches
// the texture from disk next to the layer.
if ( this.basePath ) {
return this._createTextureFromData( resolvedPath, textureAttrs, transformAttrs );
}
// Try loading via LoadingManager if available
if ( this.manager ) {
const url = this.manager.resolveURL( baseName );
if ( url !== baseName ) {
// URL modifier found a match - load it
return this._createTextureFromData( url, textureAttrs, transformAttrs );
}
}
console.warn( 'USDLoader: Texture not found:', cleanPath );
return null;
}
return this._createTextureFromData( assetData, textureAttrs, transformAttrs );
}
_createTextureFromData( data, textureAttrs, transformAttrs ) {
if ( ! data ) return null;
const scope = this;
const texture = new Texture();
let url;
if ( typeof data === 'string' ) {
url = data;
} else if ( data instanceof Uint8Array || data instanceof ArrayBuffer ) {
const blob = new Blob( [ data ] );
url = URL.createObjectURL( blob );
} else {
return null;
}
const image = new Image();
this.texturePromises.push( new Promise( ( resolve ) => {
image.onload = function () {
texture.image = image;
if ( textureAttrs ) {
texture.wrapS = scope._getWrapMode( textureAttrs[ 'inputs:wrapS' ] );
texture.wrapT = scope._getWrapMode( textureAttrs[ 'inputs:wrapT' ] );
}
scope._applyTextureTransforms( texture, transformAttrs );
texture.needsUpdate = true;
if ( typeof data !== 'string' ) {
URL.revokeObjectURL( url );
}
resolve();
};
image.onerror = function () {
console.warn( 'USDLoader: Failed to load texture:', url );
if ( typeof data !== 'string' ) {
URL.revokeObjectURL( url );
}
resolve();
};
} ) );
image.src = url;
return texture;
}
_getWrapMode( wrapValue ) {
if ( wrapValue === 'repeat' ) return RepeatWrapping;
if ( wrapValue === 'mirror' ) return MirroredRepeatWrapping;
if ( wrapValue === 'clamp' ) return ClampToEdgeWrapping;
return RepeatWrapping;
}
// ========================================================================
// Skeletal Animation
// ========================================================================
_buildSkeleton( path ) {
const attrs = this._getAttributes( path );
// Get joint names (paths like "root", "root/body_joint", etc.)
const joints = attrs[ 'joints' ];
if ( ! joints || joints.length === 0 ) return null;
// Get bind transforms (world-space bind pose matrices)
// These can be nested arrays (USDA) or flat arrays (USDC)
const rawBindTransforms = attrs[ 'bindTransforms' ];
const rawRestTransforms = attrs[ 'restTransforms' ];
const bindTransforms = this._flattenMatrixArray( rawBindTransforms, joints.length );
const restTransforms = this._flattenMatrixArray( rawRestTransforms, joints.length );
// Build bones
const bones = [];
const bonesByPath = {};
const boneInverses = [];
for ( let i = 0; i < joints.length; i ++ ) {
const jointPath = joints[ i ];
const jointName = jointPath.split( '/' ).pop();
const bone = new Bone();
bone.name = jointName;
bones.push( bone );
bonesByPath[ jointPath ] = { bone, index: i };
// Compute inverse bind matrix
if ( bindTransforms && bindTransforms.length >= ( i + 1 ) * 16 ) {
const bindMatrix = new Matrix4();
// USD matrices are row-major, Three.js is column-major - need to transpose
const m = bindTransforms.slice( i * 16, ( i + 1 ) * 16 );
bindMatrix.set(
m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
);
const inverseBindMatrix = bindMatrix.clone().invert();
boneInverses.push( inverseBindMatrix );
} else {
boneInverses.push( new Matrix4() );
}
}
// Build parent-child relationships based on joint paths
for ( let i = 0; i < joints.length; i ++ ) {
const jointPath = joints[ i ];
const parts = jointPath.split( '/' );
if ( parts.length > 1 ) {
const parentPath = parts.slice( 0, - 1 ).join( '/' );
const parentData = bonesByPath[ parentPath ];
if ( parentData ) {
parentData.bone.add( bones[ i ] );
}
}
}
// Apply rest transforms as bone local transforms.
// Rest transforms are the skeleton's default local-space pose and match
// the reference frame used by SkelAnimation data. Bind transforms are
// world-space matrices used only for computing inverse bind matrices.
if ( restTransforms && restTransforms.length >= joints.length * 16 ) {
for ( let i = 0; i < joints.length; i ++ ) {
const matrix = new Matrix4();
const m = restTransforms.slice( i * 16, ( i + 1 ) * 16 );
matrix.set(
m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
);
matrix.decompose( bones[ i ].position, bones[ i ].quaternion, bones[ i ].scale );
}
}
// Find root bone(s) - bones without a parent bone
const rootBones = bones.filter( bone => ! bone.parent || ! bone.parent.isBone );
// Get animation source path
const animSourceSpec = this.specsByPath[ path + '.skel:animationSource' ];
let animationPath = null;
if ( animSourceSpec && animSourceSpec.fields.targetPaths && animSourceSpec.fields.targetPaths.length > 0 ) {
animationPath = animSourceSpec.fields.targetPaths[ 0 ];
}
return {
skeleton: new Skeleton( bones, boneInverses ),
joints: joints,
rootBones: rootBones,
animationPath: animationPath,
path: path
};
}
_bindSkeletons() {
for ( const meshData of this.skinnedMeshes ) {
const { mesh, skeletonPath, localJoints, geomBindTransform } = meshData;
let skeletonData = null;
// Try exact match first
if ( skeletonPath && this.skeletons[ skeletonPath ] ) {
skeletonData = this.skeletons[ skeletonPath ];
}
// Try includes match as fallback
if ( ! skeletonData ) {
for ( const skelPath in this.skeletons ) {
if ( skeletonPath && ( skeletonPath.includes( skelPath ) || skelPath.includes( skeletonPath ) ) ) {
skeletonData = this.skeletons[ skelPath ];
break;
}
}
}
// Fallback to first skeleton for single-skeleton files
if ( ! skeletonData ) {
const skeletonPaths = Object.keys( this.skeletons );
if ( skeletonPaths.length > 0 ) {
skeletonData = this.skeletons[ skeletonPaths[ 0 ] ];
}
}
if ( ! skeletonData ) {
console.warn( 'USDComposer: No skeleton found for skinned mesh', mesh.name );
continue;
}
const { skeleton, rootBones, joints } = skeletonData;
if ( localJoints && localJoints.length > 0 ) {
const skinIndex = mesh.geometry.attributes.skinIndex;
if ( skinIndex ) {
const localToGlobal = [];
for ( let i = 0; i < localJoints.length; i ++ ) {
const jointName = localJoints[ i ];
const globalIdx = joints.indexOf( jointName );
localToGlobal[ i ] = globalIdx >= 0 ? globalIdx : 0;
}
const arr = skinIndex.array;
for ( let i = 0; i < arr.length; i ++ ) {
const localIdx = arr[ i ];
if ( localIdx < localToGlobal.length ) {
arr[ i ] = localToGlobal[ localIdx ];
}
}
}
}
for ( const rootBone of rootBones ) {
mesh.add( rootBone );
}
// Use geomBindTransform if available, otherwise fall back to identity.
// Estimating bind transforms from vertex/joint samples is not robust and can
// produce severe skinning distortion for valid assets.
const bindMatrix = new Matrix4();
if ( geomBindTransform && geomBindTransform.length === 16 ) {
// USD matrices are row-major, Three.js is column-major - need to transpose
const m = geomBindTransform;
bindMatrix.set(
m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
);
}
mesh.bind( skeleton, bindMatrix );
}
}
_buildAnimations() {
const animations = [];
// Find all SkelAnimation prims
for ( const path in this.specsByPath ) {
const spec = this.specsByPath[ path ];
if ( spec.specType !== SpecType.Prim ) continue;
if ( spec.fields.typeName !== 'SkelAnimation' ) continue;
const clip = this._buildAnimationClip( path );
if ( clip ) {
animations.push( clip );
}
}
// Build transform animations from time-sampled xformOps
const transformTracks = this._buildTransformAnimations();
if ( transformTracks.length > 0 ) {
animations.push( new AnimationClip( 'TransformAnimation', - 1, transformTracks ) );
}
return animations;
}
_buildTransformAnimations() {
const tracks = [];
for ( const path in this.specsByPath ) {
const spec = this.specsByPath[ path ];
if ( spec.specType !== SpecType.Prim ) continue;
const typeName = spec.fields?.typeName;
if ( typeName !== 'Xform' && typeName !== 'Scope' && typeName !== 'Mesh' ) continue;
const objectName = path.split( '/' ).pop();
// Check for animated xformOp:orient
const orientPath = path + '.xformOp:orient';
const orientSpec = this.specsByPath[ orientPath ];
if ( orientSpec?.fields?.timeSamples ) {
const { times, values } = orientSpec.fields.timeSamples;
const keyframeTimes = [];
const keyframeValues = [];
for ( let i = 0; i < times.length; i ++ ) {
keyframeTimes.push( times[ i ] / this.fps );
const q = values[ i ];
keyframeValues.push( q[ 0 ], q[ 1 ], q[ 2 ], q[ 3 ] );
}
if ( keyframeTimes.length > 0 ) {
tracks.push( new QuaternionKeyframeTrack(
objectName + '.quaternion',
new Float32Array( keyframeTimes ),
new Float32Array( keyframeValues )
) );
}
}
// Check for animated xformOp:rotateXYZ
const rotateXYZPath = path + '.xformOp:rotateXYZ';
const rotateXYZSpec = this.specsByPath[ rotateXYZPath ];
if ( rotateXYZSpec?.fields?.timeSamples ) {
const { times, values } = rotateXYZSpec.fields.timeSamples;
const keyframeTimes = [];
const keyframeValues = [];
const tempEuler = new Euler();
const tempQuat = new Quaternion();
for ( let i = 0; i < times.length; i ++ ) {
keyframeTimes.push( times[ i ] / this.fps );
const r = values[ i ];
// USD rotateXYZ: matrix = Rx * Ry * Rz, use 'ZYX' order in Three.js
tempEuler.set(
r[ 0 ] * Math.PI / 180,
r[ 1 ] * Math.PI / 180,
r[ 2 ] * Math.PI / 180,
'ZYX'
);
tempQuat.setFromEuler( tempEuler );
keyframeValues.push( tempQuat.x, tempQuat.y, tempQuat.z, tempQuat.w );
}
if ( keyframeTimes.length > 0 ) {
tracks.push( new QuaternionKeyframeTrack(
objectName + '.quaternion',
new Float32Array( keyframeTimes ),
new Float32Array( keyframeValues )
) );
}
}
// Check for animated xformOp:translate
const translatePath = path + '.xformOp:translate';
const translateSpec = this.specsByPath[ translatePath ];
if ( translateSpec?.fields?.timeSamples ) {
const { times, values } = translateSpec.fields.timeSamples;
const keyframeTimes = [];
const keyframeValues = [];
for ( let i = 0; i < times.length; i ++ ) {
keyframeTimes.push( times[ i ] / this.fps );
const t = values[ i ];
keyframeValues.push( t[ 0 ], t[ 1 ], t[ 2 ] );
}
if ( keyframeTimes.length > 0 ) {
tracks.push( new VectorKeyframeTrack(
objectName + '.position',
new Float32Array( keyframeTimes ),
new Float32Array( keyframeValues )
) );
}
}
// Check for animated xformOp:scale
const scalePath = path + '.xformOp:scale';
const scaleSpec = this.specsByPath[ scalePath ];
if ( scaleSpec?.fields?.timeSamples ) {
const { times, values } = scaleSpec.fields.timeSamples;
const keyframeTimes = [];
const keyframeValues = [];
for ( let i = 0; i < times.length; i ++ ) {
keyframeTimes.push( times[ i ] / this.fps );
const s = values[ i ];
keyframeValues.push( s[ 0 ], s[ 1 ], s[ 2 ] );
}
if ( keyframeTimes.length > 0 ) {
tracks.push( new VectorKeyframeTrack(
objectName + '.scale',
new Float32Array( keyframeTimes ),
new Float32Array( keyframeValues )
) );
}
}
// Check for animated xformOp:transform (matrix animations)
// These can have suffixes like xformOp:transform:transform
const properties = spec.fields?.properties || [];
for ( const prop of properties ) {
if ( ! prop.startsWith( 'xformOp:transform' ) ) continue;
const transformPath = path + '.' + prop;
const transformSpec = this.specsByPath[ transformPath ];
if ( ! transformSpec?.fields?.timeSamples ) continue;
const { times, values } = transformSpec.fields.timeSamples;
const positionTimes = [];
const positionValues = [];
const quaternionTimes = [];
const quaternionValues = [];
const scaleTimes = [];
const scaleValues = [];
const matrix = new Matrix4();
const position = new Vector3();
const quaternion = new Quaternion();
const scale = new Vector3();
for ( let i = 0; i < times.length; i ++ ) {
const m = values[ i ];
if ( ! m || m.length < 16 ) continue;
const t = times[ i ] / this.fps;
// USD matrices are row-major, Three.js is column-major
matrix.set(
m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
);
matrix.decompose( position, quaternion, scale );
positionTimes.push( t );
positionValues.push( position.x, position.y, position.z );
quaternionTimes.push( t );
quaternionValues.push( quaternion.x, quaternion.y, quaternion.z, quaternion.w );
scaleTimes.push( t );
scaleValues.push( scale.x, scale.y, scale.z );
}
if ( positionTimes.length > 0 ) {
tracks.push( new VectorKeyframeTrack(
objectName + '.position',
new Float32Array( positionTimes ),
new Float32Array( positionValues )
) );
tracks.push( new QuaternionKeyframeTrack(
objectName + '.quaternion',
new Float32Array( quaternionTimes ),
new Float32Array( quaternionValues )
) );
tracks.push( new VectorKeyframeTrack(
objectName + '.scale',
new Float32Array( scaleTimes ),
new Float32Array( scaleValues )
) );
}
break; // Only process first transform op
}
}
return tracks;
}
_buildAnimationClip( path ) {
const attrs = this._getAttributes( path );
const joints = attrs[ 'joints' ];
if ( ! joints || joints.length === 0 ) return null;
const tracks = [];
// Get rotation time samples
const rotationsAttr = this._getTimeSampledAttribute( path, 'rotations' );
if ( rotationsAttr && rotationsAttr.times && rotationsAttr.values ) {
const { times, values } = rotationsAttr;
for ( let jointIdx = 0; jointIdx < joints.length; jointIdx ++ ) {
const jointName = joints[ jointIdx ].split( '/' ).pop();
const keyframeTimes = [];
const keyframeValues = [];
for ( let t = 0; t < times.length; t ++ ) {
const quatData = values[ t ];
if ( ! quatData || quatData.length < ( jointIdx + 1 ) * 4 ) continue;
keyframeTimes.push( times[ t ] / this.fps );
// USD GfQuatf stores imaginary (x,y,z) first, then real (w)
// This matches Three.js quaternion order (x,y,z,w)
const x = quatData[ jointIdx * 4 + 0 ];
const y = quatData[ jointIdx * 4 + 1 ];
const z = quatData[ jointIdx * 4 + 2 ];
const w = quatData[ jointIdx * 4 + 3 ];
keyframeValues.push( x, y, z, w );
}
if ( keyframeTimes.length > 0 ) {
tracks.push( new QuaternionKeyframeTrack(
jointName + '.quaternion',
new Float32Array( keyframeTimes ),
new Float32Array( keyframeValues )
) );
}
}
}
// Get translation time samples
const translationsAttr = this._getTimeSampledAttribute( path, 'translations' );
if ( translationsAttr && translationsAttr.times && translationsAttr.values ) {
const { times, values } = translationsAttr;
for ( let jointIdx = 0; jointIdx < joints.length; jointIdx ++ ) {
const jointName = joints[ jointIdx ].split( '/' ).pop();
const keyframeTimes = [];
const keyframeValues = [];
for ( let t = 0; t < times.length; t ++ ) {
const transData = values[ t ];
if ( ! transData || transData.length < ( jointIdx + 1 ) * 3 ) continue;
keyframeTimes.push( times[ t ] / this.fps );
keyframeValues.push(
transData[ jointIdx * 3 + 0 ],
transData[ jointIdx * 3 + 1 ],
transData[ jointIdx * 3 + 2 ]
);
}
if ( keyframeTimes.length > 0 ) {
tracks.push( new VectorKeyframeTrack(
jointName + '.position',
new Float32Array( keyframeTimes ),
new Float32Array( keyframeValues )
) );
}
}
}
// Get scale time samples
const scalesAttr = this._getTimeSampledAttribute( path, 'scales' );
if ( scalesAttr && scalesAttr.times && scalesAttr.values ) {
const { times, values } = scalesAttr;
for ( let jointIdx = 0; jointIdx < joints.length; jointIdx ++ ) {
const jointName = joints[ jointIdx ].split( '/' ).pop();
const keyframeTimes = [];
const keyframeValues = [];
for ( let t = 0; t < times.length; t ++ ) {
const scaleData = values[ t ];
if ( ! scaleData || scaleData.length < ( jointIdx + 1 ) * 3 ) continue;
keyframeTimes.push( times[ t ] / this.fps );
keyframeValues.push(
scaleData[ jointIdx * 3 + 0 ],
scaleData[ jointIdx * 3 + 1 ],
scaleData[ jointIdx * 3 + 2 ]
);
}
if ( keyframeTimes.length > 0 ) {
tracks.push( new VectorKeyframeTrack(
jointName + '.scale',
new Float32Array( keyframeTimes ),
new Float32Array( keyframeValues )
) );
}
}
}
if ( tracks.length === 0 ) return null;
const clipName = path.split( '/' ).pop();
return new AnimationClip( clipName, - 1, tracks );
}
_getTimeSampledAttribute( primPath, attrName ) {
// Look for the attribute spec with time samples
const attrPath = primPath + '.' + attrName;
const attrSpec = this.specsByPath[ attrPath ];
if ( attrSpec && attrSpec.fields.timeSamples ) {
const timeSamples = attrSpec.fields.timeSamples;
if ( timeSamples.times && timeSamples.values ) {
return timeSamples;
}
}
return null;
}
_flattenMatrixArray( matrices, numMatrices ) {
if ( ! matrices || matrices.length === 0 ) return null;
if ( typeof matrices[ 0 ] === 'number' ) return matrices;
const flatArray = [];
for ( let m = 0; m < numMatrices; m ++ ) {
for ( let row = 0; row < 4; row ++ ) {
const rowData = matrices[ m * 4 + row ];
if ( rowData && rowData.length === 4 ) {
flatArray.push( rowData[ 0 ], rowData[ 1 ], rowData[ 2 ], rowData[ 3 ] );
} else {
flatArray.push( row === 0 ? 1 : 0, row === 1 ? 1 : 0, row === 2 ? 1 : 0, row === 3 ? 1 : 0 );
}
}
}
return flatArray;
}
}
export { USDComposer, SpecType };