falign/README.md

falign

A modern Python library for human face image preprocessing and alignment, inspired by NVlabs/eg3d but with a cleaner, more maintainable implementation.

Features

• 68-point facial landmark detection using modern alternatives to dlib
• Perspective-based face alignment with automatic geometric correction
• Intelligent margin handling for better context preservation
• Automatic boundary processing using reflection padding
• Simple, clean API with minimal dependencies

Installation

pip install git+https://jingyu.tplinkdns.com/gitea/Diffusion/falign.git

Quick Start

from falign.landmarks import read_image_and_get_landmarks
from falign.align import align

image, landmarks = read_image_and_get_landmarks(path_image)
aligned = align(image, landmarks, height=256, width=256)

Core Algorithm

Face Alignment Process

1. Landmark-based Quadrangle Calculation

   • Computes eye centers and mouth corners from 68 landmarks
   • Establishes face orientation using eye-to-eye and eye-to-mouth vectors
   • Creates alignment quadrangle with configurable margin

2. Perspective Transformation

   • Maps irregular face quadrangle to standard rectangle
   • Handles rotation, scaling, shearing, and perspective distortion
   • Uses OpenCV's optimized perspective transform with reflection border mode

3. Automatic Boundary Handling

   • No manual cropping or padding required
   • cv2.BORDER_REFLECT automatically handles out-of-bounds pixels
   • Preserves natural appearance at boundaries

Advanced Usage

Custom Margin Ratio

# More context (15% margin)
aligned = align(image, landmarks, height=512, width=512, margin_ratio=0.15)

# Tight crop (no margin)
aligned = align(image, landmarks, height=512, width=512, margin_ratio=0.0)

Visualization

from falign.plot import plot_landmarks_on_image

# Save image with landmark visualization
plot_landmarks_on_image(
    image, landmarks,
    save_path="output_with_landmarks.jpg",
    size=3  # landmark point size
)