# falign

A modern Python library for human face image preprocessing and alignment, inspired by [NVlabs/eg3d](https://github.com/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

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

## Quick Start

```python
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

```python
# 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

```python
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
)
```