Skip to content


Switch branches/tags


Actions Status Appveyor CI Build Status License: MIT

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.


Example - Cesium Milk Truck

Viewer Random packing Brute force packing
Viewer Random packing Brute force packing

Example - Godot Third Person Shooter demo

Godot TPS



How to use


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


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

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


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

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



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


Bakery - GPU Lightmapper

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


Godot Engine


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


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


Mesh parameterization / UV unwrapping library








No releases published


No packages published