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:

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:

• 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

Installing dependencies

npm install

Running the project in watch mode

npm start

Building the project

npm run build

Changelog

0.2.1

• 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.

0.1.0

• Initial release