Topological elements

Algorithms to extract topological elements from labelled arrays.

In a 3D labelled array:

  • A label is a dimension 3 element.

  • A surfel is a dimension 2 element, it has a neighborhood size equal to 2 and is thus expressed as a len-2 tuple of labels.

  • A linel is a dimension 1 element, it has a neighborhood size equal to 3 and is thus expressed as a len-3 tuple of labels.

  • A pointel is a dimension 0 element, it has a neighborhood size equal to 4 and is thus expressed as a len-4 tuple of labels.

In a 2D labelled array:

  • A label is a dimension 2 element.

  • A linel is a dimension 1 element, it has a neighborhood size equal to 2 and is thus expressed as a len-2 tuple of labels.

  • A pointel is a dimension 0 element, it has a neighborhood size equal to 3 and is thus expressed as a len-3 tuple of labels.

timagetk.algorithms.topological_elements.topological_elements_extraction2D(img, elem_order=None, z_coords=None, simplex=True, use_vq=False, verbose=True)[source]

Extract the topological elements coordinates of a 3D labelled image.

Extract the topological elements of order 1 (ie. wall/interface) and 0 (ie. cell vertex) by returning their coordinates grouped by pair and triplet of labels.

Parameters:

  • img (numpy.ndarray) – Array representing a labelled image.

  • elem_order (list, optional) – List of dimensional order of the elements to return, should be in [2, 1, 0]. By default, return a dictionary with every order of topological elements.

  • z_coords (numpy.ndarray, optional) – Array representing the z coordinate of the 2D image.

  • simplex (bool, optional) – Whether to return only simplicial topological elements (default) or to allow elements expressed by longer tuples of labels.

  • use_vq (bool, optional) – If False (default), Else, use scipy.cluster.vq.vq

Returns:

dict – Dictionary with topological elements order as key, each containing dictionaries of n-uplets as keys and coordinates array as values.

Notes

A “pixel” is a dimension 2 element with a neighborhood size equal to 1. A “linel” is a dimension 1 element with a neighborhood size equal to 2. A “pointel” is a dimension 0 element with a neighborhood size equal to 3.

See also

scipy.cluster.vq.vq

timagetk.algorithms.topological_elements.topological_elements_extraction3D(img, elem_order=None, simplex=True, use_vq=False, verbose=True)[source]

Extract the topological elements coordinates of a 3D labelled image.

Extract the topological elements of order 2 (i.e. cell-wall), 1 (i.e. cell-edge) and 0 (i.e. cell-vertex) by returning their coordinates grouped by pair, triplet and quadruplet of labels.

Parameters:

  • img (timagetk.LabelledImage) – The labelled image to extract topological elements for.

  • elem_order (list, optional) – List of dimensional order of the elements to return, should be in [2, 1, 0]. By default, returns a dictionary with every order of topological elements.

  • simplex (bool, optional) – Whether to return only simplicial topological elements (default) or to allow elements expressed by longer tuples of labels.

  • use_vq (bool, optional) – If False (default), Else, use scipy.cluster.vq.vq

Returns:

dict – Dictionary with topological elements order as key, each containing dictionaries of n-uplets as keys and coordinates array as values.

Example

>>> import numpy as np
>>> from timagetk import TissueImage3D
>>> from timagetk.array_util import dummy_labelled_image_3D
>>> from timagetk.algorithms.topological_elements import topological_elements_extraction3D
>>> img = dummy_labelled_image_3D()
>>> elem = topological_elements_extraction3D(img)
timagetk.algorithms.topological_elements.topological_elements_extraction3D_bbox(img, elem_order=None, simplex=True, use_vq=False, exclude_labels=None)[source]

Extract the topological elements coordinates of a 3D labelled image.

Extract the topological elements of order 2 (i.e. cell-wall), 1 (i.e. cell-edge) and 0 (i.e. cell-vertex) by returning their coordinates grouped by pair, triplet and quadruplet of labels.

Parameters:

  • img (timagetk.LabelledImage) – The labelled image to extract topological elements for.

  • elem_order (list, optional) – List of dimensional order of the elements to return, should be in [2, 1, 0]. By default, returns a dictionary with every order of topological elements.

  • simplex (bool, optional) – Whether to return only simplicial topological elements (default) or to allow elements expressed by longer tuples of labels.

  • use_vq (bool, optional) – If False (default), Else, use scipy.cluster.vq.vq

Returns:

dict – Dictionary with topological elements order as key, each containing dictionaries of n-uplets as keys and coordinates array as values.

Example

>>> import numpy as np
>>> from timagetk import TissueImage3D
>>> from timagetk.array_util import dummy_labelled_image_3D
>>> from timagetk.algorithms.topological_elements import topological_elements_extraction3D_brute
>>> from timagetk.algorithms.topological_elements import topological_elements_extraction3D_bbox
>>> img = dummy_labelled_image_3D()
>>> elem_bbox = topological_elements_extraction3D_bbox(img)
>>> elem = topological_elements_extraction3D_brute(img)
timagetk.algorithms.topological_elements.topological_elements_extraction3D_brute(img, elem_order=None, simplex=True, use_vq=False, quiet=False)[source]

Extract the topological elements coordinates of a 3D labelled image.

Extract the topological elements of order 2 (i.e. cell-wall), 1 (i.e. cell-edge) and 0 (i.e. cell-vertex) by returning their coordinates grouped by pair, triplet and quadruplet of labels.

Parameters:

  • img (numpy.ndarray) – Array representing a labelled image.

  • elem_order (list, optional) – List of dimensional order of the elements to return, should be in [2, 1, 0]. By default, returns a dictionary with every order of topological elements.

  • simplex (bool, optional) – Whether to return only simplicial topological elements (default) or to allow elements expressed by longer tuples of labels.

  • use_vq (bool, optional) – If False (default), Else, use scipy.cluster.vq.vq

Returns:

dict – Dictionary with topological elements order as key, each containing dictionaries of n-uplets as keys and coordinates array as values.

Notes

A “surfel” is a dimension 2 element with a neighborhood size equal to 2. A “linel” is a dimension 1 element with a neighborhood size equal to 3. A “pointel” is a dimension 0 element with a neighborhood size equal to 4.

See also

scipy.cluster.vq.vq

Example

>>> import numpy as np
>>> from timagetk.array_util import dummy_labelled_image_3D
>>> from timagetk.algorithms.topological_elements import topological_elements_extraction3D
>>> img = dummy_labelled_image_3D()
>>> img.shape
(5, 11, 11)
>>> # Extract topological elements coordinates:
>>> elem = topological_elements_extraction3D(img)
>>> # Get the cell-vertex coordinates between labels 1, 2, 3 and 4
>>> elem[0]
{(1, 2, 3, 4): array([[0.5, 3.5, 3.5]]),
 (1, 2, 3, 7): array([[0.5, 7.5, 3.5]]),
 (1, 3, 4, 5): array([[0.5, 3.5, 8.5]]),
 (1, 3, 5, 6): array([[0.5, 7.5, 9.5]]),
 (1, 3, 6, 7): array([[ 0.5, 10.5,  6.5]])}
>>> # Get the linel voxel coordinates between labels 1, 2 and 3:
>>> elem[1][(1, 2, 3)]
array([[0.5, 4. , 3.5],
       [0.5, 5. , 3.5],
       [0.5, 6. , 3.5],
       [0.5, 7. , 3.5]])
>>> # Get the surfel voxel coordinates between labels 6 and 7:
>>> elem[2][(6, 7)]
array([[ 1. , 11. ,  6.5],
       [ 1. , 12. ,  6.5],
       [ 2. , 11. ,  6.5],
       [ 2. , 12. ,  6.5],
       [ 3. , 11. ,  6.5],
       [ 3. , 12. ,  6.5],
       [ 4. , 11. ,  6.5],
       [ 4. , 12. ,  6.5]])