{"id":6483,"library":"xatlas","title":"xatlas-python","description":"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.","status":"active","version":"0.0.11","language":"en","source_language":"en","source_url":"https://github.com/mworchel/xatlas-python","tags":["3d","uv mapping","texture atlas","mesh processing","geometry"],"install":[{"cmd":"pip install xatlas","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for array input/output for mesh data (vertices, indices, UVs).","package":"numpy","optional":false}],"imports":[{"symbol":"Atlas","correct":"import xatlas\natlas = xatlas.Atlas()"}],"quickstart":{"code":"import xatlas\nimport numpy as np\n\n# Create an atlas instance\natlas = xatlas.Atlas()\n\n# Define a simple mesh (e.g., a quad)\nvertices = np.array([\n    [0.0, 0.0, 0.0],\n    [1.0, 0.0, 0.0],\n    [0.0, 1.0, 0.0],\n    [1.0, 1.0, 0.0],\n], dtype=np.float32)\n\nindices = np.array([\n    [0, 1, 2],\n    [2, 1, 3],\n], dtype=np.uint32)\n\n# Add the mesh to the atlas\natlas.add_mesh(vertices, indices)\n\n# Generate the UV atlas\natlas.generate()\n\n# Access the generated meshes and their UVs\nprint(f\"Generated {len(atlas.meshes)} mesh(es).\")\nfor i, mesh in enumerate(atlas.meshes):\n    print(f\"\\nMesh {i}:\")\n    print(f\"  Vertices shape: {mesh.vertices.shape} (position data)\")\n    print(f\"  Indices shape: {mesh.indices.shape} (triangle connectivity)\")\n    print(f\"  UVs shape: {mesh.uvs.shape} (texture coordinates)\")\n    # Example: print first few UVs\n    if mesh.uvs.size > 0:\n        print(f\"  First 3 UVs:\\n{mesh.uvs[:3]}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Consult the GitHub releases page and documentation for specific version changes before upgrading. Pin exact versions in production environments.","message":"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.","severity":"gotcha","affected_versions":"All versions below 1.0.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":"Before 0.0.8"},{"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`.","message":"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.","severity":"breaking","affected_versions":"Before 0.0.5"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Download and install the 'Build Tools for Visual Studio' from the provided link, ensuring the 'Desktop development with C++' workload is selected during installation.","cause":"The xatlas Python bindings are a C++ extension and require compatible Microsoft Visual C++ Build Tools on Windows for successful compilation during installation.","error":"error: Microsoft Visual C++ 14.0 or greater is required. Get it with 'Build Tools for Visual Studio': https://visualstudio.microsoft.com/downloads/"},{"fix":"Reinstall `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.","cause":"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.","error":"ModuleNotFoundError: No module named 'xatlas'"},{"fix":"Install 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`.","cause":"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`.","error":"fatal error: Python.h: No such file or directory"},{"fix":"Ensure 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).","cause":"The NumPy array provided for mesh attributes like `vertices` does not match the required shape or dimensions expected by the `xatlas` library.","error":"RuntimeError: vertices must be an Nx3 array"}]}