Update readme

README.md

@@ -1,2 +1,71 @@
 # 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
+)
+```

src/falign/align.py

@@ -63,6 +63,7 @@ def calculate_alignment_quadrangle(landmarks: numpy.ndarray, margin_ratio: float
 def align(
     image: numpy.ndarray, landmarks: numpy.ndarray,
     height: int, width: int,
+    margin_ratio: float = 0.1,
 ) -> numpy.ndarray:
     landmarks = landmarks.astype(numpy.float32)  # (68, 2)
 
@@ -73,7 +74,7 @@ def align(
         [width-1, 0]
     ], dtype=numpy.float32)
 
-    quadrangle = calculate_alignment_quadrangle(landmarks, margin_ratio=0.1).astype(numpy.float32)
+    quadrangle = calculate_alignment_quadrangle(landmarks, margin_ratio).astype(numpy.float32)
     transform = cv2.getPerspectiveTransform(quadrangle, quadrangle_target)
     aligned = cv2.warpPerspective(image, transform, (width, height), borderMode=cv2.BORDER_REFLECT)