Our take
- Activity
- 19
- Community
- 4
- Issues
- 21
- Pull requests
- 20
+0 stars in the last 30 days
- Fewer contributors than 91% of the projects we track
Project history
Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.
Stars
25Forks
4Change since Nov 16, 2026: 0 stars·0 forks
Overview
face-cropper is a Python module for finding faces in images and returning crops aligned to facial landmarks. It combines MediaPipe FaceDetection for candidate face boxes with FaceMesh for landmark detection, addressing the problem of incomplete crops when faces are rotated.
The pipeline can also mask pixels outside the face mesh and rotate faces to correct roll. It is intended for preprocessing uncontrolled images or lightweight real-time use, rather than as a high-accuracy detector for difficult lighting conditions.
Key Features
- Detects candidate faces with MediaPipe FaceDetection, with short-range and long-range model options.
- Expands candidate boxes according to approximate face roll to better include rotated faces.
- Uses FaceMesh landmarks to verify candidates and define the final crop.
- Optionally removes background pixels outside the face mesh.
- Corrects face roll by default, with an option to disable correction.
- Returns cropped RGB images as NumPy arrays through
get_faces().
Use Cases
- Prepare face crops from uncontrolled images for a machine-learning preprocessing workflow.
- Extract multiple faces from an image when a general-purpose MediaPipe detection pipeline is sufficient.
- Normalize face orientation before downstream image analysis or feature learning.
- Process a small number of faces in a real-time application where lightweight models are preferable to larger networks.
Getting Started
Add face_cropper.py to your project, then import and call FaceCropper.get_faces() with an RGB NumPy image. For configuration options and usage details, see the README.
Considerations
- The README describes MediaPipe and OpenCV-based processing, but does not provide an installation command or dependency versions.
- FaceMesh requires a maximum face count at initialization. The pipeline works around this by detecting candidates first and checking each candidate with FaceMesh.
- The project notes that its lightweight networks may perform poorly in extreme lighting and can occasionally miss faces in otherwise easy conditions.
- The repository has no license listed in the supplied project metadata, so usage permissions are unclear from that information.
Found this useful?
Share it with someone who would like face-cropper.