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)\), andenergy.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
, thennumpy.array_equal
will be used.timeout – The maximum run time of the
solve()
method (in seconds). Convex programming will be interrupted by raising aTimeoutError
if it takes longer than that. If this is set toNone
, 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 aDeformableShapeModel
object, thenparams
is returned. Otherwise, the a newDeformableShapeModel
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 thatparams[:6]
corresponds to the polynomial parameters \(\theta\) andparams[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 thatparams[:6]
corresponds to the polynomial parameters \(\theta\) andparams[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 thatparams[:6]
corresponds to the polynomial parameters \(\theta\) andparams[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.