trimesh.visual package

Submodules

trimesh.visual.color module

color.py

Hold and deal with visual information about meshes.

There are lots of ways to encode visual information, and the goal of this architecture is to make it possible to define one, and then transparently get the others. The two general categories are:

  1. colors, defined for a face, vertex, or material

  2. textures, defined as an image and UV coordinates for each vertex

This module only implements diffuse colors at the moment.

Rules

  1. If nothing is defined sane defaults should be returned

  2. If a user alters or sets a value, that is considered user data and should be saved and treated as such.

  3. Only one mode of visual is allowed at a time, and setting or altering a value should transparently change the mode. Color modes are:

    • vertex colors

    • face colors

class trimesh.visual.color.ColorVisuals(mesh=None, face_colors=None, vertex_colors=None)

Bases: object

Store color information about a mesh.

Attributes
defined

Are any colors defined for the current mesh.

face_colors

Colors defined for each face of a mesh.

kind

What color mode has been set.

main_color

What is the most commonly occurring color.

transparency

Does the current object contain any transparency.

vertex_colors

Return the colors for each vertex of a mesh

Methods

concatenate(other, *args)

Concatenate two or more ColorVisuals objects into a single object.

copy()

Return a copy of the current ColorVisuals object.

crc()

A checksum for the current visual object and its parent mesh.

face_subset(face_index)

Given a mask of face indices, return a sliced version.

update_faces(mask)

Apply a mask to remove or duplicate face properties

update_vertices(mask)

Apply a mask to remove or duplicate vertex properties.

concatenate(other, *args)

Concatenate two or more ColorVisuals objects into a single object.

Parameters
otherColorVisuals

Object to append

*args: ColorVisuals objects
Returns
result: ColorVisuals object containing information from current

object and others in the order it was passed.

copy()

Return a copy of the current ColorVisuals object.

Returns
copiedColorVisuals

Contains the same information as self

crc()

A checksum for the current visual object and its parent mesh.

Returns
crc: int, checksum of data in visual object and its parent mesh
defined

Are any colors defined for the current mesh.

Returns
defined: bool, are colors defined or not.
face_colors

Colors defined for each face of a mesh.

If no colors are defined, defaults are returned.

Returns
colors: (len(mesh.faces), 4) uint8, RGBA color for each face
face_subset(face_index)

Given a mask of face indices, return a sliced version.

Parameters
face_index: (n,) int, mask for faces

(n,) bool, mask for faces

Returns
visual: ColorVisuals object containing a subset of faces.
kind

What color mode has been set.

Returns
mode: ‘face’, ‘vertex’, or None
main_color

What is the most commonly occurring color.

Returns
color: (4,) uint8, most common color
transparency

Does the current object contain any transparency.

Returns
transparency: bool, does the current visual contain transparency
update_faces(mask)

Apply a mask to remove or duplicate face properties

update_vertices(mask)

Apply a mask to remove or duplicate vertex properties.

vertex_colors

Return the colors for each vertex of a mesh

Returns
colors: (len(mesh.vertices), 4) uint8, color for each vertex
trimesh.visual.color.colors_to_materials(colors, count=None)

Convert a list of colors into a list of unique materials and material indexes.

Parameters
colors(n, 3) or (n, 4) float

RGB or RGBA colors

countint

Number of entities to apply color to

Returns
diffuse(m, 4) int

Colors

index(count,) int

Index of each color

trimesh.visual.color.face_to_vertex_color(mesh, face_colors, dtype=<class 'numpy.uint8'>)

Convert a list of face colors into a list of vertex colors.

Parameters
meshtrimesh.Trimesh object
face_colors: (n, (3,4)) int, face colors
dtype: data type of output
Returns
vertex_colors: (m,4) dtype, colors for each vertex
trimesh.visual.color.hex_to_rgba(color)

Turn a string hex color to a (4,) RGBA color.

Parameters
color: str, hex color
Returns
rgba: (4,) np.uint8, RGBA color
trimesh.visual.color.interpolate(values, color_map=None, dtype=<class 'numpy.uint8'>)

Given a 1D list of values, return interpolated colors for the range.

Parameters
values(n, ) float

Values to be interpolated over

color_mapNone, or str

Key to a colormap contained in: matplotlib.pyplot.colormaps() e.g: ‘viridis’

Returns
interpolated(n, 4) dtype

Interpolated RGBA colors

trimesh.visual.color.linear_color_map(values, color_range=None)

Linearly interpolate between two colors.

If colors are not specified the function will interpolate between 0.0 values as red and 1.0 as green.

Parameters
values(n, ) float

Values to interpolate

color_rangeNone, or (2, 4) uint8

What colors should extrema be set to

Returns
colors(n, 4) uint8

RGBA colors for interpolated values

trimesh.visual.color.random_color(dtype=<class 'numpy.uint8'>)

Return a random RGB color using datatype specified.

Parameters
dtype: numpy dtype of result
Returns
color: (4,) dtype, random color that looks OK
trimesh.visual.color.to_rgba(colors, dtype=<class 'numpy.uint8'>)

Convert a single or multiple RGB colors to RGBA colors.

Parameters
colors: (n,[3|4]) list of RGB or RGBA colors
Returns
colors: (n,4) list of RGBA colors

(4,) single RGBA color

trimesh.visual.color.vertex_to_face_color(vertex_colors, faces)

Convert a list of vertex colors to face colors.

Parameters
vertex_colors: (n,(3,4)), colors
faces: (m,3) int, face indexes
Returns
face_colors: (m,4) colors

trimesh.visual.objects module

objects.py

Deal with objects which hold visual properties, like ColorVisuals and TextureVisuals.

trimesh.visual.objects.concatenate(visuals, *args)

Concatenate multiple visual objects.

Parameters
visuals: ColorVisuals object, or list of same
*args: ColorVisuals object, or list of same
Returns
concat: ColorVisuals object
trimesh.visual.objects.create_visual(**kwargs)

Create Visuals object from keyword arguments.

Parameters
face_colors(n,3|4) uint8, colors
vertex_colors(n,3|4) uint8, colors
mesh: Trimesh object
Returns
visuals: ColorVisuals object.

trimesh.visual.resolvers module

resolvers.py

Tools to load assets referenced in meshes, like MTL files or texture images.

class trimesh.visual.resolvers.FilePathResolver(source)

Bases: trimesh.visual.resolvers.Resolver

Resolve files from a source path on the file system.

Methods

get(name)

Get an asset.

get(name)

Get an asset.

Parameters
namestr

Name of the asset

Returns
databytes

Loaded data from asset

class trimesh.visual.resolvers.Resolver(*args, **kwargs)

Bases: object

class trimesh.visual.resolvers.WebResolver(url)

Bases: trimesh.visual.resolvers.Resolver

Resolve assets from a remote URL.

Methods

get(name)

Get a resource from the remote site.

get(name)

Get a resource from the remote site.

Parameters
namestr

Asset name, i.e. ‘quadknot.obj.mtl’

class trimesh.visual.resolvers.ZipResolver(archive)

Bases: trimesh.visual.resolvers.Resolver

Resolve files inside a ZIP archive.

Methods

get(name)

Get an asset from the ZIP archive.

get(name)

Get an asset from the ZIP archive.

Parameters
namestr

Name of the asset

Returns
databytes

Loaded data from asset

trimesh.visual.texture module

class trimesh.visual.texture.Material(*args, **kwargs)

Bases: object

class trimesh.visual.texture.PBRMaterial(name=None, emissiveFactor=None, emissiveTexture=None, normalTexture=None, occlusionTexture=None, baseColorTexture=None, baseColorFactor=None, metallicFactor=None, roughnessFactor=None, metallicRoughnessTexture=None, doubleSided=False, alphaMode='OPAQUE', alphaCutoff=0.5)

Bases: trimesh.visual.texture.Material

Create a material for physically based rendering as specified by GLTF 2.0: https://git.io/fhkPZ

Parameters with Texture in them must be PIL.Image objects

Methods

to_color

to_color(uv)
class trimesh.visual.texture.SimpleMaterial(image=None, diffuse=None, ambient=None, specular=None, **kwargs)

Bases: trimesh.visual.texture.Material

Hold a single image texture.

Methods

to_color

to_color(uv)
class trimesh.visual.texture.TextureVisuals(uv=None, material=None, image=None)

Bases: object

Attributes
defined

Check if any data is stored

kind

Return the type of visual data stored

uv

Get the stored UV coordinates.

Methods

copy()

Return a copy of the current TextureVisuals object.

crc()

Get a CRC of the stored data.

face_subset(face_index)

Get a copy of

to_color()

Convert textured visuals to a ColorVisuals with vertex color calculated from texture.

update_faces(mask)

Apply a mask to remove or duplicate face properties

update_vertices(mask)

Apply a mask to remove or duplicate vertex properties.

copy()

Return a copy of the current TextureVisuals object.

Returns
copiedTextureVisuals

Contains the same information in a new object

crc()

Get a CRC of the stored data.

Returns
crcint

Hash of items in self._data

defined

Check if any data is stored

Returns
definedbool

Are UV coordinates and images set?

face_subset(face_index)

Get a copy of

kind

Return the type of visual data stored

Returns
kindstr

What type of visuals are defined

to_color()

Convert textured visuals to a ColorVisuals with vertex color calculated from texture.

Returns
vistrimesh.visuals.ColorVisuals

Contains vertex color from texture

update_faces(mask)

Apply a mask to remove or duplicate face properties

update_vertices(mask)

Apply a mask to remove or duplicate vertex properties.

uv

Get the stored UV coordinates.

Returns
uv(n, 2) float

Pixel position per- vertex

trimesh.visual.texture.uv_to_color(uv, image)

Get the color in a texture image.

Parameters
uv(n, 2) float

UV coordinates on texture image

imagePIL.Image

Texture image

Returns
colors(n, 4) float

RGBA color at each of the UV coordinates

Module contents

visual

Handle visual properties for meshes, including color and texture