Practical overview
When it fits
Use it when you need a documented starting point for trying pretrained 2D or 3D facial-alignment models from a command line, or when locating the related landmark annotations.
Who it is for
- Computer-vision developers exploring facial landmark detection from images.
- Researchers seeking the associated facial landmark images and annotations.
- Developers adapting a documented Torch7 alignment demo or its linked implementations.
Documented uses
- Run a pretrained model to predict 2D facial landmarks.
- Estimate 3D facial landmarks with the included 3D alignment models.
- Build an image-based alignment demo that can accept supplied face bounding boxes.
- Obtain associated images and annotations for research experiments.
Requirements & limits
- The demo is implemented in Torch7 and documents Python 2.7.x and a set of Lua and Python dependencies.
- If bounding boxes are not provided, the README uses dlib for face detection and flags limitations in challenging poses and lighting.
- Model files and associated data are downloaded separately, including when using the provided Docker image.
- The repository links to separate Python implementation and training-code repositories; the README does not claim feature parity between the Torch7 demo and Python code.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Set up and launch the landmark demo
Prepare the repository and start its command-line demo with separately downloaded models and data.
Before you start
- Torch7 and Python 2.7.x
- The Lua packages listed in the README, including cutorch, cunn, cudnn, nn, nngraph, xlua, image, paths and fb.python
- Python packages NumPy and Matplotlib
- dlib when face bounding boxes are not supplied
- Downloaded model files and associated data
Steps
Clone the repository and change into its directory.
Install the documented Lua and Python dependencies.
Download the required model files and associated data.
Run
th main.lua; useth main.lua --helpto see available options.
Expected outcome
The repository's command-line demo starts with its selected options and downloaded resources.
Guide limitations
- The README does not specify a single required model or data download for every use.
- dlib is presented as a simple detector and may perform poorly with challenging poses or lighting.
- The documented setup requires legacy Torch7 and Python 2.7.x.
Build the CUDA-enabled Docker image
Build the repository's documented CUDA-supporting container image.
Before you start
- The repository and its Dockerfile
- A Docker environment
Steps
Clone the repository and change into its directory.
Run the command below.
docker build -t facealignment .
Expected outcome
A Docker image named `facealignment` is built from the repository's Dockerfile.
Guide limitations
- The Dockerfile is documented for CUDA support and cuDNN v5.1.
- The image excludes model files and data, which must be downloaded separately.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 18 October 2026
- Original website title
- 1adrianb/2D-and-3D-face-alignment · Official homepage title · retained in its source language