UnifiedAAMCLMFitter¶
-
class
menpofit.unified_aam_clm.
UnifiedAAMCLMFitter
(unified_aam_clm, algorithm_cls=<class 'menpofit.unified_aam_clm.algorithm.AlternatingRegularisedLandmarkMeanShift'>, n_shape=None, n_appearance=None, sampling=None)[source]¶ Bases:
MultiScaleParametricFitter
Class defining a Unified AAM - CLM fitter.
Note
When using a method with a parametric shape model, the first step is to reconstruct the initial shape using the shape model. The generated reconstructed shape is then used as initialisation for the iterative optimisation. This step takes place at each scale and it is not considered as an iteration, thus it is not counted for the provided max_iters.
- Parameters
unified_aam_clm (
UnifiedAAMCLM
or subclass) – The trained unified AAM-CLM model.algorithm_cls (class, optional) –
The unified optimisation algorithm that will get applied. The possible algorithms are:
Class
Method
Project-Out IC + RLMS
Alternating IC + RLMS
n_shape (int or float or list of those or
None
, optional) – The number of shape components that will be used. If int, then it defines the exact number of active components. If float, then it defines the percentage of variance to keep. If int or float, then the provided value will be applied for all scales. If list, then it defines a value per scale. IfNone
, then all the available components will be used. Note that this simply sets the active components without trimming the unused ones. Also, the available components may have already been trimmed to max_shape_components during training.n_appearance (int or float or list of those or
None
, optional) – The number of appearance components that will be used. If int, then it defines the exact number of active components. If float, then it defines the percentage of variance to keep. If int or float, then the provided value will be applied for all scales. If list, then it defines a value per scale. IfNone
, then all the available components will be used. Note that this simply sets the active components without trimming the unused ones. Also, the available components may have already been trimmed to max_appearance_components during training.sampling (list of int or ndarray or
None
) – It defines a sampling mask per scale. If int, then it defines the sub-sampling step of the sampling mask. If ndarray, then it explicitly defines the sampling mask. IfNone
, then no sub-sampling is applied.
-
appearance_reconstructions
(appearance_parameters, n_iters_per_scale)[source]¶ Method that generates the appearance reconstructions given a set of appearance parameters. This is to be combined with a
UnifiedAAMCLMResult
object, in order to generate the appearance reconstructions of a fitting procedure.- Parameters
appearance_parameters (list of
(n_params,)
ndarray) – A set of appearance parameters per fitting iteration. It can be retrieved as a property of anUnifiedAAMCLMResult
object.n_iters_per_scale (list of int) – The number of iterations per scale. This is necessary in order to figure out which appearance parameters correspond to the model of each scale. It can be retrieved as a property of a
UnifiedAAMCLMResult
object.
- Returns
appearance_reconstructions (list of menpo.image.Image) – List of the appearance reconstructions that correspond to the provided parameters.
-
fit_from_bb
(image, bounding_box, max_iters=20, gt_shape=None, return_costs=False, **kwargs)¶ Fits the multi-scale fitter to an image given an initial bounding box.
- Parameters
image (menpo.image.Image or subclass) – The image to be fitted.
bounding_box (menpo.shape.PointDirectedGraph) – The initial bounding box from which the fitting procedure will start. Note that the bounding box is used in order to align the model’s reference shape.
max_iters (int or list of int, optional) – The maximum number of iterations. If int, then it specifies the maximum number of iterations over all scales. If list of int, then specifies the maximum number of iterations per scale.
gt_shape (menpo.shape.PointCloud, optional) – The ground truth shape associated to the image.
return_costs (bool, optional) – If
True
, then the cost function values will be computed during the fitting procedure. Then these cost values will be assigned to the returned fitting_result. Note that the costs computation increases the computational cost of the fitting. The additional computation cost depends on the fitting method. Only use this option for research purposes.kwargs (dict, optional) – Additional keyword arguments that can be passed to specific implementations.
- Returns
fitting_result (
MultiScaleNonParametricIterativeResult
or subclass) – The multi-scale fitting result containing the result of the fitting procedure.
-
fit_from_shape
(image, initial_shape, max_iters=20, gt_shape=None, return_costs=False, **kwargs)¶ Fits the multi-scale fitter to an image given an initial shape.
- Parameters
image (menpo.image.Image or subclass) – The image to be fitted.
initial_shape (menpo.shape.PointCloud) – The initial shape estimate from which the fitting procedure will start.
max_iters (int or list of int, optional) – The maximum number of iterations. If int, then it specifies the maximum number of iterations over all scales. If list of int, then specifies the maximum number of iterations per scale.
gt_shape (menpo.shape.PointCloud, optional) – The ground truth shape associated to the image.
return_costs (bool, optional) – If
True
, then the cost function values will be computed during the fitting procedure. Then these cost values will be assigned to the returned fitting_result. Note that the costs computation increases the computational cost of the fitting. The additional computation cost depends on the fitting method. Only use this option for research purposes.kwargs (dict, optional) – Additional keyword arguments that can be passed to specific implementations.
- Returns
fitting_result (
MultiScaleNonParametricIterativeResult
or subclass) – The multi-scale fitting result containing the result of the fitting procedure.
-
warped_images
(image, shapes)[source]¶ Given an input test image and a list of shapes, it warps the image into the shapes. This is useful for generating the warped images of a fitting procedure stored within an
UnifiedAAMCLMResult
.- Parameters
image (menpo.image.Image or subclass) – The input image to be warped.
shapes (list of menpo.shape.PointCloud) – The list of shapes in which the image will be warped. The shapes are obtained during the iterations of a fitting procedure.
- Returns
warped_images (list of menpo.image.MaskedImage or ndarray) – The warped images.
-
property
holistic_features
¶ The features that are extracted from the input image at each scale in ascending order, i.e. from lowest to highest scale.
- Type
list of closure
-
property
n_scales
¶ Returns the number of scales.
- Type
int
-
property
reference_shape
¶ The reference shape that is used to normalise the size of an input image so that the scale of its initial fitting shape matches the scale of this reference shape.
- Type
menpo.shape.PointCloud
-
property
response_covariance
¶ Returns the covariance value of the desired Gaussian response used to train the ensemble of experts.
- Type
int
-
property
scales
¶ The scale value of each scale in ascending order, i.e. from lowest to highest scale.
- Type
list of int or float
-
property
unified_aam_clm
¶ The trained unified AAM-CLM model.
- Type
UnifiedAAMCLM
or subclass