facemorpher package

Submodules

facemorpher.aligner module

Align face and image sizes

facemorpher.aligner.positive_cap(num)

Cap a number to ensure positivity

Parameters:num – positive or negative number Returns:(overflow, capped_number)

facemorpher.aligner.resize_align(img, points, size)

Resize image and associated points, align face to the center

and crop to the desired size

Parameters:

• img – image to be resized
• points – m x 2 array of points
• size – (height, width) tuple of new desired size

facemorpher.aligner.resize_image(img, scale)

Resize image with the provided scaling factor

Parameters:

• img – image to be resized
• scale – scaling factor for resizing the image

facemorpher.aligner.roi_coordinates(rect, size, scale)

Align the rectangle into the center and return the top-left coordinates within the new size. If rect is smaller, we add borders.

Parameters:

• rect – (x, y, w, h) bounding rectangle of the face
• size – (width, height) are the desired dimensions
• scale – scaling factor of the rectangle to be resized

Returns:

4 numbers. Top-left coordinates of the aligned ROI. (x, y, border_x, border_y). All values are > 0.

facemorpher.aligner.scaling_factor(rect, size)

Calculate the scaling factor for the current image to be

resized to the new dimensions

Parameters:

• rect – (x, y, w, h) bounding rectangle of the face
• size – (width, height) are the desired dimensions

Returns:

floating point scaling factor

facemorpher.averager module

Face averager

Usage:
  averager.py --images=<images_folder> [--blur] [--plot]
            [--background=(black|transparent|average)]
            [--width=<width>] [--height=<height>]
            [--out=<filename>] [--destimg=<filename>]

Options:
  -h, --help             Show this screen.
  --images=<folder>      Folder to images (.jpg, .jpeg, .png)
  --blur                 Flag to blur edges of image [default: False]
  --width=<width>        Custom width of the images/video [default: 500]
  --height=<height>      Custom height of the images/video [default: 600]
  --out=<filename>       Filename to save the average face [default: result.png]
  --destimg=<filename>   Destination face image to overlay average face
  --plot                 Flag to display the average face [default: False]
  --background=<bg>      Background of image to be one of (black|transparent|average) [default: black]
  --version              Show version.

facemorpher.averager.averager(imgpaths, dest_filename=None, width=500, height=600, background='black', blur_edges=False, out_filename='result.png', plot=False)

facemorpher.averager.list_imgpaths(imgfolder)

facemorpher.averager.load_image_points(path, size)

facemorpher.averager.main()

facemorpher.averager.sharpen(img)

facemorpher.blender module

facemorpher.blender.alpha_feathering(src_img, dest_img, img_mask, blur_radius=15)

facemorpher.blender.apply_mask(img, mask)

Apply mask to supplied image :param img: max 3 channel image :param mask: [0-255] values in mask :returns: new image with mask applied

facemorpher.blender.mask_from_points(size, points)

Create a mask of supplied size from supplied points :param size: tuple of output mask size :param points: array of [x, y] points :returns: mask of values 0 and 255 where

255 indicates the convex hull containing the points

facemorpher.blender.overlay_image(foreground_image, mask, background_image)

Overlay foreground image onto the background given a mask :param foreground_image: foreground image points :param mask: [0-255] values in mask :param background_image: background image points :returns: image with foreground where mask > 0 overlaid on background image

facemorpher.blender.poisson_blend(img_source, dest_img, img_mask, offset=(0, 0))

facemorpher.blender.weighted_average(img1, img2, percent=0.5)

facemorpher.locator module

Locate face points

facemorpher.locator.average_points(point_set)

Averages a set of face points from images

Parameters:point_set – n x m x 2 array of face points.

n = number of images. m = number of face points per image

facemorpher.locator.boundary_points(points)

Produce additional boundary points

Parameters:points – m x 2 np array of x,y points Returns:2 additional points at the top corners

facemorpher.locator.face_points(img, add_boundary_points=True)

Locates 77 face points using stasm (http://www.milbo.users.sonic.net/stasm)

Parameters:

• img – an image array
• add_boundary_points – bool to add 2 additional points

Returns:

Array of x,y face points. Empty array if no face found

facemorpher.locator.weighted_average_points(start_points, end_points, percent=0.5)

Weighted average of two sets of supplied points

Parameters:

• start_points – m x 2 array of start face points.
• end_points – m x 2 array of end face points.
• percent – [0, 1] percentage weight on start_points

Returns:

m x 2 array of weighted average points

facemorpher.morpher module

Morph from source to destination face or
Morph through all images in a folder

Usage:
  morpher.py (--src=<src_path> --dest=<dest_path> | --images=<folder>)
            [--width=<width>] [--height=<height>]
            [--num=<num_frames>] [--fps=<frames_per_second>]
            [--out_frames=<folder>] [--out_video=<filename>]
            [--plot] [--background=(black|transparent|average)]

Options:
  -h, --help              Show this screen.
  --src=<src_imgpath>     Filepath to source image (.jpg, .jpeg, .png)
  --dest=<dest_imgpath>   Filepath to destination image (.jpg, .jpeg, .png)
  --images=<folder>       Folderpath to images
  --width=<width>         Custom width of the images/video [default: 500]
  --height=<height>       Custom height of the images/video [default: 600]
  --num=<num_frames>      Number of morph frames [default: 20]
  --fps=<fps>             Number frames per second for the video [default: 10]
  --out_frames=<folder>   Folder path to save all image frames
  --out_video=<filename>  Filename to save a video
  --plot                  Flag to plot images [default: False]
  --background=<bg>       Background of images to be one of (black|transparent|average) [default: black]
  --version               Show version.

facemorpher.morpher.list_imgpaths(images_folder=None, src_image=None, dest_image=None)

facemorpher.morpher.load_image_points(path, size)

facemorpher.morpher.load_valid_image_points(imgpaths, size)

facemorpher.morpher.main()

facemorpher.morpher.morph(src_img, src_points, dest_img, dest_points, video, width=500, height=600, num_frames=20, fps=10, out_frames=None, out_video=None, plot=False, background='black')

Create a morph sequence from source to destination image

Parameters:

• src_img – ndarray source image
• src_points – source image array of x,y face points
• dest_img – ndarray destination image
• dest_points – destination image array of x,y face points
• video – facemorpher.videoer.Video object

facemorpher.morpher.morpher(imgpaths, width=500, height=600, num_frames=20, fps=10, out_frames=None, out_video=None, plot=False, background='black')

Create a morph sequence from multiple images in imgpaths

Parameters:imgpaths – array or generator of image paths

facemorpher.morpher.verify_args(args)

facemorpher.plotter module

Plot and save images

class facemorpher.plotter.Plotter(plot=True, rows=0, cols=0, num_images=0, out_folder=None, out_filename=None)

Bases: object

plot_mesh(*args, **kwargs)

plot_one(*args, **kwargs)

save(*args, **kwargs)

set_filepath(folder)

show(*args, **kwargs)

facemorpher.plotter.bgr2rgb(img)

facemorpher.plotter.check_do_plot(func)

facemorpher.plotter.check_do_save(func)

facemorpher.videoer module

Create a video with image frames

class facemorpher.videoer.Video(filename, fps, w, h)

Bases: object

end(*args, **kwargs)

write(*args, **kwargs)

facemorpher.videoer.check_write_video(func)

facemorpher.warper module

facemorpher.warper.bilinear_interpolate(img, coords)

Interpolates over every image channel http://en.wikipedia.org/wiki/Bilinear_interpolation

Parameters:

• img – max 3 channel image
• coords – 2 x _m_ array. 1st row = xcoords, 2nd row = ycoords

Returns:

array of interpolated pixels with same shape as coords

facemorpher.warper.grid_coordinates(points)

x,y grid coordinates within the ROI of supplied points

Parameters:points – points to generate grid coordinates Returns:array of (x, y) coordinates

facemorpher.warper.process_warp(src_img, result_img, tri_affines, dst_points, delaunay)

Warp each triangle from the src_image only within the ROI of the destination image (points in dst_points).

facemorpher.warper.test_local()

facemorpher.warper.triangular_affine_matrices(vertices, src_points, dest_points)

Calculate the affine transformation matrix for each triangle (x,y) vertex from dest_points to src_points

Parameters:

• vertices – array of triplet indices to corners of triangle
• src_points – array of [x, y] points to landmarks for source image
• dest_points – array of [x, y] points to landmarks for destination image

Returns:

2 x 3 affine matrix transformation for a triangle

facemorpher.warper.warp_image(src_img, src_points, dest_points, dest_shape, dtype=<class 'numpy.uint8'>)

Module contents

Face Morpher module init code

facemorpher.list_imgpaths(images_folder=None, src_image=None, dest_image=None)

facemorpher.morpher(imgpaths, width=500, height=600, num_frames=20, fps=10, out_frames=None, out_video=None, plot=False, background='black')

Create a morph sequence from multiple images in imgpaths

Parameters:imgpaths – array or generator of image paths

facemorpher.averager(imgpaths, dest_filename=None, width=500, height=600, background='black', blur_edges=False, out_filename='result.png', plot=False)