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: collections.abc.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)

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”

Returns

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.hash_file(file_obj, hash_function=<built-in function openssl_md5>)

Get the hash of an open file-like object.

Parameters

file_obj (file like object) –
hash_function (function to use to hash data) –

Returns

hashed

Return type

str, hex version of result

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 (JSON-serializable blob) –
**kwargs – 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
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) –

Returns

Return type

named class, or None

trimesh.util.unique_id(length=12, increment=0)

Generate a decent looking alphanumeric unique identifier. First 16 bits are time-incrementing, followed by randomness.

This function is used as a nicer looking alternative to: >>> uuid.uuid4().hex

Follows the advice in: https://eager.io/blog/how-long-does-an-id-need-to-be/

Parameters

length (int) – Length of desired identifier
increment (int) – Number to add to header uint16 useful if calling this function repeatedly in a tight loop executing faster than time can increment the header

Returns

unique – Unique alphanumeric identifier

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.

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,)