MTCNN (Multi-task Cascaded Convolutional Networks)

Warnings

• breaking The `mtcnn` library (v1.0.0 and later) explicitly requires Python 3.10 or newer due to `tensorflow` dependency constraints.
  Fix: Ensure your Python environment is version 3.10 or later. Consider using `pyenv` or `conda` to manage Python versions.
• breaking Older versions of `mtcnn` (prior to v1.0.0) may not be fully compatible with TensorFlow 2.x and its API changes. Version 1.0.0 introduced specific compatibility fixes.
  Fix: Upgrade `mtcnn` to version 1.0.0 or later to ensure compatibility with TensorFlow 2.x (specifically >=2.12 as per PyPI).
• gotcha Changes in `numpy` (specifically `allow_pickle=False` by default in `numpy.load()` for security reasons) could cause issues when loading MTCNN's internal pre-trained models if `mtcnn` is older than v1.0.0. Version 1.0.0 addressed this internally.
• gotcha The `detect_faces` method expects input images to be in RGB format. If you load images using OpenCV (`cv2.imread`), they are typically in BGR format and will need conversion.
  Fix: After loading with OpenCV, convert the image using `img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)`.
• gotcha The first time `MTCNN` is initialized, it will automatically download pre-trained model weights from the internet. This requires an active connection and can introduce a delay on the initial run.
  Fix: Ensure internet connectivity during the first initialization. Subsequent runs will use the cached models.
• gotcha MTCNN leverages TensorFlow, so its performance is highly dependent on the TensorFlow installation. For significant speed improvements, ensure you have `tensorflow[and-cuda]` (or `tensorflow-gpu` for older versions) installed and a compatible GPU available.
  Fix: Install TensorFlow with GPU support if your hardware allows. Otherwise, be aware that CPU-only inference will be considerably slower.

Install

• pip install mtcnn Install stable version

Imports

• MTCNN

  from mtcnn.mtcnn import MTCNN

Quickstart

This quickstart demonstrates how to load an image (using OpenCV, converting to RGB), initialize the MTCNN detector, and use `detect_faces` to find faces and their keypoints. The output `faces` is a list of dictionaries, where each dictionary contains the bounding box, confidence score, and facial keypoints.

import cv2
from mtcnn.mtcnn import MTCNN

# Example image (replace with your path or download one)
# For demonstration, we'll create a dummy image if file not found
try:
    img_path = 'sample_image.jpg' # Replace with a path to a real image
    img = cv2.imread(img_path)
    if img is None:
        # Create a blank image with a simple 'face' if sample_image.jpg not found
        print(f"Warning: '{img_path}' not found. Creating a dummy image.")
        img = 255 * (cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (50, 50)))
        img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
        # Add a simple rectangle to simulate a face
        cv2.rectangle(img, (100, 100), (200, 200), (0, 0, 255), 2)

except Exception as e:
    print(f"Error loading image or creating dummy: {e}")
    # Fallback to a completely black image if even dummy creation fails
    img = (255 * (cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (50, 50))))
    img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)

# MTCNN expects RGB images, OpenCV loads BGR by default
img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

# Initialize the MTCNN detector
detector = MTCNN()

# Detect faces in the image
faces = detector.detect_faces(img_rgb)

# Print detected faces (each face is a dict with 'box', 'confidence', 'keypoints')
for face in faces:
    print(face)

# Optional: Draw bounding boxes and keypoints on the original image
# for face in faces:
#     x, y, width, height = face['box']
#     cv2.rectangle(img, (x, y), (x + width, y + height), (0, 255, 0), 2)
#     for key, value in face['keypoints'].items():
#         cv2.circle(img, value, 2, (0, 0, 255), 2)
# cv2.imshow('Detected Faces', img)
# cv2.waitKey(0)
# cv2.destroyAllWindows()