or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdanalysis.mdcore-operations.mdfile-io.mdindex.mdmesh-processing.mdpoint-clouds.mdspatial-queries.mdvisualization.md
tile.json

tessl/pypi-trimesh

Import, export, process, analyze and view triangular meshes.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/trimesh@4.8.x

To install, run

npx @tessl/cli install tessl/pypi-trimesh@4.8.0

index.mddocs/

Trimesh

A pure Python library for loading and using triangular meshes with emphasis on watertight surfaces. Trimesh provides comprehensive mesh processing capabilities including loading/saving various formats, geometric analysis, mesh repair, boolean operations, collision detection, and visualization.

Package Information

  • Package Name: trimesh
  • Language: Python
  • Installation: pip install trimesh

Core Imports

import trimesh

For specific functionality:

from trimesh import Trimesh, Scene, PointCloud
from trimesh.exchange import load, export
from trimesh import primitives, path, voxel

Basic Usage

import trimesh
import numpy as np

# Load a mesh from file
mesh = trimesh.load('model.stl')

# Basic properties
print(f"Volume: {mesh.volume}")
print(f"Surface area: {mesh.area}")
print(f"Is watertight: {mesh.is_watertight}")
print(f"Bounds: {mesh.bounds}")

# Create a primitive mesh
sphere = trimesh.primitives.Sphere(radius=1.0)
box = trimesh.primitives.Box(extents=[2, 2, 2])

# Transform the mesh
translation = trimesh.transformations.translation_matrix([1, 0, 0])
mesh.apply_transform(translation)

# Boolean operations
result = mesh.union(sphere)

# Visualization
mesh.show()  # Interactive 3D viewer

# Export to different format
mesh.export('output.ply')

Architecture

Trimesh follows a clean object-oriented design with several key components:

  • Geometry3D: Base class for all 3D geometric objects providing common properties and methods
  • Trimesh: Main triangular mesh class with comprehensive mesh processing capabilities
  • Scene: Container for multiple geometries with hierarchical transformations and scene graph management
  • PointCloud: Specialized class for point cloud data and operations
  • Path2D/Path3D: Vector path handling for curves and 2D/3D sketches

The library emphasizes:

  • Watertight meshes: Focus on manifold, closed surfaces for robust operations
  • NumPy integration: Efficient array-based operations throughout
  • Modular design: Clear separation between core geometry, I/O, processing, and visualization
  • Minimal dependencies: Only numpy required, with optional dependencies for enhanced functionality

Capabilities

Core Mesh Operations

Essential mesh creation, loading, and basic geometric operations. These form the foundation for all mesh processing workflows in trimesh.

def load(file_obj, file_type=None, resolver=None, **kwargs):
    """Load mesh from file"""

class Trimesh(Geometry3D):
    """Main triangular mesh class"""
    @property
    def vertices(self) -> np.ndarray: ...
    @property 
    def faces(self) -> np.ndarray: ...
    @property
    def volume(self) -> float: ...
    @property
    def area(self) -> float: ...
    def apply_transform(self, matrix: np.ndarray) -> 'Trimesh': ...

Core Mesh Operations

File I/O and Data Exchange

Comprehensive support for loading and saving meshes in various formats including STL, PLY, OBJ, GLTF/GLB, 3MF, and many others.

def load(file_obj, file_type=None, **kwargs):
    """Universal mesh loader with format auto-detection"""

def load_mesh(file_obj, **kwargs) -> Trimesh:
    """Load specifically as Trimesh object"""

def available_formats() -> dict:
    """List all supported file formats"""

File I/O and Data Exchange

Mesh Processing and Modification

Advanced mesh processing including repair operations, boolean operations, remeshing, and mesh quality improvement.

def union(self, other, **kwargs) -> 'Trimesh':
    """Boolean union with another mesh"""

def intersection(self, other, **kwargs) -> 'Trimesh':
    """Boolean intersection with another mesh"""

def fix_normals(self) -> None:
    """Fix mesh face winding and normals"""

def fill_holes(self) -> 'Trimesh':
    """Fill holes in the mesh"""

Mesh Processing and Modification

Analysis and Measurement

Comprehensive geometric analysis including mass properties, curvature analysis, mesh quality metrics, and geometric measurements.

@property
def mass_properties(self) -> dict:
    """Calculate mass, center of mass, and inertia tensor"""

@property
def principal_inertia_components(self) -> np.ndarray:
    """Principal moments of inertia"""

def discrete_gaussian_curvature_measure(self) -> np.ndarray:
    """Gaussian curvature at vertices"""

def discrete_mean_curvature_measure(self) -> np.ndarray:
    """Mean curvature at vertices"""

Analysis and Measurement

Spatial Queries and Collision

Ray casting, nearest point queries, collision detection, and spatial acceleration structures for efficient geometric queries.

def ray_triangle(self, ray_origins, ray_directions, **kwargs):
    """Intersect rays with mesh triangles"""

@property
def nearest(self):
    """Nearest point query object"""

def collision(self, other_mesh) -> dict:
    """Check collision with another mesh"""

def contains(self, points) -> np.ndarray:
    """Test if points are inside the mesh"""

Spatial Queries and Collision

Visualization and Rendering

Interactive 3D visualization, material and texture support, scene management, and integration with various rendering systems.

def show(self, **kwargs) -> None:
    """Display mesh in interactive 3D viewer"""

def scene(self) -> Scene:
    """Create scene containing this mesh"""

@property
def visual(self):
    """Visual properties (materials, colors, textures)"""

class Scene:
    """Scene graph for multiple geometries"""
    def show(self, **kwargs) -> None: ...
    def export(self, file_obj, **kwargs) -> None: ...

Visualization and Rendering

Advanced Features

Specialized functionality including voxelization, vector path handling, primitive shape generation, and advanced algorithms.

def voxelized(self, pitch) -> VoxelGrid:
    """Convert mesh to voxel representation"""

class VoxelGrid:
    """Voxel grid representation"""
    def as_boxes(self) -> Trimesh: ...
    def marching_cubes(self) -> Trimesh: ...

# Primitive shapes
def Sphere(radius=1.0, **kwargs) -> Trimesh: ...
def Box(extents=None, **kwargs) -> Trimesh: ...
def Cylinder(radius=1.0, height=1.0, **kwargs) -> Trimesh: ...

Advanced Features

Point Clouds and Alternative Representations

Point cloud processing, conversion between different geometric representations, and point-based analysis operations.

class PointCloud(Geometry3D):
    """Point cloud representation"""
    @property
    def vertices(self) -> np.ndarray: ...
    def convex_hull(self) -> Trimesh: ...
    def k_means(self, k) -> tuple: ...

def sample_surface(self, count) -> np.ndarray:
    """Sample points on mesh surface"""

def sample_surface_even(self, count) -> np.ndarray:
    """Even distribution surface sampling"""

Point Clouds and Alternative Representations

Types

class Geometry3D:
    """Base class for 3D geometric objects"""
    @property
    def bounds(self) -> np.ndarray: ...
    @property
    def extents(self) -> np.ndarray: ...
    @property
    def centroid(self) -> np.ndarray: ...
    def apply_transform(self, matrix: np.ndarray): ...

class Trimesh(Geometry3D):
    """Triangular mesh representation"""
    vertices: np.ndarray  # (n, 3) vertex positions
    faces: np.ndarray     # (m, 3) face indices

class Scene:
    """Scene graph container"""
    geometry: dict        # Geometry objects in scene
    graph: dict          # Transform hierarchy

class PointCloud(Geometry3D):
    """Point cloud representation"""
    vertices: np.ndarray  # (n, 3) point positions

class VoxelGrid:
    """Voxel grid representation"""
    encoding: np.ndarray  # Voxel data
    transform: np.ndarray # Coordinate transform
    
class Path2D:
    """2D vector path"""
    vertices: np.ndarray  # Path vertices
    entities: list       # Path entities (lines, arcs, etc.)

class Path3D:
    """3D vector path"""
    vertices: np.ndarray  # 3D path vertices
    entities: list       # 3D path entities