Profiles¶

This submodule contains the attribute profiles related classes.

Example

>>> import sap
>>> import numpy as np

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

Create the attribute profiles (AP) of image based on area attribute and three thresholds.

>>> aps = sap.attribute_profiles(image, {'area': [10, 100, 1000]})
>>> aps.vectorize()
[[...]]

Create the extended AP of image based on area compactness and volume attributes.

>>> attributes = {'compactness': [.1, .5, .7], 'volume': [10, 100]}
>>> eaps = sap.attribute_profiles(image, attributes)
>>> eaps.vectorize()
[[...]]

Concatenation of profiles to create complex extended profiles.

>>> profiles = sap.attribute_profiles(image, {'area': [10, 100]}) \
...            + sap.feature_profiles(image, {'compactness': [.3, .7]}) \
...            + sap.self_dual_attribute_profiles(image, {'height': [5, 15]})
Profiles[{'attribute': 'area',
  'filtering rule': 'direct',
  'image': -7518820387991786804,
  'name': 'attribute profiles',
  'out feature': 'altitude',
  'profiles': [{'operation': 'thinning', 'threshold': 100},
               {'operation': 'thinning', 'threshold': 10},
               {'operation': 'copy feature altitude'},
               {'operation': 'thickening', 'threshold': 10},
               {'operation': 'thickening', 'threshold': 100}]},
 {'attribute': 'compactness',
  'filtering rule': 'direct',
  'image': -7518820387991786804,
  'name': 'feature profiles',
  'out feature': 'compactness',
  'profiles': [{'operation': 'thinning', 'threshold': 0.7},
               {'operation': 'thinning', 'threshold': 0.3},
               {'operation': 'copy feature compactness'},
               {'operation': 'thickening', 'threshold': 0.3},
               {'operation': 'thickening', 'threshold': 0.7}]},
 {'attribute': 'height',
  'filtering rule': 'direct',
  'image': -7518820387991786804,
  'name': 'self dual attribute profiles',
  'out feature': 'altitude',
  'profiles': [{'operation': 'copy feature altitude'},
               {'operation': 'sd filtering', 'threshold': 5},
               {'operation': 'sd filtering', 'threshold': 15}]}]

class sap.profiles.Profiles(data, description)[source]¶

Bases: object

Base class for profiles.

Parameters

data (list of ndarray) – List of ndarray representing profiles grouped by image or attribute filtering.
description (list of dict) – List of dictionary containing the metadata of the profiles.

diff()[source]¶

Compute the differential of profiles.

Refer to differential() for full documentation.

Returns: differential – The processed differential profiles.
Return type: Profiles

lf(self, local_feature=(np.mean, np.std), patch_size=7)[source]¶

Compute the local features of profiles

Refer to local_features() for full documentation.

local_featurefunction or tuple of functions: The function(s) to describe the local patches.
patch_sizeint: The size of the patches.

Returns: local_features – The local features of profiles.
Return type: Profiles

vectorize()[source]¶

Return the vectors of the profiles.

Refer to vectorize() for full documentation.

Returns: vectors – The vectors of the profiles.
Return type: numpy.ndarray

See also

vectorize: equivalent function.

strip(lambda x: x['operation'] != 'thinning')[source]¶

Remove profiles according to condition. Iteration is done on profiles description.

Refer to strip_profiles() for full documentation.

Parameters: condition (function) – The function (or lambda function) to use on profiles description to filter the profiles.
Returns: new_profiles – Filtered profiles.
Return type: Profiles

See also

strip_profiles: equivalent function

strip_copy()[source]¶

Remove all the copied images in profiles.

Refer to strip_profiles_copy() for full documentation.

Parameters: profiles (Profiles) – The profiles to strip on the copied images.
Returns: new_profiles – Copy of profiles without copied image.
Return type: Profiles

See also

strip_profiles_copy: equivalent function

sap.profiles.create_profiles(tree, attribute, out_feature='altitude', filtering_rule='direct', profiles_name='unknow')[source]¶

Compute the profiles of an images. Generic function.

Parameters

image (ndarray) – The image to be profiled.
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, iterable of thresholds).
tree_type (sap.trees.Tree, serie of sap.trees.Tree) – Tree or pair of tree for non dual filtering (e.g. min-tree and max-tree for attribute profiles).
adjacency (int, optional) – Adjacency used for the tree construction. Default is 4.
image_name (str, optional) – The name of the image Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
out_feature (str or list, optional) – Out feature of the profiles. Can be ‘altitude’ (default), ‘same’ or a list of feature. If ‘same’ then out feature of the profiles match the filtering attribute. Refer to feature_profiles() and self_dual_feature_profiles() for more details.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.
profiles_name (str, optional) – Name of the profiles (e.g. ‘attribute profiles’).

Todo

out_feature takes a list of features.

Example

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

>>> sap.create_profiles(image, {'area': [5, 10]},
...                     (sap.MinTree, sap.MaxTree))
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'image': -7518820387991786804,
 'name': 'unknow',
 'out feature': 'altitude',
 'profiles': [{'operation': 'thinning', 'threshold': 10},
              {'operation': 'thinning', 'threshold': 5},
              {'operation': 'copy feature altitude'},
              {'operation': 'thickening', 'threshold': 5},
              {'operation': 'thickening', 'threshold': 10}]}

sap.profiles.attribute_profiles(image, attribute, adjacency=4, image_name=None, filtering_rule='direct')[source]¶

Compute the attribute profiles of an image.

Parameters

image (ndarray) – The image
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, number).
adjacency (int) – Adjacency used for the tree construction. Default is 4.
image_name (str) – The name of the image (optional). Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.

Examples

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

>>> sap.attribute_profiles(image, {'area': [10, 100]})
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'image': -7518820387991786804,
 'name': 'attribute profiles',
 'out feature': 'altitude',
 'profiles': [{'operation': 'thinning', 'threshold': 100},
              {'operation': 'thinning', 'threshold': 10},
              {'operation': 'copy feature altitude'},
              {'operation': 'thickening', 'threshold': 10},
              {'operation': 'thickening', 'threshold': 100}]}

See also

sap.trees.available_attributes: List available attributes.

sap.profiles.self_dual_attribute_profiles(image, attribute, adjacency=4, image_name=None, filtering_rule='direct')[source]¶

Compute the self dual attribute profiles of an image.

Parameters

image (ndarray) – The image
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, number).
adjacency (int) – Adjacency used for the tree construction. Default is 4.
image_name (str) – The name of the image (optional). Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.

Examples

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

>>> sap.self_dual_attribute_profiles(image, {'area': [10, 100]})
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'image': -7518820387991786804,
 'name': 'self dual attribute profiles',
 'out feature': 'altitude',
 'profiles': [{'operation': 'copy feature altitude'},
              {'operation': 'sd filtering', 'threshold': 10},
              {'operation': 'sd filtering', 'threshold': 100}]}

See also

sap.trees.available_attributes: List available attributes.
attribute_profiles: other profiles.

sap.profiles.self_dual_feature_profiles(image, attribute, adjacency=4, image_name=None, out_feature='same', filtering_rule='direct')[source]¶

Compute the self dual features profiles of an image.

Parameters

image (ndarray) – The image
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, number).
adjacency (int) – Adjacency used for the tree construction. Default is 4.
image_name (str) – The name of the image (optional). Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
out_feature (str or list, optional) – Out feature of the profiles. Can be ‘altitude’ (default), ‘same’ or a list of feature. If ‘same’ then out feature of the profiles match the filtering attribute.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.

Examples

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

>>> sap.self_dual_feature_profiles(image, {'area': [10, 100]})
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'image': -7518820387991786804,
 'name': 'self dual feature profiles',
 'out feature': 'area',
 'profiles': [{'operation': 'copy feature area'},
              {'operation': 'sd filtering', 'threshold': 10},
              {'operation': 'sd filtering', 'threshold': 100}]}

See also

sap.trees.available_attributes: List available attributes.
attribute_profiles: other profiles.

sap.profiles.feature_profiles(image, attribute, adjacency=4, image_name=None, out_feature='same', filtering_rule='direct')[source]¶

Compute the feature profiles of an image.

Parameters

image (ndarray) – The image
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, number).
adjacency (int) – Adjacency used for the tree construction. Default is 4.
image_name (str) – The name of the image (optional). Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
out_feature (str or list, optional) – Out feature of the profiles. Can be ‘altitude’ (default), ‘same’ or a list of feature. If ‘same’ then out feature of the profiles match the filtering attribute.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.

Examples

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

>>> sap.feature_profiles(image, {'area': [5, 10]})
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'image': -7518820387991786804,
 'name': 'feature profiles',
 'out feature': 'area',
 'profiles': [{'operation': 'thinning', 'threshold': 10},
              {'operation': 'thinning', 'threshold': 5},
              {'operation': 'copy feature area'},
              {'operation': 'thickening', 'threshold': 5},
              {'operation': 'thickening', 'threshold': 10}]}

See also

sap.trees.available_attributes: List available attributes.
attribute_profiles: other profiles.

sap.profiles.alpha_profiles(image, attribute, adjacency=4, image_name=None, filtering_rule='direct')[source]¶

Compute the alpha profiles of an image.

Parameters

image (ndarray) – The image
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, number).
adjacency (int) – Adjacency used for the tree construction. Default is 4.
image_name (str) – The name of the image (optional). Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.

Examples

>>> image = np.arange(5 * 5).reshape(5, 5)
>>> sap.alpha_profiles(image, {'area': [10, 100]})
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'name': 'alpha profiles',
 'out feature': 'altitude',
 'profiles': [{'operation': 'copy feature altitude'},
              {'operation': 'alpha filtering', 'threshold': 10},
              {'operation': 'alpha filtering', 'threshold': 100}],
 'tree': {'adjacency': 4, 'image_hash': '44f17c0f', 'image_name': None}}

See also

sap.trees.available_attributes: List available attributes.

sap.profiles.omega_profiles(image, attribute, adjacency=4, image_name=None, filtering_rule='direct')[source]¶

Compute the omega profiles of an image.

Parameters

image (ndarray) – The image
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, number).
adjacency (int) – Adjacency used for the tree construction. Default is 4.
image_name (str) – The name of the image (optional). Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.

Examples

>>> image = np.arange(5 * 5).reshape(5, 5)
>>> sap.omega_profiles(image, {'area': [10, 100]})
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'name': 'omega profiles',
 'out feature': 'altitude',
 'profiles': [{'operation': 'copy feature altitude'},
              {'operation': '(ω) filtering', 'threshold': 10},
              {'operation': '(ω) filtering', 'threshold': 100}],
 'tree': {'adjacency': 4, 'image_hash': '44f17c0f', 'image_name': None}}

See also

sap.trees.available_attributes: List available attributes.

sap.profiles.watershed_profiles(image, attribute, markers=None, adjacency=4, image_name=None, filtering_rule='direct', weight_function='L1', watershed_attribute='area')[source]¶

Compute the watershed profiles of an image.

Parameters

image (ndarray) – The image
attribute (dict) – Dictionary of attribute (as key, str) with according thresholds (as values, number).
markers (2D ndarray of same dimension as 'image') – Prior-knowledge to be combined to the image gradient before the construction of the hierarchical watershed. If None, an ndarray of ones is used, the result will be equivalent of not using markers at all.
adjacency (int) – Adjacency used for the tree construction. Default is 4.
image_name (str) – The name of the image (optional). Useful to track filtering process and display. If not set, the name is replaced by the hash of the image.
filtering_rule (str, optional) – The filtering rule to use. It can be ‘direct’, ‘min’, ‘max’ or ‘subtractive’. Default is ‘direct’.
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 contruction of the hierarchical watershed. The allowed criteria are : ‘area’, ‘volume’, ‘dynamics’ and ‘parents’.

Examples

>>> image = np.arange(5 * 5).reshape(5, 5)
>>> markers = np.ones((5,5))
>>> sap.watershed_profiles(image, markers, {'area': [10, 100]})
Profiles{'attribute': 'area',
 'filtering rule': 'direct',
 'name': 'watershed profiles',
 'out feature': 'altitude',
 'profiles': [{'operation': 'copy feature altitude'},
              {'operation': 'watershed filtering', 'threshold': 10},
              {'operation': 'watershed filtering', 'threshold': 100}],
 'tree': {'adjacency': 4, 'image_hash': '44f17c0f', 'image_name': None}}

See also

sap.trees.available_attributes: List available attributes.

sap.profiles.show_all_profiles(profiles, attribute=None, image=None, height=None, fname=None, **kwargs)[source]¶

Display profiles with matplotlib.

Parameters

profiles (sap.profiles.Profiles) – The profiles to display.
attribute (sring, optional) – Name of attribute to display. By default display all the attributes contained in profiles.
image (string, optional) – Name of the image to display. By default display the profiles of all images.
height (scalar, optional, default: None) – Height of the figure in inches. Automatically adjust the size of the figure to display correctly the profiles and the title with matplot.
fname (str or PathLike, optional) – If set, the file path to save the figure. The attribute name is automatically inserted in the file name.

See also

show_profiles: Display a profiles stack.

Notes

This is a utility function to call recursively show_profiles. Attribute and image filters are available to filter the profiles to display.

sap.profiles.strip_profiles_copy(profiles)[source]¶

Remove all the copied images in profiles.

Copy are the original images where profiles are computed on.

Parameters: profiles (Profiles) – The profiles to strip on the copied images.
Returns: new_profiles – Copy of profiles without copied image.
Return type: Profiles

See also

sap.strip_profiles: Filter profiles according to condition.

sap.profiles.strip_profiles(lambda x: x['operation'] != 'thinning', profiles)[source]¶

Remove profiles according to condition. Iteration is done on profiles description (see Notes).

Parameters

condition (function) – The function (or lambda function) to use on profiles description to filter the profiles.
profiles (Profiles) – The profiles to filter.

Returns

new_profiles – Filtered profiles.

Return type

Profiles

Notes

The condition is tested on the description of each profiles. Considering this stack:

>>> aps
Profiles{'attribute': 'area',
 'image': -8884649894275650052,
 'profiles': [{'operation': 'thinning', 'threshold': 1000},
              {'operation': 'thinning', 'threshold': 100},
              {'operation': 'thinning', 'threshold': 10},
              {'operation': 'copy'},
              {'operation': 'thickening', 'threshold': 10},
              {'operation': 'thickening', 'threshold': 100},
              {'operation': 'thickening', 'threshold': 1000}]}

The condition function is tested on each item of the list 'profiles'.

See also

Profiles.strip: Remove profiles based on condition.

Examples

Strip profiles depending on thresholds level:

>>> image = np.random.random((100, 100))
>>> aps = sap.attribute_profiles(image, {'area': [10, 100, 1000]})

>>> sap.strip_profiles(lambda x: 'threshold' in x and x['threshold'] > 20, aps)
Profiles{'attribute': 'area',
 'image': 2376333419322655105,
 'profiles': [{'operation': 'thinning', 'threshold': 10},
              {'operation': 'copy'},
              {'operation': 'thickening', 'threshold': 10}]}

Strip profiles depending on operation:

>>> sap.strip_profiles(lambda x: x['operation'] == 'thinning', aps)
Profiles{'attribute': 'area',
 'image': 2376333419322655105,
 'profiles': [{'operation': 'copy'},
              {'operation': 'thickening', 'threshold': 10},
              {'operation': 'thickening', 'threshold': 100},
              {'operation': 'thickening', 'threshold': 1000}]}

sap.profiles.differential(profiles)[source]¶

Compute the differential of profiles.

Parameters: profiles (Profiles) – Attribute profiles or other profiles to process the differential on.
Returns: differential – The processed differential profiles.
Return type: Profiles

sap.profiles.local_features(profiles, local_feature=(np.mean, np.std), patch_size=7)[source]¶

Compute the local features of profiles

Parameters

profiles (Profiles) – Input Profiles.
local_feature (function or tuple of functions) – The function(s) to describe the local patches.
patch_size (int) – The size of the patches.

Returns

local_feature – The local features of profiles.

Return type

Profiles

sap.profiles.show_profiles(profiles, height=None, fname=None, **kwargs)[source]¶

Display a profiles stack with matplotlib.

Parameters

profiles (Profiles) – The profiles to display. Can be only of length 1.
height (scalar, optional, default: None) – Height of the figure in inches. Automatically adjust the size of the figure to display correctly the profiles and the title with matplot.
fname (str or PathLike, optional) – If set, the file path to save the figure. The attribute name is automatically inserted in the file name.

See also

show_profiles_all: Display several profiles at once.

sap.profiles.concatenate((profiles_1, profiles_2, ...))[source]¶

Concatenate a sequence of profiles.

Parameters: sequence (sequence of Profiles) – The sequence of profiles to concatenate.
Returns: profiles – The concatenated profiles.
Return type: Profiles

Examples

>>> aps_a = sap.attribute_profiles(image, {'area': [10, 100]})
>>> aps_b = sap.attribute_profiles(image, {'compactness': [.1, .5]})

>>> aps = sap.concatenate((aps_a, aps_b))

>>> len(aps) == len(aps_a) + len(aps_b)
True

sap.profiles.vectorize(profiles)[source]¶

Return the classification vectors of the profiles.

Parameters: profiles (Profiles) – Profiles on which process the vectors.
Returns: vectors – The vectors of the profiles.
Return type: numpy.ndarray

See also

Profiles.vectorize: get the vectors of profiles.

Example

>>> image = np.random.random((100, 100))
>>> aps = sap.attribute_profiles(image, {'area': [10, 100]})

>>> vectors = sap.vectorize(aps)
>>> vectors.shape
(5, 100, 100)