PickleWrappedFitter

class menpofit.io.PickleWrappedFitter(fitter_cls, fitter_args, fitter_kwargs, fit_from_bb_kwargs, fit_from_shape_kwargs, image_preprocess=<function image_greyscale_crop_preprocess>)

Bases: object

Wrapper around a menpofit fitter so that we can a) efficiently pickle it and b) parametrize over both the fitter construction and the fit methods (e.g. .fit_from_bb() and .fit_from_shape())

Pickling menpofit fitters is a little tricky for a two reasons. Firstly, on construction of a fitter from a deformable model some amount of pre-processing takes place which allocates potentially large arrays. To ship a compact model we would therefore rather delay the construction of the fitter until load time on the client.

If this was the only issue, we could achieve this by simply saving a partial over the fitter constructor with all the args and kwargs the fitter constructor takes - after loading the pickle, invoking the partial with no args (it’s parameters being fully specified) would return the fitter and all would be well.

However, we also may want to choose fit-time parameters for the fitter for optimal usage, (for instance, a choice over the max_iters kwarg that we know to be efficient). This leaves us with a problem, as now we need to have some entity that can store state which we can pass to both the fitter and to the resulting fitters methods on the client at unpickle time.

This class is the solution to this problem. To use, you should pickle down a partial over this class specifying all arguments and kwargs needed for the fitter constructor and for the fit methods.

At load time, menpofit will invoke the partial, returning this object instantiated. This offers the same API as a menpofit fitter, and so can be used transparently to fit. If you wish to access the original fitter (without fit parameter customization) this can be accessed as the wrapped_fitter property.

Parameters

• fitter_cls (Fitter) – A menpofit fitter class that will be constructed at unpickle time, e.g. LucasKanadeAAMFitter

• fitter_args (tuple) – A tuple of all args that need to be passed to fitter_cls at construction time e.g. (aam,)

• fitter_kwargs (dict) – A dictionary of kwargs that will to be passed to fitter_cls at construction time e.g. { 'lk_algorithm_cls': WibergInverseCompositional }

• fit_from_bb_kwargs (dict, e.g. { max_iters: [25, 5] }) – A dictionary of kwargs that will to be passed to the wrapped fitter’s fit_from_bb method at fit time. These in effect change the defaults that the original fitter offered, but can still be overridden at call time (e.g. self.fit_from_bb(image, bbox, max_iters=[50, 50]) would take precedence over the max_iters in the above example)

• fit_from_shape_kwargs (dict, e.g. { max_iters: [25, 5] }) – A dictionary of kwargs that will to be passed to the wrapped fitter’s fit_from_shape method at fit time. These in effect change the defaults that the original fitter offered, but can still be overridden at call time (e.g. self.fit_from_shape(image, shape, max_iters=[50, 50]) would take precedence over the max_iters in the above example)

• image_preprocess (callable or None, optional) –

  A pre-processing function to apply on the test image before fitting. The default option converts the image to greyscale. The function needs to have the following signature:

  new_image, transform = image_preprocess(image, pointcloud)
  

  where new_image is the pre-processed image and transform is the menpo.transform.Homogeneous object that was applied on the image. If None, then no pre-processing is performed.

Examples

from menpofit.io import PickleWrappedFitter, image_greyscale_crop_preprocess
from functools import partial

# LucasKanadeAAMFitter only takes one argument, a trained aam.
fitter_args = (aam, )

# kwargs for fitter construction. Note that here sampling is a
# list of numpy arrays we have already constructed (one per level)
fitter_kwargs = dict(lk_algorithm_cls=WibergInverseCompositional,
                     sampling=sampling)

# kwargs for fitter.fit_from_{bb, shape}
# (note here we reuse the same kwargs twice)
fit_kwargs = dict(max_iters=[25, 5])

# Partial over the PickleWrappedFitter to prepare an object that can be
# invoked at load time
fitter_wrapper = partial(PickleWrappedFitter, LucasKanadeAAMFitter,
                         fitter_args, fitter_kwargs,
                         fit_kwargs, fit_kwargs,
                         image_preprocess=image_greyscale_crop_preprocess)

# save the pickle down.
mio.export_pickle(fitter_wrapper, 'pretrained_aam.pkl')

# ----------------------- L O A D  T I M E ---------------------------#

# at load time, invoke the partial to instantiate this class (and build
# the internally-held wrapped fitter)
fitter = mio.import_pickle('pretrained_aam.pkl')()

fit_from_bb(image, bounding_box, **kwargs)

Fits the fitter to an image given an initial bounding box, using the optimal parameters that we chosen for this pickled fitter.

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.

• kwargs (dict, optional) – Other kwargs to override the optimal defaults. See the documentation for .fit_from_bb() on the type of self.wrapped_fitter to see what can be provided here.

Returns

fitting_result (FittingResult or subclass) – The fitting result containing the result of the fitting procedure.

fit_from_shape(image, initial_shape, **kwargs)

Fits the fitter to an image given an initial shape, using the optimal parameters that we chosen for this pickled fitter.

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.

• kwargs (dict) – Other kwargs to override the optimal defaults. See the documentation for .fit_from_shape() on the type of self.wrapped_fitter to see what can be provided here.

Returns

fitting_result (FittingResult or subclass) – The fitting result containing the result of the fitting procedure.