SupervisedDescentAAMFitter

class menpofit.aam.SupervisedDescentAAMFitter(images, aam, group=None, bounding_box_group_glob=None, n_shape=None, n_appearance=None, sampling=None, sd_algorithm_cls=<class 'menpofit.aam.algorithm.sd.ProjectOutNewton'>, n_iterations=6, n_perturbations=30, perturb_from_gt_bounding_box=<function noisy_shape_from_bounding_box>, batch_size=None, verbose=False)[source]

Bases: SupervisedDescentFitter

Class for training a multi-scale cascaded-regression Supervised Descent AAM fitter.

Parameters
  • images (list of menpo.image.Image) – The list of training images.

  • aam (AAM or subclass) – The trained AAM model.

  • group (str or None, optional) – The landmark group that will be used to train the fitter. If None and the images only have a single landmark group, then that is the one that will be used. Note that all the training images need to have the specified landmark group.

  • bounding_box_group_glob (glob or None, optional) – Glob that defines the bounding boxes to be used for training. If None, then the bounding boxes of the ground truth shapes are used.

  • 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. If None, 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. If None, 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. If None, then no sub-sampling is applied.

  • sd_algorithm_cls (class, optional) –

    The Supervised Descent algorithm to be used. The possible algorithms are:

    Class

    Features

    Regression

    MeanTemplateNewton

    Mean Template

    IRLRegression

    MeanTemplateGaussNewton

    IIRLRegression

    ProjectOutNewton

    Project-Out

    IRLRegression

    ProjectOutGaussNewton

    IIRLRegression

    AppearanceWeightsNewton

    App. Weights

    IRLRegression

    AppearanceWeightsGaussNewton

    IIRLRegression

  • n_iterations (int or list of int, optional) – The number of iterations (cascades) of each level. If list, it must specify a value per scale. If int, then it defines the total number of iterations (cascades) over all scales.

  • n_perturbations (int or None, optional) – The number of perturbations to be generated from the provided bounding boxes.

  • perturb_from_gt_bounding_box (callable, optional) – The function that will be used to generate the perturbations.

  • batch_size (int or None, optional) – If an int is provided, then the training is performed in an incremental fashion on image batches of size equal to the provided value. If None, then the training is performed directly on the all the images.

  • verbose (bool, optional) – If True, then the progress of training will be printed.

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.

increment(images, group=None, bounding_box_group_glob=None, verbose=False, batch_size=None)

Method to increment the trained SDM with a new set of training images.

Parameters
  • images (list of menpo.image.Image) – The list of training images.

  • group (str or None, optional) – The landmark group that corresponds to the ground truth shape of each image. If None and the images only have a single landmark group, then that is the one that will be used. Note that all the training images need to have the specified landmark group.

  • bounding_box_group_glob (glob or None, optional) – Glob that defines the bounding boxes to be used for training. If None, then the bounding boxes of the ground truth shapes are used.

  • verbose (bool, optional) – If True, then the progress of training will be printed.

  • batch_size (int or None, optional) – If an int is provided, then the training is performed in an incremental fashion on image batches of size equal to the provided value. If None, then the training is performed directly on the all the images.

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 a MultiScaleParametricIterativeResult.

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 scales

The scale value of each scale in ascending order, i.e. from lowest to highest scale.

Type

list of int or float