superdsm.dsm

class superdsm.dsm.CP(energy, params0, scale=1, cachesize=0, cachetest=None, timeout=None)

Bases: object

Represents the convex problem of minimizing a convex energy function \(\psi\).

Parameters:

  • energy – The convex energy function to be minimized, so that energy(p) corresponds to the value of \(\psi(p)\), energy.grad(p) corresponds to the gradient vector \(\nabla\psi(p)\), and energy.hessian(p) corresponds to the Hessian matrix \(\nabla^2 \psi(p)\).

  • params0 – Parameters vector used for initialization.

  • scale – Fixed factor used to slightly improve numerical stabilities.

  • cachesize – The maximum number of entries used for caching the values of the energy function, the gradient, and the Hessian.

  • cachetest – The test function to be used for cache testing. If None, then numpy.array_equal will be used.

  • timeout – The maximum run time of the solve() method (in seconds). Convex programming will be interrupted by raising a TimeoutError if it takes longer than that. If this is set to None, the run time is not limited.

CHECK_NUMBERS = False

Performs additional assertions when set to True which are useful for debugging but might increase the overall run time (sparse matrices need to be converted to dense).

solve(**options)

Performs convex programming.

Parameters:

options – Currently not used.

class superdsm.dsm.DeformableShapeModel(*args)

Bases: object

Represents a deformable shape model, defined by a set of fixed parameters.

Each deformable shape model is defined by the polynomial parameters \(\theta\) and the deformation parameters \(\xi\) (see details). The polynomial parameters define the polynomial surface \(f_x^\top \theta\), where \(f_x\) is a second-order polynomial basis function expansion of the image point \(x\),

\[f_x = (x_1^2, x_2^2, 2 x_1 x_2, x_1, x_2, 1).\]

Using \(\theta = (a_1, a_2, a_3, b_1, b_2, c)\) the polynomial surface can be written

\[f_x^\top \theta = x_1^2 a_1 + x_2^2 a_2 + 2 x_1 x_2 a_3 + x_1 b_1 + x_2 b_2 + c,\]

or equivalently,

\[f_x^\top \theta = x^\top A x + b^\top x + c,\]

where

\[\begin{split}A = \begin{bmatrix} a_1 & a_3 \\ a_3 & a_2 \end{bmatrix}, \qquad b = \begin{bmatrix} b_1 \\ b_2 \end{bmatrix}.\end{split}\]
Variables:

  • array – The vector of polynomial and deformation parameters of this model.

  • a – The vector \(\theta_{1:3} = (a_1, a_2, a_3)\) corresponding to this model.

  • b – The vector \(\theta_{4:5} = b = (b_1, b_2)\) corresponding to this model.

  • c – The parameter \(\theta_{6} = c\) of this model.

  • ξ – The deformation parameters \(\xi\) of this model.

property A

Returns the matrix \(A\) corresponding to this model.

copy()

Returns a deep copy.

static create_ellipse(ξ, center, halfaxis1_len, halfaxis2_len, U=None)

Creates a deformable shape model corresponding to an ellipse, possibly deformbed.

Parameters:

  • ξ – The deformation parameters.

  • center – The coordinates of the center of the ellipse.

  • halfaxis1_len – The length of the first half axis.

  • halfaxis2_len – The length of the second half axis.

  • U – An orthonormal matrix whose eigenvectors define the rotation of the ellipse, or None if a random rotation should be used.

static get_model(params)

Returns a DeformableShapeModel object.

If params is a DeformableShapeModel object, then params is returned. Otherwise, the a new DeformableShapeModel object is instantiated using the given parameters.

map_to_image_pixels(g, roi, pad=0)

Transforms the model from the coordinate system of an image region into the coordinate system of the whole image.

Parameters:

  • g – An Image object corresponding to the whole image.

  • roi – An Image object corresponding to the image region.

  • pad – The number of pixels by which the coordinate system of the whole image is padded (once in each direction, i.e. twice along each axis). Using a value larger than 0 yields the same result as using an image g padded by the same value.

Returns:

The transformed deformable shape model.

s(x, smooth_mat)

Computes the deformable surface \(S_\omega(\theta, \xi)\) as described in Deformable shape models.

Parameters:

x – Either a list of coordinates of those image points for which the values of the deformable surface are to be computed, or a stack of two 2D arrays corresponding to the pixel coordinates.

class superdsm.dsm.Energy(roi, epsilon, alpha, smooth_matrix_factory, sparsity_tol=0, hessian_sparsity_tol=0)

Bases: object

Represents the convex energy function \(\psi\) for deformable shape models.

Instances of this class can be used as functions (e.g., energy(params) computes the value \(\psi_\omega(\theta, \xi)\) of the convex energy function \(\psi\) so that params[:6] corresponds to the polynomial parameters \(\theta\) and params[6:] corresponds to the deformation parameters \(\xi\)).

Parameters:

  • roi – An image region represented by an instance of the Image class.

  • epsilon – Corresponds to the constant \(\epsilon\) which is used for the smooth approximation of the regularization term \(\|\xi\|_1 \approx \mathbb 1^\top_\Omega \sqrt{\xi^2 + \epsilon} - \sqrt{\epsilon} \cdot \#\Omega\) (see Supplemental Material 2 of Kostrykin and Rohr, TPAMI 2023).

  • alpha – Governs the regularization of the deformations and corresponds to \(\alpha\) described in Convex energy minimization. Increasing this value leads to a smoother segmentation result.

  • smooth_matrix_factory – An object with a get method which yields the matrix \(\tilde G_\omega\) for any image region \(\omega\) (represented as a binary mask and passed as a parameter).

  • sparsity_tol – Absolute values below this threshold will be treated as zeros for computation of the gradient.

  • hessian_sparsity_tol – Absolute values below this threshold will be treated as zeros for computation of the Hessian.

grad(params)

Computes the gradient vector \(\nabla \psi_\omega(\theta, \xi)\).

The parameters are represented by params so that params[:6] corresponds to the polynomial parameters \(\theta\) and params[6:] corresponds to the deformation parameters \(\xi\).

hessian(params)

Computes the Hessian matrix \(\nabla^2 \psi_\omega(\theta, \xi)\).

The parameters are represented by params so that params[:6] corresponds to the polynomial parameters \(\theta\) and params[6:] corresponds to the deformation parameters \(\xi\). The Hessian matrix is returned as a sparse block matrix.

class superdsm.dsm.SmoothMatrixFactory(smooth_amount, shape_multiplier, smooth_subsample, lock=None, dtype='float32')

Bases: object

Instantiates the matrix \(\tilde G_\omega\) for any image region \(\omega\).

The matrix \(\tilde G_\omega\) is the sub-sampled variant of the \(G_\omega\) matrix.

Parameters:

  • smooth_amount – This is \(\sigma_G\) described in Deformable shape models.

  • shape_multiplier – The Gaussian function with standard deviation \(\sigma_G\) used to construct the block Toeplitz matrix \(G_\omega\) is cut off after \(4 \sigma_G\) multiplied by this value (see Deformable shape models).

  • smooth_subsample – Corresponds to the amount of sub-sampling used (see Section 3.3 in Kostrykin and Rohr, TPAMI 2023).

  • lock – A critical section lock used for allocation of the matrix.

  • dtype – The data type used for the matrix.

NULL_FACTORY = <superdsm.dsm.SmoothMatrixFactory object>
get(mask, uplift=False)

Yields the matrix \(\tilde G_\omega\) for an image region \(\omega\).

Parameters:

  • mask – The image region \(\omega\) represented as a binary mask.

  • uplift – Currently not used.

exception superdsm.dsm.TimeoutError

Bases: Exception

Indicates that an operation has timed out.