xAtlas + three.js: Mesh parameterization / UV unwrapping module for three.js in wasm with webworkers.
Can be used to unwrap UVs in BufferGeometry or pack multiple geometries into a single atlas for lightmap/AO baking.
To use xatlas in JS without three.js you can use xatlas.js directly.
Unwrap geometry and debug UV
./public/uvs-debug.html
Demo: https://repalash.com/xatlas-three/public/uvs-debug.html
Pack multiple geometries into a single atlas and unwrap GLTF
./public/pack-atlas.html
Demo: https://repalash.com/xatlas-three/public/pack-atlas.html
Install via npm by running:
npm install xatlas-three
Create an instance for UVUnwrapper and optionally set the packing and charting options for xatlas.
const unwrapper = new UVUnwrapper({BufferAttribute: THREE.BufferAttribute});
// Default options
unwrapper.chartOptions = {
fixWinding: false,
maxBoundaryLength: 0,
maxChartArea: 0,
maxCost: 2,
maxIterations: 1,
normalDeviationWeight: 2,
normalSeamWeight: 4,
roundnessWeight: 0.009999999776482582,
straightnessWeight: 6,
textureSeamWeight: 0.5,
useInputMeshUvs: false,
}
unwrapper.packOptions = {
bilinear: true,
blockAlign: false,
bruteForce: false,
createImage: false,
maxChartSize: 0,
padding: 0,
resolution: 0,
rotateCharts: true,
rotateChartsToAxis: true,
texelsPerUnit: 0
}
Next load the xatlasjs library:
await unwrapper.loadLibrary(
(mode, progress)=>{console.log(mode, progress);},
'https://cdn.jsdelivr.net/npm/[email protected]/dist/xatlas.wasm',
'https://cdn.jsdelivr.net/npm/[email protected]/dist/xatlas.js',
); // Make sure to wait for the library to load before unwrapping.
Here jsdelivr cdn link is used to load the xatlas.js library, any custom link can be passed. Check xatlasjs on npmjs for more details and latest version
To unwrap a THREE.BufferGeometry:
await unwrapper.unwrap(geometry);
Here, generated UVs will be written to ‘uv’ attribute, and any original uvs will be written to ‘uv2’ attribute. This can be customised by passing in a custom attribute name.
Note: only indexed geometry is supported, a non-indexed geometry can be converted to indexed geometry using THREE.BufferGeometryUtils.mergeVertices. See any example for details.
To Pack multiple geometries into a single atlas
await unwrapper.packAtlas([geometry1, geometry2, geometry3, ...]);
Here, generated UVs will be written to the ‘uv2’ attribute of each geometry, this can be customized by passing in a custom attribute name.
Note:
Import the UVUnwrapper class from src/unwrapperNodeWorker and load xatlas.js(worker.mjs and xatlas.wasm) from node_modules/other local path.
See ./test/node-worker.ts for an example. Run with npx tsx test/node-worker.ts
npm install
npm start
npm run build
packAtlas and unwrapGeometry methods return the Atlas object instead of the list of geometries. Use atlas.geometries to get the list of geometries.userData.xAtlasSubMeshes of the geometry.