{"id":4640,"library":"mtcnn","title":"MTCNN (Multi-task Cascaded Convolutional Networks)","description":"The `mtcnn` library provides a Python implementation of the Multi-task Cascaded Convolutional Networks (MTCNN) for robust face detection and alignment. It is currently at version 1.0.0, supporting Python >= 3.10 and TensorFlow >= 2.12. Releases are infrequent, indicating a mature and stable codebase.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/ipazc/mtcnn","tags":["face detection","computer vision","deep learning","tensorflow","alignment"],"install":[{"cmd":"pip install mtcnn","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Backend for neural network operations; requires >=2.12.","package":"tensorflow","optional":false},{"reason":"Fundamental package for numerical computing.","package":"numpy","optional":false},{"reason":"Commonly used for image loading and preprocessing (e.g., cv2.imread, cv2.cvtColor).","package":"opencv-python","optional":true}],"imports":[{"symbol":"MTCNN","correct":"from mtcnn.mtcnn import MTCNN"}],"quickstart":{"code":"import cv2\nfrom mtcnn.mtcnn import MTCNN\n\n# Example image (replace with your path or download one)\n# For demonstration, we'll create a dummy image if file not found\ntry:\n    img_path = 'sample_image.jpg' # Replace with a path to a real image\n    img = cv2.imread(img_path)\n    if img is None:\n        # Create a blank image with a simple 'face' if sample_image.jpg not found\n        print(f\"Warning: '{img_path}' not found. Creating a dummy image.\")\n        img = 255 * (cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (50, 50)))\n        img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)\n        # Add a simple rectangle to simulate a face\n        cv2.rectangle(img, (100, 100), (200, 200), (0, 0, 255), 2)\n\nexcept Exception as e:\n    print(f\"Error loading image or creating dummy: {e}\")\n    # Fallback to a completely black image if even dummy creation fails\n    img = (255 * (cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (50, 50))))\n    img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)\n\n# MTCNN expects RGB images, OpenCV loads BGR by default\nimg_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)\n\n# Initialize the MTCNN detector\ndetector = MTCNN()\n\n# Detect faces in the image\nfaces = detector.detect_faces(img_rgb)\n\n# Print detected faces (each face is a dict with 'box', 'confidence', 'keypoints')\nfor face in faces:\n    print(face)\n\n# Optional: Draw bounding boxes and keypoints on the original image\n# for face in faces:\n#     x, y, width, height = face['box']\n#     cv2.rectangle(img, (x, y), (x + width, y + height), (0, 255, 0), 2)\n#     for key, value in face['keypoints'].items():\n#         cv2.circle(img, value, 2, (0, 0, 255), 2)\n# cv2.imshow('Detected Faces', img)\n# cv2.waitKey(0)\n# cv2.destroyAllWindows()\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your Python environment is version 3.10 or later. Consider using `pyenv` or `conda` to manage Python versions.","message":"The `mtcnn` library (v1.0.0 and later) explicitly requires Python 3.10 or newer due to `tensorflow` dependency constraints.","severity":"breaking","affected_versions":"All versions (v1.0.0+)"},{"fix":"Upgrade `mtcnn` to version 1.0.0 or later to ensure compatibility with TensorFlow 2.x (specifically >=2.12 as per PyPI).","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"After loading with OpenCV, convert the image using `img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure internet connectivity during the first initialization. Subsequent runs will use the cached models.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install TensorFlow with GPU support if your hardware allows. Otherwise, be aware that CPU-only inference will be considerably slower.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}