WarpFaces — Help

Overview

WarpFaces is a face morphing and normalization tool. It warps a source face image so that its facial landmark positions align to a target template shape. This is used for:

Normalizing face images to a canonical shape for research or recognition pipelines
Creating caricatures by exaggerating an individual's deviations from a mean face
Exploring artistic face morphs between different face shapes

File Formats

Landmark file (.vrt)

A plain-text file listing facial landmark positions for one face image:

Line 1: header — any text, ending with two integers for the output resolution (width height). Use -1 -1 to match the source image size.
Lines 2+: one x y pixel coordinate per line, one line per landmark.

All landmarks must use the same coordinate space (the pixel dimensions of the image they were annotated from).

Tessellation file (.tri)

Defines how landmarks are connected into triangles for linear warping:

One line per triangle: three zero-based vertex indices separated by spaces.
After all triangles, the keyword groups marks the end of the triangle list.

The tessellation must be built for the same landmark set (same count and ordering) as the VRT files you are using.

Image formats

JPEG (.jpg, .jpeg) and BMP (.bmp) are supported.

Core Workflow

Critical: Source image and Source VRT must be a matched pair. The VRT must have been annotated or auto-detected from that exact image. Using a VRT from a different image will produce catastrophically distorted results.

Load or auto-detect landmarks for each source face image → produces per-image .vrt files.
Create a Template VRT — the target shape (e.g. an averaged mean face). Use the Batch Pipeline to generate this automatically from a set of face photos.
Provide a Tessellation .tri file compatible with the same landmark set. The Batch Pipeline also generates this.
Load source image + its matching VRT into the Source section.
Load Template.vrt + Tessellation.tri into the Template & Tessellation section.
Click Warp to produce the normalized/morphed result.

The one-click bundled example set is test.jpg + test.vrt + mav.vrt + mav.tri (655-point). Use that set together for a guaranteed compatible demo run.

Auto-detect Landmarks (MediaPipe)

With a face photo loaded as the source image, click Auto-detect to automatically find 478 facial landmarks using Google's MediaPipe Face Landmarker.

MediaPipe produces 478 landmarks. The bundled quick example set is 655-point, so it is not compatible with MediaPipe output. Use the Batch Pipeline (below) to generate a matching tessellation.

Requirements: pip install mediapipe opencv-python must be run in the server's Python environment.

Batch Pipeline

The recommended workflow when working with your own face photos:

Open the Batch Pipeline panel in the sidebar.
Select all your face images (multiple selection supported).
Click Run Batch & Download ZIP.
The server auto-detects 478-point landmarks for each image, averages them to create a Template.vrt, and generates a MediaPipe_Tessellation.tri matching the 478-point scheme.
Download the ZIP. It contains:
- Template.vrt — the mean face template
- MediaPipe_Tessellation.tri — compatible tessellation
- vrts/ — per-image landmark files
- README.txt — usage instructions
To warp a specific face: load that image + its matching vrts/xxx.vrt as source, load Template.vrt as template, load MediaPipe_Tessellation.tri as tessellation, then click Warp.

Caricature Mode

Enable in the Caricature panel. The formula is evaluated per landmark, where d is the pixel distance between the source landmark and the template landmark.

The caricature transformation is:

result = source + (template − source) × formula_value

Formula value	Effect
`-1.5` (negative)	True caricature — exaggerates individual features away from template
`-1.0`	Mirror displacement — amplifies differences moderately
`0`	No change — source stays as-is
`0.5`	Halfway towards template
`1.0`	Perfect normalization to template shape
`1.5` (>1)	Anti-caricature — pushes past template (over-normalized)

You can use the variable d in the formula for distance-dependent effects, e.g. -d * 0.03 applies a larger caricature effect for features far from the template.

Template Averaging

The Template Averaging panel lets you manually average a set of .vrt files to produce a mean face shape. This is an alternative to the Batch Pipeline for cases where you already have per-image VRT files.

Select two or more .vrt files (they must all have the same number of landmarks).
Click Average & Download.
The resulting averaged.vrt can be used as the Template in subsequent warps.

Warp Types

Type	Description	Notes
Linear	Triangle-based affine interpolation within each tessellation triangle	Fast. Requires a Tessellation .tri file. Results are sharp at triangle boundaries.
Spline (nonlinear)	Radial basis function (thin-plate spline) interpolation across the whole image	Experimental. Disabled by default in the UI. Can produce severe distortions on some landmark sets. Use Stiffness to control rigidity — higher values = less bending.

Troubleshooting

Problem	Likely cause	Fix
Catastrophically distorted / melted output	Source image and Source VRT are mismatched (from different faces)	Use Auto-detect on the source image, or use matched example files together
Vertex count mismatch error	Source VRT and Template VRT have different landmark counts	Ensure both use the same landmark scheme (both 47-point or both 478-point)
"warp_faces binary not found"	C++ CLI not built yet	Run: `cd legacy/apps/WarpFacesCLI && mkdir build && cd build && cmake .. && cmake --build .`
"MediaPipe is not installed"	Python dependencies missing	Run: `pip install mediapipe opencv-python`
No face detected	Image quality, pose, or lighting	Use a front-facing, well-lit photo. MediaPipe works best with clearly visible faces.