morphace 1.0.0

Generate a face-morphing video from two face images

Morphace

Generate a face-morphing video from two face images.

Morphace detects facial landmarks, aligns two faces, blends between them, and exports the result as an MP4 video.

Features

• Generate smooth MP4 face-morphing videos from two face images.
• Align and crop portraits before morphing for better results.
• Batch-process folders of images with automatic face detection.
• Customize video length, frame rate, and output location.

Video Example

Table of Contents

• Requirements
• Quick Start
• How It Works
• Morphace CLI
  • download
  • prep
  • morph
• Tips for Best Results
• License

Requirements

Morphace requires:

• Python 3.13 or newer.
• FFmpeg installed and available on your system PATH.

The required Python packages are installed automatically when you install Morphace.

You can verify that FFmpeg is available by running:

ffmpeg -version

Face landmark model

Morphace also requires a face landmark model file to detect and align faces. The model is not bundled with Morphace, so download it once after installing:

morphace download

By default, the command saves the model in Morphace's application data directory. The prep and morph commands look there automatically.

Use --landmark-model with morphace prep or morphace morph only if you want to use a model file saved somewhere else.

Quick Start

1. Install the Morphace package with pip:

   pip install morphace
   

2. Download the required face landmark model.

   morphace download
   

3. Create a morph video:

   morphace morph first_image.png second_image.png
   

4. Open the generated video file morph.mp4.

How It Works

Morphace detects landmarks in both images, aligns the faces to a shared shape, warps each frame between the two faces, blends the image content, and encodes the result as an MP4 video.

At a high level, Morphace:

1. Detects a face in each source image.
2. Finds facial landmarks such as the eyes, nose, mouth, and face outline.
3. Aligns both faces to a shared shape.
4. Warps and blends the images frame by frame.
5. Encodes the generated frames into an MP4 video.

For a more detailed explanation of the landmark detection, triangle mesh, and frame interpolation process, refer to How It Works on the Morphace documentation site.

Morphace CLI

The morphace command provides three subcommands:

Command	Purpose
morphace download	Downloads Morphace's required model file.
morphace prep	Prepares aligned square PNG face crops from raw images.
morphace morph	Generates an MP4 face-morphing video from two source images.

Each of these commands is explained briefly below. For full details, refer to CLI Reference on the Morphace documentation site.

download

The download command installs the model file described in Requirements.

morphace download

By default, the model is saved in Morphace's application data directory, where morphace prep and morphace morph can find it automatically. You usually only need to run this command once after installing Morphace.

To save the model somewhere else, use --save-to:

morphace download --save-to ./model

If a model file already exists, Morphace will not overwrite it unless you pass --force:

morphace download --force

Use --debug to show more detailed logging if the download fails.

For full details, refer to download CLI Reference on the Morphace documentation site.

prep

Use morphace prep to turn raw portraits into aligned square PNG face crops before creating a morph.

This step is optional, but recommended when your source images are framed differently. For example, a close-up portrait and a full-body photo may both contain detectable faces, but the morph will usually look better if both faces are aligned and cropped first.

morphace prep images/raw images/aligned

The prep command can process either a single image file or a directory of images. When processing a directory, Morphace scans the immediate child files with these extensions: .jpg, .jpeg, .png, .bmp, .tiff, and .webp.

For each detected face, Morphace writes one aligned PNG file. Output files are named with the original file stem and face number, such as:

portrait_face01.png
portrait_face02.png

By default, aligned crops are saved as 1024x1024 PNG images.

Examples

Prepare a directory of images:

morphace prep \
  images/raw \
  images/aligned

Prepare a single image and save the output beside the original file:

morphace prep images/raw/portrait.jpg

Prepare tighter or wider crops around the detected face:

morphace prep \
  images/raw \
  images/aligned \
  --x-scale 1.2 \
  --y-scale 1.3

After preparing your images, choose two aligned PNG files and pass them to morphace morph:

morphace morph \
  images/aligned/person1_face01.png \
  images/aligned/person2_face01.png

Common options

• --output-size sets the square crop size in pixels. The default is 1024.
• --x-scale controls how much horizontal context is included around the face.
• --y-scale controls how much vertical context is included around the face.
• --em-scale shifts the crop center from the eyes toward the mouth.
• --alpha uses transparent padding instead of reflected padding.
• --force overwrites existing prepared images.
• --landmark-model uses a custom model path instead of the default download location.

For full details, refer to prep CLI Reference on the Morphace documentation site.

morph

Use morphace morph to generate an MP4 video that smoothly transitions from one face image to another.

morphace morph images/first.png images/second.png

By default, Morphace writes the result to morph.mp4, creates a 5-second video, and renders it at 30 frames per second.

The frame count is based on the selected duration and frame rate. With the defaults, --duration 5 and --fps 30, Morphace generates 150 frames. The first frame matches the first image, the last frame matches the second image, and the frames between them move through evenly spaced steps.

For best results, use images where the faces are similarly framed. If your source images have different crops, angles, or face sizes, run them through morphace prep first.

Examples

Create a morph video with the default settings:

morphace morph \
  images/first.png \
  images/second.png

Choose the output file:

morphace morph \
  images/first.png \
  images/second.png \
  --output output/friends_morph.mp4

Create a longer, smoother morph:

morphace morph \
  images/first.png \
  images/second.png \
  --duration 8 \
  --fps 60

Show the triangle mesh used for the face warp:

morphace morph \
  images/first.png \
  images/second.png \
  --show-mesh

Common options

• --output sets the MP4 output path. The default is morph.mp4.
• --duration sets the video length in seconds. The default is 5.
• --fps sets the output frame rate. The default is 30.
• --show-mesh draws the face-warping mesh over the generated video.
• --force overwrites an existing output video.
• --landmark-model uses a custom model path instead of the default download location.
• --show-ffmpeg-output shows FFmpeg encoder output instead of only errors.

For full details, refer to morph CLI Reference on the Morphace documentation site.

Tips for Best Results

• Use front-facing portraits when possible.
• Choose images with similar lighting and head angle.
• Run morphace prep first if the faces are different sizes or crops.
• Use --show-mesh to inspect how the face geometry is being warped.

License

The code in this project is licensed under the MIT license. See LICENSE.txt for details.