GeoTex: UV Unwrapping for Python via Geogram

GeoTex is a minimal Python wrapper that exposes the UV atlas generation functions from Geogram. Given a triangulated 3D mesh, it produces per-corner UV coordinates packed into a texture atlas, ready to be used for texture mapping or baking.

Installation

Install from PyPI:

pip install geotex

Or install the latest version directly from GitHub:

pip install git+https://github.com/vork/geotex.git

Usage

Basic example

import numpy as np
import geotex

# Define a simple mesh (a single triangle here, but any triangulated mesh works)
vertices = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0],
], dtype=np.float64)

faces = np.array([
    [0, 1, 2],
], dtype=np.uint32)

# Generate UV atlas with default settings
uv = geotex.make_atlas(vertices, faces)

# uv has shape (len(faces) * 3, 2):
# one (u, v) coordinate per face corner, in [0, 1] x [0, 1]
print(uv.shape)   # (3, 2)
print(uv)

Cube mesh example

import numpy as np
import geotex

vertices = np.array([
    [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],  # bottom face
    [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1],  # top face
], dtype=np.float64)

faces = np.array([
    [0, 1, 2], [0, 2, 3],  # bottom
    [4, 5, 6], [4, 6, 7],  # top
    [0, 1, 5], [0, 5, 4],  # front
    [2, 3, 7], [2, 7, 6],  # back
    [0, 3, 7], [0, 7, 4],  # left
    [1, 2, 6], [1, 6, 5],  # right
], dtype=np.uint32)

uv = geotex.make_atlas(vertices, faces)
print(uv.shape)   # (36, 2)  — 12 triangles × 3 corners

Choosing a parameterizer and packer

# Use LSCM parameterization with the tetris packer
uv = geotex.make_atlas(
    vertices, faces,
    parameterizer="lscm",
    packer="tetris",
)

# Control the hard-angle threshold (in degrees) used to split charts
uv = geotex.make_atlas(vertices, faces, hard_angles_threshold=60.0)

API Reference

geotex.make_atlas

geotex.make_atlas(
    vertices,
    faces,
    hard_angles_threshold=45.0,
    parameterizer="abf",
    packer="xatlas",
    verbose=False,
) -> np.ndarray

Parameters

Returns

np.ndarray of shape (M * 3, 2) and dtype float64 — one (u, v) coordinate per face corner, with values in [0, 1].

License

The project is licensed under BSD 3.

Geogram is also licensed under BSD 3.