Mesh

kiui.mesh.Mesh class provides an implementation of triangle meshes in PyTorch.

kiui.mesh_utils provides utility functions for mesh processing and loss functions.

Examples

import kiui
from kiui.mesh import Mesh

# load mesh
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
mesh = Mesh.load('model.glb', device=device)

# inspect attributes
kiui.lo(mesh.v, mesh.f, mesh.albedo, mesh.vt, mesh.ft, mesh.vn, mesh.fn)

# write mesh (can change to obj format)
mesh.write('model.obj')

API

class kiui.mesh.Mesh(v: Tensor | None = None, f: Tensor | None = None, vn: Tensor | None = None, fn: Tensor | None = None, vt: Tensor | None = None, ft: Tensor | None = None, vc: Tensor | None = None, albedo: Tensor | None = None, metallicRoughness: Tensor | None = None, device: device | None = None)[source]

A torch-native trimesh class, with support for ply/obj/glb formats.

Note

This class only supports one mesh with a single texture image (an albedo texture and a metallic-roughness texture).

__init__(v: Tensor | None = None, f: Tensor | None = None, vn: Tensor | None = None, fn: Tensor | None = None, vt: Tensor | None = None, ft: Tensor | None = None, vc: Tensor | None = None, albedo: Tensor | None = None, metallicRoughness: Tensor | None = None, device: device | None = None)[source]

Init a mesh directly using all attributes.

Parameters:

  • v (Optional[Tensor]) – vertices, float [N, 3]. Defaults to None.

  • f (Optional[Tensor]) – faces, int [M, 3]. Defaults to None.

  • vn (Optional[Tensor]) – vertex normals, float [N, 3]. Defaults to None.

  • fn (Optional[Tensor]) – faces for normals, int [M, 3]. Defaults to None.

  • vt (Optional[Tensor]) – vertex uv coordinates, float [N, 2]. Defaults to None.

  • ft (Optional[Tensor]) – faces for uvs, int [M, 3]. Defaults to None.

  • vc (Optional[Tensor]) – vertex colors, float [N, 3]. Defaults to None.

  • albedo (Optional[Tensor]) – albedo texture, float [H, W, 3], RGB format. Defaults to None.

  • metallicRoughness (Optional[Tensor]) – metallic-roughness texture, float [H, W, 3], metallic(Blue) = metallicRoughness[…, 2], roughness(Green) = metallicRoughness[…, 1]. Defaults to None.

  • device (Optional[torch.device]) – torch device. Defaults to None.

classmethod load(path, resize=True, clean=False, renormal=True, retex=False, vmap=True, bound=0.9, front_dir='+z', **kwargs)[source]

load mesh from path.

Parameters:

  • path (str) – path to mesh file, supports ply, obj, glb.

  • clean (bool, optional) – perform mesh cleaning at load (e.g., merge close vertices). Defaults to False.

  • resize (bool, optional) – auto resize the mesh using bound into [-bound, bound]^3. Defaults to True.

  • renormal (bool, optional) – re-calc the vertex normals. Defaults to True.

  • retex (bool, optional) – re-calc the uv coordinates, will overwrite the existing uv coordinates. Defaults to False.

  • vmap (bool, optional) – remap vertices based on uv coordinates, so each v correspond to a unique vt. Defaults to True.

  • wotex (bool, optional) – do not try to load any texture. Defaults to False.

  • bound (float, optional) – bound to resize. Defaults to 0.9.

  • front_dir (str, optional) – front-view direction of the mesh, should be [+-][xyz][ 123]. Defaults to ‘+z’.

  • device (torch.device, optional) – torch device. Defaults to None.

Note

a device keyword argument can be provided to specify the torch device. If it’s not provided, we will try to use 'cuda' as the device if it’s available.

Returns:

the loaded Mesh object.

Return type:

Mesh

classmethod load_fbx(path, device=None)[source]

load an fbx mesh.

Parameters:

  • path (str) – path to mesh.

  • device (torch.device, optional) – torch device. Defaults to None.

Note

We only support loading geometry without texture. Please see [fbxloader](https://github.com/ashawkey/fbxloader) for more details and limitations.

Returns:

the loaded Mesh object.

Return type:

Mesh

classmethod load_obj(path, wotex=False, albedo_path=None, device=None)[source]

load an obj mesh.

Parameters:

  • path (str) – path to mesh.

  • wotex (bool, optional) – do not try to load any texture. Defaults to False.

  • albedo_path (str, optional) – path to the albedo texture image, will overwrite the existing texture path if specified in mtl. Defaults to None.

  • device (torch.device, optional) – torch device. Defaults to None.

Note

We will try to read mtl path from obj, else we assume the file name is the same as obj but with mtl extension. The usemtl statement is ignored, and we only use the last material path in mtl file.

Returns:

the loaded Mesh object.

Return type:

Mesh

classmethod load_trimesh(path, wotex=False, device=None, process=False)[source]

load a mesh using trimesh.load().

Can load various formats like glb and serves as a fallback.

Note

We will try to merge all meshes if the glb contains more than one, but this may cause the texture to lose, since we only support one texture image!

Parameters:

  • path (str) – path to the mesh file.

  • wotex (bool, optional) – do not try to load any texture. Defaults to False.

  • device (torch.device, optional) – torch device. Defaults to None.

Returns:

the loaded Mesh object.

Return type:

Mesh

sample_surface(count: int)[source]

sample points on the surface of the mesh.

Parameters:

count (int) – number of points to sample.

Returns:

the sampled points, float [count, 3].

Return type:

torch.Tensor

aabb()[source]

get the axis-aligned bounding box of the mesh.

Returns:

the min xyz and max xyz of the mesh.

Return type:

Tuple[torch.Tensor]

auto_size(bound=0.9)[source]

auto resize the mesh.

Parameters:

bound (float, optional) – resizing into [-bound, bound]^3. Defaults to 0.9.

auto_normal()[source]

auto calculate the vertex normals.

auto_uv(cache_path=None, vmap=True)[source]

auto calculate the uv coordinates.

Parameters:

  • cache_path (str, optional) – path to save/load the uv cache as a npz file, this can avoid calculating uv every time when loading the same mesh, which is time-consuming. Defaults to None.

  • vmap (bool, optional) – remap vertices based on uv coordinates, so each v correspond to a unique vt (necessary for formats like gltf). Usually this will duplicate the vertices on the edge of uv atlas. Defaults to True.

remap_uv(v)[source]

remap uv texture (vt) to other surface.

Parameters:

v (torch.Tensor) – the target mesh vertices, float [N, 3].

align_v_to_vt(vmapping=None)[source]

remap v/f and vn/fn to vt/ft.

Parameters:

vmapping (np.ndarray, optional) – the mapping relationship from f to ft. Defaults to None.

to(device)[source]

move all tensor attributes to device.

Parameters:

device (torch.device) – target device.

Returns:

self.

Return type:

Mesh

write(path)[source]

write the mesh to a path.

Parameters:

path (str) – path to write, supports ply, obj and glb.

write_ply(path)[source]

write the mesh in ply format. Only for geometry!

Parameters:

path (str) – path to write.

write_glb(path)[source]
write the mesh in glb/gltf format.

This will create a scene with a single mesh.

Parameters:

path (str) – path to write.

write_obj(path)[source]

write the mesh in obj format. Will also write the texture and mtl files.

Parameters:

path (str) – path to write.

clone()[source]

clone the mesh.

Returns:

the cloned Mesh object.

Return type:

Mesh

kiui.mesh_utils.decimate_mesh(verts, faces, target=50000.0, backend='pymeshlab', remesh=False, optimalplacement=True, verbose=True)[source]

perform mesh decimation.

Parameters:

  • verts (np.ndarray) – mesh vertices, float [N, 3]

  • faces (np.ndarray) – mesh faces, int [M, 3]

  • target (int) – targeted number of faces

  • backend (str, optional) – algorithm backend, can be “pymeshlab” or “pyfqmr”. Defaults to “pymeshlab”.

  • remesh (bool, optional) – whether to remesh after decimation. Defaults to False.

  • optimalplacement (bool, optional) – For flat mesh, use False to prevent spikes. Defaults to True.

  • verbose (bool, optional) – whether to print the decimation process. Defaults to True.

Returns:

vertices and faces after decimation.

Return type:

Tuple[np.ndarray]

kiui.mesh_utils.clean_mesh(verts, faces, v_pct=1, min_f=0, min_d=0, repair=False, remesh=False, remesh_size=0.01, remesh_iters=3, verbose=True)[source]

perform mesh cleaning, including floater removal, non manifold repair, and remeshing.

Parameters:

  • verts (np.ndarray) – mesh vertices, float [N, 3]

  • faces (np.ndarray) – mesh faces, int [M, 3]

  • v_pct (int, optional) – percentage threshold to merge close vertices. Defaults to 1.

  • min_f (int, optional) – maximal number of faces for isolated component to remove. Defaults to 0.

  • min_d (int, optional) – maximal diameter percentage of isolated component to remove. Defaults to 0.

  • repair (bool, optional) – whether to repair non-manifold faces (cannot gurantee). Defaults to True.

  • remesh (bool, optional) – whether to perform a remeshing after all cleaning. Defaults to True.

  • remesh_size (float, optional) – the targeted edge length for remeshing. Defaults to 0.01.

  • remesh_iters (int, optional) – the iterations of remeshing. Defaults to 3.

  • verbose (bool, optional) – whether to print the cleaning process. Defaults to True.

Returns:

vertices and faces after decimation.

Return type:

Tuple[np.ndarray]

kiui.mesh_utils.normalize_mesh(vertices, bound=0.95)[source]

normalize the mesh vertices to a unit cube.

Parameters:

  • vertices (np.ndarray) – mesh vertices, float [N, 3]

  • bound (float, optional) – the bounding box size. Defaults to 0.95.

Returns:

normalized vertices.

Return type:

np.ndarray

kiui.mesh_utils.laplacian_uniform(verts, faces)[source]

calculate laplacian uniform matrix

Parameters:

  • verts (torch.Tensor) – mesh vertices, float [N, 3]

  • faces (torch.Tensor) – mesh faces, long [M, 3]

Returns:

sparse laplacian matrix.

Return type:

torch.Tensor

kiui.mesh_utils.laplacian_smooth_loss(verts, faces)[source]

calculate laplacian smooth loss.

Parameters:

  • verts (torch.Tensor) – mesh vertices, float [N, 3]

  • faces (torch.Tensor) – mesh faces, int [M, 3]

Returns:

loss value.

Return type:

torch.Tensor

kiui.mesh_utils.compute_edge_to_face_mapping(faces)[source]

compute edge to face mapping.

Parameters:

faces (torch.Tensor) – mesh faces, int [M, 3]

Returns:

indices to faces for each edge, long, [N, 2]

Return type:

torch.Tensor

kiui.mesh_utils.normal_consistency(verts, faces, face_normals=None)[source]

calculate normal consistency loss.

Parameters:

  • verts (torch.Tensor) – mesh vertices, float [N, 3]

  • faces (torch.Tensor) – mesh faces, int [M, 3]

  • face_normals (Optional[torch.Tensor]) – the normal vector for each face, will be calculated if not provided, float [M, 3]

Returns:

loss value.

Return type:

torch.Tensor