1. Fitter Objects
menpofit has specialised classes for performing a fitting process that are called
Fitter objects are subclasses of one of the following:
MultiScaleNonParametricFitter: multi-scale non-parametric fitting method, i.e. a method that does not optimise over a parametric shape model but directly optimizes the coordinates of the landmarks
MultiScaleParametricFitter: multi-scale parametric fitting method, i.e. a method that optimises over the parameters of a statistical shape model
The behaviour of
Fitter classes can differ depending on the deformable model.
For example, a Lucas-Kanade AAM fitter (
LucasKanadeAAMFitter) assumes that you have trained an AAM model
aam we trained in the Training section) and can be created as:
from menpofit.aam import LucasKanadeAAMFitter, WibergInverseCompositional fitter = LucasKanadeAAMFitter(aam, lk_algorithm_cls=WibergInverseCompositional, n_shape=[3, 20], n_appearance=[30, 150])
The constructor of the
Fitter will set the active shape and appearance components based on
and will also perform all the necessary pre-computations based on the selected algorithm.
However, there are deformable models that are directly defined through a
which is responsible for training the model.
SupervisedDescentFitter is a good example.
The reason for that is that the fitting process is utilised during the building procedure,
thus the functionality of a
Fitter is required. Such models can be trained as:
from menpofit.sdm import SupervisedDescentFitter, NonParametricNewton fitter = SupervisedDescentFitter(training_images, sd_algorithm_cls=NonParametricNewton, verbose=True)
Information about any
Fitter object can be retrieved as:
2. Fitting Methods
All the deformable models that are currently implemented in
which are the state-of-the-art approaches in current literature,
aim to find a local optimum of the cost function that they try to optimise, given an initialization.
The initialization can be seen as an initial estimation of the target shape.
Fitter objects provide two functions for fitting a model to an image:
result = fitter.fit_from_shape(image, initial_shape, max_iters=20, gt_shape=None, return_costs=False, **kwargs)
result = fitter.fit_from_bb(image, bounding_box, max_iters=20, gt_shape=None, return_costs=False, **kwargs)
They only differ on the type of initialization.
fit_from_shape expects a
PointCloud as the
On the other hand, the
bounding_box argument of
fit_from_bb is a
PointDirectedGraph of 4 vertices that
represents the initial bounding box. The bounding box is used in order to align the model's reference shape and
use the resulting
PointCloud as the initial shape. Such a bounding box can be retrieved using the detection methods
menpodetect. The rest of the options are:
Defines the maximum number of iterations. If
int, then it specifies the maximum number of iterations over all scales.
int, then it specifies the maximum number of iterations per scale.
Note that this does not apply on all deformable models.
For example, it can control the number of iterations of a Lucas-Kanade optimization algorithm,
but it does not affect the fitting of a cascaded-regression method (e.g. SDM) which has a predefined number of cascades (iterations).
The ground truth shape associated to the image. This is only useful to compute the final fitting error. It is not used, of course, at any internal stage of the optimisation.
True, then the cost function values will be computed during the fitting procedure.
Then these cost values will be assigned to the returned
Note that the costs computation increases the computational cost of the fitting.
The additional computation cost depends on the fitting method.
Thus, this option should only be used for research purposes.
Finally, this argument does not apply to all deformable models.
Additional keyword arguments that can be passed to specific models.