xAtlas-three

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.

Examples

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

Usage

Install via npm by running:
``sh
npm install xatlas-three
`

Create an instance for UVUnwrapper and optionally set the packing and charting options for xatlas.
`js
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:
`js

await unwrapper.loadLibrary(
(mode, progress)=>{console.log(mode, progress);},
'https://cdn.jsdelivr.net/npm/xatlasjs@0.2.0/dist/xatlas.wasm',
'https://cdn.jsdelivr.net/npm/xatlasjs@0.2.0/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:
`js
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
`js

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:
* xatlas might add or remove some vertices data.
* interleaved geometry is not yet supported.

Nodejs (not tested)

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

Development

$3

npm install

$3

npm start

$3

npm run build




Changelog

$3


- Update xatlasjs to 0.2.0
- packAtlas and unwrapGeometry methods return the Atlas object instead of the list of geometries. Use atlas.geometries to get the list of geometries.
- Any subMesh data (in case of multiple sub-atlas), is saved to userData.xAtlasSubMeshes` of the geometry.
- Throws error in-case of invalid inputs.

$3

- Initial release