Install & Compatibility
Where this runs
tested against v0.0.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 21.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.002s · 19MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Atlas
✓ import xatlas
atlas = xatlas.Atlas()
This quickstart demonstrates how to initialize an `Atlas`, add a mesh defined by NumPy arrays for vertices and indices, generate the UV atlas, and then access the resulting meshes with their generated UV coordinates. Input data types (`np.float32` for vertices, `np.uint32` for indices) are crucial.
import xatlas
import numpy as np
# Create an atlas instance
atlas = xatlas.Atlas()
# Define a simple mesh (e.g., a quad)
vertices = np.array([
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
[1.0, 1.0, 0.0],
], dtype=np.float32)
indices = np.array([
[0, 1, 2],
[2, 1, 3],
], dtype=np.uint32)
# Add the mesh to the atlas
atlas.add_mesh(vertices, indices)
# Generate the UV atlas
atlas.generate()
# Access the generated meshes and their UVs
print(f"Generated {len(atlas.meshes)} mesh(es).")
for i, mesh in enumerate(atlas.meshes):
print(f"\nMesh {i}:")
print(f" Vertices shape: {mesh.vertices.shape} (position data)")
print(f" Indices shape: {mesh.indices.shape} (triangle connectivity)")
print(f" UVs shape: {mesh.uvs.shape} (texture coordinates)")
# Example: print first few UVs
if mesh.uvs.size > 0:
print(f" First 3 UVs:\n{mesh.uvs[:3]}")
Debug
Known issues
gotchaThe library is in `0.0.x` versioning. This means the API is not yet stable and breaking changes may occur in minor or patch releases without strict adherence to semantic versioning. Always review release notes when upgrading.fixConsult the GitHub releases page and documentation for specific version changes before upgrading. Pin exact versions in production environments.
affects: All versions below 1.0.0
gotchaInput mesh data (vertices and indices) must be provided as specific NumPy data types: `numpy.float32` for vertices and `numpy.uint32` for indices. Using incorrect types will lead to runtime errors or incorrect behavior.fixEnsure your NumPy arrays are explicitly cast to the correct data types, e.g., `vertices = np.array([...], dtype=np.float32)` and `indices = np.array([...], dtype=np.uint32)`.
affects: All versions
breakingThe parameter naming for the `Atlas.add_mesh` function was fixed in version `0.0.8`. Users upgrading from `0.0.7` or earlier versions might find their `add_mesh` calls failing due to changed keyword argument names.fixIf upgrading from `0.0.7` or earlier, consult the `v0.0.8` release notes or the latest documentation/examples on GitHub to verify the correct parameter names for `Atlas.add_mesh`.
affects: Before 0.0.8
breakingThe parameter naming for the `parametrize` function (e.g., `atlas.parametrize()`) was fixed in version `0.0.5`. Similar to `add_mesh`, users on older versions may encounter breaking changes if they relied on previous parameter names.fixIf upgrading from `0.0.4` or earlier, check the `v0.0.5` release notes or latest documentation for the correct parameter names when calling `parametrize`.
affects: Before 0.0.5
Errors
Common errors & fixes
error: Microsoft Visual C++ 14.0 or greater is required. Get it with 'Build Tools for Visual Studio': https://visualstudio.microsoft.com/downloads/
The xatlas Python bindings are a C++ extension and require compatible Microsoft Visual C++ Build Tools on Windows for successful compilation during installation.
fixDownload and install the 'Build Tools for Visual Studio' from the provided link, ensuring the 'Desktop development with C++' workload is selected during installation.
ModuleNotFoundError: No module named 'xatlas'
The xatlas package or its C++ extensions failed to install correctly, or it's not installed in the active Python environment, often due to missing build dependencies.
fixReinstall `xatlas` (`pip install xatlas`) after verifying all necessary build tools (e.g., `python3-dev` on Linux, Visual C++ Build Tools on Windows) are present for successful compilation. Check the full `pip install` output for specific build errors.
fatal error: Python.h: No such file or directory
On Linux, building Python packages with C/C++ extensions requires the Python development headers, which are typically provided by packages like `python3-dev` or `python3-devel`.
fixInstall the Python development headers using your system's package manager (e.g., `sudo apt-get install python3-dev` on Debian/Ubuntu, `sudo yum install python3-devel` on RHEL/CentOS), then retry `pip install xatlas`.
RuntimeError: vertices must be an Nx3 array
The NumPy array provided for mesh attributes like `vertices` does not match the required shape or dimensions expected by the `xatlas` library.
fixEnsure the NumPy array has the correct shape for the attribute (e.g., `(N, 3)` for vertices, `(N, 2)` for uvs, and `(N,)` for indices) and the correct data type (e.g., `np.float32` for coordinates, `np.uint32` for indices).
Upgrade
Version history
0.0.11latest on PyPI · released Jul 4, 2025
Audit
Dependencies
numpyrequiredRequired for array input/output for mesh data (vertices, indices, UVs).