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.

concatenate(other, *args)

Concatenate two or more ColorVisuals objects into a single object.

Parameters
  • other (ColorVisuals) – Object to append

  • *args (ColorVisuals objects) –

Returns

result – object and others in the order it was passed.

Return type

ColorVisuals object containing information from current

copy()

Return a copy of the current ColorVisuals object.

Returns

copied – Contains the same information as self

Return type

ColorVisuals

crc()

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

Returns

crc

Return type

int, checksum of data in visual object and its parent mesh

property defined

Are any colors defined for the current mesh.

Returns

defined

Return type

bool, are colors defined or not.

property face_colors

Colors defined for each face of a mesh.

If no colors are defined, defaults are returned.

Returns

colors

Return type

(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

Return type

ColorVisuals object containing a subset of faces.

property kind

What color mode has been set.

Returns

mode

Return type

‘face’, ‘vertex’, or None

property main_color

What is the most commonly occurring color.

Returns

color

Return type

(4,) uint8, most common color

property transparency

Does the current object contain any transparency.

Returns

transparency

Return type

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.

property vertex_colors

Return the colors for each vertex of a mesh

Returns

colors

Return type

(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

  • 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.Trimesh object) –

  • face_colors ((n, (3,4)) int, face colors) –

  • dtype (data type of output) –

Returns

vertex_colors

Return type

(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

Return type

(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 – Interpolated RGBA colors

Return type

(n, 4) dtype

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 – RGBA colors for interpolated values

Return type

(n, 4) uint8

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

Return type

(4,) dtype, random color that looks OK

trimesh.visual.color.to_float(colors)

Convert integer colors to 0.0 - 1.0 floating point colors

Parameters

colors ((n, d) int) – Integer colors

Returns

as_float – Float colors 0.0 - 1.0

Return type

(n, d) float

trimesh.visual.color.to_rgba(colors, dtype=<class 'numpy.uint8'>)

Convert a single or multiple RGB colors to RGBA colors.

Parameters

colors ((n, 3) or (n, 4) array) – RGB or RGBA colors

Returns

colors – (4,) single RGBA color

Return type

(n, 4) list of RGBA colors

trimesh.visual.color.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 – RGBA color at each of the UV coordinates

Return type

(n, 4) float

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

Return type

(m,4) colors

trimesh.visual.material module

material.py

Store visual materials as objects.

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

Bases: object

property main_color
class trimesh.visual.material.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.material.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

property main_color
to_color(uv)

Get the rough color at a list of specified UV coordinates.

Parameters

uv ((n, 2) float) – UV coordinates on the material

Returns

Return type

colors

class trimesh.visual.material.SimpleMaterial(image=None, diffuse=None, ambient=None, specular=None, glossiness=None, **kwargs)

Bases: trimesh.visual.material.Material

Hold a single image texture.

property glossiness
property main_color

Return the most prominent color.

to_color(uv)
to_pbr()

Convert the current simple material to a PBR material.

Returns

pbr – Contains material information in PBR format.

Return type

PBRMaterial

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

Return type

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

Return type

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.

get(name)

Get an asset.

Parameters

name (str) – Name of the asset

Returns

data – Loaded data from asset

Return type

bytes

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.

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.

get(name)

Get an asset from the ZIP archive.

Parameters

name (str) – Name of the asset

Returns

data – Loaded data from asset

Return type

bytes

trimesh.visual.texture module

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

Bases: object

copy()

Return a copy of the current TextureVisuals object.

Returns

copied – Contains the same information in a new object

Return type

TextureVisuals

crc()

Get a CRC of the stored data.

Returns

crc – Hash of items in self._data

Return type

int

property defined

Check if any data is stored

Returns

defined – Are UV coordinates and images set?

Return type

bool

face_subset(face_index)

Get a copy of

property kind

Return the type of visual data stored

Returns

kind – What type of visuals are defined

Return type

str

to_color()

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

Returns

vis – Contains vertex color from texture

Return type

trimesh.visuals.ColorVisuals

update_faces(mask)

Apply a mask to remove or duplicate face properties

update_vertices(mask)

Apply a mask to remove or duplicate vertex properties.

property uv

Get the stored UV coordinates.

Returns

uv – Pixel position per- vertex

Return type

(n, 2) float

trimesh.visual.texture.power_resize(image, resample=1, square=False)

Resize a PIL image so every dimension is a power of two.

Parameters
  • image (PIL.Image) – Input image

  • resample (int) – Passed to Image.resize

  • square (bool) – If True, upsize to a square image

Returns

resized – Input image resized

Return type

PIL.Image

trimesh.visual.texture.unmerge_faces(faces, *args)

Textured meshes can come with faces referencing vertex indices (v) and an array the same shape which references vertex texture indices (vt) and sometimes even normal (vn).

Vertex locations with different values of any of these can’t be considered the “same” vertex, and for our simple data model we need to not combine these vertices.

Parameters
  • faces ((n, d) int) – References vertex indices

  • *args ((n, d) int) – Various references of corresponding values This is usually UV coordinates or normal indexes

Returns

  • new_faces ((m, d) int) – New faces for masked vertices

  • mask_v ((p,) int) – A mask to apply to vertices

  • mask_* ((p,) int) – A mask to apply to vt array to get matching UV coordinates Returns as many of these as args were passed

Module contents

visual

Handle visual properties for meshes, including color and texture

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

Bases: object

copy()

Return a copy of the current TextureVisuals object.

Returns

copied – Contains the same information in a new object

Return type

TextureVisuals

crc()

Get a CRC of the stored data.

Returns

crc – Hash of items in self._data

Return type

int

property defined

Check if any data is stored

Returns

defined – Are UV coordinates and images set?

Return type

bool

face_subset(face_index)

Get a copy of

property kind

Return the type of visual data stored

Returns

kind – What type of visuals are defined

Return type

str

to_color()

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

Returns

vis – Contains vertex color from texture

Return type

trimesh.visuals.ColorVisuals

update_faces(mask)

Apply a mask to remove or duplicate face properties

update_vertices(mask)

Apply a mask to remove or duplicate vertex properties.

property uv

Get the stored UV coordinates.

Returns

uv – Pixel position per- vertex

Return type

(n, 2) float

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

Bases: object

Store color information about a mesh.

concatenate(other, *args)

Concatenate two or more ColorVisuals objects into a single object.

Parameters
  • other (ColorVisuals) – Object to append

  • *args (ColorVisuals objects) –

Returns

result – object and others in the order it was passed.

Return type

ColorVisuals object containing information from current

copy()

Return a copy of the current ColorVisuals object.

Returns

copied – Contains the same information as self

Return type

ColorVisuals

crc()

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

Returns

crc

Return type

int, checksum of data in visual object and its parent mesh

property defined

Are any colors defined for the current mesh.

Returns

defined

Return type

bool, are colors defined or not.

property face_colors

Colors defined for each face of a mesh.

If no colors are defined, defaults are returned.

Returns

colors

Return type

(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

Return type

ColorVisuals object containing a subset of faces.

property kind

What color mode has been set.

Returns

mode

Return type

‘face’, ‘vertex’, or None

property main_color

What is the most commonly occurring color.

Returns

color

Return type

(4,) uint8, most common color

property transparency

Does the current object contain any transparency.

Returns

transparency

Return type

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.

property vertex_colors

Return the colors for each vertex of a mesh

Returns

colors

Return type

(len(mesh.vertices), 4) uint8, color for each vertex

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

Return a random RGB color using datatype specified.

Parameters

dtype (numpy dtype of result) –

Returns

color

Return type

(4,) dtype, random color that looks OK

trimesh.visual.to_rgba(colors, dtype=<class 'numpy.uint8'>)

Convert a single or multiple RGB colors to RGBA colors.

Parameters

colors ((n, 3) or (n, 4) array) – RGB or RGBA colors

Returns

colors – (4,) single RGBA color

Return type

(n, 4) list of RGBA colors

trimesh.visual.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

Return type

ColorVisuals object.

trimesh.visual.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 – Interpolated RGBA colors

Return type

(n, 4) dtype

trimesh.visual.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 – RGBA colors for interpolated values

Return type

(n, 4) uint8

trimesh.visual.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 – RGBA color at each of the UV coordinates

Return type

(n, 4) float