ATM

class menpofit.atm.base.ATM(template, shapes, group=None, holistic_features=<function no_op>, reference_shape=None, diagonal=None, scales=(0.5, 1.0), transform=<class 'menpofit.transform.piecewiseaffine.DifferentiablePiecewiseAffine'>, shape_model_cls=<class 'menpofit.modelinstance.OrthoPDM'>, max_shape_components=None, verbose=False, batch_size=None)[source]

Bases: object

Class for training a multi-scale holistic Active Template Model.

Parameters
  • template (menpo.image.Image) – The template image.

  • shapes (list of menpo.shape.PointCloud) – The list of training shapes.

  • group (str or None, optional) – The landmark group of the template that will be used to train the ATM. If None and the template only has a single landmark group, then that is the one that will be used.

  • holistic_features (closure or list of closure, optional) – The features that will be extracted from the training images. Note that the features are extracted before warping the images to the reference shape. If list, then it must define a feature function per scale. Please refer to menpo.feature for a list of potential features.

  • reference_shape (menpo.shape.PointCloud or None, optional) – The reference shape that will be used for building the ATM. The purpose of the reference shape is to normalise the size of the training images. The normalization is performed by rescaling all the training images so that the scale of their ground truth shapes matches the scale of the reference shape. Note that the reference shape is rescaled with respect to the diagonal before performing the normalisation. If None, then the mean shape will be used.

  • diagonal (int or None, optional) – This parameter is used to rescale the reference shape so that the diagonal of its bounding box matches the provided value. In other words, this parameter controls the size of the model at the highest scale. If None, then the reference shape does not get rescaled.

  • scales (float or tuple of float, optional) – The scale value of each scale. They must provided in ascending order, i.e. from lowest to highest scale. If float, then a single scale is assumed.

  • transform (subclass of DL and DX, optional) – A differential warp transform object, e.g. DifferentiablePiecewiseAffine or DifferentiableThinPlateSplines.

  • shape_model_cls (subclass of PDM, optional) – The class to be used for building the shape model. The most common choice is OrthoPDM.

  • max_shape_components (int, float, list of those or None, optional) – The number of shape components to keep. If int, then it sets the exact number of components. If float, then it defines the variance percentage that will be kept. If list, then it should define a value per scale. If a single number, then this will be applied to all scales. If None, then all the components are kept. Note that the unused components will be permanently trimmed.

  • verbose (bool, optional) – If True, then the progress of building the ATM 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.

References

1

S. Baker, and I. Matthews. “Lucas-Kanade 20 years on: A unifying framework”, International Journal of Computer Vision, 56(3): 221-255, 2004.

build_fitter_interfaces(sampling)[source]

Method that builds the correct Lucas-Kanade fitting interface.

Parameters

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.

Returns

fitter_interfaces (list) – The list of Lucas-Kanade interface per scale.

increment(template, shapes, group=None, shape_forgetting_factor=1.0, verbose=False, batch_size=None)[source]

Method to increment the trained ATM with a new set of training shapes and a new template.

Parameters
  • template (menpo.image.Image) – The template image.

  • shapes (list of menpo.shape.PointCloud) – The list of training shapes.

  • group (str or None, optional) – The landmark group of the template that will be used to train the ATM. If None and the template only has a single landmark group, then that is the one that will be used.

  • shape_forgetting_factor ([0.0, 1.0] float, optional) – Forgetting factor that weights the relative contribution of new samples vs old samples for the shape model. If 1.0, all samples are weighted equally and, hence, the result is the exact same as performing batch PCA on the concatenated list of old and new simples. If <1.0, more emphasis is put on the new samples.

  • verbose (bool, optional) – If True, then the progress of building the ATM 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.

instance(shape_weights=None, scale_index=- 1)[source]

Generates a novel ATM instance given a set of shape weights. If no weights are provided, the mean ATM instance is returned.

Parameters
  • shape_weights ((n_weights,) ndarray or list or None, optional) – The weights of the shape model that will be used to create a novel shape instance. If None, the weights are assumed to be zero, thus the mean shape is used.

  • scale_index (int, optional) – The scale to be used.

Returns

image (menpo.image.Image) – The ATM instance.

random_instance(scale_index=- 1)[source]

Generates a random instance of the ATM.

Parameters

scale_index (int, optional) – The scale to be used.

Returns

image (menpo.image.Image) – The ATM instance.

property n_scales

Returns the number of scales.

Type

int