@needle-tools/three
Version:
JavaScript 3D library
2,049 lines (1,296 loc) • 95.6 kB
JavaScript
import {
AnimationClip,
BufferAttribute,
BufferGeometry,
ClampToEdgeWrapping,
Euler,
Group,
Matrix4,
Mesh,
MeshPhysicalMaterial,
MirroredRepeatWrapping,
NoColorSpace,
Object3D,
Quaternion,
QuaternionKeyframeTrack,
RepeatWrapping,
ShapeUtils,
SkinnedMesh,
Skeleton,
Bone,
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
};
/**
* 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;
}
/**
* 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 = {};
// 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.framesPerSecond || rootFields.timeCodesPerSecond || 30;
const group = new Group();
this._buildHierarchy( group, '/' );
// Bind skeletons to skinned meshes
this._bindSkeletons();
// Build animations
group.animations = this._buildAnimations();
// 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 of materials)
if ( typeName === 'Shader' && lastSlash > 0 ) {
const materialPath = path.slice( 0, lastSlash );
if ( ! this.shadersByMaterialPath.has( materialPath ) ) {
this.shadersByMaterialPath.set( materialPath, [] );
}
this.shadersByMaterialPath.get( materialPath ).push( path );
}
// 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 refValue = this._getReference( spec );
if ( refValue ) {
// Get local variant selections from this prim
const localVariants = this._getLocalVariantSelections( spec.fields );
// Resolve the reference
const referencedGroup = this._resolveReference( refValue, localVariants );
if ( referencedGroup ) {
const attrs = this._getAttributes( path );
// Check if the referenced content is a single mesh (or container with single mesh)
// This handles the USDZExporter pattern: Xform references geometry file
const singleMesh = this._findSingleMesh( referencedGroup );
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 );
} else {
// Create a container for the referenced content
const obj = new Object3D();
obj.name = name;
this.applyTransform( obj, spec.fields, attrs );
// Add all children from the referenced group
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 );
}
} else if ( typeName === 'Material' || typeName === 'Shader' ) {
// Skip materials/shaders, 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 );
}
// Combine with base path
if ( this.basePath ) {
return this.basePath + '/' + cleanPath;
}
return cleanPath;
}
/**
* 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 reference value from a prim spec.
*/
_getReference( spec ) {
if ( spec.fields.references && spec.fields.references.length > 0 ) {
const ref = spec.fields.references[ 0 ];
if ( typeof ref === 'string' ) return ref;
if ( ref.assetPath ) return '@' + ref.assetPath + '@';
}
if ( spec.fields.payload ) {
const payload = spec.fields.payload;
if ( typeof payload === 'string' ) return payload;
if ( payload.assetPath ) return '@' + payload.assetPath + '@';
}
return null;
}
/**
* 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 ) {
if ( attrSpec.fields?.default !== undefined ) {
attrs[ attrName ] = attrSpec.fields.default;
} else if ( attrSpec.fields?.timeSamples ) {
// For animated attributes without default, use the first time sample (rest pose)
const { times, values } = attrSpec.fields.timeSamples;
if ( times && values && times.length > 0 ) {
// Find time 0, or use the first available time
const idx = times.indexOf( 0 );
attrs[ attrName ] = idx >= 0 ? values[ idx ] : values[ 0 ];
}
}
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 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 ) {
const opacity = displayOpacity[ 0 ];
const applyDisplayOpacity = ( mat ) => {
if ( opacity < 1 ) {
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;
}
_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
let materialPath = this._getMaterialBindingTarget( p );
subsets.push( {
name: p.split( '/' ).pop(),
indices: indices,
materialPath: materialPath
} );
}
return subsets;
}
/**
* Get material binding target path, checking variant paths if needed.
*/
_getMaterialBindingTarget( primPath ) {
const attrName = 'material:binding';
// First check direct path
const directPath = primPath + '.' + attrName;
const directSpec = this.specsByPath[ directPath ];
if ( directSpec?.fields?.targetPaths?.length > 0 ) {
return directSpec.fields.targetPaths[ 0 ];
}
// Check variant paths at ancestor levels
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 ) {
return overrideSpec.fields.targetPaths[ 0 ];
}
}
}
return 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 {
geometry.computeVertexNormals();
}
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 );
for ( let i = 0; i < numVertices; i ++ ) {
for ( let j = 0; j < 4; j ++ ) {
if ( j < elementSize ) {
skinIndices[ i * 4 + j ] = skinIndexData[ i * elementSize + j ] || 0;
skinWeights[ i * 4 + j ] = skinWeightData[ i * elementSize + j ] || 0;
} else {
skinIndices[ i * 4 + j ] = 0;
skinWeights[ i * 4 + j ] = 0;
}
}
}
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 origUvIndices = uvIndices ? this._applyTriangulationPattern( uvIndices, triPattern ) : null;
const origUv2Indices = uv2Indices ? this._applyTriangulationPattern( uv2Indices, triPattern ) : null;
const numFaceVertices = faceVertexCounts.reduce( ( a, b ) => a + b, 0 );
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 );
// 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 ? new Float32Array( vertexCount * 3 ) : null;
const skinIndexData = jointIndices ? new Uint16Array( vertexCount * 4 ) : null;
const skinWeightData = jointWeights ? new Float32Array( vertexCount * 4 ) : 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 && normals ) {
if ( 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.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 ];
}
}
if ( skinIndexData && skinWeightData && jointIndices && jointWeights ) {
for ( let j = 0; j < 4; j ++ ) {
if ( j < elementSize ) {
skinIndexData[ newIdx * 4 + j ] = jointIndices[ pointIdx * elementSize + j ] || 0;
skinWeightData[ newIdx * 4 + j ] = jointWeights[ pointIdx * elementSize + j ] || 0;
} else {
skinIndexData[ newIdx * 4 + j ] = 0;
skinWeightData[ newIdx * 4 + 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 ) );
}
if ( normalData ) {
geometry.setAttribute( 'normal', new BufferAttribute( normalData, 3 ) );
} else {
geometry.computeVertexNormals();
}
if ( skinIndexData ) {
geometry.setAttribute( 'skinIndex', new BufferAttribute( skinIndexData, 4 ) );
}
if ( skinWeightData ) {
geometry.setAttribute( 'skinWeight', new BufferAttribute( skinWeightData, 4 ) );
}
return geometry;
}
_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