salientregions package¶

Submodules¶

salientregions.binarization module¶

Binarization methods. Thresholding: Otsu, data-driven.

class salientregions.binarization.Binarizer¶

Bases: object

Abstract class for objects that can binarize an image.

binarize(img, visualize=True)¶: Subclasses should implement this method.

class salientregions.binarization.DatadrivenBinarizer(lam, area_factor_large=0.001, area_factor_verylarge=0.1, weights=(0.33, 0.33, 0.33), offset=80, stepsize=1, connectivity=4)¶

Bases: salientregions.binarization.Binarizer

Binarizes the image such that the desired number of (large) connected components is maximized.

Parameters:

lam (float) – lambda, minimumm area of a connected component
area_factor_large (float, optional) – factor that describes the minimum area of a large CC
area_factor_verylarge (float, optional) – factor that describes the minimum area of a very large CC
weights ((float, float, float)) – weights for number of CC, number of large CC and number of very large CC respectively.
offset (int, optional) – The offset (number of gray levels) to search for around the Otsu level
stepsize (int, optional) – the size of the step between consequtive gray levels to process
connectivity (int, optional) – What connectivity to use to define CCs

binarize(img, visualize=True)¶

Binarizes the image such that the desired number of (large) connected components is maximized.

Parameters:	img (numpy array) – grayscale image to be binarized. visualize (bool, optional) – Option for visualizing the process
Returns:	binarized – Binary image with values 0 and 255
Return type:	numpy array

binarize_withthreshold(img, visualize=True, output_scores=False)¶

Binarizes the image such that the desired number of (large) connected components is maximized. Also returns the optimal threshold.

Parameters:

img (numpy array) – grayscale image to be binarized.
visualize (bool, optional) – Option for visualizing the process

Returns:

t_opt (int) – Optimal threshold
binarized (numpy array) – Binary image with values 0 and 255

class salientregions.binarization.OtsuBinarizer¶

Bases: salientregions.binarization.Binarizer

Binarizes the image with the Otsu method.

binarize(img, visualize=True)¶

Binarizes the image with the Otsu method.

Parameters:	img (numpy array) – grayscale image to be binarized. visualize (bool, optional) – Option for visualizing the process
Returns:	binarized – Binary image with values 0 and 255
Return type:	numpy array

class salientregions.binarization.ThresholdBinarizer(threshold=127)¶

Bases: salientregions.binarization.Binarizer

Binarizes the image with a given threshold.

Parameters:	threshold (int, optional) – Threshold value

binarize(img, visualize=True)¶

Binarizes the image according to the threshold.

Parameters:	img (numpy array) – grayscale image to be binarized. visualize (bool, optional) – Option for visualizing the process
Returns:	binarized – Binary image with values 0 and 255
Return type:	numpy array

salientregions.binarydetector module¶

Binary detection of salient regions using mathematical moprhology.

class salientregions.binarydetector.BinaryDetector(SE, lam, area_factor, connectivity)¶

Bases: object

Class for detecting salient regions in binary images.

Parameters:	SE (numpy array) – The structuring element to use in processing the image lam (float) – lambda, minimumm area of a connected component area_factor (float) – factor that describes the minimum area of a significent CC connectivity (int) – What connectivity to use to define CCs

holes¶: numpy array – binary mask of the holes

islands¶: numpy array – binary mask of the islands

indentations¶: numpy array – binary mask of the indentations

protrusions¶: numpy array – binary mask of the protrusions

Note

The methods detect, get_holes, get_islands, get_indentations and get_protrusions invoke the calculation of the regions. After that, the regions are also available as attributes holes, islands, indentations and protrusions.

detect(img, find_holes=True, find_islands=True, find_indentations=True, find_protrusions=True, visualize=True)¶

Find salient regions of the types specified.

Parameters:	img (numpy array) – binary image to detect regions find_holes (bool, optional) – Whether to detect regions of type hole find_islands (bool, optional) – Whether to detect regions of type island find_indentations (bool, optional) – Whether to detect regions of type indentation find_protrusions (bool, optional) – Whether to detect regions of type protrusion visualize (bool, optional) – option for visualizing the process
Returns:	regions – For each type of region, the maks with detected regions.
Return type:	dict

get_holes()¶: Get salient regions of type ‘hole’

get_indentations()¶: Get salient regions of type ‘indentation’

get_islands()¶: Get salient regions of type ‘island’

get_protrusions()¶: Get salient regions of type ‘protrusion’

reset()¶: Reset all attributes.

salientregions.detectors module¶

Salient regions detectors.

class salientregions.detectors.Detector(SE_size_factor=0.15, lam_factor=5, area_factor=0.05, connectivity=4)¶

Bases: object

Abstract class for salient region detectors.

Parameters:	SE_size_factor (float, optional) – The fraction of the image size that the structuring element should be lam_factor (float, optional) – The factor of lambda compared to the SE size area_factor (float, optional) – factor that describes the minimum area of a significent CC connectivity (int) – What connectivity to use to define CCs

detect(img)¶

This method should be implemented to return a dictionary with the salientregions. Calling this function from the superclass makes sure the structuring element and lamda are created.

Parameters:	img (numpy arrary) – grayscale or color image to detect regions

get_SE(imgsize)¶

Get the structuring element en minimum salient region area for this image. The standard type of binarization is Datadriven (as in DMSR), but it is possible to pass a different Binarizer.

Parameters:	imgsize (int) – size (nr of pixels) of the image
Returns:	SE (numpy array) – The structuring element for this image lam (float) – lambda, minimumm area of a salient region

class salientregions.detectors.MSSRDetector(min_thres=0, max_thres=255, step=1, perc=0.7, **kwargs)¶

Bases: salientregions.detectors.Detector

Find salient regions of all four types, in color or greyscale images. It uses MSSR, meaning that it detects on a series of threshold levels.

Parameters:	min_thres (int, optional) – Minimum threshold level max_thres (int, optional) – Maximum threshold level step (int, optional) – Stepsize for looping through threshold levels perc (float, optional) – The percentile at which the threshold is taken **kwargs – Other arguments to pass along to the constructor of the superclass Detector

gray¶: numpy array – The image converted to grayscale

regions_sum¶: numpy array – The sum of the regions of all levels, before thresholding

Note

This algorithm is much slower than the DMSR, so should be used with care.

detect(img, find_holes=True, find_islands=True, find_indentations=True, find_protrusions=True, visualize=True)¶

Find salient regions of the types specified.

Parameters:	img (numpy arrary) – grayscale or color image to detect regions find_holes (bool, optional) – Whether to detect regions of type hole find_islands (bool, optional) – Whether to detect regions of type island find_indentations (bool, optional) – Whether to detect regions of type indentation find_protrusions (bool, optional) – Whether to detect regions of type protrusion visualize (bool, optional) – Option for visualizing the process
Returns:	regions – For each type of region, the maks with detected regions.
Return type:	dict

threshold_cumsum(data)¶

Thresholds an image based on a percentile of the non-zero pixel values.

Parameters:	data (2-dimensional numpy array) – the image to threshold
Returns:	binarized – Thresholded image
Return type:	numpy array

class salientregions.detectors.SalientDetector(binarizer=None, **kwargs)¶

Bases: salientregions.detectors.Detector

Find salient regions of all four types, in color or greyscale images. The image is first binarized using the specified binarizer, then a binary detector is used.

Parameters:	binarizer (Binerizer object, optional) – Binerizer object that handles the binarization. By default, we use datadriven binarization **kwargs – Other arguments to pass along to the constructor of the superclass Detector

gray¶: numpy array – The image converted to grayscale

binarized¶: numpy array – The binarized image

detect(img, find_holes=True, find_islands=True, find_indentations=True, find_protrusions=True, visualize=True)¶

Find salient regions of the types specified.

Parameters:	img (numpy arrary) – grayscale or color image to detect regions find_holes (bool, optional) – Whether to detect regions of type hole find_islands (bool, optional) – Whether to detect regions of type island find_indentations (bool, optional) – Whether to detect regions of type indentation find_protrusions (bool, optional) – Whether to detect regions of type protrusion visualize (bool, optional) – Option for visualizing the process
Returns:	regions – For each type of region, the maks with detected regions.
Return type:	dict

salientregions.helpers module¶

Module for helper functions, e.g. image and regions visualization, region to ellipse conversion, loading MAT files, array/vector difference etc.

salientregions.helpers.array_diff(arr1, arr2, rtol=1e-05, atol=1e-08)¶

Compares two arrays. Useful for testing purposes.

Parameters:	arr1 (2-dimensional numpy, first array to compare) – arr2 (2-dimensional numpy, second array to compare) –
Returns:	is_close – True if elemetns of the two arrays are close within the defaults tolerance (see numpy.allclose documentaiton for tolerance values)
Return type:	bool

salientregions.helpers.binary_mask2ellipse_features(regions, connectivity=4, min_square=False)¶

Conversion of all types of regions to ellipse features.

Parameters:

regions (dict) – Dict of binary masks of the detected salient regions
connectivity (int, optional) – Neighborhood connectivity
min_square (bool, optional) – whether to use minimum sqrt fitting for ellipses (default is bounded rotated rectangle fitting)

Returns:

num_regions (dict) – The number of saleint regions for each saliency_type
features_standard (dict) – dictionary with standard ellipse features for each of the ellipses
features_poly (dict) – dictionary with polynomial ellipse features for each of the ellipses

Note

The keys of the dictionaries are the saliency type.

Every row in the array per key of features_standard corresponds to a single region/ellipse and is of format: x0 y0 a b angle saliency_type , where (x0,y0) are the coordinates of the ellipse centroid and a, b and ``angle``(in degrees) are the standard parameters from the ellipse equation: math:(x+cos(angle) + y+sin(angle))^2/a^2 + (x*sin(angle) - y*cos(angle))^2/b^2 = 1

Every row in the array per key of features_poly corresponds to a single region/ellipse and is of format: x0 y0 A B C saliency_type , where (x0,y0) are the coordinates of the ellipse centroid and A, B and C are the polynomial coefficients from the ellipse equation $Ax^2 + Bxy + Cy^2 = 1$ .

salientregions.helpers.binary_mask2ellipse_features_single(binary_mask, connectivity=4, saliency_type=1, min_square=False)¶

Conversion of a single saliency type of binary regions to ellipse features.

Parameters:

binary_mask (2-D numpy array) – Binary mask of the detected salient regions of the given saliency type
connectivity (int) – Neighborhood connectivity
saliency_type (int) – Type of salient regions. The code is: 1: holes 2: islands 3: indentations 4: protrusions
min_square (bool, optional) – whether to use minimum sqrt fitting for ellipses (default is bounded rotated rectangle fitting)

Returns:

num_regions (int) – The number of saleint regions of saliency_type
features_standard (numpy array) – array with standard ellipse features for each of the ellipses for a given saliency type
features_poly (numpy array) – array with polynomial ellipse features for each of the ellipses for a given saliency type

Notes

Every row in the resulting feature_standard array corresponds to a single region/ellipse and is of format: x0 y0 a b angle saliency_type , where (x0,y0) are the coordinates of the ellipse centroid and a, b and ``angle``(in degrees) are the standard parameters from the ellipse equation: math:(x+cos(angle) + y+sin(angle))^2/a^2 + (x*sin(angle) - y*cos(angle))^2/b^2 = 1

Every row in the resulting feature_poly array corresponds to a single region/ellipse and is of format: x0 y0 A B C saliency_type , where (x0,y0) are the coordinates of the ellipse centroid and A, B and C are the polynomial coefficients from the ellipse equation $Ax^2 + Bxy + Cy^2 = 1$ .

salientregions.helpers.image_diff(img1, img2, visualize=True)¶

Compares two images and shows the difference. Useful for testing purposes.

Parameters:	img1 (numpy array) – first image to compare img2 (numpy array) – second image to compare visualize (bool, optional) – option for visualizing the process
Returns:	is_same – True if all pixels of the two images are equal
Return type:	bool

salientregions.helpers.load_ellipse_features_from_file(filename)¶

Load elipse features (polynomial or standard) from, file.

Parameters:	filename (str) – the filename where to load the features from
Returns:	total_num_regions (int) – the total number of salient regions of saliency types num_regions (dict) – The number of saleint regions for each saliency type features (dict) – dictionary with ellipse features for each of the ellipses

Notes

see save_ellipse_features2file

salientregions.helpers.poly2standard_ellipse(A, B, C)¶

Conversion of elliptic polynomial coefficients to standard parameters.

Parameters:	B, C (A,) – The coefficients of the polynomial equation of an ellipse $Ax^2 + Bxy + Cy^2 = 1$
Returns:	half_major_axis (float) – Half of the length of the ellipse’s major axis half_minor_axis (float) – Half of the length of the ellipse’s minor axis theta (float) – The ellipse orientation angle (radians) between the major and the x axis Note WARNING: The conversion might be correct only if the resulting angle is between 0 and pi/2!

salientregions.helpers.read_matfile(filename, visualize=True)¶

Read a matfile with the binary masks for the salient regions. Returns the masks with 0/255 values for the 4 salient types

Parameters:

filename (str) – Path to the mat file
visualize (bool, optional) – option for visualizing the process

Returns:

holes (numpy array) – Binary image with holes as foreground
islands (numpy array) – Binary image with islands as foreground
protrusions (numpy array) – Binary image with protrusions as foreground
indentations (numpy array) – Binary image with indentations as foreground

salientregions.helpers.save_ellipse_features2file(num_regions, features, filename)¶

Saving the ellipse features (polynomial or standard) to file.

Parameters:	num_regions (dict) – The number of saleint regions for each saliency type features (dict) – dictionary with ellipse features for each of the ellipses filename (str) – the filename where to save the features
Returns:	total_num_regions – the total number of salient regions of saliency types
Return type:	int

Notes

see load_ellipse_features_from_file

salientregions.helpers.show_image(img, title=None)¶

Display the image. When a key is pressed, the window is closed

Parameters:	img (numpy array) – image title (str, optional) – Title of the image

salientregions.helpers.standard2poly_ellipse(half_major_axis, half_minor_axis, theta)¶

Conversion of elliptic parameters to polynomial coefficients.

Parameters:	half_major_axis (float) – Half of the length of the ellipse’s major axis half_minor_axis (float) – Half of the length of the ellipse’s minor axis theta (float) – The ellipse orientation angle (radians) between the major and the x axis
Returns:	A, B, C – The coefficients of the polynomial equation of an ellipse $Ax^2 + Bxy + Cy^2 = 1$
Return type:	floats

salientregions.helpers.visualize_elements(img, regions=None, holes=None, islands=None, indentations=None, protrusions=None, visualize=True, title='salient regions')¶

Display the image with the salient regions provided.

Parameters:	img (numpy array) – image regions (dict) – dictionary with the regions to show holes (numpy array) – Binary mask of the holes, to display in blue islands (numpy array) – Binary mask of the islands, to display in yellow indentations (numpy array) – Binary mask of the indentations, to display in green protrusions (numpy array) – Binary mask of the protrusions, to display in red visualize (bool, optional) – visualizations flag display_name (str, optional) – name of the window
Returns:	img_to_show – image with the colored regions
Return type:	numpy array

salientregions.helpers.visualize_elements_ellipses(img, features, visualize=True, title='salient regions')¶

Display the image with the salient regions provided.

Parameters:	img (numpy array) – image features (dict) – dictionary with the ellipse features of the regions to show visualize (bool, optional) – visualizations flag display_name (str, optional) – name of the window
Returns:	img_to_show – image with the colored regions
Return type:	numpy array

salientregions.helpers.visualize_ellipses(img, features, color=(0, 0, 255), visualize=True)¶

Visualise ellipses in an image

Parameters:	regions (img) – image to show the ellipses on features (numpy array) – standard ellipse features for each of the ellipses color (tuple of ints, optional) – color to show the ellipses visualize (bool, optional) – visualizations flag
Returns:	img_to_show – image with the colored ellipses
Return type:	numpy array

Module contents¶

The initialization module for the salient regions package.