superdsm.objects

class superdsm.objects.BaseObject

Bases: object

Each object of this class represents a segmentation mask, consisting of a foreground fragment and an offset.

The attributes fg_offset and fg_fragment are initialized with None, indicating that they have not been computed yet.

fill_foreground(out, value=True)

Reproduces the segmentation mask of this object.

The foreground fragment is written into the image out, which must be an object of numpy.ndarray type. Image points corresponding to the segmentation mask will be set to value.

The method requires that fg_offset and fg_fragment have been computed before (see the compute_objects() function).

Returns:

The slice corresponding to the altered region of out.

>>> import superdsm.objects
>>> import numpy as np
>>> obj = superdsm.objects.BaseObject()
>>> obj.fg_fragment = np.array([[False,  True],
...                             [ True,  True],
...                             [ True, False]])
>>> obj.fg_offset = (1, 2)
>>> mask = np.zeros((4, 5), bool)
>>> obj.fill_foreground(mask)
(slice(1, 4, None), slice(2, 4, None))
>>> mask
array([[False, False, False, False, False],
       [False, False, False,  True, False],
       [False, False,  True,  True, False],
       [False, False,  True, False, False]])

This method is the counterpart of the extract_foreground_fragment() function.

exception superdsm.objects.CvxprogError(*args, cidx=None, cause=None)

Bases: Exception

class superdsm.objects.Object

Bases: BaseObject

Each object of this class represents a set of atomic image regions.

Each object corresponds to a realization of the set \(X\) in Kostrykin and Rohr (TPAMI 2023, Section 3). It also represents a segmented object after it has been passed to the compute_objects() function.

Variables:

  • footprint – Set of integer labels that identify the atomic image regions, which the object represents.

  • energy – The value of the set energy function \(\nu(X)\) (see Joint segmentation and cluster splitting).

  • on_boundary – True if this object intersects the image boundary.

  • is_optimal – True if optimization of energy was successful.

  • processing_time – How long the computation of the attributes took (in seconds).

The attributes energy, on_boundary, is_optimal, processing_time are initialized with nan, which indicates that the values have not been computed yet, i.e. the object was not passed to the compute_objects() function yet.

Possible reasons for is_optimal being False include the rare cases of numerical issues during optimization as well as regions of the size of a single pixel.

copy()

Returns a deep copy of this object.

get_cvxprog_region(y, atoms, background_margin)

Returns the image region used for convex programming.

Parameters:

  • y – Object of Image class, corresponding to the offset image intensities.

  • atoms – Integer-valued image representing the universe of atomic image regions (each atomic image region has a unique label, which is the integer value).

  • background_margin – Governs the amount of image background included in the obtained image region. This is the width of the “stripe” of background retained around each connected foreground region (in pixels, intersected with the image region determined by the get_mask() method).

Returns:

Image region corresponds to \(\tilde\omega'(X)\) in Kostrykin and Rohr (TPAMI 2023) see Supplemental Material 6), where each object of this class is a realization of the set \(X\) (see Kostrykin and Rohr, TPAMI 2023, Section 3). The image region is represented by an object of Image type.

>>> import superdsm.objects
>>> import superdsm.image
>>> import numpy as np
>>> y_data = np.array([[-1, -1, -1, -1, -1],
...                    [-1, -1, -1, -1, -1],
...                    [-1, -1, -1, -1, -1],
...                    [-1, +1, -1, -1, -1],
...                    [-1, +1, -1, -1, +1],
...                    [-1, +1, -1, -1, +1]])
>>> atoms  = np.array([[ 1,  1,  1,  1,  1],
...                    [ 1,  1,  1,  1,  1],
...                    [ 1,  1,  1,  1,  2],
...                    [ 1,  1,  1,  2,  2],
...                    [ 1,  1,  1,  2,  2],
...                    [ 1,  1,  1,  2,  2]])
>>> obj = superdsm.objects.Object()
>>> obj.footprint = set([1])
>>> y = superdsm.image.Image(y_data)
>>> region = obj.get_cvxprog_region(y, atoms, background_margin=2)
>>> region.mask
array([[False, False, False, False, False],
       [False,  True, False, False, False],
       [ True,  True,  True, False, False],
       [ True,  True,  True, False, False],
       [ True,  True,  True, False, False],
       [ True,  True,  True, False, False]])
get_mask(atoms)

Returns binary image corresponding to the union of the represented set of atomic image regions.

Parameters:

atoms – Integer-valued image representing the universe of atomic image regions (each atomic image region has a unique label, which is the integer value).

Returns:

Binary image corresponding to \(\tilde\omega(X) = \bigcup X\) in the paper, where each object of this class is a realization of the set \(X\) (see Kostrykin and Rohr, TPAMI 2023, Section 3).

>>> import superdsm.objects
>>> import numpy as np
>>> atoms = np.array([[1, 1, 2],
...                   [1, 3, 2],
...                   [3, 3, 3]])
>>> obj = superdsm.objects.Object()
>>> obj.footprint = set([2, 3])
>>> obj.get_mask(atoms)
array([[False, False,  True],
       [False,  True,  True],
       [ True,  True,  True]])
set(state)

Adopts the state of another object.

superdsm.objects.compute_objects(objects, y, atoms, dsm_cfg, log_root_dir, status_line=('Computing objects', 'Computed objects'), out=None)

Computes the attributes of a list of objects.

The computation concerns the attributes energy, on_boundary, is_optimal, processing_time, fg_fragment, fg_offset of the objects.

Parameters:

  • objects – List of objects for which the above mentioned attributes are to be computed.

  • y – An Image object corresponding to the offset image intensities.

  • atoms – Integer-valued image representing the universe of atomic image regions (each atomic image region has a unique label, which is the integer value).

  • dsm_cfg – Dictionary of hyperparameters defined in the DSM_Config stage (without the leading dsm/ namespace prefix).

  • log_root_dir – Path of directory where log files will be written, or None if no log files should be written.

  • status_line – Tuple (s1, s2), where s1 is the line of text to be written while objects are being computed, and s2 is the line of text to be written when finished.

  • out – An instance of an Output sub-class, 'muted' if no output should be produced, or None if the default output should be used.

superdsm.objects.cvxprog(region, scale, epsilon, alpha, smooth_amount, smooth_subsample, gaussian_shape_multiplier, smooth_mat_allocation_lock, smooth_mat_dtype, sparsity_tol=0, hessian_sparsity_tol=0, init=None, cachesize=0, cachetest=None, cp_timeout=None)

Fits a deformable shape model to the intensities of an image region.

Performs convex programming in an image region \(X\) to determine the value of the set energy function \(\nu(X)\) and the optimal parameters \(\theta\) and \(\xi\) (see Convex energy minimization and Joint segmentation and cluster splitting).

Parameters:

  • region – An Image object corresponding to the image region \(X\).

  • smooth_mat_allocation_lock – A critical section lock used for allocation of the matrix \(\tilde G_\omega\).

The other parameters correspond to the hyperparameters defined in the DSM_Config stage (without the leading dsm/ namespace prefix).

Returns:

A tuple with the following components:

  • The value of the set energy function \(\nu(X)\).

  • An instance of the DeformableShapeModel class which represents the optimal parameters \(\theta\) and \(\xi\).

  • A status indicator string, where optimal indicats that convex programming was successful and fallback indicates that convex programming failed for the deformable shape model and the initialization is used instead.

superdsm.objects.extract_foreground_fragment(fg_mask)

Returns the minimal-size rectangle region of image foreground and the corresponding offset.

>>> import superdsm.objects
>>> import numpy as np
>>> mask = np.array([[False, False, False, False, False],
...                  [False, False, False,  True, False],
...                  [False, False,  True,  True, False],
...                  [False, False,  True, False, False]])
>>> offset, fragment = superdsm.objects.extract_foreground_fragment(mask)
>>> offset
array([1, 2])
>>> fragment
array([[False,  True],
       [ True,  True],
       [ True, False]])

This function is the counterpart of the fill_foreground() method.