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)
sap.trees.available_attributes()[source]

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.save(file, tree)[source]

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)
sap.trees.load(file)[source]

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}
class sap.trees.Tree(image, adjacency, image_name=None, operation_name='non def')[source]

Bases: object

Abstract class for tree representations of images.

Notes

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

get_params()[source]
available_attributes()[source]

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

Tree.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)[source]

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.])
reconstruct(deleted_nodes=None, feature='altitude', filtering='direct')[source]

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]])
num_nodes()[source]

Return the node count of the tree.

Returns

nodes_count – The node count of the tree.

Return type

int

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

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)[source]

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.TosTree(image, adjacency=4, image_name=None)[source]

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) – Not implemented yet, this parameter is set for compatibility with other tree constructors.

  • 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.AlphaTree(image, adjacency=4, image_name=None, weight_function='L1')[source]

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’.

Notes

Inherits all the methods of Tree class.

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

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.

Notes

Inherits all the methods of Tree class.

class sap.trees.WatershedTree(image, markers=None, adjacency=4, image_name=None, weight_function='L1', watershed_attribute='area')[source]

Bases: sap.trees.Tree

Construct a hierarchical watershed from the gradient of the input image.

Parameters

  • image (2D ndarray) – The image from which the gradient (an edge-weighted graph) is constructed.

  • markers (2D ndarray of same dimension as 'image') – Prior-knowledge to be combined to the image gradient before the construction of the hierarchical watershed. See notes.

  • adjacency (int) – The pixel connectivity used to compute edge-weighted graph which represents the image gradient. The allowed adjacency are 4 or 8. Default is 4.

  • image_name (str, optional) – The name of the image.

  • weight_function (str) – The function used to compute dissimilarity between neighbour pixels. Default is ‘L1’ (absolute different between pixel values).

  • watershed_attribute (str) – The criteria used to guide the construction of the hierarchical watershed. The allowed criteria are : ‘area’, ‘volume’, ‘dynamics’ and ‘parents’.

Notes

Inherits all the methods of Tree class.

The markers parameter is prior-knowledge to be combined to the image gradient before the construction of the hierarchical watershed. The method is described in :

Maia, Deise Santana, Minh-Tan Pham, and Sébastien Lefèvre. Watershed-based attribute profiles for pixel classification of remote sensing data. International Conference on Discrete Geometry and Mathematical Morphology. Springer, Cham, 2021.

We expect the markers to be a gray-scale image in which dark and homogeneous regions have the highest probability of belonging to the same catchment basins. If markers is None, it is replaced by an ndarray of ones, the result will be equivalent of not using markers at all.