jpcy / Xatlas

xatlas

xatlas is a small C++11 library with no external dependencies that generates unique texture coordinates suitable for baking lightmaps or texture painting.

It is an independent fork of thekla_atlas, used by The Witness.

Screenshots

Example - Cesium Milk Truck

Viewer	Random packing	Brute force packing

Example - Godot Third Person Shooter demo

Graphite/Geogram

How to use

Building

Premake is used. For CMake support, see here.

Integration into an existing build is simple, only xatlas.cpp and xatlas.h are required. They can be found in source/xatlas

Windows

Run build\premake.bat. Open build\vs2019\xatlas.sln.

Note: change the build configuration to "Release". The default - "Debug" - severely degrades performance.

Linux

Required packages: libgl1-mesa-dev libgtk-3-dev xorg-dev.

Install Premake version 5. Run premake5 gmake, cd build/gmake, make.

Bindings

Python

Generate an atlas (simple API)

1. Create an empty atlas with xatlas::Create.
2. Add one or more meshes with xatlas::AddMesh.
3. Call xatlas::Generate. Meshes are segmented into charts, which are parameterized and packed into an atlas.

The xatlas::Atlas instance created in the first step now contains the result: each input mesh added by xatlas::AddMesh has a corresponding new mesh with a UV channel. New meshes have more vertices (the UV channel adds seams), but the same number of indices.

Cleanup with xatlas::Destroy.

Example code here.

Generate an atlas (tools/editor integration API)

Instead of calling xatlas::Generate, the following functions can be called in sequence:

1. xatlas::ComputeCharts: meshes are segmented into charts and parameterized.
2. xatlas::PackCharts: charts are packed into one or more atlases.

All of these functions take a progress callback. Return false to cancel.

You can call any of these functions multiple times, followed by the proceeding functions, to re-generate the atlas. E.g. calling xatlas::PackCharts multiple times to tweak options like unit to texel scale and resolution.

See the viewer for example code.

Pack multiple atlases into a single atlas

1. Create an empty atlas with xatlas::Create.
2. Add one or more meshes with xatlas::AddUvMesh.
3. Call xatlas::PackCharts.

Example code here.

Technical information / related publications

Ignacio Castaño's blog post on thekla_atlas

P. Sander, J. Snyder, S. Gortler, and H. Hoppe. Texture Mapping Progressive Meshes

K. Hormann, B. Lévy, and A. Sheffer. Mesh Parameterization: Theory and Practice

P. Sander, Z. Wood, S. Gortler, J. Snyder, and H. Hoppe. Multi-Chart Geometry Images

D. Julius, V. Kraevoy, and A. Sheffer. D-Charts: Quasi-Developable Mesh Segmentation

B. Lévy, S. Petitjean, N. Ray, and J. Maillot. Least Squares Conformal Maps for Automatic Texture Atlas Generation

O. Sorkine, D. Cohen-Or, R. Goldenthal, and D. Lischinski. Bounded-distortion Piecewise Mesh Parameterization

Y. O’Donnell. Precomputed Global Illumination in Frostbite

Used by

ArmorPaint

Bakery - GPU Lightmapper

DXR Ambient Occlusion Baking - A demo of ambient occlusion map baking using DXR inline ray tracing.

Filament

Godot Engine

Graphite/Geogram

Lightmaps - An OpenGL sample demonstrating path traced lightmap baking on the CPU with Embree

redner

Skylicht Engine

toy / two

UNIGINE - video

Wicked Engine

Related projects

aobaker - Ambient occlusion baking. Uses thekla_atlas.

Lightmapper - Hemicube based lightmap baking. The example model texture coordinates were generated by thekla_atlas.

Microsoft's UVAtlas - isochart texture atlasing.

Ministry of Flat - Commercial automated UV unwrapper.

seamoptimizer - A C/C++ single-file library that minimizes the hard transition errors of disjoint edges in lightmaps.

simpleuv - Automatic UV Unwrapping Library for Dust3D.

Models used

Gazebo model by Teh_Bucket