Metadata-Version: 2.4
Name: facelapse
Version: 0.1.0
Summary: CLI tool for face alignment and timelapse generation using MediaPipe Face Landmarker.
Author-email: Leonardo Zilli <leonardo.zilli19@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/leonardozilli/facelapse
Project-URL: Repository, https://github.com/leonardozilli/facelapse
Keywords: face-alignment,opencv,mediapipe,timelapse
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.1
Requires-Dist: mediapipe>=0.10.33
Requires-Dist: natsort>=8.4.0
Requires-Dist: opencv-python>=4.13.0.92
Dynamic: license-file

# facelapse

<div align="center">

<img src="https://i.gifer.com/JuiH.gif" alt="Homer Simpson timelapse" style="width: 300px;">

<a href="">[![PyPI version](https://img.shields.io/pypi/v/facelapse)](https://pypi.org/project/facelapse/)</a>
<a href="">![Python versions](https://img.shields.io/pypi/pyversions/facelapse)</a>
<a href="">![License](https://img.shields.io/pypi/l/facelapse)</a>

</div>



A CLI tool for facial image alignment and timelapse generation using MediaPipe's [Face Landmarker](https://ai.google.dev/edge/mediapipe/solutions/vision/face_landmarker/).
Can be used to generate timelapse videos and datasets of aligned faces.

## Installation

Using pip:

```bash
pip install facelapse
```

Or run it directly as a tool with `uv`:

```bash
uvx facelapse -i <input_folder> [options]
```

## Usage

```bash
facelapse -i <input_folder> [options]
```

**Options:**

- `-i, --input`: Input folder containing images to process. Files are processed in <u>natural filename order</u>.
- `-o, --output`: Output folder (default: `output`).
- `--model-path`: Optional path to a custom MediaPipe .task model file (default: uses built-in model).
- `--width`: Width of aligned output images (default: `512`).
- `--height`: Height of aligned output images (default: `512`).
- `--fps`: Timelapse frame rate (default: `24.0`).
- `--skip-video`: Skip timelapse video generation.
- `--save-aligned-images`: Save aligned and cropped face images to `output/aligned` (default: off).
- `--blend-steps`: Number of interpolated frames to insert between images in the timelapse video (default: `0`).
- `--video-crop-mode`: Crop strategy for stitched video.
    - `tight`: crops to area valid for all frames (smallest, no extrapolation).
    - `balanced`: crops to area valid for the 90th percentile of frames.
    - `canvas`: no crop, preserves each frame's entire canvas (may use border extrapolation).
