Basic Example

To illustrate the simplest use case let us assume that we start with a photo with a single face in it.

Original image

pychubby implements a class LandmarkFace which stores all relevant data that enable face warping. Namely it is the image itself and 68 landmark points. To instantiate a LandmarkFace one needs to use a utility class method estimate.

import matplotlib.pyplot as plt
from pychubby.detect import LandmarkFace

img = plt.imread("path/to/the/image")
lf = LandmarkFace.estimate(img)
lf.plot()
Face with landmarks

Note that it might be necessary to upsample the image before the estimation. For convenience the estimate method has an optional parameter n_upsamples.

Once the landmark points are estimated we can move on with performing actions on the face. Let’s try to make the person smile:

from pychubby.actions import Smile

a = Smile(scale=0.2)
new_lf, df = a.perform(lf)  # lf defined above
new_lf.plot(show_landmarks=False)
Smiling face

There are 2 important things to note. Firstly the new_lf now contains both the warped version of the original image as well as the transformed landmark points. Secondly, the perform method also returns a df which is an instance of pychubby.base.DisplacementField and represents the pixel by pixel transformation between the old and the new (smiling) image.

To see all currently available actions go to Gallery.

To create an animation of the action we can use the visualize module.

from pychubby.visualize import create_animation

ani = create_animation(df, img) # the displacement field and the original image
https://i.imgur.com/jB6Vlnc.gif