Guide · Open source
How to use faceai: setup, face detection and examples
Updated · written with AI from the project's own documentation and checked against our catalogue data
faceai is an open-source Python project from vipstone that bundles introductory tutorials and example code for detecting and recognizing faces in images and video. This guide explains what it contains, what you need before you start, and how to work through its examples. The README and tutorials are written in Chinese, so the guide focuses on the structure and the steps the source documents.
faceaivipstone/faceai · ★ 11.1k · MIT Install options & downloads Quick start
- 1Check your Python version. The README lists Python 3.6.4 as the tested version. Confirm which Python you have before you install anything else.
- 2Clone the repository. Run git clone https://github.com/vipstone/faceai to download the project files.
- 3Set up OpenCV. Open the OpenCV environment setup tutorial in the doc folder and follow its steps for your system.
- 4Install Dlib and face_recognition. Install the Dlib and face_recognition versions named in the README, since the examples rely on them.
- 5Run an image detection example. Start with the image face detection tutorial for OpenCV, then try the Dlib version to compare results.
- 6Add optional features. Install Tesseract OCR only if you want the OCR examples, and follow its tutorial.
What faceai includes
faceai is described by its author as an introductory project. Its README lists face detection and recognition for images and video, face outlines, drawing effects such as hats and makeup, gender recognition, emotion recognition across seven emotion categories, OCR text recognition, and image inpainting.
Some features are marked as unfinished in the README, including face swapping and eye movement tracking.
- Face detection and recognition in images and video
- Face outline drawing and 68-point facial landmark display
- Hat compositing and digital makeup
- Gender and emotion recognition
- Video object extraction and image inpainting
- OCR text recognition with Tesseract
Check the prerequisites before installing
The README lists its development environment as Windows 10 (x64) with Python 3.6.4, OpenCV 3.4.1, Dlib 19.8.1, face_recognition 1.2.2, keras 2.1.6, TensorFlow 1.8.0 and Tesseract OCR 4.0.0-beta.1. These are the versions the author tested, and they are old. Newer Python or library versions may not work without changes.
Tesseract OCR is only needed for the OCR features.
Clone the repository
The README gives a git clone command to download the project. Run it in the folder where you want the code to live.
git clone https://github.com/vipstone/faceaiFollow the tutorials in order
The README links a set of tutorials in the doc folder. The setup guide for OpenCV comes first, followed by the image and video detection tutorials for OpenCV and Dlib. Later tutorials cover contours, makeup, face recognition in video, hat compositing, gender and emotion recognition.
Work through the setup guide before the examples, because the later tutorials assume that OpenCV is installed and working.
- OpenCV environment setup (doc/settingup.md)
- Image face detection with OpenCV and with Dlib
- Video face detection with OpenCV and with Dlib
- Face outline drawing and digital makeup
- Gender and emotion recognition
Understand the detection approaches
The README says face recognition uses OpenCV or Dlib, face detection uses the face_recognition library, gender recognition uses Keras with TensorFlow, and text recognition uses Tesseract OCR. Comparing the OpenCV and Dlib versions of the same example is a useful way to see how the two libraries differ.
Know the limits of the project
The README is in Chinese, and the English README it links to is not part of the material used here. The repository's last push was in April 2020, and the documented setup dates from 2018. For production work, check whether the libraries still build on your system before relying on any example.
What people use it for
- Learning how OpenCV finds faces in a still photo
- Comparing OpenCV and Dlib detection on the same images
- Adding a hat or makeup overlay to a face in a video
- Experimenting with gender and emotion classification as a class project
Frequently asked questions
Is faceai free to use?
faceai is released under the MIT licence, as stated in the project information. The MIT licence allows use, modification and redistribution, provided the licence notice is kept.
What Python version does faceai need?
The README lists Python 3.6.4 as the development version. Newer Python versions are not documented, so you may need an older interpreter to follow the examples as written.
How do I install faceai?
The README gives one install step: clone the repository with git clone https://github.com/vipstone/faceai. You then set up the listed libraries and follow the tutorials in the doc folder.
Does faceai work with current OpenCV and Dlib?
The README lists OpenCV 3.4.1 and Dlib 19.8.1, and the repository's last push was in April 2020. Newer library versions are not covered, so the examples may need code changes to run.
Is faceai documentation available in English?
The main docs are in Chinese. The README links to an English version, but that file is not included in the material used for this guide.
What are alternatives to faceai?
Comparable projects include face_recognition, MediaPipe and InsightFace. These are better suited to production work, though they serve different needs and their docs should be checked directly.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
faceai suits students and developers who want simple, working OpenCV and Dlib examples and can read Chinese. It is not a good choice for production systems or for anyone who needs current Python and library versions, so look at face_recognition, MediaPipe or InsightFace in those cases.
Install options & downloads