trimesh.grouping module

grouping.py

Functions for grouping values and rows.

Functions

blocks(data[, min_len, max_len, wrap, …])

Find the indices in an array of contiguous blocks of equal values.

boolean_rows(a, b[, operation])

Find the rows in two arrays which occur in both rows.

clusters(points, radius)

Find clusters of points which have neighbours closer than radius

float_to_int(data[, digits, dtype])

Given a numpy array of float/bool/int, return as integers.

group(values[, min_len, max_len])

Return the indices of values that are identical

group_distance(values, distance)

Find groups of points which have neighbours closer than radius, where no two points in a group are farther than distance apart.

group_min(groups, data)

Given a list of groups find the minimum element of data

group_rows(data[, require_count, digits])

Returns index groups of duplicate rows, for example:

group_vectors(vectors[, angle, include_negative])

Group vectors based on an angle tolerance, with the option to include negative vectors.

hashable_rows(data[, digits])

We turn our array into integers based on the precision given by digits and then put them in a hashable format.

merge_runs(data[, digits])

Merge duplicate sequential values.

merge_vertices(mesh[, digits, textured, …])

Removes duplicate vertices based on integer hashes of each row.

unique_bincount(values[, minlength, …])

For arrays of integers find unique values using bin counting.

unique_float(data[, return_index, …])

Identical to the numpy.unique command, except evaluates floating point numbers, using a specified number of digits.

unique_ordered(data)

Returns the same as np.unique, but ordered as per the first occurrence of the unique value in data.

unique_rows(data[, digits])

Returns indices of unique rows.

unique_value_in_row(data[, unique])

For a 2D array of integers find the position of a value in each row which only occurs once.

trimesh.grouping.blocks(data, min_len=2, max_len=inf, wrap=False, digits=None, only_nonzero=False)

Find the indices in an array of contiguous blocks of equal values.

Parameters
  • data ((n,) array) – Data to find blocks on

  • min_len (int) – The minimum length group to be returned

  • max_len (int) – The maximum length group to be retuurned

  • wrap (bool) – Combine blocks on both ends of 1D array

  • digits (None or int) – If dealing with floats how many digits to consider

  • only_nonzero (bool) – Only return blocks of non- zero values

Returns

blocks – Indices referencing data

Return type

  1. sequence of (*,) int

trimesh.grouping.boolean_rows(a, b, operation=<function intersect1d>)

Find the rows in two arrays which occur in both rows.

Parameters
  • a ((n, d) int) – Array with row vectors

  • b ((m, d) int) – Array with row vectors

  • operation (function) –

    Numpy boolean set operation function:

    -np.intersect1d -np.setdiff1d

Returns

shared

Return type

(p, d) array containing rows in both a and b

trimesh.grouping.clusters(points, radius)

Find clusters of points which have neighbours closer than radius

Parameters
  • points ((n, d) float) – Points of dimension d

  • radius (float) – Max distance between points in a cluster

Returns

groups – Indices of points in a cluster

Return type

(m,) sequence of int

trimesh.grouping.float_to_int(data, digits=None, dtype=<class 'numpy.int32'>)

Given a numpy array of float/bool/int, return as integers.

Parameters
  • data ((n, d) float, int, or bool) – Input data

  • digits (float or int) – Precision for float conversion

  • dtype (numpy.dtype) – What datatype should result be returned as

Returns

as_int – Data as integers

Return type

(n, d) int

trimesh.grouping.group(values, min_len=0, max_len=inf)

Return the indices of values that are identical

Parameters
  • values (1D array) –

  • min_len (int, the shortest group allowed) – All groups will have len >= min_length

  • max_len (int, the longest group allowed) – All groups will have len <= max_length

Returns

groups – IE [0,1,0,1] returns [[0,2], [1,3]]

Return type

sequence of indices to form groups

trimesh.grouping.group_distance(values, distance)

Find groups of points which have neighbours closer than radius, where no two points in a group are farther than distance apart.

Parameters
  • points ((n, d) float) – Points of dimension d

  • distance (float) – Max distance between points in a cluster

Returns

  • unique ((m, d) float) – Median value of each group

  • groups ((m) sequence of int) – Indexes of points that make up a group

trimesh.grouping.group_min(groups, data)

Given a list of groups find the minimum element of data within each group

Parameters
  • groups ((n,) sequence of (q,) int) – Indexes of each group corresponding to each element in data

  • data ((m,)) – The data that groups indexes reference

Returns

minimums – Minimum value of data per group

Return type

(n,)

trimesh.grouping.group_rows(data, require_count=None, digits=None)

Returns index groups of duplicate rows, for example: [[1,2], [3,4], [1,2]] will return [[0,2], [1]]

Note that using require_count allows numpy advanced indexing to be used in place of looping and checking hashes and is ~10x faster.

Parameters
  • data ((n, m) array) – Data to group

  • require_count (None or int) – Only return groups of a specified length, eg: require_count = 2 [[1,2], [3,4], [1,2]] will return [[0,2]]

  • digits (None or int) –

  • data is floating point how many decimals (If) –

  • consider, or calculated from tol.merge (to) –

Returns

groups – Indices from in indicating identical rows.

Return type

sequence (*,) int

trimesh.grouping.group_vectors(vectors, angle=0.0001, include_negative=False)

Group vectors based on an angle tolerance, with the option to include negative vectors.

Parameters
  • vectors ((n,3) float) – Direction vector

  • angle (float) – Group vectors closer than this angle in radians

  • include_negative (bool) – If True consider the same: [0,0,1] and [0,0,-1]

Returns

  • new_vectors ((m,3) float) – Direction vector

  • groups ((m,) sequence of int) – Indices of source vectors

trimesh.grouping.hashable_rows(data, digits=None)

We turn our array into integers based on the precision given by digits and then put them in a hashable format.

Parameters
  • data ((n, m) array) – Input data

  • digits (int or None) – How many digits to add to hash if data is floating point If None, tol.merge will be used

Returns

hashable – Custom data type which can be sorted or used as hash keys

Return type

(n,) array

trimesh.grouping.merge_runs(data, digits=None)

Merge duplicate sequential values. This differs from unique_ordered in that values can occur in multiple places in the sequence, but only consecutive repeats are removed

Parameters

data ((n,) float or int) –

Returns

merged

Return type

(m,) float or int

Examples

In [1]: a Out[1]: array([-1, -1, -1, 0, 0, 1, 1, 2, 0,

3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 9])

In [2]: trimesh.grouping.merge_runs(a) Out[2]: array([-1, 0, 1, 2, 0, 3, 4, 5, 6, 7, 8, 9])

trimesh.grouping.merge_vertices(mesh, digits=None, textured=True, uv_digits=4)

Removes duplicate vertices based on integer hashes of each row.

Parameters
  • mesh (Trimesh object) – Mesh to merge vertices on

  • digits (int) – How many digits to consider for vertices If not specified uses tol.merge

  • textured (bool) – If True, for textured meshes only merge vertices with identical positions AND UV coordinates. No effect on untextured meshes

  • uv_digits (int) – Number of digits to consider for UV coordinates.

trimesh.grouping.unique_bincount(values, minlength=0, return_inverse=False, return_counts=False)

For arrays of integers find unique values using bin counting. Roughly 10x faster for correct input than np.unique

Parameters
  • values ((n,) int) – Values to find unique members of

  • minlength (int) – Maximum value that will occur in values (values.max())

  • return_inverse (bool) – If True, return an inverse such that unique[inverse] == values

  • return_counts (bool) – If True, also return the number of times each unique item appears in values

Returns

  • unique ((m,) int) – Unique values in original array

  • inverse ((n,) int, optional) – An array such that unique[inverse] == values Only returned if return_inverse is True

  • counts ((m,) int, optional) – An array holding the counts of each unique item in values Only returned if return_counts is True

trimesh.grouping.unique_float(data, return_index=False, return_inverse=False, digits=None)

Identical to the numpy.unique command, except evaluates floating point numbers, using a specified number of digits.

If digits isn’t specified, the library default TOL_MERGE will be used.

trimesh.grouping.unique_ordered(data)

Returns the same as np.unique, but ordered as per the first occurrence of the unique value in data.

Examples

In [1]: a = [0, 3, 3, 4, 1, 3, 0, 3, 2, 1]

In [2]: np.unique(a) Out[2]: array([0, 1, 2, 3, 4])

In [3]: trimesh.grouping.unique_ordered(a) Out[3]: array([0, 3, 4, 1, 2])

trimesh.grouping.unique_rows(data, digits=None)

Returns indices of unique rows. It will return the first occurrence of a row that is duplicated: [[1,2], [3,4], [1,2]] will return [0,1]

Parameters
  • data ((n, m) array) – Floating point data

  • digits (int or None) – How many digits to consider

Returns

  • unique ((j,) int) – Index in data which is a unique row

  • inverse ((n,) int) – Array to reconstruct original Example: unique[inverse] == data

trimesh.grouping.unique_value_in_row(data, unique=None)

For a 2D array of integers find the position of a value in each row which only occurs once.

If there are more than one value per row which occur once, the last one is returned.

Parameters
  • data ((n, d) int) – Data to check values

  • unique ((m,) int) – List of unique values contained in data. Generated from np.unique if not passed

Returns

result – With one or zero True values per row.

Return type

(n, d) bool

Examples

In [0]: r = np.array([[-1, 1, 1],

[-1, 1, -1], [-1, 1, 1], [-1, 1, -1], [-1, 1, -1]], dtype=np.int8)

In [1]: unique_value_in_row(r) Out[1]:

array([[ True, False, False],

[False, True, False], [ True, False, False], [False, True, False], [False, True, False]], dtype=bool)

In [2]: unique_value_in_row(r).sum(axis=1) Out[2]: array([1, 1, 1, 1, 1])

In [3]: r[unique_value_in_row(r)] Out[3]: array([-1, 1, -1, 1, 1], dtype=int8)