salientregions package

Submodules

salientregions.binarization module

class salientregions.binarization.Binarizer

Bases: object

binarize(img, visualize=True)
class salientregions.binarization.DatadrivenBinarizer(area_factor_large=0.001, area_factor_verylarge=0.1, lam=-1, SE_size_factor=0.15, weights=(0.33, 0.33, 0.33), offset=80, num_levels=256, connectivity=4)

Bases: salientregions.binarization.Binarizer

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

Parameters:
  • 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
  • lam (float, optional) – lambda, minimumm area of a connected component
  • 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
  • num_levels (int, optional) – number of gray levels to be considered [1..255], the default number 256 gives a stepsize of 1.
  • connectivity (int) – What connectivity to use to define CCs
  • visualize (bool, optional) – option for vizualizing the process
binarize(img, visualize=True)
binarize_withthreshold(img, visualize=True)
class salientregions.binarization.OtsuBinarizer

Bases: salientregions.binarization.Binarizer

Binarizes the image with the Otsu method.

binarize(img, visualize=True)
class salientregions.binarization.ThresholdBinarizer(threshold=127)

Bases: salientregions.binarization.Binarizer

binarize(img, visualize=True)

salientregions.binarydetector module

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

Bases: object

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

Detect hole-like salient regions, using the image and its filled version

Parameters:
  • img (2-dimensional numpy array with values 0/255) – image to detect holes
  • filled (2-dimensional numpy array with values 0/255, optional) – precomputed filled image
Returns:

  • filled (2-dimensional numpy array with values 0/255) – The filled image
  • holes (2-dimensional numpy array with values 0/255) – Image with all holes as foreground.
detect_protrusionlike(img, filled, holes)

Detect ‘protrusion’-like salient regions

Parameters:
  • img (2-dimensional numpy array with values 0/255) – image to detect holes
  • filled (2-dimensional numpy array with values 0/255, optional) – precomputed filled image
  • holes (2-dimensional numpy array with values 0/255) – The earlier detected holes
  • visualize (bool, optional) – option for vizualizing the process
Returns:

  • filled (2-dimensional numpy array with values 0/255) – The filled image
  • protrusions (2-dimensional numpy array with values 0/255) – Image with all protrusions as foreground.
static fill_image(img)

Fills all holes in connected components in the image.

Parameters:img (2-dimensional numpy array with values 0/255) – image to fill
Returns:filled – The filled image
Return type:2-dimensional numpy array with values 0/255
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’

remove_small_elements(elements, connectivity=None, remove_border_elements=True, visualize=False)

Remove elements (Connected Components) that are smaller then a given threshold

Parameters:
  • img (2-dimensional numpy array with values 0/255) – binary image with elements
  • lam (float, optional) – lambda, minimumm area of a salient region
  • remove_border_elements (bool, optional) – Also remove elements that are attached to the border
  • visualize (bool, optional) – option for vizualizing the process
Returns:

result – Image with all elements larger then lam
Return type:

2-dimensional numpy array with values 0/255
reset()

salientregions.detectors module

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
  • 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, find_holes=True, find_islands=True, find_indentations=True, find_protrusions=True, visualize=True)
This method should be implemented to return a
dictionary with the salientregions.
Calling this function from the superclass makes sure the
structuring elemnt and lamda are created.
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 (2-dimensional numpy array of shape (k,k)) – The structuring element to use in processing the 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

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 (2-dimensional numpy array with values between 0 and 255) – grayscale 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 vizualizing the process
Returns:

  • dictionary with the following possible items
  • holes (2-dimensional numpy array with values 0/255) – Image with all holes as foreground.
  • islands (2-dimensional numpy array with values 0/255) – Image with all islands as foreground.
  • indentations (2-dimensional numpy array with values 0/255) – Image with all indentations as foreground.
  • protrusions (2-dimensional numpy array with values 0/255) – Image with all protrusions as foreground.
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:2-dimensional 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
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 (2-dimensional numpy array with values between 0 and 255) – grayscale 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 vizualizing the process
Returns:

  • dictionary with the following possible items
  • holes (2-dimensional numpy array with values 0/255) – Image with all holes as foreground.
  • islands (2-dimensional numpy array with values 0/255) – Image with all islands as foreground.
  • indentations (2-dimensional numpy array with values 0/255) – Image with all indentations as foreground.
  • protrusions (2-dimensional numpy array with values 0/255) – Image with all protrusions as foreground.

salientregions.helpers module

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(binary_mask, connectivity=4, saliency_type=1)

Conversion 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: indentaitons 4: protrusions
Returns:

  • num_regions (int) – The number of saleint regions of saliency_type
  • features (2-D numpy array with he equivalnet ellipse features) – Every row corresponds to a single region/ellipse ans 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 (2-dimensional numpy array with values 0/255) – first image to compare
  • img1 – second image to compare
  • visualize (bool, optional) – option for vizualizing the process
Returns:

is_same – True if all pixels of the two images are equal
Return type:

bool
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 vizualizing the process
Returns:

  • holes (2-dimensional numpy array with values 0/255) – Binary image with holes as foreground
  • islands (2-dimensional numpy array with values 0/255) – Binary image with islands as foreground
  • protrusions (2-dimensional numpy array with values 0/255) – Binary image with protrusions as foreground
  • indentations (2-dimensional numpy array with values 0/255) – Binary image with indentations as foreground
salientregions.helpers.region2ellipse(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.show_image(img, window_name='image')

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

Parameters:
  • img (multidimensional numpy array)) – image
  • window_name (str, optional) – name of the window
salientregions.helpers.visualize_elements(img, holes=None, islands=None, indentations=None, protrusions=None, visualize=True, display_name='salient regions')

Display the image with the salient regions provided.

Parameters:
  • img (multidimensional numpy array) – image
  • holes (2-dimensional numpy array with values 0/255, optional) – The holes, to display in blue
  • islands (2-dimensional numpy array with values 0/255, optional) – The islands, to display in yellow
  • indentations (2-dimensional numpy array with values 0/255, optional) – The indentations, to display in green
  • protrusions (2-dimensional numpy array with values 0/255, optional) – The protrusions, to display in red
  • visualize (bool, optional) – vizualizations flag
  • display_name (str, optional) – name of the window
Returns:

img_to_show – image with the colored regions
Return type:

3-dimensional numpy array

Module contents