skshape.image.segmentation package

Submodules

skshape.image.segmentation.shape_energy module

Definitions of shape energies.

This module contains several shape energies that can be used to guide an iterative shape optimization algorithm for segmentation. In such an approach, initial curves (or surfaces in 3d) are placed in the image, and these are deformed iteratively to converge on the actual region boundaries in the image. The shape energy is used to guide the curves/surfaces through the optimization. When the shape energy of a curve is minimized, the optimal location in the image has been achieved.

skshape.image.segmentation.shape_energy.ChanVeseEnergy: alias of skshape.image.segmentation.shape_energy.PwConstRegionEnergy

skshape.image.segmentation.shape_energy.GeodesicActiveContourEnergy: alias of skshape.image.segmentation.shape_energy.IsotropicBoundaryEnergy

class skshape.image.segmentation.shape_energy.IsotropicBoundaryEnergy(parameters)[source]

Bases: skshape.image.segmentation.shape_energy.ShapeEnergy

The isotropic boundary energy approximates the energy of a curve or surface given by the weighted boundary integral:

$J(\Gamma) = \int_\Gamma g(x) d\Gamma,$

where $\Gamma$ is a surface or curve and $g(x)$ is a spatially-varying weight function. This class can compute the energy values, and the first and second shape derivatives.

When combined with an image-based weight function $g(x)$ , such as the edge indicator function of an image intensity function $I(x)$

$g(x) = 1 / (1 + | \nabla I(x)|^2 / \lambda^2), \lambda > 0$

this energy can be used to detect boundaries of objects in images, by fitting curves (or surfaces in 3d) to locations of high image gradient (see [Caselles1997]). This energy implements the Lagrangian approach proposed in [Dogan2017].

Parameters

parameters (dict) –

A dictionary of parameters used to initialize and setup the energy object. It has the following keys:

’weight function’, a weight function $g(x)$ that depends on the spatial coordinates $x$ , an array of shape (dim x n_coord_pts) where dim = 2,3. It should return a 1d array of scalar values of length n_coord_pts.

’basin width’, (optional) float parameter indicating the width of the minima or valleys or basins. The default value is inherited from the image interpolant function, and can be inter-pixel dist.

’adaptive integral’, (optional) boolean parameter indicating whether the integration will be adaptive or not. The default value is False, so (non-adaptive) fixed quadrature integration is used.

’integral tol’, (optional) float parameter indicating the error tolerance of adaptive integration. The default value is 1e-4.

Notes

Caselles1997: : Caselles, V.; Kimmel, R.; Sapiro, G. “Geodesic Active Contours.” International Journal of Computer Vision, 22(1), 61-79 (1997).
Dogan2017: : Dogan, G. “An Efficient Lagrangian Algorithm for an Anisotropic Geodesic Active Contour Model.” In International Conference on Scale Space and Variational Methods in Computer Vision, 408-420, Springer, Cham (2017).

basin_width()[source]

estimate_errors(surface, integral_error=None)[source]

estimate_errors_from_tol(surface)[source]

has_maximum_accuracy()[source]

is_minimized(surface, parameters={}, history=None)[source]

set_accuracy(surface, factor=None, use_shape_gradient=False)[source]

shape_gradient(surface, s=None, mask=None, coarsened=None, split=False)[source]

shape_hessian(surface, full_hessian=None, threshold=None)[source]

skshape.image.segmentation.shape_energy.MultiphaseRegionEnergy: alias of skshape.image.segmentation.shape_energy.PwConstRegionEnergy

class skshape.image.segmentation.shape_energy.PwConstRegionEnergy(parameters)[source]

Bases: skshape.image.segmentation.shape_energy.ShapeEnergy

The piecewise constant energy approximates the multiphase segmentation energy for a curve family $\Gamma = \bigcup_k \Gamma_k$ . The curves partition the image domain into regions $\{ \Omega_k \}_k$ . $\Omega_k$ is the region enclosed by the curve $\Gamma_k$ . $\Omega_0$ is the region left outside of all curves. For a given curve family $\Gamma$ , the energy is

$J(\Gamma) = \mu \int_\Gamma d\Gamma + \sum_k \int_{\Omega_k} (I(x) - c_k)^2 dx,$

where $I(x)$ is the image intensity function, and $c_k=\frac{1}{|\Omega_k|} \int_{\Omega_k} I(x) dx$ are the region averages of the image intensity function.

The default version is the energy is multiphase, i.e. each curve $\Gamma_k$ encloses a separate region as in [Dogan2015A], but it can also be set to two phases (see [Chan2001], [Dogan2015B]), then the union of the regions bounded by $\Gamma_k$ with even indices represent the background region, and those with odd indices represent the foreground region.

Parameters

parameters (dict) –

A dictionary of parameters used to initialize and setup the energy object. It has the following keys:

’image’, a NumPy array of doubles, storing the image pixels, needs to be specified if an image function is not given.

’image function’, an optional ImageFunction, which can be internally defined using the image array if not provided.

’domain averages’, (optional) an array of region averages of image intensity, they are computed automatically if not provided.

’number of phases’, (optional) 2 or ‘many’, the default value is ‘many’.

’world boundary’, (optional) a rectangle :class:Curve indicating the boundary of the image/world. The nodes should be in normalized coordinates, e.g. for a square-shaped image, the computational domain is a unit square, and the boundary of the unit square is world boundary. If not provided, it is inherited from the image.

’domain integration method’, (optional) the integration method for the domain integrals, one of the three options ‘adaptive quadrature’, ‘pixel summation’, ‘trapezoidal rule’. The default value is ‘pixel summation’.

’total integration method’, (optional) the integration method for the of the image intensity function over all the image domain., one of the three options ‘adaptive quadrature’, ‘pixel summation’, ‘trapezoidal rule’. The default value is ‘trapezoidal rule’.

’domain integral tol’, (optional) integration error tolerance value, used by adaptive quadrature in the domains

’surface integral tol’ (optional) integration error tolerance value, used by adaptive quadrature on the surfaces or curves.

’use tight initial tol’ (optional) boolean flag indicating whether to use specified integral tolerances, even at the beginning of shape optimization when accuracy of adaptive quadrature is not very important. The default value is false, initial tol is not tight, it is relaxed a higher integral tol.

Notes

Chan2001: : Chan, T.F.; Vese, L.A. “Active contours without edges.” IEEE Transactions on Image Processing 10(2), 266-277 (2001).
Dogan2015A: : Dogan, G. “An efficient curve evolution algorithm for multiphase image segmentation.” In International Workshop on Energy Minimization Methods in Computer Vision and Pattern Recognition, 292-306, Springer, Cham (2015).
Dogan2015B: : Dogan, G. “Fast minimization of region-based active contours using the shape hessian of the energy.” In International Conference on Scale Space and Variational Methods in Computer Vision, 307-319, Springer, Cham (2015).

basin_width()[source]

estimate_errors(surface, domain_error=None, surface_error=None)[source]

Estimates the error in energy and shape gradient calculations.

This functions estimates the error in the values of the energy and the L^2 norm of the shape gradient, based on the current surface and given domain and surface errors. Currently it only accounts for the domain integrals in the energy, but not the the surface area term.

Parameters

surface (Surface object) – The current surface, e.g. an instance of a CurveHierarchy etc.
domain_error (float, optional) – An average estimate of the integration error when the image is integrated over a unit volume. Its default value is None. In this case, the current internal error estimates for the domain integrals are used. If internal error estimates are not available (because domains have not been integrated yet), then the current tolerance for domain integration is used (current tolerance is not necessarily the domain tolerance specified at initialization, it may be larger).
surface_error (float, optional) – An average estimate of the integration error when the image is integrated over a unit surface area. Its default value is None. In this case, the current internal error estimate for integral of the image over the surface is used. If the internal error estimate is not available, then the current tolerance for surface integration is used (current tolerance is not necessarily the domain tolerance specified at initialization, it may be larger).

Returns

energy_error (float) – An estimate of the error in the data-dependent parts of the energy, namely the domain integrals.
gradient_error (float) – An estimate of the error in the squared L^2 norm of the shape gradient over the surface: int_surface G^2.

estimate_errors_from_tol(surface)[source]

Estimates errors in energy and shape gradient based on given tol.

This functions estimates the minimum expected error in the values of the energy and the L^2 norm of the shape gradient, based on the current surface and prescribed tolerances for domain and surface integration. Currently it only accounts for the domain integrals in the energy, but not the the surface area term.

Parameters

surface (Surface object) – The current surface, e.g. an instance of a CurveHierarchy etc.

Returns

energy_error (float) – An estimate of the minimum expected error in the data-dependent parts of the energy, namely the domain integrals.
gradient_error (float) – An estimate of the minimum expected error in the squared L^2 norm of the shape gradient over the surface.

has_maximum_accuracy()[source]

is_minimized(surface, parameters={}, history=None)[source]

set_accuracy(surface, factor=None)[source]

shape_gradient(surface, s=None, mask=None, coarsened=None, split=False, new_mu=None, FEM='scalar')[source]

shape_hessian(surface, full_hessian=None, threshold=None)[source]

class skshape.image.segmentation.shape_energy.ShapeEnergy[source]

Bases: object

Parent class inherited by all the ShapeEnergy child classes. It includes default implementations of the some of the shared methods, such as :meth:’skshape.image.segmentation.shape_energy.ShapeEnergy.shape_gradient_norm’, :meth:’skshape.image.segmentation.shape_energy.ShapeEnergy.shape_derivative’, :meth:’skshape.image.segmentation.shape_energy.ShapeEnergy.shape_is_minimized’.

basin_width()[source]

is_minimized(surface, parameters={}, history=None)[source]

shape_derivative(surface, velocity)[source]

shape_gradient(surface)[source]

shape_gradient_norm(surface, function_space='L2')[source]

shape_hessian(surface)[source]

skshape.image.segmentation.shape_optimization module

Optimization of curve/surface dependent shape energies.

This module contains shape optimization functions to compute optimal shapes with respect to a specified shape energy. Typically, an initial curve or curve family is specified, and the curves are iteratively moved/deformed in a manner gradually decreasing their shape energy. This process concludes with optimal curves with minimum shape energy.

skshape.image.segmentation.shape_optimization.optimize(energy, surface, world_boundary=None, parameters=None, keep_history=True)[source]

skshape.image.segmentation.topology_optimization module

Labeling pixels into separate groups/regions by topology optimization.

This module includes functions to compute topological derivatives of region-regularized statistical label energies, and to minimize these energies iteratively to assign optimal region labels to image pixels. Using this approach, an image can be segmented, and a label image showing the distinct regions in the image can be obtained.

skshape.image.segmentation.topology_optimization.optimize(image, n_phases, model, mu, sigma, init_method, gamma, epsilon)[source]

Label image pixels into separate regions by topology optimization.

This functions segments an image by topology optimization of a statistical label energy. The goal is to label each image pixel with a region label, hence identify the regions of the image. The iterative topology optimization procedure first initializes the label array using init_method, then computes topological derivative matrix and switches labels iteratively until topological derivative is nonegative, and meets termination criterion.

Parameters

image (NumPy ndarray) – Array of image values.
n_phases (int) – Number of regions.
model (string) – One of ‘pwconst’, ‘Laplace’, ‘Gaussian’.
mu (int) – Parameter mu for regularization.
sigma (int) – Parameter sigma for distance computation.
init_method (str) – Choose an initilization method from ‘zero’, ‘rand’, ‘chk’, ‘grid’.
gamma (int) –
epsilon (int) – Parameter epsilon for stopping criteria.

Returns

label (NumPy ndarray) – Final array of region labels.
new_image (NumPy array) – New image formed by coloring with region averages within each region.

Module contents

skshape.image.segmentation.segment_boundaries(image, initial_curves, method='multiphase', parameters={'mu': 0.001, 'domain integral tol': 0.01, 'surface integral tol': 0.01, 'min beta': 0.01, 'use full hessian': True}, {'minimum iterations': 0, 'maximum iterations': 1000, 'absolute tolerance': 0.001, 'relative tolerance': 0.001, 'descent direction': 'L2', True, 'step size parameters': None, 'verbose': False})[source]

This function segments a given image starting with given initial curves.

This function takes an image and a given set of initial curves, performs shape optimization on the surfaces based on a specified shape energy, thus performs image segmentation and returns the final set of surfaces delineating the region or object boundaries.

Parameters

image (NumPy array or ImageFunction object) – A NumPy array storing the image pixel values, or an image function that returns the values of the image at the points given by a Numpy coordinate array size 2 x n_pts. The image function can be an instance of class :class:skshape.numerics.function.ImageFunction.
initial_curves (CurveHierarchy object) – An instance of a CurveHierarchy that specify the collection of initial curves to initialize the curve evolution to compute the segmentation boundaries.
method (str, optional) – One of ‘multiphase’ (or ‘piecewise-constant’), ‘two-phase’ (or ‘Chan-Vese’), ‘GAC’ (or ‘Geodesic-Active-Contours’). Default value is ‘multiphase’.
parameters (tuple of dict, optional) – A pair of parameter dictionaries: (energy parameters, optimization parameters) Examples are in :data:skshape.image.segmentation.shape_energy.default_energy_parameters and :data:image.segmentation.shape_optim.default_parameters.

Returns

final_curves – The initial curves are evolved by performing shape optimization and returned as final curves.

Return type

CurveHierarchy object

skshape.image.segmentation.segment_by_topology(image, n_phases, model='Laplace', mu=30, sigma=6, init_method='zero', gamma=0.5, epsilon=0)[source]

Label image pixels into separate regions by topology optimization.

This functions segments an image by topology optimization of a statistical label energy. The goal is to label each image pixel with a region label, hence identify the regions of the image. The iterative topology optimization procedure first initializes the label array using init_method, then computes topological derivative matrix and switches labels iteratively until topological derivative is nonegative, and meets termination criterion.

Parameters

image (NumPy ndarray) – Array of image values.
n_phases (int) – Number of regions.
model (str, optional) – The statistical distribution of pixel values assumed within each region. It can be one of three values: ‘pwconst’, ‘Laplace’, ‘Gaussian’. Default value is ‘Laplace’.
mu (float, optional) – Parameter mu for weight of nonlocal region regularization. Default value is 30.
sigma (int, optional) – Parameter sigma for distance computation (in terms of number of pixels). Default value is 6.
init_method (str, optional) – Choose an initilization method from ‘zero’, ‘rand’, ‘chk’, ‘grid’, namely, zero or random or checkerboard or grid initialization. Default value is ‘zero’.
gamma (float, optional) – Parameter gamma for stopping criterion. Default value is 0.5.
epsilon (float, optional) – Parameter epsilon for stopping criteria. Default value is 0.

Returns

labels (NumPy ndarray) – Final array of region labels.
new_image (NumPy array) – New image formed by coloring with region averages within each region.

skshape.image.segmentation.segment_phase_field(image, u0=None, data_weight=500, s=0.85, a=0.0, eps=None, step_size=None, max_iter=1000, termination_tol=0.1, verbose=False)[source]

Segment image to foreground/background using phase field representation.

This function uses the fractional phase field equation to segment the given image into foreground objects and a background region.

Parameters

image (NumPy ndarray) – A 2d gray-scale image array or the name of an image file.
u0 (NumPy array or str or tuple, optional) – An initialization array for the phase field functions, or an initialization pattern ‘rand’, ‘sine’, ‘cosine’, ‘checkerboard’, ‘circles’ or a cell record indicating the pattern and the number of repetitions in x,y dirs, e.g. (‘sine’,(4,6)), (‘circles’,(5,3)). The default value is None, it results in ‘sine’ pattern with (8,8) repetitions.
data_weight (float, optional) – The weight of the data fidelity term. Default value is 500.
s (float, optional) – The fractional exponent of the Laplacian, a value in (0.5,1.0]. Default value is 0.85.
a (float, optional) – The fractional exponent in the (H^-1)^a gradient descent term, a value in [0.0,1.0]. Default value is 0.0.
epsilon (float, optional) – The order parameter for the phase field transition width. Default value is None, so that it is automatically assigned based on grid spacing.
step_size (float, optional) – The step size for the phase field evolution. Default value is None.
max_iter (int, optional) – Maximum number of iterations for the phase field evolution. Default value os 1000.
termination_tol (float, optional) –
Stopping tolerance on the norm of the change between the Fourier coefficients of the phase field U:

norm( U2_tilde - U1_tilde ) < TOL

Default value is 0.1.
verbose (bool, optional) – True (default) or False, to print additional information at each iteration. Default value is False.

Returns

segmentation – A boolean array storing the binary mask to represent the segmentation.

Return type

NumPy array