xatlas-python

0.0.11 · active · verified Wed Apr 15

xatlas-python provides Python bindings for xatlas, a C++ library for generating UV atlases. It allows users to create texture atlases for 3D meshes, optimizing texture space and improving rendering performance. The current version is 0.0.11, and releases occur semi-regularly as new features are added or bugs fixed, typically every few months, reflecting active development.

Warnings

gotcha The 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.
Fix: Consult the GitHub releases page and documentation for specific version changes before upgrading. Pin exact versions in production environments.
gotcha Input 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.
Fix: Ensure 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)`.
breaking The 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.
Fix: If 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`.
breaking The 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.
Fix: If 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`.

Install

pip install xatlas Install stable version

Imports

Atlas
```
import xatlas
atlas = xatlas.Atlas()
```

Quickstart

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]}")

view raw JSON →