Hierarchical representations of image

Classes

class pylena.morpho.ComponentTree(parent: ndarray, values: ndarray, nodemap: ndarray)

Tree representation of the inclusion of some connected components of an image (max-tree, min-tree, or tree of shapes)

compute_area() → ndarray

Compute the area attribute map of an image.

Returns:

A mapping \(n \to \text{area}\) which return the area of a node \(n\).

Return type:

np.ndarray

Example

>>> t = pln.morpho.tos(img)  # img is a (10, 10) image
>>> area = t.compute_area()
>>> area[0]  # 0 is the index of the root of the tree
100
compute_attribute(fun: Callable, init_value: Any) → ndarray

Compute an attribute using the callable object fun

Parameters:

  • fun (Callable) – A function fun(cur, arg) where cur is the value of the attribute of the current node and arg is the value taken for the current node.

  • init_value (Any) – The value used to initialize the attribute

Returns:

A mapping \(n \to \text{attr}\) which return the attribute computed by fun for a node \(n\).

Return type:

np.ndarray

Example

>>> t = pln.morpho.tos(img)  # img is a (10, 10) image
>>> def area_acc(cur: int, arg):
...     if isinstance(arg, tuple):  # Arg is a point of the nodemap
...         return cur + 1
...     return cur + arg  # Arg is the value of the mapping (here a child)
>>> area = t.compute_attribute(area_acc, 0)  # area_acc is an accumulator function to compute the area
>>> area[0]
100
compute_depth() → ndarray

Compute the depth attribute map of an image.

Returns:

A mapping \(n \to \text{depth}\) which return the depth of a node \(n\).

Return type:

np.ndarray

Example

>>> t = pln.morpho.tos(img)
>>> depth = t.compute_depth()
>>> depth[0]  # 0 is the root, so its depth is 0
0
filter(predicate: ndarray, values: ndarray | None = None, inplace=True) → ndarray

Filter (direct filtering rule) the tree based on a boolean predicate for each node. If inplace, the values array is modified inplace (a copy is returned otherwise).

Parameters:

  • predicate (np.ndarray) – A boolean array that tells if a node as to be preserved or not.

  • values (np.ndarray, optional) – The node values to filter. Defaults to self.values.

  • inplace (bool, optional) – Modify the values array or return a copy. Defaults to True.

Returns:

The filtered value array.

Return type:

np.ndarray

Example

>>> t = pln.morpho.tos(img)
>>> area = t.compute_area()
>>> t.filter(area >= 100)  # Remove all the nodes whose area is smaller than 100
reconstruct(values: ndarray | None = None) → ndarray

Reconstruct an image from the values array.

Parameters:

values (np.ndarray, optional) – Values of the nodes. Defaults is self.values.

Returns:

The reconstructed image

Return type:

np.ndarray

Example

>>> t = pln.morpho.tos(img)
>>> area = t.compute_area()
>>> new_values = t.filter(area >= 100, inplace=False)
>>> rec = t.reconstruct(new_values)

Functions

pylena.morpho.maxtree(img: ndarray, connectivity: int) → ComponentTree

Compute the max-tree [1] of a 2D 8-bit image.

Parameters:

  • img (np.ndarray) – The input image

  • connectivity (int) – Input connectivity used to compute the maxt-tree (4 for 4-neighborhood or 8 for 8-neighborhood)

Raises:

ValueError – If the input connectivity is incorrect

Returns:

The computed max-tree

Return type:

ComponentTree

Example

>>> import pylena as pln
>>> t = pln.morpho.maxtree(img, 4)  # Compute the maxtree of an image using 4 connectivity.
pylena.morpho.maxtree3d(img: ndarray, connectivity: int) → ComponentTree

Compute the max-tree [1] of a 3D 8-bit image.

Parameters:

  • img (np.ndarray) – The input image

  • connectivity (int) – Input connectivity used to compute the maxt-tree (6 for 6-neighborhood or 26 for 26-neighborhood)

Raises:

ValueError – If the input connectivity is incorrect

Returns:

The computed max-tree

Return type:

ComponentTree

Example

>>> import pylena as pln
>>> t = pln.morpho.maxtree3d(img, 6)  # Compute the maxtree of an image using 6 connectivity.
pylena.morpho.tos(img: ndarray, root: Tuple = None, padding: str = None, subsampling: str = 'original') → ComponentTree

Compute the tree of shapes [2] of a 2D image in linear complexity [3]

Parameters:

  • input (np.ndarray) – An 2D image with values encoded as 8 bits unsigned integer.

  • root (Tuple, optional) – The root point of the tree (in the form (row, column)) used as a starting point in the propagation. Defaults to None.

  • padding (str, optional) –

    Add an extra border if not None. Defaults to None. Options available:

    • ”median”: Border with the median value of the original border

  • subsampling (str, optional) –

    The size of the returned nodemap. Defaults to “original”. Options available:

    • ”original”: The nodemap is returned with the same dimension as the original image.

    • ”full”: The nodemap is returned with the same dimension as in the Khalimsky space

    • ”full-no-border”: The nodemap is returned with the same dimension as in the Khalimsky space without border.

Raises:

ValueError – If an argument is invalid.

Returns:

The component tree.

Return type:

ComponentTree

Example

>>> import pylena as pln
>>> t = pln.morpho.tos(img, root=(0, 0), padding="median")
pylena.morpho.tos3d(img: ndarray, root: Tuple = None, padding: str = None, subsampling: str = 'original') → ComponentTree

Compute the tree of shapes [2] of a 3D image in linear complexity [3]

Parameters:

  • input (np.ndarray) – An 3D image with values encoded as 8 bits unsigned integer.

  • root (Tuple, optional) – The root point of the tree (in the form (row, column, depth)) used as a starting point in the propagation. Defaults to None.

  • padding (str, optional) –

    Add an extra border if not None. Defaults to None. Options available:

    • ”median”: Border with the median value of the original border

  • subsampling (str, optional) – The size of the returned nodemap. Defaults to “original”.

Raises:

ValueError – If an argument is invalid.

Returns:

The component tree.

Return type:

ComponentTree

Example

>>> import pylena as pln
>>> t = pln.morpho.tos3d(img, root=(0, 0, 0), padding="median")
pylena.morpho.dahu_distance(t: ComponentTree, n1: int, n2: int, depth: ndarray | None = None) → number

Compute the Dahu pseudo-distance [4] based on the Tree of Shapes (ToS) between two nodes n1 and n2.

For two nodes \(n_1\) and \(n_2\) belonging to a ToS \(\mathfrak{G}\), the Dahu pseudo-distance \(d_{\mathfrak{G}}^{DAHU}\) is defined by:

\[d_{\mathfrak{G}}^{DAHU} = \underset{n \in \widehat{\pi}(n_1, n_2)}{\text{max}} \nu(n) - \underset{n \in \widehat{\pi}(n_1, n_2)}{\text{min}} \nu(n)\]

with \(\nu : \mathfrak{G} \rightarrow \mathcal{V}\) the mapping from a node of the ToS to its associated value and \(\widehat{\pi}(n_1, n_2) = (n_1, ..., \text{lca}(n_1, n_2), ..., n_2)\) the path in the ToS \(\mathfrak{G}\) between the nodes \(n_1\) and \(n_2\).

Parameters:

  • t (ComponentTree) – The input Tree of Shapes

  • n1 (int) – A node of the Tree of Shapes.

  • n2 (int) – A second node of the Tree of Shapes.

  • depth (Optional[np.ndarray]) – The depth attribute of each node of the Tree of Shapes. This argument is optional and is computed if missing. However, for performance purposes, it is advised to compute it before computing the Dahu pseudo-distance several times.

Returns:

The Dahu pseudo-distance between the two nodes n1 and n2.

Return type:

np.ndarray

Example

>>> t = pln.morpho.tos(img)
>>> depth = t.compute_depth()
>>> d = dahu_distance(t, n1, n2, depth)
pylena.morpho.dahu_distance_map(t: ComponentTree, seed_nodes: Iterable[int] | None = None, depth: ndarray | None = None) → ndarray

Compute the distance map based on the Dahu pseudo-distance.

For a set of seed nodes \(N\) whose elements belong to a ToS \(\mathfrak{G}\), the distance map \(D_{\mathfrak{G}}^{DAHU}\) computed using the Dahu pseudo-distance \(d_{\mathfrak{G}}^{DAHU}\) is defined by:

\[D_{\mathfrak{G}}^{DAHU}(n, N) = \underset{n' \in N}{\text{min}}\ d_{\mathfrak{G}}^{DAHU}(n, n')\]

for each node \(n \in \mathfrak{G}\). This function takes by default a set only containing the root node of the tree as described in [5] to compute visual saliency detection.

Parameters:

  • t (ComponentTree) – The input Tree of Shapes.

  • seed_nodes (Optional[Iterable[int]]) – The set of seed nodes. If not provided, this set is initialized with the root.

  • depth (Optional[np.ndarray]) – The depth attribute of the ToS.

Returns:

The Dahu distance map.

Return type:

np.ndarray