tessl/pypi-trimesh

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

Overview

Eval results

Files

File I/O and Data Exchange

Name: tessl/pypi-trimesh
Author: tessl

Comprehensive support for loading and saving meshes in various formats including STL, PLY, OBJ, GLTF/GLB, 3MF, COLLADA, and many others. Trimesh provides unified interfaces for format handling with automatic format detection and extensive customization options.

Capabilities

Universal Loading Functions

Core loading functions that automatically detect file formats and handle different data types.

def load(file_obj, file_type=None, resolver=None, **kwargs):
    """
    Universal loader with automatic format detection.
    
    Parameters:
    - file_obj: str file path, file-like object, or URL
    - file_type: str, force specific format ('stl', 'ply', 'obj', etc.)
    - resolver: function to resolve referenced files (materials, textures)
    - **kwargs: format-specific loading options
    
    Returns:
    Trimesh, Scene, Path2D, Path3D, or PointCloud depending on content
    """

def load_mesh(file_obj, **kwargs) -> Trimesh:
    """
    Load file specifically as Trimesh object.
    
    Parameters:
    - file_obj: file path or file-like object
    - **kwargs: loading options
    
    Returns:
    Trimesh object (converts other types if necessary)
    """

def load_scene(file_obj, **kwargs) -> Scene:
    """
    Load file as Scene object.
    
    Parameters:
    - file_obj: file path or file-like object
    - **kwargs: loading options
    
    Returns:
    Scene object containing loaded geometries
    """

def load_path(file_obj, **kwargs):
    """
    Load file as Path2D or Path3D object.
    
    Parameters:
    - file_obj: file path or file-like object
    - **kwargs: loading options
    
    Returns:
    Path2D or Path3D object
    """

def load_remote(url, **kwargs):
    """
    Load mesh from remote URL.
    
    Parameters:
    - url: str, URL to mesh file
    - **kwargs: loading options
    
    Returns:
    Loaded geometry object
    """

Format Support and Discovery

Query supported formats and capabilities.

def available_formats() -> set:
    """
    Get set of supported file formats.
    
    Returns:
    set of format strings
    """

def export_formats() -> set:
    """
    Get set of supported export formats.
    
    Returns:
    set of format strings
    """

def load_formats() -> set:
    """
    Get set of supported load formats.
    
    Returns:
    set of format strings
    """

Export Functions

Save meshes and scenes to various file formats.

def export(self, file_obj=None, file_type=None, **kwargs):
    """
    Export mesh to file or return as bytes.
    
    Parameters:
    - file_obj: str file path or file-like object (None returns bytes)
    - file_type: str, force specific format
    - **kwargs: format-specific export options
    
    Returns:
    bytes if file_obj is None, otherwise None
    """

def export_scene(scene, file_obj=None, file_type=None, **kwargs):
    """
    Export Scene object to file.
    
    Parameters:
    - scene: Scene object to export
    - file_obj: file path or file-like object
    - file_type: str, force specific format
    - **kwargs: export options
    
    Returns:
    bytes if file_obj is None, otherwise None
    """

Mesh Creation from Data

Create meshes from various data sources and formats.

def from_dict(data: dict) -> Trimesh:
    """
    Create mesh from dictionary representation.
    
    Parameters:
    - data: dict with 'vertices' and 'faces' keys
    
    Returns:
    Trimesh object
    """

def from_glb(data: bytes) -> Scene:
    """
    Load mesh from GLB binary data.
    
    Parameters:
    - data: bytes, GLB file content
    
    Returns:
    Scene object
    """

def from_gltf(data: dict) -> Scene:
    """
    Load mesh from GLTF dictionary.
    
    Parameters:
    - data: dict, parsed GLTF content
    
    Returns:
    Scene object
    """

Specific Format Loaders

Direct access to format-specific loading functions.

# STL format
def load_stl(file_obj, **kwargs) -> Trimesh:
    """Load STL format (ASCII or binary)"""

def load_stl_ascii(file_obj) -> Trimesh:
    """Load ASCII STL format"""

def load_stl_binary(file_obj) -> Trimesh:
    """Load binary STL format"""

# PLY format  
def load_ply(file_obj, **kwargs) -> Trimesh:
    """Load PLY format (ASCII or binary)"""

# OBJ format
def load_obj(file_obj, **kwargs):
    """Load Wavefront OBJ format with materials"""

# GLTF/GLB format
def load_gltf(file_obj, resolver=None, **kwargs) -> Scene:
    """Load GLTF/GLB format"""

# OFF format
def load_off(file_obj, **kwargs) -> Trimesh:
    """Load Object File Format (OFF)"""

# 3MF format
def load_3mf(file_obj, **kwargs) -> Scene:
    """Load 3D Manufacturing Format (3MF)"""

Scene and Multi-Mesh Handling

Handle complex scenes with multiple meshes and transformations.

class Scene:
    """Container for multiple geometries with transforms"""
    
    def export(self, file_obj=None, file_type=None, **kwargs):
        """Export entire scene to file"""
    
    def save_image(self, resolution=None, **kwargs) -> bytes:
        """Render scene to image"""
    
    def dump(self) -> list:
        """Export scene as list of transformed meshes"""
    
    @property
    def geometry(self) -> dict:
        """Dictionary of geometry objects in scene"""
    
    @property
    def graph(self) -> dict:
        """Scene graph with transformations"""

Advanced I/O Options

Specialized loading and export options for advanced use cases.

def load_compressed(file_obj, **kwargs):
    """Load from compressed archive formats"""

def load_step(file_obj, **kwargs):
    """Load STEP CAD format (requires opencascade)"""

def load_collada(file_obj, **kwargs) -> Scene:
    """Load COLLADA (.dae) format"""

def load_x3d(file_obj, **kwargs) -> Scene:
    """Load X3D format"""

def export_gltf(mesh, **kwargs) -> dict:
    """Export mesh as GLTF dictionary"""

def export_obj(mesh, include_materials=True, **kwargs) -> str:
    """Export mesh as OBJ format with materials"""

Usage Examples

Basic Loading and Saving

import trimesh

# Load various formats - automatic detection
mesh_stl = trimesh.load('model.stl')
mesh_ply = trimesh.load('scan.ply') 
scene_gltf = trimesh.load('scene.gltf')
path_svg = trimesh.load('drawing.svg')

# Force specific format
mesh = trimesh.load('model.dat', file_type='stl')

# Load from URL
mesh = trimesh.load_remote('https://example.com/model.stl')

# Export to different formats
mesh.export('output.ply')
mesh.export('output.obj')
mesh.export('compressed.stl.gz')

# Export as bytes
stl_data = mesh.export(file_type='stl')

Working with Scenes

# Load complex scene
scene = trimesh.load('assembly.gltf')

print(f"Scene contains {len(scene.geometry)} objects")
print(f"Scene bounds: {scene.bounds}")

# Export entire scene
scene.export('output.gltf')

# Get individual meshes with transforms applied  
meshes = scene.dump()
for i, mesh in enumerate(meshes):
    mesh.export(f'part_{i}.stl')

# Access individual objects
for name, geometry in scene.geometry.items():
    print(f"Object {name}: {type(geometry)}")

Format-Specific Options

# STL with custom precision
mesh.export('high_precision.stl', digits=8)

# PLY with vertex colors
mesh.visual.vertex_colors = colors  # Set colors first
mesh.export('colored.ply')

# OBJ with materials and textures
mesh.export('textured.obj', include_materials=True)

# GLTF with compression
scene.export('compressed.glb', compress=True)

# Check supported formats
formats = trimesh.available_formats()
print("Supported formats:")
for fmt, info in formats.items():
    print(f"  {fmt}: {info}")

Custom Resolution and Loading

# Custom file resolver for relative paths
def my_resolver(name):
    return open(f'/assets/{name}', 'rb')

# Load with custom resolver
scene = trimesh.load('model.gltf', resolver=my_resolver)

# Load with specific options
mesh = trimesh.load('scan.ply', 
                   skip_materials=True,
                   process_args={'validate': True})

# Create mesh from dictionary
data = {
    'vertices': [[0, 0, 0], [1, 0, 0], [0, 1, 0]],
    'faces': [[0, 1, 2]]
}
mesh = trimesh.Trimesh.from_dict(data)

Install with Tessl CLI