trimesh 4.4.0 documentation (2024)

Keeping trimesh easy to install is a core goal, thus the only harddependency is numpy. Installing otherpackages adds functionality but is not required. For the easiest installwith just numpy, pip can generally install trimesh cleanly onWindows, Linux, and OSX:

pip install trimesh

The minimal install can load many supported formats (STL, PLY, GLTF/GLB)into numpy arrays. More functionality is available when softdependencies are installed. This includes things like convex hulls(scipy), graph operations (networkx), faster ray queries(embreex), vector path handling (shapely and rtree), XMLformats like 3DXML/XAML/3MF (lxml), preview windows (pyglet),faster cache checks (xxhash), etc. To install trimesh with thesoft dependencies that generally install cleanly on Linux, OSX, andWindows using pip:

pip install trimesh[easy]

Further information is available in the advanced installationdocumentation.

Here is an example of loading a mesh from file and colorizing its faces.Here is a nicely formatted ipython notebookversion of this example. Alsocheck out the cross sectionexample.

import numpy as npimport trimesh# attach to logger so trimesh messages will be printed to consoletrimesh.util.attach_to_log()# mesh objects can be created from existing faces and vertex datamesh = trimesh.Trimesh(vertices=[[0, 0, 0], [0, 0, 1], [0, 1, 0]], faces=[[0, 1, 2]])# by default, Trimesh will do a light processing, which will# remove any NaN values and merge vertices that share position# if you want to not do this on load, you can pass `process=False`mesh = trimesh.Trimesh(vertices=[[0, 0, 0], [0, 0, 1], [0, 1, 0]], faces=[[0, 1, 2]], process=False)# some formats represent multiple meshes with multiple instances# the loader tries to return the datatype which makes the most sense# which will for scene-like files will return a `trimesh.Scene` object.# if you *always* want a straight `trimesh.Trimesh` you can ask the# loader to "force" the result into a mesh through concatenationmesh = trimesh.load('models/CesiumMilkTruck.glb', force='mesh')# mesh objects can be loaded from a file name or from a buffer# you can pass any of the kwargs for the `Trimesh` constructor# to `trimesh.load`, including `process=False` if you would like# to preserve the original loaded data without merging vertices# STL files will be a soup of disconnected triangles without# merging vertices however and will not register as watertightmesh = trimesh.load('../models/featuretype.STL')# is the current mesh watertight?mesh.is_watertight# what's the euler number for the mesh?mesh.euler_number# the convex hull is another Trimesh object that is available as a property# lets compare the volume of our mesh with the volume of its convex hullprint(mesh.volume / mesh.convex_hull.volume)# since the mesh is watertight, it means there is a# volumetric center of mass which we can set as the origin for our meshmesh.vertices -= mesh.center_mass# what's the moment of inertia for the mesh?mesh.moment_inertia# if there are multiple bodies in the mesh we can split the mesh by# connected components of face adjacency# since this example mesh is a single watertight body we get a list of one meshmesh.split()# facets are groups of coplanar adjacent faces# set each facet to a random color# colors are 8 bit RGBA by default (n, 4) np.uint8for facet in mesh.facets: mesh.visual.face_colors[facet] = trimesh.visual.random_color()# preview mesh in an opengl window if you installed pyglet and scipy with pipmesh.show()# transform method can be passed a (4, 4) matrix and will cleanly apply the transformmesh.apply_transform(trimesh.transformations.random_rotation_matrix())# axis aligned bounding box is availablemesh.bounding_box.extents# a minimum volume oriented bounding box also available# primitives are subclasses of Trimesh objects which automatically generate# faces and vertices from data stored in the 'primitive' attributemesh.bounding_box_oriented.primitive.extentsmesh.bounding_box_oriented.primitive.transform# show the mesh appended with its oriented bounding box# the bounding box is a trimesh.primitives.Box object, which subclasses# Trimesh and lazily evaluates to fill in vertices and faces when requested# (press w in viewer to see triangles)(mesh + mesh.bounding_box_oriented).show()# bounding spheres and bounding cylinders of meshes are also# available, and will be the minimum volume version of each# except in certain degenerate cases, where they will be no worse# than a least squares fit version of the primitive.print(mesh.bounding_box_oriented.volume, mesh.bounding_cylinder.volume, mesh.bounding_sphere.volume)

• Import meshes from binary/ASCII STL, Wavefront OBJ, ASCII OFF,binary/ASCII PLY, GLTF/GLB 2.0, 3MF, XAML, 3DXML, etc.

• Import and export 2D or 3D vector paths from/to DXF or SVG files

• Import geometry files using the GMSH SDK if installed (BREP, STEP,IGES, INP, BDF, etc)

• Export meshes as binary STL, binary PLY, ASCII OFF, OBJ, GLTF/GLB2.0, COLLADA, etc.

• Export meshes using the GMSH SDK if installed (Abaqus INP, NastranBDF, etc)

• Preview meshes using pyglet or in- line in jupyter notebooks usingthree.js

• Automatic hashing of numpy arrays for change tracking using MD5, zlibCRC, or xxhash

  See Also

  TriMesh — HoloViews v1.18.3How to Install Python on Windows 10 | DigitalOceanInstalling Python with Miniforgemeshio

• Internal caching of computed values validated from hashes

• Calculate face adjacencies, face angles, vertex defects, etc.

• Calculate cross sections, i.e. the slicing operation used in 3Dprinting

• Slice meshes with one or multiple arbitrary planes and return theresulting surface

• Split mesh based on face connectivity using networkx, graph-tool, orscipy.sparse

• Calculate mass properties, including volume, center of mass, momentof inertia, principal components of inertia vectors and components

• Repair simple problems with triangle winding, normals, and quad/triholes

• Convex hulls of meshes

• Compute rotation/translation/tessellation invariant identifier andfind duplicate meshes

• Determine if a mesh is watertight, convex, etc.

• Uniformly sample the surface of a mesh

• Ray-mesh queries including location, triangle index, etc.

• Boolean operations on meshes (intersection, union, difference) usingManifold3D or Blender Note that mesh booleans in general are usuallyslow and unreliable

• Voxelize watertight meshes

• Volume mesh generation (TETgen) using Gmsh SDK

• Smooth watertight meshes using laplacian smoothing algorithms(Classic, Taubin, Humphrey)

• Subdivide faces of a mesh

• Approximate minimum volume oriented bounding boxes for meshes

• Approximate minimum volume bounding spheres

• Calculate nearest point on mesh surface and signed distance

• Determine if a point lies inside or outside of a well constructedmesh using signed distance

  See Also

  Defining complex geometries using trimesh Flexcompute

• Primitive objects (Box, Cylinder, Sphere, Extrusion) which aresubclassed Trimesh objects and have all the same features (inertia,viewers, etc)

• Simple scene graph and transform tree which can be rendered (pygletwindow, three.js in a jupyter notebook,pyrender) or exported.

• Many utility functions, like transforming points, unitizing vectors,aligning vectors, tracking numpy arrays for changes, grouping rows,etc.

Trimesh includes an optional pyglet based viewer for debugging andinspecting. In the mesh view window, opened with mesh.show(), thefollowing commands can be used:

• mouse click + drag rotates the view

• ctl + mouse click + drag pans the view

• mouse wheel zooms

• z returns to the base view

• w toggles wireframe mode

• c toggles backface culling

• g toggles an XY grid with Z set to lowest point

• a toggles an XYZ-RGB axis marker between: off, at world frame, orat every frame and world, and at every frame

• f toggles between fullscreen and windowed mode

• m maximizes the window

• q closes the window

If called from inside a jupyter notebook, mesh.show() displaysan in-line preview using three.js to display the mesh or scene. Formore complete rendering (PBR, better lighting, shaders, betteroff-screen support, etc)pyrender is designed tointeroperate with trimesh objects.

You can check out the Githubnetwork forthings using trimesh. A select few:

• Nvidia’s kaolin fordeep learning on 3D geometry.

• Cura, a popular slicer for 3Dprinting.

• Berkeley’sDexNet4and related ambidextrous.ai workwith robotic grasp planning and manipulation.

• Kerfed’s Kerfed’s Engine foranalyzing assembly geometry for manufacturing.

• MyMiniFactory’s P2Slice forpreparing models for 3D printing.

• pyrender A library to renderscenes from Python using nice looking PBR materials.

• urdfpy Load URDF robotdescriptions in Python.

• moderngl-window Ahelper to create GL contexts and load meshes.

• vedo Visualize meshesinteractively (see examplegallery).

• FSLeyes View MRIimages and brain data.

Quick recommendation: GLB or PLY. Every time you replace OBJwith GLB an angel gets its wings.

If you want things like by-index faces, instancing, colors, textures,etc, GLB is a terrific choice. GLTF/GLB is an extremely wellspecifiedmodern format that is easy and fast to parse: it has a JSON headerdescribing data in a binary blob. It has a simple hierarchical scenegraph, a great looking modern physically based material system, supportin dozens-to-hundreds oflibraries, and aJohn Carmackendorsment.Note that GLTF is a large specification, and trimesh only supports asubset of features: loading basic geometry is supported, NOT supportedare fancier things like animations, skeletons, etc.

In the wild, STL is perhaps the most common format. STL filesare extremely simple: it is basically just a list of triangles. They arerobust and are a good choice for basic geometry. Binary PLY filesare a good step up, as they support indexed faces and colors.

Wavefront OBJ is also pretty common: unfortunately OBJ doesn’t havea widely accepted specification so every importer and exporterimplements things slightly differently, making it tough to support. Italso allows unfortunate things like arbitrary sized polygons, has a facerepresentation which is easy to mess up, references other files formaterials and textures, arbitrarily interleaves data, and is slow toparse. Give GLB or PLY a try as an alternative!

A question that comes up pretty frequently is how to cite thelibrary. Aquick BibTex recommendation:

@software{trimesh, author = {{Dawson-Haggerty et al.}}, title = {trimesh}, url = {https://trimesh.org/}, version = {3.2.0}, date = {2019-12-8},}

If you want to deploy something in a container that uses trimeshautomated debian:slim-bullseye based builds with trimesh and mostdependencies are available on DockerHub withimage tags for latest, git short hash for the commit in main(i.e. trimesh/trimesh:0c1298d), and version (i.e.trimesh/trimesh:3.5.27):

docker pull trimesh/trimesh

Here’s anexampleof how to render meshes using LLVMpipe and XVFB inside a container.