trimesh.visual package

Submodules

trimesh.visual.color module

visual.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:
other : ColorVisuals

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:
copied : ColorVisuals

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,4)) colors
count: int, 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:
mesh: 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_map : None, 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_range : None, 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:
name : str

Name of the asset

Returns:
data : bytes

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:
name : str

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:
name : str

Name of the asset

Returns:
data : bytes

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)

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)

Bases: trimesh.visual.texture.Material

Hold a single image texture.

Methods

to_color  
to_color(uv)
class trimesh.visual.texture.TextureVisuals(uv, 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:
copied : TextureVisuals

Contains the same information in a new object

crc()

Get a CRC of the stored data.

Returns:
crc : int

Hash of items in self._data

defined

Check if any data is stored

Returns:
defined : bool

Are UV coordinates and images set?

face_subset(face_index)

Get a copy of

kind

Return the type of visual data stored

Returns:
kind : str

What type of visuals are defined

to_color()

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

Returns:
vis : trimesh.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

image : PIL.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