trimesh.util module¶
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
Classes
|
Non-overwritable mapping of string keys to functions. |
Same basic usage as tempfile.TemporaryDirectory |
Functions
|
A replacement for np.allclose that does few checks and validation and as a result is faster. |
|
Given a sequence of zero- indexed faces and vertices combine them into a single array of faces and a single array of vertices. |
|
Export a numpy array to a compact serializable dictionary. |
|
Convert a 1 or 2D array into a string with a specified number of digits and delimiter. |
|
Attach a stream handler to all loggers. |
|
Given a set of axis aligned bounds, create an r-tree for broad- phase |
|
Compress data stored in a dict. |
|
Concatenate two or more meshes. |
|
Convert an item to have the dtype of another item |
|
Return the number of digits to the first nonzero decimal. |
|
If a dictionary has keys that are bytes decode them to a str. |
|
Try to decode byte input as a string. |
|
Given an open file object and a file type, return all components of the archive as open file objects in a dict. |
|
Dot product by row of a and b. |
|
For an open file object how far is it to the end |
|
Turn a dictionary with base64 encoded strings back into a numpy array. |
|
Euclidean distance between vectors a and b. |
Generate an arbitrary basis (also known as a coordinate frame) from a given z-axis vector. |
|
|
Return a grid from an (2,dimension) bounds with samples step distance apart. |
|
Return a grid spaced inside a bounding box with edges spaced using np.linspace. |
|
Get the hash of an open file- like object. |
|
Returns True if file has non-ASCII characters (> 0x7F, or 127) |
|
Check if an object is file- like |
|
Given an object, if it is a member of the class ‘name’, or a subclass of ‘name’, return True. |
|
Check to see if an object is None or not. |
|
Check if the object is a pathlib.Path or subclass. |
|
Check if an object is a sequence or not. |
|
Compare the shape of a numpy.ndarray to a target shape, |
|
Check if an object is a string. |
|
A replacement for np.isclose that does fewer checks and validation and as a result is roughly 4x faster. |
|
A version of json.dumps that can handle numpy arrays by creating a custom encoder for numpy dtypes. |
|
Given an object, if it is a sequence return, otherwise add it to a length 1 sequence and return. |
|
If an object is hashable, return the string of the MD5. |
|
Given a set of key value pairs, create a dictionary. |
|
For an iterable, group values into pairs. |
|
Compute the norm per- row of a numpy array. |
|
Convert a set of floating point values into integers with a specified number of significant figures and an exponent. |
|
Round a single value to a specified number of significant figures. |
|
Convert a set of (n, 2) spherical vectors to (n, 3) vectors |
|
Find the file extension of a file name, including support for |
|
For a list of (n, 2) or (n, 3) points return them as (n, 3) 3D points, 2D points on the XY plane. |
|
Stack a list of values that represent a polyline into individual line segments with duplicated consecutive values. |
|
Return a subset of a mesh. |
|
Ensure that any arrays or dicts passed containing |
|
Given a sequence of triangle strips, convert them to (n, 3) faces. |
|
Return the bases of the object passed. |
|
Similar to the type() builtin, but looks in class bases for named instance. |
|
Generate a decent looking alphanumeric unique identifier. |
|
Unitize a vector or an array or row- vectors. |
|
For a set of 3D vectors alter the sign so they are all in the upper hemisphere. |
|
Convert a set of cartesian points to (n, 2) spherical unit vectors. |
|
A thin wrapper for numpy.vstack that ignores empty lists. |
|
Wrap a string or bytes object as a file object. |
|
If a file is open in binary mode and a string is passed, encode and write. |
|
|
-
class
trimesh.util.FunctionRegistry(**kwargs)¶ Bases:
collections.abc.MappingNon-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.
-
class
trimesh.util.TemporaryDirectory¶ Bases:
objectSame basic usage as tempfile.TemporaryDirectory but functional in Python 2.7+
-
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 (logging level) –
handler (log handler object) –
loggers (list of loggers to attach to) – if None, will try to attach to all available
colors (bool, if True try to use colorlog formatter) –
blacklist (list of 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, dimension * 2) float) –
- Non- interleaved bounds, i.e. for a 2D bounds tree:
[(minx, miny, maxx, maxy), …]
- Returns
tree – Tree containing bounds by index
- Return type
Rtree
-
trimesh.util.compress(info)¶ Compress data stored in a dict.
- Parameters
info (dict) – Data to compress in form: {file name in archive: bytes or file-like object}
- Returns
compressed – Compressed file data
- Return type
bytes
-
trimesh.util.concatenate(a, b=None)¶ Concatenate two or more meshes.
- Parameters
a (Trimesh object, or list of such) –
b (Trimesh object, or list of such) –
- Returns
result
- Return type
Trimesh object containing concatenated mesh
-
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)¶ Try to decode byte input as a string.
Initially guesses that text is UTF-8, and then if that fails it tries to detect the encoding and try once more.
- Parameters
text (bytes) – Data that might be a string
- 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 the 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.tostring
- 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)¶ 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
- 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.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_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 math negatives in shape.
- Returns
shape_ok
- Return type
bool, True if shape of obj matches query shape
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.md5_object(obj)¶ If an object is hashable, return the string of the MD5.
- Parameters
obj (object) –
- Returns
md5
- Return type
str, MD5 hash
-
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) – Only returned if return_2D If source points were (n, 2) True
-
trimesh.util.stack_lines(indices)¶ Stack a list of values that represent a polyline into individual line segments with duplicated consecutive values.
- Parameters
indices (sequence of items) –
- Returns
stacked ((n, 2) set of items)
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.submesh(mesh, faces_sequence, only_watertight=False, 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.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)¶ Given a sequence of triangle strips, convert them 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)
-
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,)