Trees

This submodule contains the component tree classes.

Example

Simple creation of the max-tree of an image, compute the area attributes of the nodes and reconstruct a filtered image removing nodes with area less than 100 pixels:

>>>  t = sap.MaxTree(image)
>>>  area = t.get_attribute('area')
>>>  filtered_image = t.reconstruct(area < 100)

class sap.trees.AlphaTree(image, adjacency=4, image_name=None, weight_function='L1')

Bases: sap.trees.Tree

Alpha tree, partition the image depending of the weight between pixels.

Parameters

• image (ndarray) – The image to be represented by the tree structure.

• adjacency (int) – The pixel connectivity to use during the tree creation. It determines the number of pixels to be taken into account in the neighborhood of each pixel. The allowed adjacency are 4 or 8. Default is 4.

• image_name (str, optional) – The name of the image Useful to track filtering process and display.

• weight_function (str or higra.WeightFunction) – The weight function to use during the construction of the tree. Can be ‘L0’, ‘L1’, ‘L2’, ‘L2_squared’, ‘L_infinity’, ‘max’, ‘min’, ‘mean’ or a higra.WeightFunction. The default is ‘L1’.

class sap.trees.MaxTree(image, adjacency=4, image_name=None)

Bases: sap.trees.Tree

Max tree class, the local maxima values of the image are in leafs.

Parameters

• image (ndarray) – The image to be represented by the tree structure.

• adjacency (int) – The pixel connectivity to use during the tree creation. It determines the number of pixels to be taken into account in the neighborhood of each pixel. The allowed adjacency are 4 or 8. Default is 4.

• image_name (str, optional) – The name of the image Useful to track filtering process and display.

Notes

Inherits all methods of Tree class.

class sap.trees.MinTree(image, adjacency=4, image_name=None)

Bases: sap.trees.Tree

Min tree class, the local minima values of the image are in leafs.

Parameters

• image (ndarray) – The image to be represented by the tree structure.

• adjacency (int) – The pixel connectivity to use during the tree creation. It determines the number of pixels to be taken into account in the neighborhood of each pixel. The allowed adjacency are 4 or 8. Default is 4.

• image_name (str, optional) – The name of the image Useful to track filtering process and display.

Notes

Inherits all methods of Tree class.

class sap.trees.OmegaTree(image, adjacency=4, image_name=None)

Bases: sap.trees.Tree

Partition the image depending of the constrained weight between pixels.

Parameters

• image (ndarray) – The image to be represented by the tree structure.

• adjacency (int) – The pixel connectivity to use during the tree creation. It determines the number of pixels to be taken into account in the neighborhood of each pixel. The allowed adjacency are 4 or 8. Default is 4.

• image_name (str, optional) – The name of the image Useful to track filtering process and display.

class sap.trees.TosTree(image, adjacency=4, image_name=None)

Bases: sap.trees.Tree

Tree of shapes, the local maxima values of the image are in leafs.

Parameters

• image (ndarray) – The image to be represented by the tree structure.

• adjacency (int) – The pixel connectivity to use during the tree creation. It determines the number of pixels to be taken into account in the neighborhood of each pixel. The allowed adjacency are 4 or 8. Default is 4.

• image_name (str, optional) – The name of the image Useful to track filtering process and display.

Notes

Inherits all the methods of Tree class.

Todo

• take into account adjacency

class sap.trees.Tree(image, adjacency, image_name=None, operation_name='non def')

Bases: object

Abstract class for tree representations of images.

Notes

You should not instantiate class Tree directly, use MaxTree or MinTree instead.

available_attributes()

Return a dictionary of available attributes and parameters.

Returns

dict_of_attributes – The names of available attributes and parameters required. The names are keys (str) and the parameters are values (list of str) of the dictionary.

Return type

dict

See also

get_attribute()

Return the attribute values of the tree nodes.

Notes

The list of available attributes is generated dynamically. It is dependent of higra’s installed version. For more details, please refer to higra documentation according to the appropriate higra’s version.

Example

>>> sap.Tree.available_attributes()
{'area': ['vertex_area=None', 'leaf_graph=None'],
 'compactness': ['area=None', 'contour_length=None', ...],
 ...
 'volume': ['altitudes', 'area=None']}

get_attribute(attribute_name, **kwargs)

Get attribute values of the tree nodes.

Parameters

attribute_name (str) – Name of the attribute (e.g. ‘area’, ‘compactness’, …)

Returns

attribute_values – The values of attribute for each nodes.

Return type

ndarray

See also

available_attributes()

Return the list of available attributes.

Notes

Some attributes require additional parameters. Please refer to available_attributes. If not stated, some additional parameters are automatically deducted. These deducted parameters are ‘altitudes’ and ‘vertex_weights’.

The available attributes depends of higra’s installed version. For further details Please refer to higra documentation according to the appropriate higra’s version.

Examples

>>> image = np.arange(20 * 50).reshape(20, 50)
>>> t = sap.MaxTree(image)
>>> t.get_attribute('area')
array([   1.,    1.,    1., ...,  998.,  999., 1000.])

get_params()

num_nodes()

Return the node count of the tree.

Returns

nodes_count – The node count of the tree.

Return type

int

reconstruct(deleted_nodes=None, feature='altitude', filtering='direct')

Return the reconstructed image according to deleted nodes.

Parameters

• deleted_nodes (ndarray or boolean, optional) – Boolean array of nodes to delete. The length of the array should be of same of node count.

• feature (str, optional) – The feature to be reconstructed. Can be any attribute of the tree (see available_attributes()). The default is ‘altitude’, the grey level of the node.

• filtering (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.

Returns

filtered_image – The reconstructed image.

Return type

ndarray

Examples

>>> image = np.arange(5 * 5).reshape(5, 5)
>>> mt = sap.MaxTree(image)

>>> mt.reconstruct()
array([[ 0,  1,  2,  3,  4],
       [ 5,  6,  7,  8,  9],
       [10, 11, 12, 13, 14],
       [15, 16, 17, 18, 19],
       [20, 21, 22, 23, 24]])

>>> area = mt.get_attribute('area')

>>> mt.reconstruct(area > 10)
array([[ 0,  0,  0,  0,  0],
       [ 0,  0,  0,  0,  0],
       [ 0,  0,  0,  0,  0],
       [15, 16, 17, 18, 19],
       [20, 21, 22, 23, 24]])

sap.trees.available_attributes()

Return a dictionary of available attributes and parameters.

Returns

dict_of_attributes – The names of available attributes and parameters required. The names are keys (str) and the parameters are values (list of str) of the dictionary.

Return type

dict

See also

get_attribute()

Return the attribute values of the tree nodes.

Notes

The list of available attributes is generated dynamically. It is dependent of higra’s installed version. For more details, please refer to higra documentation according to the appropriate higra’s version.

Example

>>> sap.available_attributes()
{'area': ['vertex_area=None', 'leaf_graph=None'],
 'compactness': ['area=None', 'contour_length=None', ...],
 ...
 'volume': ['altitudes', 'area=None']}

sap.trees.load(file)

Load a tree from a Higra tree file.

Parameters

file (str or pathlib.Path) – File to which the tree is loaded.

Examples

>>> mt = sap.MaxTree(np.arange(10000).reshape(100,100))
>>> sap.save('tree.npz', mt)

>>> sap.load('tree.npz')
MaxTree{num_nodes: 20000, image.shape: (100, 100), image.dtype: int64}

sap.trees.save(file, tree)

Save a tree to a NumPy archive file.

Parameters

• file (str or pathlib.Path) – File to which the tree is saved.

• tree (Tree) – Tree to be saved.

Examples

>>> mt = sap.MaxTree(np.random.random((100,100)))
>>> sap.save('tree.npz', mt)