A trimesh face coloring study

[villares]

I always struggle with the trimesh documentation... Also it can be confusing that the "facets" describe a group of planar triangular mesh face elements (triangles), but the mesh.facets attribute does not contain single face/triangle regions...

So here a small sketch to demo setting a random color to planar regions, we would in common language call "faces" of a solid.

import py5
from py5_tools import animated_gif

import numpy as np
import trimesh

import io

# Dürer's solid coords, courtesy of João Antonio <introscopia.github.io>
ds = """o Durers_Solid 
v 0.000000 -0.719944 0.347016
v 0.000000 -0.411397 0.644458
v -0.356280 0.205698 0.644458
v -0.623490 0.359972 0.347016
v -0.623490 -0.359972 -0.347016
v 0.000000 0.719944 -0.347016
v 0.000000 0.411397 -0.644458
v -0.356280 -0.205698 -0.644458
v 0.623490 -0.359972 -0.347016
v 0.356280 -0.205698 -0.644458
v 0.623490 0.359972 0.347016
v 0.356280 0.205698 0.644458
s 0
f 3 4 5 1 2
f 8 5 4 6 7
f 7 6 11 9 10
f 2 1 9 11 12
f 10 9 1 5 8
f 12 11 6 4 3
f 8 7 10
f 12 3 2
""" 
mesh = trimesh.load(io.StringIO(ds), file_type='obj')

faces_in_facets = np.zeros(len(mesh.faces), dtype=bool)
if mesh.facets:
    faces_in_facets[np.concatenate(mesh.facets)] = True
single_triangle_faces = np.nonzero(~faces_in_facets)[0]

face_groups = [*mesh.facets, *single_triangle_faces[:, None]]
for face_group in face_groups:
    mesh.visual.face_colors[face_group] = trimesh.visual.random_color()

def setup():
    py5.size(600, 600, py5.P3D)
    py5.no_smooth()
    animated_gif('out.gif', frame_numbers=range(1, 181, 4), duration=0.15)

def draw():
    py5.background('black')
    py5.lights()
    py5.translate(py5.width / 2, py5.height / 2, 0)
    py5.scale(200)
    py5.rotate_y(py5.radians(py5.frame_count * 2))
    py5.rotate_x(py5.radians(py5.frame_count * 4))
    py5.shape(mesh)

def key_pressed():
    if py5.key == 's':
        py5.save_frame('#####.png')

py5.run_sketch(block=False)

[hx2A]

Also it can be confusing that the "facets" describe a group of planar triangular mesh face elements (triangles), but the mesh.facets attribute does not contain single face/triangle regions...

Yes, I hate that also. It's a confusing feature of the library that won't likely be changed because it would likely break people's code that has adapted to this.

I like how you approached this here by setting the face colors with mesh.visual.face_colors. Also I didn't know there was a trimesh.visual.random_color(), that is useful and more elegant than np.random.randint(255, size=4, dtype=np.uint8).

[villares]

I feel sad I couldn't get any conversation about documentation started with the maintainers of trimesh... mikedh/trimesh#1557 (comment)

I have tried a few more things but nothing very structured. I was thinking about some docs PRs maybe in the future, would you like to discuss some drafts I have? Perhaps during Python Brasil 2026? :)

[villares]

Or maybe I should start a repo with examples, tutorials, how-tos and explanations and see if more people join in.

[hx2A]

You are right, there isn't great documentation for trimesh. Part of the issue is that the api is a moving target, so the docstrings (what the documentation website is made from) is really the only source of truth for how it works.

[villares]

Yeah, I understand the API can be a moving target, but I think it is a poor excuse not to have a crowdsourced pool of examples and tutorials, other projects manage to do it. You have tools to tag/link the docs to the library version it refers to, like NumPy and docs.python.org do. Granted those are big projects, but I've seen smaller projects do it too.

[villares]

Compare this: https://trimesh.org/#features

To this: https://hackmd.io/@py5coding/trimesh-features-list