# face-cropper: Advanced Face Cropping with Mediapipe and OpenCV

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/tsen-dev-face-cropper
Generated for open source discovery and AI-assisted research.

The `face-cropper` repository offers a robust Python solution for extracting faces from images. It implements a custom pipeline leveraging Mediapipe's FaceDetection and FaceMesh networks to accurately crop, optionally remove backgrounds, and correct the roll of detected faces. This tool is ideal for pre-processing images in computer vision tasks or real-time applications.

GitHub: https://github.com/tsen-dev/face-cropper
OSRepos URL: https://osrepos.com/repo/tsen-dev-face-cropper

## Summary

The `face-cropper` repository offers a robust Python solution for extracting faces from images. It implements a custom pipeline leveraging Mediapipe's FaceDetection and FaceMesh networks to accurately crop, optionally remove backgrounds, and correct the roll of detected faces. This tool is ideal for pre-processing images in computer vision tasks or real-time applications.

## Topics

- computer-vision
- face-cropping
- mediapipe
- opencv
- python
- image-processing
- face-detection
- face-segmentation

## Repository Information

Last analyzed by OSRepos: Sun Oct 12 2025 05:10:49 GMT+0100 (Western European Summer Time)
Detail views: 5
GitHub clicks: 2

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction

The `face-cropper` project by tsen-dev is a powerful Python library designed for precise face cropping from images. It implements a custom pipeline leveraging Mediapipe's FaceDetection and FaceMesh networks to accurately identify, segment, and extract faces. Key features include intelligent bounding box inflation to handle rotated faces, optional background removal, and automatic roll correction for perfectly aligned outputs. The repository includes several [demos](https://github.com/tsen-dev/face-cropper#demos) showcasing its capabilities across various 'in the wild' image conditions.

## Installation

To integrate `face-cropper` into your project, simply add the `face_cropper.py` module to your Python environment. Ensure you have the necessary dependencies installed, primarily `mediapipe`, `opencv-python`, and `numpy`. You can install them via pip:

bash
pip install mediapipe opencv-python numpy


## Examples

Using `face-cropper` is straightforward. First, import the `FaceCropper` class and then instantiate it with your desired configuration. Finally, call the `get_faces()` method with your image.

python
import cv2
import numpy as np
from face_cropper import FaceCropper, LONG_RANGE, STATIC_MODE

# Load an image (replace with your image path)
image = cv2.imread("path/to/your/image.jpg")
if image is None:
    print("Error: Image not found.")
    exit()

# Convert BGR to RGB (Mediapipe expects RGB)
image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

# Create a FaceCropper object with custom configuration
face_cropper = FaceCropper(
    min_face_detector_confidence=0.5,
    face_detector_model_selection=LONG_RANGE,
    landmark_detector_static_image_mode=STATIC_MODE,
    min_landmark_detector_confidence=0.5
)

# Get cropped faces, with background removal and roll correction
cropped_faces = face_cropper.get_faces(
    image_rgb,
    remove_background=True,
    correct_roll=True
)

# Process or save the cropped faces
for i, face in enumerate(cropped_faces):
    # Convert back to BGR for OpenCV display/save
    face_bgr = cv2.cvtColor(face, cv2.COLOR_RGB2BGR)
    cv2.imwrite(f"cropped_face_{i}.jpg", face_bgr)
    print(f"Saved cropped_face_{i}.jpg")

# Example with default settings
# face_cropper_default = FaceCropper()
# cropped_faces_default = face_cropper_default.get_faces(image_rgb)


The `FaceCropper` constructor and `get_faces` method offer various parameters for fine-tuning behavior, such as confidence thresholds, model selection (short-range or long-range), and whether to enable background removal or roll correction.

## Why Use

The `face-cropper` library offers several compelling reasons for its adoption in projects requiring face extraction:

- **Accurate and Robust:** It handles 'in the wild' images effectively, including faces with in-plane rotation, thanks to its intelligent pipeline that inflates bounding boxes and corrects roll.
- **Efficient:** Built upon light-weight Mediapipe networks, it is suitable for real-time applications, especially when processing a small number of faces.
- **Customizable Pipeline:** The modular design allows for optional background removal and roll correction, providing flexibility to suit specific application needs.
- **Pre-processing for ML:** It serves as an excellent pre-processing step to accelerate the learning of face features from uncontrolled image datasets, improving the quality of input for downstream machine learning models.

## Links

Explore the `face-cropper` project further using these links:

- [GitHub Repository](https://github.com/tsen-dev/face-cropper)
- [Mediapipe FaceDetection Documentation](https://google.github.io/mediapipe/solutions/face_detection.html)
- [Mediapipe FaceMesh Documentation](https://google.github.io/mediapipe/solutions/face_mesh.html)