cleardusk/3ddfa

3DDFA is a research codebase for analyzing human faces in photographs using a technique called 3D face alignment. Given a photo of a person, it estimates the full three-dimensional shape of their face, including the position and orientation of the head even when it is turned sideways or tilted. This goes beyond simpler approaches that only work well when faces are looking straight at the camera. The project is an improved PyTorch implementation of a paper published in a major computer vision journal, with additional features added beyond what the original paper described. The system produces several types of output from a single input image: a set of 68 landmark points that map the face geometry in 3D, a reconstructed 3D face mesh, an estimated head pose (yaw, pitch, and roll angles), a depth map showing distance from the camera, and specialized feature maps used in pose-adaptive processing. These outputs can be saved as standard 3D files that work with common 3D software, or as image overlays. To use it, you clone the repository, install several Python libraries including PyTorch, OpenCV, and optionally Dlib for face detection, then compile a small Cython module for performance-critical parts. Running the main script on any image containing faces produces the various output files automatically. The inference speed is roughly 0.27 milliseconds per image on a GPU when processing a batch of images, which is fast enough for real-time or near-real-time applications. The repository has been updated over several years and includes a C++ port for environments where Python is not suitable. A follow-up version called 3DDFA_V2 was also released for people who need faster and more accurate results, and is linked from this README. This project is primarily aimed at researchers and developers working on computer vision applications such as face recognition, augmented reality, or facial animation. It is licensed under MIT.