72 lines
2.1 KiB
Markdown
72 lines
2.1 KiB
Markdown
# 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
|
|
)
|
|
```
|