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
andfg_fragment
are initialized withNone
, 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 ofnumpy.ndarray
type. Image points corresponding to the segmentation mask will be set tovalue
.The method requires that
fg_offset
andfg_fragment
have been computed before (see thecompute_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.
- 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 ofenergy
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 withnan
, which indicates that the values have not been computed yet, i.e. the object was not passed to thecompute_objects()
function yet.Possible reasons for
is_optimal
beingFalse
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 leadingdsm/
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)
, wheres1
is the line of text to be written while objects are being computed, ands2
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, orNone
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 leadingdsm/
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 andfallback
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.