/xatlas

Mesh parameterization / UV unwrapping library

Primary LanguageC++MIT LicenseMIT

xatlas

Appveyor CI Build Status Travis CI Build Status License: MIT

A cleaned up version of thekla_atlas.

Mesh charting, parameterization and atlas packing. Suitable for generating unique texture coordinates for baking lightmaps.

Changes from thekla_atlas

  • Smaller code size - from about 18 KLOC to 9 KLOC
  • Easier to integrate and build - a single source/header file pair instead of around 120 files and 10 directories.
  • Atlas resolution option for outputting multiple atlases.
  • Flexible data description API for input meshes.
  • Better tolerance of bad input geometry. Zero length edges and zero area faces are ignored.
  • Support for packing multiple atlases/parameterizations into a single atlas.

How to use

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.
  2. xatlas::ParameterizeCharts: charts are flattened into 2D parameterizations.
  3. 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.

TODO

  • Adding meshes: check for overlapping and intersecting geometry
  • Parameterization: use a better hole filling argorithm for non-planar holes
  • Packing: bilinear-aware rasterization
  • Viewer: bake lightmaps with simple path tracer
  • Viewer: chart picking in scene and texture views

Technical information

Ignacio Castaño's blog post on thekla_atlas

Related projects

Microsoft's UVAtlas - isochart texture atlasing.

Ministry of Flat - Commercial automated UV unwrapper.

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

aobaker - Ambient occlusion baking. Uses thekla_atlas.

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

Models used

Gazebo model by Teh_Bucket

Tunnel scene by LMHPoly