facemorph 0.1.0

Face morphing and alignment package using MediaPipe and OpenCV

Face Morphing

Smooth, fast, and robust, facemorph is a simple face morphing package that creates smooth transitions between faces. It uses Delaunay triangulation and piecewise affine warping. Optional face alignment ensures more natural results.

• Landmarks: MediaPipe
• Warping: OpenCV
• Triangulation: SciPy
• Math: NumPy

Install

pip install facemorph

Or from this repo:

git clone https://github.com/Robys01/Face-Morphing.git
cd Face-Morphing
pip install -e .

Requirements

• Python 3.9 - 3.12
• Works on Linux / macOS / Windows
• Key dependencies: mediapipe, opencv-python, scipy, numpy

CLI Usage

Morph all images from a folder:

facemorph --input-dir images_dir

If --output is not provided, FaceMorph auto-generates a name like: output_24.02.2026_02.22.17_20fps.mp4

Skip alignment:

facemorph --input-dir images_dir --no-align

Use parallel workers for speed:

facemorph --input-dir images_dir --workers 4

Other options:

• --duration 3.0: Seconds per transition
• --fps 30: Video frame rate
• --output output.mp4: Custom output file
• --aligned-dir aligned_images: Directory for aligned images
• --output-size 1024: Video resolution (aligned only)
• --guideline: Draw triangulation lines
• --workers: Number of parallel workers (default: 1)
• --show-native-logs: Show MediaPipe logs

If an image contains multiple faces, FaceMorph automatically uses the largest detected face. Also, it skips images where it does not detect a face.

Python API

Morph Images

from facemorph import morph_folder, morph_images

# Morph a folder of images
morph_folder(
    input_dir="images_dir",
    output_path="output.mp4",
    align=True,
    workers=4,
)

# Morph specific images
paths = ["a.jpg", "b.jpg", "c.jpg"]
morph_images(paths, duration=3.0, fps=30, workers=4)

Align Faces Only

from facemorph import align_folder, align_images, align_image

# Align a folder
aligned_paths = align_folder(
    input_dir="images",
    output_dir="aligned_images",
)

# Align specific images
aligned_paths = align_images(
    image_paths=["images/1.png", "images/2.png"],
    output_dir="aligned_images_custom",
)

# Align a single image
align_image(
    source_path="images/1.png",
    destination_path="aligned_images/1_aligned.png",
)

License

This project is licensed under the MIT License. See the LICENSE file for details.