trimesh.util

util.py

Standalone functions which require only imports from numpy and the standard library.

Other libraries may be imported must be wrapped in try/except blocks or imported inside of a function

class trimesh.util.FunctionRegistry(**kwargs)

Bases: Mapping

Non-overwritable mapping of string keys to functions.

This allows external packages to register additional implementations of common functionality without risk of breaking implementations provided by trimesh.

See trimesh.voxel.morphology for example usage.

__init__(**kwargs)

class trimesh.util.TemporaryDirectory

Bases: object

Same basic usage as tempfile.TemporaryDirectory but functional in Python 2.7+.

Example

``` with trimesh.util.TemporaryDirectory() as path:

writable = os.path.join(path, ‘hi.txt’)

```

trimesh.util.allclose(a, b, atol=1e-08)

A replacement for np.allclose that does few checks and validation and as a result is faster.

Parameters

• a (np.ndarray) – To be compared

• b (np.ndarray) – To be compared

• atol (float) – Acceptable distance between a and b to be “close”

Return type

bool indicating if all elements are within atol.

trimesh.util.append_faces(vertices_seq, faces_seq)

Given a sequence of zero-indexed faces and vertices combine them into a single array of faces and a single array of vertices.

Parameters

• vertices_seq ((n, ) sequence of (m, d) float) – Multiple arrays of verticesvertex arrays

• faces_seq ((n, ) sequence of (p, j) int) – Zero indexed faces for matching vertices

Returns

• vertices ((i, d) float) – Points in space

• faces ((j, 3) int) – Reference vertex indices

trimesh.util.array_to_encoded(array, dtype=None, encoding='base64')

Export a numpy array to a compact serializable dictionary.

Parameters

• array (array) – Any numpy array

• dtype (str or None) – Optional dtype to encode array

• encoding (str) – ‘base64’ or ‘binary’

Returns

encoded – Has keys: ‘dtype’: str, of dtype ‘shape’: tuple of shape ‘base64’: str, base64 encoded string

Return type

dict

trimesh.util.array_to_string(array, col_delim=' ', row_delim='\n', digits=8, value_format='{}')

Convert a 1 or 2D array into a string with a specified number of digits and delimiter. The reason this exists is that the basic numpy array to string conversions are surprisingly bad.

Parameters

• array ((n,) or (n, d) float or int) – Data to be converted If shape is (n,) only column delimiter will be used

• col_delim (str) – What string should separate values in a column

• row_delim (str) – What string should separate values in a row

• digits (int) – How many digits should floating point numbers include

• value_format (str) – Format string for each value or sequence of values If multiple values per value_format it must divide into array evenly.

Returns

formatted – String representation of original array

Return type

str

trimesh.util.attach_to_log(level=10, handler=None, loggers=None, colors=True, capture_warnings=True, blacklist=None)

Attach a stream handler to all loggers.

Parameters

• level (enum) – Logging level, like logging.INFO

• handler (None or logging.Handler) – Handler to attach

• loggers (None or (n,) logging.Logger) – If None, will try to attach to all available

• colors (bool) – If True try to use colorlog formatter

• blacklist ((n,) str) – Names of loggers NOT to attach to

trimesh.util.bounds_tree(bounds)

Given a set of axis aligned bounds create an r-tree for broad-phase collision detection.

Parameters

bounds ((n, 2D) or (n, 2, D) float) – Non-interleaved bounds where D=dimension E.G a 2D bounds tree: [(minx, miny, maxx, maxy), …]

Returns

tree – Tree containing bounds by index

Return type

Rtree

trimesh.util.comment_strip(text, starts_with='#', new_line='\n')

Strip comments from a text block.

Parameters

• text (str) – Text to remove comments from

• starts_with (str) – Character or substring that starts a comment

• new_line (str) – Character or substring that ends a comment

Returns

stripped – Text with comments stripped

Return type

str

trimesh.util.compress(info, **kwargs)

Compress data stored in a dict.

Parameters

• info (dict) – Data to compress in form: {file name in archive: bytes or file-like object}

• kwargs (dict) – Passed to zipfile.ZipFile

Returns

compressed – Compressed file data

Return type

bytes

trimesh.util.concatenate(a, b=None)

Concatenate two or more meshes.

Parameters

• a (trimesh.Trimesh) – Mesh or list of meshes to be concatenated object, or list of such

• b (trimesh.Trimesh) – Mesh or list of meshes to be concatenated

Returns

result – Concatenated mesh

Return type

trimesh.Trimesh

trimesh.util.convert_like(item, like)

Convert an item to have the dtype of another item

Parameters

• item (any) – Item to be converted

• like (any) – Object with target dtype If None, item is returned unmodified

Returns

result

Return type

item, but in dtype of like

trimesh.util.decimal_to_digits(decimal, min_digits=None)

Return the number of digits to the first nonzero decimal.

Parameters

• decimal (float) –

• min_digits (int, minimum number of digits to return) –

Returns

digits

Return type

int, number of digits to the first nonzero decimal

trimesh.util.decode_keys(store, encoding='utf-8')

If a dictionary has keys that are bytes decode them to a str.

Parameters

store (dict) – Dictionary with data

Returns

result – Values are untouched but keys that were bytes are converted to ASCII strings.

Return type

dict

Example

In [1]: d Out[1]: {1020: ‘nah’, b’hi’: ‘stuff’}

In [2]: trimesh.util.decode_keys(d) Out[2]: {1020: ‘nah’, ‘hi’: ‘stuff’}

trimesh.util.decode_text(text, initial='utf-8')

Try to decode byte input as a string.

Tries initial guess (UTF-8) then if that fails it uses chardet to try another guess before failing.

Parameters

• text (bytes) – Data that might be a string

• initial (str) – Initial guess for text encoding.

Returns

decoded – Data as a string

Return type

str

trimesh.util.decompress(file_obj, file_type)

Given an open file object and a file type, return all components of the archive as open file objects in a dict.

Parameters

• file_obj (file-like) – Containing compressed data

• file_type (str) – File extension, ‘zip’, ‘tar.gz’, etc

Returns

decompressed – Data from archive in format {file name : file-like}

Return type

dict

trimesh.util.diagonal_dot(a, b)

Dot product by row of a and b.

There are a lot of ways to do this though performance varies very widely. This method uses a dot product to sum the row and avoids function calls if at all possible.

Comparing performance of some equivalent versions: ``` In [1]: import numpy as np; import trimesh

In [2]: a = np.random.random((10000, 3))

In [3]: b = np.random.random((10000, 3))

In [4]: %timeit (a * b).sum(axis=1) 1000 loops, best of 3: 181 us per loop

In [5]: %timeit np.einsum(‘ij,ij->i’, a, b) 10000 loops, best of 3: 62.7 us per loop

In [6]: %timeit np.diag(np.dot(a, b.T)) 1 loop, best of 3: 429 ms per loop

In [7]: %timeit np.dot(a * b, np.ones(a.shape[1])) 10000 loops, best of 3: 61.3 us per loop

In [8]: %timeit trimesh.util.diagonal_dot(a, b) 10000 loops, best of 3: 55.2 us per loop ```

Parameters

• a ((m, d) float) – First array

• b ((m, d) float) – Second array

Returns

result – Dot product of each row

Return type

(m,) float

trimesh.util.distance_to_end(file_obj)

For an open file object how far is it to the end

Parameters

file_obj (open file-like object) –

Returns

distance

Return type

int, bytes to end of file

trimesh.util.encoded_to_array(encoded)

Turn a dictionary with base64 encoded strings back into a numpy array.

Parameters

encoded (dict) –

Has keys:

dtype: string of dtype shape: int tuple of shape base64: base64 encoded string of flat array binary: decode result coming from numpy.tobytes

Returns

array

Return type

numpy array

trimesh.util.euclidean(a, b)

Euclidean distance between vectors a and b.

Parameters

• a ((n,) float) – First vector

• b ((n,) float) – Second vector

Returns

distance – Euclidean distance between A and B

Return type

float

trimesh.util.generate_basis(z, epsilon=1e-12)

Generate an arbitrary basis (also known as a coordinate frame) from a given z-axis vector.

Parameters

• z ((3,) float) – A vector along the positive z-axis.

• epsilon (float) – Numbers smaller than this considered zero.

Returns

• x ((3,) float) – Vector along x axis.

• y ((3,) float) – Vector along y axis.

• z ((3,) float) – Vector along z axis.

trimesh.util.grid_arange(bounds, step)

Return a grid from an (2,dimension) bounds with samples step distance apart.

Parameters

• bounds ((2,dimension) list of [[min x, min y, etc], [max x, max y, etc]]) –

• step (float, or (dimension) floats, separation between points) –

Returns

grid

Return type

(n, dimension), points inside the specified bounds

trimesh.util.grid_linspace(bounds, count)

Return a grid spaced inside a bounding box with edges spaced using np.linspace.

Parameters

• bounds ((2,dimension) list of [[min x, min y, etc], [max x, max y, etc]]) –

• count (int, or (dimension,) int, number of samples per side) –

Returns

grid

Return type

(n, dimension) float, points in the specified bounds

trimesh.util.has_module(name)

Check to see if a module is installed by name without actually importing the module.

Parameters

name (str) – The name of the module to check

Returns

installed – True if module is installed

Return type

bool

trimesh.util.is_binary_file(file_obj)

Returns True if file has non-ASCII characters (> 0x7F, or 127) Should work in both Python 2 and 3

trimesh.util.is_ccw(points)

Check if connected 2D points are counterclockwise.

Parameters

points ((n, 2) float) – Connected points on a plane

Returns

ccw – True if points are counter-clockwise

Return type

bool

trimesh.util.is_file(obj)

Check if an object is file-like

Parameters

obj (object) – Any object type to be checked

Returns

is_file – True if object is a file

Return type

bool

trimesh.util.is_instance_named(obj, name)

Given an object, if it is a member of the class ‘name’, or a subclass of ‘name’, return True.

Parameters

• obj (instance) – Some object of some class

• name (str) – The name of the class we want to check for

Returns

is_instance – Whether the object is a member of the named class

Return type

bool

trimesh.util.is_none(obj)

Check to see if an object is None or not.

Handles the case of np.array(None) as well.

Parameters

obj (object) – Any object type to be checked

Returns

is_none – True if obj is None or numpy None-like

Return type

bool

trimesh.util.is_pathlib(obj)

Check if the object is a pathlib.Path or subclass.

Parameters

obj (object) – Object to be checked

Returns

is_pathlib – Is the input object a pathlib path

Return type

bool

trimesh.util.is_sequence(obj)

Check if an object is a sequence or not.

Parameters

obj (object) – Any object type to be checked

Returns

is_sequence – True if object is sequence

Return type

bool

trimesh.util.is_shape(obj, shape, allow_zeros=False)

Compare the shape of a numpy.ndarray to a target shape, with any value less than zero being considered a wildcard

Note that if a list-like object is passed that is not a numpy array, this function will not convert it and will return False.

Parameters

• obj (np.ndarray) – Array to check the shape on

• shape (list or tuple) – Any negative term will be considered a wildcard Any tuple term will be evaluated as an OR

• allow_zeros (bool) – if False, zeros do not match negatives in shape

Returns

shape_ok – True if shape of obj matches query shape

Return type

bool

Examples

In [1]: a = np.random.random((100, 3))

In [2]: a.shape Out[2]: (100, 3)

In [3]: trimesh.util.is_shape(a, (-1, 3)) Out[3]: True

In [4]: trimesh.util.is_shape(a, (-1, 3, 5)) Out[4]: False

In [5]: trimesh.util.is_shape(a, (100, -1)) Out[5]: True

In [6]: trimesh.util.is_shape(a, (-1, (3, 4))) Out[6]: True

In [7]: trimesh.util.is_shape(a, (-1, (4, 5))) Out[7]: False

trimesh.util.is_string(obj)

Check if an object is a string.

Parameters

obj (object) – Any object type to be checked

Returns

is_string – True if obj is a string

Return type

bool

trimesh.util.isclose(a, b, atol)

A replacement for np.isclose that does fewer checks and validation and as a result is roughly 4x faster.

Note that this is used in tight loops, and as such a and b MUST be np.ndarray, not list or “array-like”

Parameters

• a (np.ndarray) – To be compared

• b (np.ndarray) – To be compared

• atol (float) – Acceptable distance between a and b to be “close”

Returns

close – Per-element closeness

Return type

np.ndarray, bool

trimesh.util.jsonify(obj, **kwargs)

A version of json.dumps that can handle numpy arrays by creating a custom encoder for numpy dtypes.

Parameters

• obj (list, dict) – A JSON-serializable blob

• kwargs (dict) – Passed to json.dumps

Returns

dumped – JSON dump of obj

Return type

str

trimesh.util.make_sequence(obj)

Given an object, if it is a sequence return, otherwise add it to a length 1 sequence and return.

Useful for wrapping functions which sometimes return single objects and other times return lists of objects.

Parameters

obj (object) – An object to be made a sequence

Returns

as_sequence – Contains input value

Return type

(n,) sequence

trimesh.util.multi_dict(pairs)

Given a set of key value pairs, create a dictionary. If a key occurs multiple times, stack the values into an array.

Can be called like the regular dict(pairs) constructor

Parameters

pairs ((n, 2) array of key, value pairs) –

Returns

result

Return type

dict, with all values stored (rather than last with regular dict)

trimesh.util.pairwise(iterable)

For an iterable, group values into pairs.

Parameters

iterable ((m, ) list) – A sequence of values

Returns

pairs – Pairs of sequential values

Return type

(n, 2)

Example

In [1]: data Out[1]: [0, 1, 2, 3, 4, 5, 6]

In [2]: list(trimesh.util.pairwise(data)) Out[2]: [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6)]

trimesh.util.row_norm(data)

Compute the norm per-row of a numpy array.

This is identical to np.linalg.norm(data, axis=1) but roughly three times faster due to being less general.

In [3]: %timeit trimesh.util.row_norm(a) 76.3 us +/- 651 ns per loop

In [4]: %timeit np.linalg.norm(a, axis=1) 220 us +/- 5.41 us per loop

Parameters

data ((n, d) float) – Input 2D data to calculate per-row norm of

Returns

norm – Norm of each row of input array

Return type

(n,) float

trimesh.util.sigfig_int(values, sigfig)

Convert a set of floating point values into integers with a specified number of significant figures and an exponent.

Parameters

• values ((n,) float or int) – Array of values

• sigfig ((n,) int) – Number of significant figures to keep

Returns

• as_int ((n,) int) – Every value[i] has sigfig[i] digits

• multiplier ((n, int)) – Exponent, so as_int * 10 ** multiplier is the same order of magnitude as the input

trimesh.util.sigfig_round(values, sigfig=1)

Round a single value to a specified number of significant figures.

Parameters

• values (float) – Value to be rounded

• sigfig (int) – Number of significant figures to reduce to

Returns

rounded – Value rounded to the specified number of significant figures

Return type

float

Examples

In [1]: trimesh.util.round_sigfig(-232453.00014045456, 1) Out[1]: -200000.0

In [2]: trimesh.util.round_sigfig(.00014045456, 1) Out[2]: 0.0001

In [3]: trimesh.util.round_sigfig(.00014045456, 4) Out[3]: 0.0001405

trimesh.util.spherical_to_vector(spherical)

Convert a set of (n, 2) spherical vectors to (n, 3) vectors

Parameters

spherical ((n , 2) float) – Angles, in radians

Returns

vectors – Unit vectors

Return type

(n, 3) float

trimesh.util.split_extension(file_name, special=['tar.bz2', 'tar.gz'])

Find the file extension of a file name, including support for special case multipart file extensions (like .tar.gz)

Parameters

• file_name (str) – File name

• special (list of str) – Multipart extensions eg: [‘tar.bz2’, ‘tar.gz’]

Returns

extension – Last characters after a period, or a value from ‘special’

Return type

str

trimesh.util.stack_3D(points, return_2D=False)

For a list of (n, 2) or (n, 3) points return them as (n, 3) 3D points, 2D points on the XY plane.

Parameters

• points ((n, 2) or (n, 3) float) – Points in either 2D or 3D space

• return_2D (bool) – Were the original points 2D?

Returns

• points ((n, 3) float) – Points in space

• is_2D (bool) – [OPTIONAL] if source points were (n, 2)

trimesh.util.stack_lines(indices)

Stack a list of values that represent a polyline into individual line segments with duplicated consecutive values.

Parameters

indices ((m,) any) – List of items to be stacked

Returns

stacked – Stacked items

Return type

(n, 2) any

Examples

In [1]: trimesh.util.stack_lines([0, 1, 2]) Out[1]: array([[0, 1],

[1, 2]])

In [2]: trimesh.util.stack_lines([0, 1, 2, 4, 5]) Out[2]: array([[0, 1],

[1, 2], [2, 4], [4, 5]])

In [3]: trimesh.util.stack_lines([[0, 0], [1, 1], [2, 2], [3, 3]]) Out[3]: array([[0, 0],

[1, 1], [1, 1], [2, 2], [2, 2], [3, 3]])

trimesh.util.structured_array_to_string(array, col_delim=' ', row_delim='\n', digits=8, value_format='{}')

Convert an unstructured array into a string with a specified number of digits and delimiter. The reason thisexists is that the basic numpy array to string conversionsare surprisingly bad.

Parameters

• array ((n,) or (n, d) float or int) – Data to be converted If shape is (n,) only column delimiter will be used

• col_delim (str) – What string should separate values in a column

• row_delim (str) – What string should separate values in a row

• digits (int) – How many digits should floating point numbers include

• value_format (str) – Format string for each value or sequence of values If multiple values per value_format it must divide into array evenly.

Returns

formatted – String representation of original array

Return type

str

trimesh.util.submesh(mesh, faces_sequence, repair=True, only_watertight=False, min_faces=None, append=False)

Return a subset of a mesh.

Parameters

• mesh (Trimesh) – Source mesh to take geometry from

• faces_sequence (sequence (p,) int) – Indexes of mesh.faces

• repair (bool) – Try to make submeshes watertight

• only_watertight (bool) – Only return submeshes which are watertight

• append (bool) – Return a single mesh which has the faces appended, if this flag is set, only_watertight is ignored

Returns

• if append (Trimesh object)

• else list of Trimesh objects

trimesh.util.to_ascii(text)

Force a string or other to ASCII text ignoring errors.

Parameters

text (any) – Input to be converted to ASCII string

Returns

ascii – Input as an ASCII string

Return type

str

trimesh.util.tolist(data)

Ensure that any arrays or dicts passed containing numpy arrays are properly converted to lists

Parameters

data (any) – Usually a dict with some numpy arrays as values

Returns

result – JSON-serializable version of data

Return type

any

trimesh.util.triangle_strips_to_faces(strips)

Convert a sequence of triangle strips to (n, 3) faces.

Processes all strips at once using np.concatenate and is significantly faster than loop-based methods.

From the OpenGL programming guide describing a single triangle strip [v0, v1, v2, v3, v4]:

Draws a series of triangles (three-sided polygons) using vertices v0, v1, v2, then v2, v1, v3 (note the order), then v2, v3, v4, and so on. The ordering is to ensure that the triangles are all drawn with the same orientation so that the strip can correctly form part of a surface.

Parameters

strips ((n,) list of (m,) int) – Vertex indices

Returns

faces – Vertex indices representing triangles

Return type

(m, 3) int

trimesh.util.type_bases(obj, depth=4)

Return the bases of the object passed.

trimesh.util.type_named(obj, name)

Similar to the type() builtin, but looks in class bases for named instance.

Parameters

• obj (object to look for class of) –

• name (str, name of class) –

Return type

named class, or None

trimesh.util.unique_id(length=12)

Generate a random alphanumeric unique identifier using UUID logic.

Parameters

length (int) – Length of desired identifier

Returns

unique – Unique alphanumeric identifier

Return type

str

trimesh.util.unique_name(start, contains)

Deterministically generate a unique name not contained in a dict, set or other grouping with __includes__ defined. Will create names of the form “start_10” and increment accordingly.

Parameters

• start (str) – Initial guess for name.

• contains (dict, set, or list) – Bundle of existing names we can not use.

Returns

unique – A name that is not contained in contains

Return type

str

trimesh.util.unitize(vectors, check_valid=False, threshold=None)

Unitize a vector or an array or row-vectors.

Parameters

• vectors ((n,m) or (j) float) – Vector or vectors to be unitized

• check_valid (bool) – If set, will return mask of nonzero vectors

• threshold (float) – Cutoff for a value to be considered zero.

Returns

• unit ((n,m) or (j) float) – Input vectors but unitized

• valid ((n,) bool or bool) – Mask of nonzero vectors returned if check_valid

trimesh.util.vector_hemisphere(vectors, return_sign=False)

For a set of 3D vectors alter the sign so they are all in the upper hemisphere.

If the vector lies on the plane all vectors with negative Y will be reversed.

If the vector has a zero Z and Y value vectors with a negative X value will be reversed.

Parameters

• vectors ((n, 3) float) – Input vectors

• return_sign (bool) – Return the sign mask or not

Returns

• oriented ((n, 3) float) – Vectors with same magnitude as source but possibly reversed to ensure all vectors are in the same hemisphere.

• sign ((n,) float) – [OPTIONAL] sign of original vectors

trimesh.util.vector_to_spherical(cartesian)

Convert a set of cartesian points to (n, 2) spherical unit vectors.

Parameters

cartesian ((n, 3) float) – Points in space

Returns

spherical – Angles, in radians

Return type

(n, 2) float

trimesh.util.vstack_empty(tup)

A thin wrapper for numpy.vstack that ignores empty lists.

Parameters

tup (tuple or list of arrays) – With the same number of columns

Returns

stacked – With same number of columns as constituent arrays.

Return type

(n, d) array

trimesh.util.wrap_as_stream(item)

Wrap a string or bytes object as a file object.

Parameters

item (str or bytes) – Item to be wrapped

Returns

wrapped – Contains data from item

Return type

file-like object

trimesh.util.write_encoded(file_obj, stuff, encoding='utf-8')

If a file is open in binary mode and a string is passed, encode and write.

If a file is open in text mode and bytes are passed decode bytes to str and write.

Assumes binary mode if file_obj does not have a ‘mode’ attribute (e.g. io.BufferedRandom).

Parameters

• file_obj (file object) – With ‘write’ and ‘mode’

• stuff (str or bytes) – Stuff to be written

• encoding (str) – Encoding of text

trimesh.util.zero_pad(data, count, right=True)

Parameters

• data ((n,)) – 1D array

• count (int) – Minimum length of result array

Returns

padded – 1D array where m >= count

Return type

(m,)