Upload 195 files

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+deepface/tests/dataset/img1.jpg filter=lfs diff=lfs merge=lfs -text
+deepface/tests/dataset/img26.jpg filter=lfs diff=lfs merge=lfs -text
+deepface/tests/dataset/img33.jpg filter=lfs diff=lfs merge=lfs -text
+deepface/tests/dataset/img35.jpg filter=lfs diff=lfs merge=lfs -text
+deepface/tests/dataset/img40.jpg filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,20 @@
+# Use an official Python runtime as a parent image
+FROM python:3.9-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the requirements file into the container at /app
+COPY requirements.txt /app/requirements.txt
+
+# Install any needed packages specified in requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+# Copy the rest of the application code to /app
+COPY . /app
+
+# Expose port 8000 to the outside world
+EXPOSE 8000
+
+# Command to run the FastAPI application using Uvicorn
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,12 +1,11 @@
----
-title: FV V6
-emoji: 📊
-colorFrom: pink
-colorTo: gray
-sdk: gradio
-sdk_version: 4.42.0
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: FV V4
+emoji: 📈
+colorFrom: red
+colorTo: indigo
+sdk: docker
+pinned: false
+license: mit
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,213 @@
+from fastapi import FastAPI, File, UploadFile, HTTPException
+from fastapi.responses import JSONResponse
+import pickle
+import numpy as np
+import face_recognition
+from PIL import Image
+import io
+from mtcnn import MTCNN
+import cv2
+import faiss
+import os
+import imgaug.augmenters as iaa
+from deepface import DeepFace
+
+app = FastAPI()
+
+# Load encodings from the file
+def load_encodings(file_path):
+    if not os.path.exists(file_path):
+        return np.array([]), []
+    with open(file_path, "rb") as file:
+        data = pickle.load(file)
+    return np.array(data["encodings"]), data["labels"]
+
+# Save encodings to the file
+def save_encodings(encodings, labels, file_path):
+    data = {"encodings": encodings, "labels": labels}
+    with open(file_path, "wb") as file:
+        pickle.dump(data, file)
+
+# Detect and align face
+def detect_and_align_face(image):
+    detector = MTCNN()  # Initialize the MTCNN face detector
+    image_rgb = cv2.cvtColor(np.array(image), cv2.COLOR_BGR2RGB)  # Convert the image to RGB format
+    detections = detector.detect_faces(image_rgb)  # Detect faces in the image
+
+    if len(detections) == 0:
+        raise ValueError("No face detected in the image.")
+
+    detection = detections[0]  # Assume the first detected face
+    x, y, width, height = detection['box']  # Get the bounding box of the face
+    keypoints = detection['keypoints']  # Get facial keypoints (eyes, nose, mouth)
+    face = image_rgb[y:y + height, x:x + width]  # Extract the face from the image
+
+    # Calculate the angle to align the face based on eye positions
+    left_eye = keypoints['left_eye']
+    right_eye = keypoints['right_eye']
+    delta_x = right_eye[0] - left_eye[0]
+    delta_y = right_eye[1] - left_eye[1]
+    angle = np.arctan2(delta_y, delta_x) * (180.0 / np.pi)
+
+    # Compute the center of the face and create a rotation matrix
+    center = ((x + x + width) // 2, (y + y + height) // 2)
+    rot_matrix = cv2.getRotationMatrix2D(center, angle, scale=1.0)
+
+    # Rotate the image to align the face
+    aligned_image = cv2.warpAffine(image_rgb, rot_matrix, (image_rgb.shape[1], image_rgb.shape[0]))
+    aligned_face = aligned_image[y:y + height, x:x + width]  # Extract the aligned face
+
+    return Image.fromarray(aligned_face)  # Convert to PIL Image format and return
+
+# Create FAISS index
+def create_faiss_index(known_encodings):
+    dimension = known_encodings.shape[1]  # Get the dimensionality of the encodings
+    index = faiss.IndexFlatL2(dimension)  # Create a FAISS index using L2 distance
+    index.add(known_encodings)  # Add known encodings to the index
+    return index  # Return the FAISS index
+
+# Augment image function
+def augment_image(image, num_augmented=5):
+    """
+    Apply data augmentation to an image.
+    
+    Parameters:
+    image (PIL.Image): The image to augment.
+    num_augmented (int): Number of augmented images to generate.
+    
+    Returns:
+    List[PIL.Image]: List of augmented images.
+    """
+    image = np.array(image)
+
+    # Define a sequence of augmentation techniques
+    aug = iaa.Sequential([
+        iaa.Fliplr(0.5),  # horizontal flips
+        iaa.Affine(rotate=(-25, 25)),  # rotation
+        iaa.AdditiveGaussianNoise(scale=(0, 0.05*255)),  # noise
+        iaa.Multiply((0.8, 1.2)),  # brightness
+        iaa.GaussianBlur(sigma=(0.0, 1.0))  # blur
+    ])
+
+    # Generate augmented images
+    augmented_images = [Image.fromarray(aug(image=image)) for _ in range(num_augmented)]
+    return augmented_images
+
+# Endpoint to process and save augmented encodings
+@app.post("/create/")
+async def preprocess_and_save_augmented_encodings(image: UploadFile = File(...), num_augmented: int = 5):
+    known_encodings = []
+    known_labels = []
+
+    # Load the uploaded image
+    image_bytes = await image.read()
+    original_image = Image.open(io.BytesIO(image_bytes)).convert("RGB")  # Ensure the image is in RGB format
+
+    # Augment the image
+    augmented_images = augment_image(original_image, num_augmented=num_augmented)
+
+    # Include the original image in the list of images to encode
+    images_to_encode = [original_image] + augmented_images
+
+    for img in images_to_encode:
+        img_array = np.array(img)
+        # Encode the face
+        encodings = face_recognition.face_encodings(img_array)
+        if encodings:
+            encoding = encodings[0]
+            # Store the encoding and the corresponding label
+            known_encodings.append(encoding)
+            known_labels.append(image.filename)  # Use the uploaded image filename as the label
+
+    # Save encodings and labels to a file
+    encodings_file = "face_encoding.pkl"
+    save_encodings(np.array(known_encodings), known_labels, encodings_file)
+
+    return JSONResponse(content={"status": "Success", "message": "Augmented encodings created and saved."})
+
+@app.post("/encode/")
+async def encode_face(image: UploadFile = File(...)):
+    # Load the image from the uploaded file
+    image_bytes = await image.read()
+    pil_image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    
+    # Align the face
+    try:
+        aligned_face = detect_and_align_face(pil_image)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    
+    # Load existing encodings
+    encodings_file = "face_encoding.pkl"
+    known_encodings, known_labels = load_encodings(encodings_file)
+    
+    # Encode the face
+    encodings = face_recognition.face_encodings(np.array(aligned_face))
+    if not encodings:
+        raise HTTPException(status_code=400, detail="No face encoding found.")
+    
+    # Append the new encoding and label
+    known_encodings = list(known_encodings)
+    known_encodings.append(encodings[0])
+    known_labels.append(image.filename)
+    
+    # Save the updated encodings
+    save_encodings(np.array(known_encodings), known_labels, encodings_file)
+    
+    return JSONResponse(content={"status": "Success", "message": "Face encoded and saved."})
+
+@app.post("/match/")
+async def match_face(image: UploadFile = File(...), similarity_threshold: float = 70.0):
+    # Load the image from the uploaded file
+    image_bytes = await image.read()
+    pil_image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    
+    # Align the face
+    try:
+        aligned_face = detect_and_align_face(pil_image)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    
+    # Load existing encodings
+    encodings_file = "face_encoding.pkl"
+    known_encodings, known_labels = load_encodings(encodings_file)
+    
+    if len(known_encodings) == 0:
+        raise HTTPException(status_code=400, detail="No known faces in the database. Please add some faces first.")
+    
+    # Encode the face
+    target_encodings = face_recognition.face_encodings(np.array(aligned_face))
+    if not target_encodings:
+        raise HTTPException(status_code=400, detail="No face encoding found.")
+    
+    target_encoding = target_encodings[0].reshape(1, -1)
+    
+    # Create FAISS index and search for the best match
+    index = create_faiss_index(np.array(known_encodings))
+    distances, indices = index.search(target_encoding, 1)
+    
+    best_match_index = indices[0][0]
+    best_similarity_percentage = (1 - distances[0][0]) * 100
+    
+    # Default to True (real) for spoof detection
+    is_real = True
+    
+    # Perform face spoof detection using DeepFace
+    try:
+        result = DeepFace.extract_faces(img_path=image.filename, anti_spoofing=True)
+        if result and isinstance(result, list):
+            is_real = result[0].get('is_real', True)
+    except Exception as e:
+        # Log the exception if necessary, but do not interrupt the program
+        is_real = False  # Conservative approach if spoof detection fails
+    
+    return JSONResponse(content={
+        "status": "Success",
+        "similarity": f"{best_similarity_percentage:.2f}%",
+        "is_real": is_real,
+        "message": "Face matched successfully" if best_similarity_percentage >= similarity_threshold else "Face not matched"
+    })
+
+if __name__ == '__main__':
+    import uvicorn
+    uvicorn.run(app, host='0.0.0.0', port=8000)

deepface/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-vendored

deepface/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: serengil
+patreon: serengil
+buy_me_a_coffee: serengil

deepface/.github/ISSUE_TEMPLATE/01-report-bug.yaml

@@ -0,0 +1,86 @@
+name: '🐛 Report a bug'
+description: 'Use this template to report DeepFace related issues'
+title: '[BUG]: <short description of the issue>'
+labels:
+  - bug
+body:
+  - type: checkboxes
+    id: preliminary-checks
+    attributes:
+      label: Before You Report a Bug, Please Confirm You Have Done The Following...
+      description: If any of these required steps are not taken, we may not be able to review your issue. Help us to help you!
+      options:
+        - label: I have updated to the latest version of the packages.
+          required: true
+        - label: I have searched for both [existing issues](https://github.com/serengil/deepface/issues) and [closed issues](https://github.com/serengil/deepface/issues?q=is%3Aissue+is%3Aclosed) and found none that matched my issue.
+          required: true
+  - type: input
+    id: deepface-version
+    attributes:
+      label: DeepFace's version
+      description: |
+        Please provide your deepface version with calling the command `python -c "import deepface; print(deepface.__version__)"` in your terminal
+      placeholder: e.g. v0.0.90
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: |
+        Please provide your python programming language's version with calling `python --version` in your terminal
+      placeholder: e.g. 3.8.5
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: |
+        Please provide your operation system's details
+      placeholder: e.g. Windows 10 or Ubuntu 20.04
+    validations:
+      required: false
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies
+      description: |
+        Please provide python dependencies with calling `pip freeze` in your terminal, in particular tensorflow's and keras' versions
+    validations:
+      required: true
+  - type: textarea
+    id: repro-code
+    attributes:
+      label: Reproducible example
+      description: A ***minimal*** code sample which reproduces the issue
+      render: Python
+    validations:
+      required: true
+  - type: textarea
+    id: exception-message
+    attributes:
+      label: Relevant Log Output
+      description: Please share the exception message from your terminal if your program is failing
+    validations:
+      required: false
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Result
+      description: What did you expect to happen? 
+    validations:
+      required: false
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened instead?
+      description: What actually happened?
+    validations:
+      required: false
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Info
+      description: |
+        Any additional info you'd like to provide.

deepface/.github/ISSUE_TEMPLATE/02-request-feature.yaml

@@ -0,0 +1,18 @@
+name: '✨ Request a New Feature'
+description: 'Use this template to propose a new feature'
+title: '[FEATURE]: <a short description of my proposal>'
+labels:
+  - 'enhancement'
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Explain what your proposed feature would do and why this is useful.
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Info
+      description: Any additional info you'd like to provide.

deepface/.github/ISSUE_TEMPLATE/03-documentation.yaml

@@ -0,0 +1,18 @@
+name: '📝 Documentation'
+description: 'Use this template to add or improve docs'
+title: '[DOC]: <a short description of my proposal>'
+labels:
+  - documentation
+body:
+  - type: textarea
+    attributes:
+      label: Suggested Changes
+      description: What would you like to see happen in the docs?
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Info
+      description: |
+        Any additional info you'd like to provide.

deepface/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a question on StackOverflow
+    about: If you just want to ask a question, consider asking it on StackOverflow!
+    url: https://stackoverflow.com/search?tab=newest&q=deepface

deepface/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Tickets
+
+https://github.com/serengil/deepface/issues/XXX
+
+### What has been done
+
+With this PR, ...
+
+## How to test
+
+```shell
+make lint && make test
+```

deepface/.github/workflows/tests.yml

@@ -0,0 +1,69 @@
+name: Tests and Linting
+
+on: 
+  push:
+    paths:
+      - '.github/workflows/tests.yml'
+      - 'deepface/**'  
+      - 'tests/**'
+      - 'api/**'
+      - 'requirements.txt'
+      - '.gitignore'
+      - 'setup.py'
+  pull_request:
+    paths:
+      - '.github/workflows/tests.yml'
+      - 'deepface/**'  
+      - 'tests/**'
+      - 'api/**'
+      - 'requirements.txt'
+      - '.gitignore'
+      - 'setup.py'
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest
+        pip install .
+        
+    - name: Test with pytest
+      run: |
+        cd tests
+        python -m pytest . -s --disable-warnings
+  linting:
+    needs: unit-tests
+    
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+  
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint==3.0.2
+        pip install black
+        pip install .
+        
+    - name: Lint with pylint
+      run: |
+        pylint --fail-under=10 deepface/

deepface/.gitignore

@@ -0,0 +1,20 @@
+**/__pycache__
+**/.DS_Store
+build/
+dist/
+Pipfile
+Pipfile.lock
+.mypy_cache/
+.idea/
+deepface.egg-info/
+tests/dataset/*.pkl
+tests/*.ipynb
+tests/*.csv
+*.pyc
+**/.coverage
+**/.coverage.*
+benchmarks/results
+benchmarks/outputs
+benchmarks/dataset
+benchmarks/lfwe
+venv

deepface/.pylintrc

@@ -0,0 +1,641 @@
+[MAIN]
+
+# Analyse import fallback blocks. This can be used to support both Python 2 and
+# 3 compatible code, which means that the block might have code that exists
+# only in one or another interpreter, leading to false positives when analysed.
+analyse-fallback-blocks=no
+
+# Load and enable all available extensions. Use --list-extensions to see a list
+# all available extensions.
+#enable-all-extensions=
+
+# In error mode, messages with a category besides ERROR or FATAL are
+# suppressed, and no reports are done by default. Error mode is compatible with
+# disabling specific errors.
+#errors-only=
+
+# Always return a 0 (non-error) status code, even if lint errors are found.
+# This is primarily useful in continuous integration scripts.
+#exit-zero=
+
+# A comma-separated list of package or module names from where C extensions may
+# be loaded. Extensions are loading into the active Python interpreter and may
+# run arbitrary code.
+extension-pkg-allow-list=
+
+# A comma-separated list of package or module names from where C extensions may
+# be loaded. Extensions are loading into the active Python interpreter and may
+# run arbitrary code. (This is an alternative name to extension-pkg-allow-list
+# for backward compatibility.)
+extension-pkg-whitelist=
+
+# Return non-zero exit code if any of these messages/categories are detected,
+# even if score is above --fail-under value. Syntax same as enable. Messages
+# specified are enabled, while categories only check already-enabled messages.
+fail-on=
+
+# Specify a score threshold under which the program will exit with error.
+fail-under=10
+
+# Interpret the stdin as a python script, whose filename needs to be passed as
+# the module_or_package argument.
+#from-stdin=
+
+# Files or directories to be skipped. They should be base names, not paths.
+ignore=CVS
+
+# Add files or directories matching the regular expressions patterns to the
+# ignore-list. The regex matches against paths and can be in Posix or Windows
+# format. Because '\' represents the directory delimiter on Windows systems, it
+# can't be used as an escape character.
+ignore-paths=
+
+# Files or directories matching the regular expression patterns are skipped.
+# The regex matches against base names, not paths. The default value ignores
+# Emacs file locks
+ignore-patterns=^\.#
+
+# List of module names for which member attributes should not be checked
+# (useful for modules/projects where namespaces are manipulated during runtime
+# and thus existing member attributes cannot be deduced by static analysis). It
+# supports qualified module names, as well as Unix pattern matching.
+ignored-modules=
+
+# Python code to execute, usually for sys.path manipulation such as
+# pygtk.require().
+#init-hook=
+
+# Use multiple processes to speed up Pylint. Specifying 0 will auto-detect the
+# number of processors available to use, and will cap the count on Windows to
+# avoid hangs.
+jobs=1
+
+# Control the amount of potential inferred values when inferring a single
+# object. This can help the performance when dealing with large functions or
+# complex, nested conditions.
+limit-inference-results=100
+
+# List of plugins (as comma separated values of python module names) to load,
+# usually to register additional checkers.
+load-plugins=
+
+# Pickle collected data for later comparisons.
+persistent=yes
+
+# Minimum Python version to use for version dependent checks. Will default to
+# the version used to run pylint.
+py-version=3.9
+
+# Discover python modules and packages in the file system subtree.
+recursive=no
+
+# When enabled, pylint would attempt to guess common misconfiguration and emit
+# user-friendly hints instead of false-positive error messages.
+suggestion-mode=yes
+
+# Allow loading of arbitrary C extensions. Extensions are imported into the
+# active Python interpreter and may run arbitrary code.
+unsafe-load-any-extension=no
+
+# In verbose mode, extra non-checker-related info will be displayed.
+#verbose=
+
+
+[BASIC]
+
+# Naming style matching correct argument names.
+argument-naming-style=snake_case
+
+# Regular expression matching correct argument names. Overrides argument-
+# naming-style. If left empty, argument names will be checked with the set
+# naming style.
+#argument-rgx=
+
+# Naming style matching correct attribute names.
+attr-naming-style=snake_case
+
+# Regular expression matching correct attribute names. Overrides attr-naming-
+# style. If left empty, attribute names will be checked with the set naming
+# style.
+#attr-rgx=
+
+# Bad variable names which should always be refused, separated by a comma.
+bad-names=foo,
+          bar,
+          baz,
+          toto,
+          tutu,
+          tata
+
+# Bad variable names regexes, separated by a comma. If names match any regex,
+# they will always be refused
+bad-names-rgxs=
+
+# Naming style matching correct class attribute names.
+class-attribute-naming-style=any
+
+# Regular expression matching correct class attribute names. Overrides class-
+# attribute-naming-style. If left empty, class attribute names will be checked
+# with the set naming style.
+#class-attribute-rgx=
+
+# Naming style matching correct class constant names.
+class-const-naming-style=UPPER_CASE
+
+# Regular expression matching correct class constant names. Overrides class-
+# const-naming-style. If left empty, class constant names will be checked with
+# the set naming style.
+#class-const-rgx=
+
+# Naming style matching correct class names.
+class-naming-style=PascalCase
+
+# Regular expression matching correct class names. Overrides class-naming-
+# style. If left empty, class names will be checked with the set naming style.
+#class-rgx=
+
+# Naming style matching correct constant names.
+const-naming-style=UPPER_CASE
+
+# Regular expression matching correct constant names. Overrides const-naming-
+# style. If left empty, constant names will be checked with the set naming
+# style.
+#const-rgx=
+
+# Minimum line length for functions/classes that require docstrings, shorter
+# ones are exempt.
+docstring-min-length=-1
+
+# Naming style matching correct function names.
+function-naming-style=snake_case
+
+# Regular expression matching correct function names. Overrides function-
+# naming-style. If left empty, function names will be checked with the set
+# naming style.
+#function-rgx=
+
+# Good variable names which should always be accepted, separated by a comma.
+good-names=i,
+           j,
+           k,
+           ex,
+           Run,
+           _
+
+# Good variable names regexes, separated by a comma. If names match any regex,
+# they will always be accepted
+good-names-rgxs=
+
+# Include a hint for the correct naming format with invalid-name.
+include-naming-hint=no
+
+# Naming style matching correct inline iteration names.
+inlinevar-naming-style=any
+
+# Regular expression matching correct inline iteration names. Overrides
+# inlinevar-naming-style. If left empty, inline iteration names will be checked
+# with the set naming style.
+#inlinevar-rgx=
+
+# Naming style matching correct method names.
+method-naming-style=snake_case
+
+# Regular expression matching correct method names. Overrides method-naming-
+# style. If left empty, method names will be checked with the set naming style.
+#method-rgx=
+
+# Naming style matching correct module names.
+module-naming-style=snake_case
+
+# Regular expression matching correct module names. Overrides module-naming-
+# style. If left empty, module names will be checked with the set naming style.
+#module-rgx=
+
+# Colon-delimited sets of names that determine each other's naming style when
+# the name regexes allow several styles.
+name-group=
+
+# Regular expression which should only match function or class names that do
+# not require a docstring.
+no-docstring-rgx=^_
+
+# List of decorators that produce properties, such as abc.abstractproperty. Add
+# to this list to register other decorators that produce valid properties.
+# These decorators are taken in consideration only for invalid-name.
+property-classes=abc.abstractproperty
+
+# Regular expression matching correct type variable names. If left empty, type
+# variable names will be checked with the set naming style.
+#typevar-rgx=
+
+# Naming style matching correct variable names.
+variable-naming-style=snake_case
+
+# Regular expression matching correct variable names. Overrides variable-
+# naming-style. If left empty, variable names will be checked with the set
+# naming style.
+#variable-rgx=
+
+
+[CLASSES]
+
+# Warn about protected attribute access inside special methods
+check-protected-access-in-special-methods=no
+
+# List of method names used to declare (i.e. assign) instance attributes.
+defining-attr-methods=__init__,
+                      __new__,
+                      setUp,
+                      __post_init__
+
+# List of member names, which should be excluded from the protected access
+# warning.
+exclude-protected=_asdict,
+                  _fields,
+                  _replace,
+                  _source,
+                  _make
+
+# List of valid names for the first argument in a class method.
+valid-classmethod-first-arg=cls
+
+# List of valid names for the first argument in a metaclass class method.
+valid-metaclass-classmethod-first-arg=cls
+
+
+[DESIGN]
+
+# List of regular expressions of class ancestor names to ignore when counting
+# public methods (see R0903)
+exclude-too-few-public-methods=
+
+# List of qualified class names to ignore when counting class parents (see
+# R0901)
+ignored-parents=
+
+# Maximum number of arguments for function / method.
+max-args=5
+
+# Maximum number of attributes for a class (see R0902).
+max-attributes=7
+
+# Maximum number of boolean expressions in an if statement (see R0916).
+max-bool-expr=5
+
+# Maximum number of branch for function / method body.
+max-branches=12
+
+# Maximum number of locals for function / method body.
+max-locals=15
+
+# Maximum number of parents for a class (see R0901).
+max-parents=7
+
+# Maximum number of public methods for a class (see R0904).
+max-public-methods=20
+
+# Maximum number of return / yield for function / method body.
+max-returns=6
+
+# Maximum number of statements in function / method body.
+max-statements=50
+
+# Minimum number of public methods for a class (see R0903).
+min-public-methods=2
+
+
+[EXCEPTIONS]
+
+# Exceptions that will emit a warning when caught.
+overgeneral-exceptions=BaseException,
+                       Exception
+
+
+[FORMAT]
+
+# Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
+expected-line-ending-format=
+
+# Regexp for a line that is allowed to be longer than the limit.
+ignore-long-lines=^\s*(# )?<?https?://\S+>?$
+
+# Number of spaces of indent required inside a hanging or continued line.
+indent-after-paren=4
+
+# String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1
+# tab).
+indent-string='    '
+
+# Maximum number of characters on a single line.
+max-line-length=100
+
+# Maximum number of lines in a module.
+max-module-lines=1000
+
+# Allow the body of a class to be on the same line as the declaration if body
+# contains single statement.
+single-line-class-stmt=no
+
+# Allow the body of an if to be on the same line as the test if there is no
+# else.
+single-line-if-stmt=no
+
+
+[IMPORTS]
+
+# List of modules that can be imported at any level, not just the top level
+# one.
+allow-any-import-level=
+
+# Allow wildcard imports from modules that define __all__.
+allow-wildcard-with-all=no
+
+# Deprecated modules which should not be used, separated by a comma.
+deprecated-modules=
+
+# Output a graph (.gv or any supported image format) of external dependencies
+# to the given file (report RP0402 must not be disabled).
+ext-import-graph=
+
+# Output a graph (.gv or any supported image format) of all (i.e. internal and
+# external) dependencies to the given file (report RP0402 must not be
+# disabled).
+import-graph=
+
+# Output a graph (.gv or any supported image format) of internal dependencies
+# to the given file (report RP0402 must not be disabled).
+int-import-graph=
+
+# Force import order to recognize a module as part of the standard
+# compatibility libraries.
+known-standard-library=
+
+# Force import order to recognize a module as part of a third party library.
+known-third-party=enchant
+
+# Couples of modules and preferred modules, separated by a comma.
+preferred-modules=
+
+
+[LOGGING]
+
+# The type of string formatting that logging methods do. `old` means using %
+# formatting, `new` is for `{}` formatting.
+logging-format-style=old
+
+# Logging modules to check that the string format arguments are in logging
+# function parameter format.
+logging-modules=logging
+
+
+[MESSAGES CONTROL]
+
+# Only show warnings with the listed confidence levels. Leave empty to show
+# all. Valid levels: HIGH, CONTROL_FLOW, INFERENCE, INFERENCE_FAILURE,
+# UNDEFINED.
+confidence=HIGH,
+           CONTROL_FLOW,
+           INFERENCE,
+           INFERENCE_FAILURE,
+           UNDEFINED
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once). You can also use "--disable=all" to
+# disable everything first and then re-enable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use "--disable=all --enable=classes
+# --disable=W".
+disable=raw-checker-failed,
+        bad-inline-option,
+        locally-disabled,
+        file-ignored,
+        suppressed-message,
+        useless-suppression,
+        deprecated-pragma,
+        use-symbolic-message-instead,
+        import-error,
+        invalid-name,
+        missing-module-docstring,
+        missing-function-docstring,
+        missing-class-docstring,
+        too-many-arguments, 
+        too-many-locals, 
+        too-many-branches, 
+        too-many-statements,
+        global-variable-undefined,
+        import-outside-toplevel,
+        singleton-comparison,
+        too-many-lines,
+        duplicate-code,
+        bare-except,
+        cyclic-import,
+        global-statement,
+        no-member,
+        no-name-in-module,
+        unrecognized-option,
+        consider-using-dict-items,
+        consider-iterating-dictionary,
+        unexpected-keyword-arg
+
+# Enable the message, report, category or checker with the given id(s). You can
+# either give multiple identifier separated by comma (,) or put this option
+# multiple time (only on the command line, not in the configuration file where
+# it should appear only once). See also the "--disable" option for examples.
+enable=c-extension-no-member
+
+
+[METHOD_ARGS]
+
+# List of qualified names (i.e., library.method) which require a timeout
+# parameter e.g. 'requests.api.get,requests.api.post'
+timeout-methods=requests.api.delete,requests.api.get,requests.api.head,requests.api.options,requests.api.patch,requests.api.post,requests.api.put,requests.api.request
+
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+notes=FIXME,
+      XXX,
+      TODO
+
+# Regular expression of note tags to take in consideration.
+notes-rgx=
+
+
+[REFACTORING]
+
+# Maximum number of nested blocks for function / method body
+max-nested-blocks=5
+
+# Complete name of functions that never returns. When checking for
+# inconsistent-return-statements if a never returning function is called then
+# it will be considered as an explicit return statement and no message will be
+# printed.
+never-returning-functions=sys.exit,argparse.parse_error
+
+
+[REPORTS]
+
+# Python expression which should return a score less than or equal to 10. You
+# have access to the variables 'fatal', 'error', 'warning', 'refactor',
+# 'convention', and 'info' which contain the number of messages in each
+# category, as well as 'statement' which is the total number of statements
+# analyzed. This score is used by the global evaluation report (RP0004).
+evaluation=max(0, 0 if fatal else 10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10))
+
+# Template used to display messages. This is a python new-style format string
+# used to format the message information. See doc for all details.
+msg-template=
+
+# Set the output format. Available formats are text, parseable, colorized, json
+# and msvs (visual studio). You can also give a reporter class, e.g.
+# mypackage.mymodule.MyReporterClass.
+#output-format=
+
+# Tells whether to display a full report or only the messages.
+reports=no
+
+# Activate the evaluation score.
+score=yes
+
+
+[SIMILARITIES]
+
+# Comments are removed from the similarity computation
+ignore-comments=yes
+
+# Docstrings are removed from the similarity computation
+ignore-docstrings=yes
+
+# Imports are removed from the similarity computation
+ignore-imports=yes
+
+# Signatures are removed from the similarity computation
+ignore-signatures=yes
+
+# Minimum lines number of a similarity.
+min-similarity-lines=4
+
+
+[SPELLING]
+
+# Limits count of emitted suggestions for spelling mistakes.
+max-spelling-suggestions=4
+
+# Spelling dictionary name. Available dictionaries: none. To make it work,
+# install the 'python-enchant' package.
+spelling-dict=
+
+# List of comma separated words that should be considered directives if they
+# appear at the beginning of a comment and should not be checked.
+spelling-ignore-comment-directives=fmt: on,fmt: off,noqa:,noqa,nosec,isort:skip,mypy:
+
+# List of comma separated words that should not be checked.
+spelling-ignore-words=
+
+# A path to a file that contains the private dictionary; one word per line.
+spelling-private-dict-file=
+
+# Tells whether to store unknown words to the private dictionary (see the
+# --spelling-private-dict-file option) instead of raising a message.
+spelling-store-unknown-words=no
+
+
+[STRING]
+
+# This flag controls whether inconsistent-quotes generates a warning when the
+# character used as a quote delimiter is used inconsistently within a module.
+check-quote-consistency=no
+
+# This flag controls whether the implicit-str-concat should generate a warning
+# on implicit string concatenation in sequences defined over several lines.
+check-str-concat-over-line-jumps=no
+
+
+[TYPECHECK]
+
+# List of decorators that produce context managers, such as
+# contextlib.contextmanager. Add to this list to register other decorators that
+# produce valid context managers.
+contextmanager-decorators=contextlib.contextmanager
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E1101 when accessed. Python regular
+# expressions are accepted.
+generated-members=
+
+# Tells whether to warn about missing members when the owner of the attribute
+# is inferred to be None.
+ignore-none=yes
+
+# This flag controls whether pylint should warn about no-member and similar
+# checks whenever an opaque object is returned when inferring. The inference
+# can return multiple potential results while evaluating a Python object, but
+# some branches might not be evaluated, which results in partial inference. In
+# that case, it might be useful to still emit no-member and other checks for
+# the rest of the inferred objects.
+ignore-on-opaque-inference=yes
+
+# List of symbolic message names to ignore for Mixin members.
+ignored-checks-for-mixins=no-member,
+                          not-async-context-manager,
+                          not-context-manager,
+                          attribute-defined-outside-init
+
+# List of class names for which member attributes should not be checked (useful
+# for classes with dynamically set attributes). This supports the use of
+# qualified names.
+ignored-classes=optparse.Values,thread._local,_thread._local,argparse.Namespace
+
+# Show a hint with possible names when a member name was not found. The aspect
+# of finding the hint is based on edit distance.
+missing-member-hint=yes
+
+# The minimum edit distance a name should have in order to be considered a
+# similar match for a missing member name.
+missing-member-hint-distance=1
+
+# The total number of similar names that should be taken in consideration when
+# showing a hint for a missing member.
+missing-member-max-choices=1
+
+# Regex pattern to define which classes are considered mixins.
+mixin-class-rgx=.*[Mm]ixin
+
+# List of decorators that change the signature of a decorated function.
+signature-mutators=
+
+
+[VARIABLES]
+
+# List of additional names supposed to be defined in builtins. Remember that
+# you should avoid defining new builtins when possible.
+additional-builtins=
+
+# Tells whether unused global variables should be treated as a violation.
+allow-global-unused-variables=yes
+
+# List of names allowed to shadow builtins
+allowed-redefined-builtins=
+
+# List of strings which can identify a callback function by name. A callback
+# name must start or end with one of those strings.
+callbacks=cb_,
+          _cb
+
+# A regular expression matching the name of dummy variables (i.e. expected to
+# not be used).
+dummy-variables-rgx=_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_
+
+# Argument names that match this expression will be ignored.
+ignored-argument-names=_.*|^ignored_|^unused_
+
+# Tells whether we should check for unused import in __init__ files.
+init-import=no
+
+# List of qualified module names which can have objects that can redefine
+# builtins.
+redefining-builtins-modules=six.moves,past.builtins,future.builtins,builtins,io

deepface/.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+  "python.linting.pylintEnabled": true,
+  "python.linting.enabled": true,
+  "python.linting.pylintUseMinimalCheckers": false,
+  "editor.formatOnSave": true,
+  "editor.renderWhitespace": "all",
+  "files.autoSave": "afterDelay",
+  "python.analysis.typeCheckingMode": "basic",
+  "python.formatting.provider": "black",
+  "python.formatting.blackArgs": ["--line-length=100"],
+  "editor.fontWeight": "normal",
+  "python.analysis.extraPaths": [
+    "./deepface"
+  ],
+  "black-formatter.args": [
+    "--line-length=100"
+  ]
+}

deepface/CITATION.md

@@ -0,0 +1,71 @@
+## Cite DeepFace Papers
+
+Please cite deepface in your publications if it helps your research. Here are its BibTex entries:
+
+### Facial Recognition
+
+If you use deepface in your research for facial recogntion purposes, please cite these publications:
+
+```BibTeX
+@article{serengil2024lightface,
+  title         = {A Benchmark of Facial Recognition Pipelines and Co-Usability Performances of Modules},
+  author        = {Serengil, Sefik Ilkin and Ozpinar, Alper},
+  journal       = {Bilisim Teknolojileri Dergisi},
+  volume        = {17},
+  number        = {2},
+  pages         = {95-107},
+  year          = {2024},
+  doi           = {10.17671/gazibtd.1399077},
+  url           = {https://dergipark.org.tr/en/pub/gazibtd/issue/84331/1399077},
+  publisher     = {Gazi University}
+}
+```
+
+```BibTeX
+@inproceedings{serengil2020lightface,
+  title        = {LightFace: A Hybrid Deep Face Recognition Framework},
+  author       = {Serengil, Sefik Ilkin and Ozpinar, Alper},
+  booktitle    = {2020 Innovations in Intelligent Systems and Applications Conference (ASYU)},
+  pages        = {23-27},
+  year         = {2020},
+  doi          = {10.1109/ASYU50717.2020.9259802},
+  url          = {https://ieeexplore.ieee.org/document/9259802},
+  organization = {IEEE}
+}
+```
+
+### Facial Attribute Analysis
+
+If you use deepface in your research for facial attribute analysis purposes such as age, gender, emotion or ethnicity prediction, please cite the this publication.
+
+```BibTeX
+@inproceedings{serengil2021lightface,
+  title        = {HyperExtended LightFace: A Facial Attribute Analysis Framework},
+  author       = {Serengil, Sefik Ilkin and Ozpinar, Alper},
+  booktitle    = {2021 International Conference on Engineering and Emerging Technologies (ICEET)},
+  pages        = {1-4},
+  year         = {2021},
+  doi          = {10.1109/ICEET53442.2021.9659697},
+  url          = {https://ieeexplore.ieee.org/document/9659697/},
+  organization = {IEEE}
+}
+```
+
+### Additional Papers
+
+We have additionally released these papers within the DeepFace project for a multitude of purposes.
+
+```BibTeX
+@misc{serengil2023db,
+  title         = {An evaluation of sql and nosql databases for facial recognition pipelines},
+  author        = {Serengil, Sefik Ilkin and Ozpinar, Alper},
+  year          = {2023},
+  archivePrefix = {Cambridge Open Engage},
+  doi           = {10.33774/coe-2023-18rcn},
+  url           = {https://www.cambridge.org/engage/coe/article-details/63f3e5541d2d184063d4f569}
+}
+```
+
+### Repositories
+
+Also, if you use deepface in your GitHub projects, please add `deepface` in the `requirements.txt`. Thereafter, your project will be listed in its [dependency graph](https://github.com/serengil/deepface/network/dependents).

deepface/Dockerfile

@@ -0,0 +1,58 @@
+# base image
+FROM python:3.8.12
+LABEL org.opencontainers.image.source https://github.com/serengil/deepface
+
+# -----------------------------------
+# create required folder
+RUN mkdir /app
+RUN mkdir /app/deepface
+
+# -----------------------------------
+# switch to application directory
+WORKDIR /app
+
+# -----------------------------------
+# update image os
+RUN apt-get update
+RUN apt-get install ffmpeg libsm6 libxext6 -y
+
+# -----------------------------------
+# Copy required files from repo into image
+COPY ./deepface /app/deepface
+# even though we will use local requirements, this one is required to perform install deepface from source code
+COPY ./requirements.txt /app/requirements.txt
+COPY ./requirements_local /app/requirements_local.txt
+COPY ./package_info.json /app/
+COPY ./setup.py /app/
+COPY ./README.md /app/
+
+# -----------------------------------
+# if you plan to use a GPU, you should install the 'tensorflow-gpu' package
+# RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org tensorflow-gpu
+
+# if you plan to use face anti-spoofing, then activate this line
+# RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org torch==2.1.2
+# -----------------------------------
+# install deepface from pypi release (might be out-of-date)
+# RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org deepface
+# -----------------------------------
+# install dependencies - deepface with these dependency versions is working
+RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org -r /app/requirements_local.txt
+# install deepface from source code (always up-to-date)
+RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org -e .
+
+# -----------------------------------
+# some packages are optional in deepface. activate if your task depends on one.
+# RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org cmake==3.24.1.1
+# RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org dlib==19.20.0
+# RUN pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host=files.pythonhosted.org lightgbm==2.3.1
+
+# -----------------------------------
+# environment variables
+ENV PYTHONUNBUFFERED=1
+
+# -----------------------------------
+# run the app (re-configure port if necessary)
+WORKDIR /app/deepface/api/src
+EXPOSE 5000
+CMD ["gunicorn", "--workers=1", "--timeout=3600", "--bind=0.0.0.0:5000", "app:create_app()"]

deepface/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Sefik Ilkin Serengil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deepface/Makefile

@@ -0,0 +1,8 @@
+test:
+	cd tests && python -m pytest . -s --disable-warnings
+
+lint:
+	python -m pylint deepface/ --fail-under=10
+
+coverage:
+	pip install pytest-cov && cd tests && python -m pytest --cov=deepface

deepface/README.md

@@ -0,0 +1,461 @@
+# deepface
+
+<div align="center">
+
+[![Downloads](https://static.pepy.tech/personalized-badge/deepface?period=total&units=international_system&left_color=grey&right_color=blue&left_text=downloads)](https://pepy.tech/project/deepface)
+[![Stars](https://img.shields.io/github/stars/serengil/deepface?color=yellow&style=flat&label=%E2%AD%90%20stars)](https://github.com/serengil/deepface/stargazers)
+[![License](http://img.shields.io/:license-MIT-green.svg?style=flat)](https://github.com/serengil/deepface/blob/master/LICENSE)
+[![Tests](https://github.com/serengil/deepface/actions/workflows/tests.yml/badge.svg)](https://github.com/serengil/deepface/actions/workflows/tests.yml)
+[![DOI](http://img.shields.io/:DOI-10.17671/gazibtd.1399077-blue.svg?style=flat)](https://doi.org/10.17671/gazibtd.1399077)
+
+[![Blog](https://img.shields.io/:blog-sefiks.com-blue.svg?style=flat&logo=wordpress)](https://sefiks.com)
+[![YouTube](https://img.shields.io/:[email protected]?style=flat&logo=youtube)](https://www.youtube.com/@sefiks?sub_confirmation=1)
+[![Twitter](https://img.shields.io/:[email protected]?style=flat&logo=x)](https://twitter.com/intent/user?screen_name=serengil)
+
+[![Support me on Patreon](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dserengil%26type%3Dpatrons&style=flat)](https://www.patreon.com/serengil?repo=deepface)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/serengil?logo=GitHub&color=lightgray)](https://github.com/sponsors/serengil)
+[![Buy Me a Coffee](https://img.shields.io/badge/-buy_me_a%C2%A0coffee-gray?logo=buy-me-a-coffee)](https://buymeacoffee.com/serengil)
+
+<!-- [![DOI](http://img.shields.io/:DOI-10.1109/ICEET53442.2021.9659697-blue.svg?style=flat)](https://doi.org/10.1109/ICEET53442.2021.9659697) -->
+<!-- [![DOI](http://img.shields.io/:DOI-10.1109/ASYU50717.2020.9259802-blue.svg?style=flat)](https://doi.org/10.1109/ASYU50717.2020.9259802) -->
+
+</div>
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/deepface-icon-labeled.png" width="200" height="240"></p>
+
+DeepFace is a lightweight [face recognition](https://sefiks.com/2018/08/06/deep-face-recognition-with-keras/) and facial attribute analysis ([age](https://sefiks.com/2019/02/13/apparent-age-and-gender-prediction-in-keras/), [gender](https://sefiks.com/2019/02/13/apparent-age-and-gender-prediction-in-keras/), [emotion](https://sefiks.com/2018/01/01/facial-expression-recognition-with-keras/) and [race](https://sefiks.com/2019/11/11/race-and-ethnicity-prediction-in-keras/)) framework for python. It is a hybrid face recognition framework wrapping **state-of-the-art** models: [`VGG-Face`](https://sefiks.com/2018/08/06/deep-face-recognition-with-keras/), [`FaceNet`](https://sefiks.com/2018/09/03/face-recognition-with-facenet-in-keras/), [`OpenFace`](https://sefiks.com/2019/07/21/face-recognition-with-openface-in-keras/), [`DeepFace`](https://sefiks.com/2020/02/17/face-recognition-with-facebook-deepface-in-keras/), [`DeepID`](https://sefiks.com/2020/06/16/face-recognition-with-deepid-in-keras/), [`ArcFace`](https://sefiks.com/2020/12/14/deep-face-recognition-with-arcface-in-keras-and-python/), [`Dlib`](https://sefiks.com/2020/07/11/face-recognition-with-dlib-in-python/), `SFace` and `GhostFaceNet`.
+
+[`Experiments`](https://github.com/serengil/deepface/tree/master/benchmarks) show that **human beings have 97.53% accuracy** on facial recognition tasks whereas those models already reached and passed that accuracy level.
+
+## Installation [![PyPI](https://img.shields.io/pypi/v/deepface.svg)](https://pypi.org/project/deepface/)
+
+The easiest way to install deepface is to download it from [`PyPI`](https://pypi.org/project/deepface/). It's going to install the library itself and its prerequisites as well.
+
+```shell
+$ pip install deepface
+```
+
+Alternatively, you can also install deepface from its source code. Source code may have new features not published in pip release yet.
+
+```shell
+$ git clone https://github.com/serengil/deepface.git
+$ cd deepface
+$ pip install -e .
+```
+
+Once you installed the library, then you will be able to import it and use its functionalities.
+
+```python
+from deepface import DeepFace
+```
+
+**A Modern Facial Recognition Pipeline** - [`Demo`](https://youtu.be/WnUVYQP4h44)
+
+A modern [**face recognition pipeline**](https://sefiks.com/2020/05/01/a-gentle-introduction-to-face-recognition-in-deep-learning/) consists of 5 common stages: [detect](https://sefiks.com/2020/08/25/deep-face-detection-with-opencv-in-python/), [align](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), [normalize](https://sefiks.com/2020/11/20/facial-landmarks-for-face-recognition-with-dlib/), [represent](https://sefiks.com/2018/08/06/deep-face-recognition-with-keras/) and [verify](https://sefiks.com/2020/05/22/fine-tuning-the-threshold-in-face-recognition/). While DeepFace handles all these common stages in the background, you don’t need to acquire in-depth knowledge about all the processes behind it. You can just call its verification, find or analysis function with a single line of code.
+
+**Face Verification** - [`Demo`](https://youtu.be/KRCvkNCOphE)
+
+This function verifies face pairs as same person or different persons. It expects exact image paths as inputs. Passing numpy or base64 encoded images is also welcome. Then, it is going to return a dictionary and you should check just its verified key.
+
+```python
+result = DeepFace.verify(
+  img1_path = "img1.jpg",
+  img2_path = "img2.jpg",
+)
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/stock-1.jpg" width="95%" height="95%"></p>
+
+**Face recognition** - [`Demo`](https://youtu.be/Hrjp-EStM_s)
+
+[Face recognition](https://sefiks.com/2020/05/25/large-scale-face-recognition-for-deep-learning/) requires applying face verification many times. Herein, deepface has an out-of-the-box find function to handle this action. It's going to look for the identity of input image in the database path and it will return list of pandas data frame as output. Meanwhile, facial embeddings of the facial database are stored in a pickle file to be searched faster in next time. Result is going to be the size of faces appearing in the source image. Besides, target images in the database can have many faces as well.
+
+
+```python
+dfs = DeepFace.find(
+  img_path = "img1.jpg",
+  db_path = "C:/workspace/my_db",
+)
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/stock-6-v2.jpg" width="95%" height="95%"></p>
+
+**Embeddings** - [`Demo`](https://youtu.be/OYialFo7Qo4)
+
+Face recognition models basically represent facial images as multi-dimensional vectors. Sometimes, you need those embedding vectors directly. DeepFace comes with a dedicated representation function. Represent function returns a list of embeddings. Result is going to be the size of faces appearing in the image path.
+
+```python
+embedding_objs = DeepFace.represent(
+  img_path = "img.jpg"
+)
+```
+
+This function returns an array as embedding. The size of the embedding array would be different based on the model name. For instance, VGG-Face is the default model and it represents facial images as 4096 dimensional vectors.
+
+```python
+for embedding_obj in embedding_objs:
+  embedding = embedding_obj["embedding"]
+  assert isinstance(embedding, list)
+  assert (
+    model_name == "VGG-Face"
+    and len(embedding) == 4096
+  )
+```
+
+Here, embedding is also [plotted](https://sefiks.com/2020/05/01/a-gentle-introduction-to-face-recognition-in-deep-learning/) with 4096 slots horizontally. Each slot is corresponding to a dimension value in the embedding vector and dimension value is explained in the colorbar on the right. Similar to 2D barcodes, vertical dimension stores no information in the illustration.
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/embedding.jpg" width="95%" height="95%"></p>
+
+**Face recognition models** - [`Demo`](https://youtu.be/eKOZawGR3y0)
+
+DeepFace is a **hybrid** face recognition package. It currently wraps many **state-of-the-art** face recognition models: [`VGG-Face`](https://sefiks.com/2018/08/06/deep-face-recognition-with-keras/) , [`FaceNet`](https://sefiks.com/2018/09/03/face-recognition-with-facenet-in-keras/), [`OpenFace`](https://sefiks.com/2019/07/21/face-recognition-with-openface-in-keras/), [`DeepFace`](https://sefiks.com/2020/02/17/face-recognition-with-facebook-deepface-in-keras/), [`DeepID`](https://sefiks.com/2020/06/16/face-recognition-with-deepid-in-keras/), [`ArcFace`](https://sefiks.com/2020/12/14/deep-face-recognition-with-arcface-in-keras-and-python/), [`Dlib`](https://sefiks.com/2020/07/11/face-recognition-with-dlib-in-python/), `SFace` and `GhostFaceNet`. The default configuration uses VGG-Face model.
+
+```python
+models = [
+  "VGG-Face", 
+  "Facenet", 
+  "Facenet512", 
+  "OpenFace", 
+  "DeepFace", 
+  "DeepID", 
+  "ArcFace", 
+  "Dlib", 
+  "SFace",
+  "GhostFaceNet",
+]
+
+#face verification
+result = DeepFace.verify(
+  img1_path = "img1.jpg",
+  img2_path = "img2.jpg",
+  model_name = models[0],
+)
+
+#face recognition
+dfs = DeepFace.find(
+  img_path = "img1.jpg",
+  db_path = "C:/workspace/my_db", 
+  model_name = models[1],
+)
+
+#embeddings
+embedding_objs = DeepFace.represent(
+  img_path = "img.jpg",
+  model_name = models[2],
+)
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/model-portfolio-20240316.jpg" width="95%" height="95%"></p>
+
+FaceNet, VGG-Face, ArcFace and Dlib are overperforming ones based on experiments - see [`BENCHMARKS`](https://github.com/serengil/deepface/tree/master/benchmarks) for more details. You can find the measured scores of various models in DeepFace and the reported scores from their original studies in the following table.
+
+| Model          | Measured Score | Declared Score     |
+| -------------- | -------------- | ------------------ |
+| Facenet512     | 98.4%          | 99.6%              |
+| Human-beings   | 97.5%          | 97.5%              |
+| Facenet        | 97.4%          | 99.2%              |
+| Dlib           | 96.8%          | 99.3 %             |
+| VGG-Face       | 96.7%          | 98.9%              |
+| ArcFace        | 96.7%          | 99.5%              |
+| GhostFaceNet   | 93.3%          | 99.7%              |
+| SFace          | 93.0%          | 99.5%              |
+| OpenFace       | 78.7%          | 92.9%              |
+| DeepFace       | 69.0%          | 97.3%              |
+| DeepID         | 66.5%          | 97.4%              |
+
+Conducting experiments with those models within DeepFace may reveal disparities compared to the original studies, owing to the adoption of distinct detection or normalization techniques. Furthermore, some models have been released solely with their backbones, lacking pre-trained weights. Thus, we are utilizing their re-implementations instead of the original pre-trained weights.
+
+**Similarity** - [`Demo`](https://youtu.be/1EPoS69fHOc)
+
+Face recognition models are regular [convolutional neural networks](https://sefiks.com/2018/03/23/convolutional-autoencoder-clustering-images-with-neural-networks/) and they are responsible to represent faces as vectors. We expect that a face pair of same person should be [more similar](https://sefiks.com/2020/05/22/fine-tuning-the-threshold-in-face-recognition/) than a face pair of different persons.
+
+Similarity could be calculated by different metrics such as [Cosine Similarity](https://sefiks.com/2018/08/13/cosine-similarity-in-machine-learning/), Euclidean Distance or L2 normalized Euclidean. The default configuration uses cosine similarity. According to [experiments](https://github.com/serengil/deepface/tree/master/benchmarks), no distance metric is overperforming than other.
+
+```python
+metrics = ["cosine", "euclidean", "euclidean_l2"]
+
+#face verification
+result = DeepFace.verify(
+  img1_path = "img1.jpg", 
+  img2_path = "img2.jpg", 
+  distance_metric = metrics[1],
+)
+
+#face recognition
+dfs = DeepFace.find(
+  img_path = "img1.jpg", 
+  db_path = "C:/workspace/my_db", 
+  distance_metric = metrics[2],
+)
+```
+
+**Facial Attribute Analysis** - [`Demo`](https://youtu.be/GT2UeN85BdA)
+
+DeepFace also comes with a strong facial attribute analysis module including [`age`](https://sefiks.com/2019/02/13/apparent-age-and-gender-prediction-in-keras/), [`gender`](https://sefiks.com/2019/02/13/apparent-age-and-gender-prediction-in-keras/), [`facial expression`](https://sefiks.com/2018/01/01/facial-expression-recognition-with-keras/) (including angry, fear, neutral, sad, disgust, happy and surprise) and [`race`](https://sefiks.com/2019/11/11/race-and-ethnicity-prediction-in-keras/) (including asian, white, middle eastern, indian, latino and black) predictions. Result is going to be the size of faces appearing in the source image.
+
+```python
+objs = DeepFace.analyze(
+  img_path = "img4.jpg", 
+  actions = ['age', 'gender', 'race', 'emotion'],
+)
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/stock-2.jpg" width="95%" height="95%"></p>
+
+Age model got ± 4.65 MAE; gender model got 97.44% accuracy, 96.29% precision and 95.05% recall as mentioned in its [tutorial](https://sefiks.com/2019/02/13/apparent-age-and-gender-prediction-in-keras/).
+
+
+**Face Detection and Alignment** - [`Demo`](https://youtu.be/GZ2p2hj2H5k)
+
+Face detection and alignment are important early stages of a modern face recognition pipeline. [Experiments](https://github.com/serengil/deepface/tree/master/benchmarks) show that detection increases the face recognition accuracy up to 42%, while alignment increases it up to 6%. [`OpenCV`](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), [`Ssd`](https://sefiks.com/2020/08/25/deep-face-detection-with-opencv-in-python/), [`Dlib`](https://sefiks.com/2020/07/11/face-recognition-with-dlib-in-python/),  [`MtCnn`](https://sefiks.com/2020/09/09/deep-face-detection-with-mtcnn-in-python/), `Faster MtCnn`, [`RetinaFace`](https://sefiks.com/2021/04/27/deep-face-detection-with-retinaface-in-python/), [`MediaPipe`](https://sefiks.com/2022/01/14/deep-face-detection-with-mediapipe/), `Yolo`, `YuNet` and `CenterFace` detectors are wrapped in deepface.
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/detector-portfolio-v6.jpg" width="95%" height="95%"></p>
+
+All deepface functions accept optional detector backend and align input arguments. You can switch among those detectors and alignment modes with these arguments. OpenCV is the default detector and alignment is on by default.
+
+```python
+backends = [
+  'opencv', 
+  'ssd', 
+  'dlib', 
+  'mtcnn', 
+  'fastmtcnn',
+  'retinaface', 
+  'mediapipe',
+  'yolov8',
+  'yunet',
+  'centerface',
+]
+
+alignment_modes = [True, False]
+
+#face verification
+obj = DeepFace.verify(
+  img1_path = "img1.jpg", 
+  img2_path = "img2.jpg", 
+  detector_backend = backends[0],
+  align = alignment_modes[0],
+)
+
+#face recognition
+dfs = DeepFace.find(
+  img_path = "img.jpg", 
+  db_path = "my_db", 
+  detector_backend = backends[1],
+  align = alignment_modes[0],
+)
+
+#embeddings
+embedding_objs = DeepFace.represent(
+  img_path = "img.jpg", 
+  detector_backend = backends[2],
+  align = alignment_modes[0],
+)
+
+#facial analysis
+demographies = DeepFace.analyze(
+  img_path = "img4.jpg", 
+  detector_backend = backends[3],
+  align = alignment_modes[0],
+)
+
+#face detection and alignment
+face_objs = DeepFace.extract_faces(
+  img_path = "img.jpg", 
+  detector_backend = backends[4],
+  align = alignment_modes[0],
+)
+```
+
+Face recognition models are actually CNN models and they expect standard sized inputs. So, resizing is required before representation. To avoid deformation, deepface adds black padding pixels according to the target size argument after detection and alignment.
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/detector-outputs-20240414.jpg" width="90%" height="90%"></p>
+
+[RetinaFace](https://sefiks.com/2021/04/27/deep-face-detection-with-retinaface-in-python/) and [MtCnn](https://sefiks.com/2020/09/09/deep-face-detection-with-mtcnn-in-python/) seem to overperform in detection and alignment stages but they are much slower. If the speed of your pipeline is more important, then you should use opencv or ssd. On the other hand, if you consider the accuracy, then you should use retinaface or mtcnn.
+
+The performance of RetinaFace is very satisfactory even in the crowd as seen in the following illustration. Besides, it comes with an incredible facial landmark detection performance. Highlighted red points show some facial landmarks such as eyes, nose and mouth. That's why, alignment score of RetinaFace is high as well.
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/retinaface-results.jpeg" width="90%" height="90%">
+<br><em>The Yellow Angels - Fenerbahce Women's Volleyball Team</em>
+</p>
+
+You can find out more about RetinaFace on this [repo](https://github.com/serengil/retinaface).
+
+**Real Time Analysis** - [`Demo`](https://youtu.be/-c9sSJcx6wI)
+
+You can run deepface for real time videos as well. Stream function will access your webcam and apply both face recognition and facial attribute analysis. The function starts to analyze a frame if it can focus a face sequentially 5 frames. Then, it shows results 5 seconds.
+
+```python
+DeepFace.stream(db_path = "C:/User/Sefik/Desktop/database")
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/stock-3.jpg" width="90%" height="90%"></p>
+
+Even though face recognition is based on one-shot learning, you can use multiple face pictures of a person as well. You should rearrange your directory structure as illustrated below.
+
+```bash
+user
+├── database
+│   ├── Alice
+│   │   ├── Alice1.jpg
+│   │   ├── Alice2.jpg
+│   ├── Bob
+│   │   ├── Bob.jpg
+```
+
+**React UI** - [`Demo part-i`](https://youtu.be/IXoah6rhxac), [`Demo part-ii`](https://youtu.be/_waBA-cH2D4)
+
+If you intend to perform face verification tasks directly from your browser, [deepface-react-ui](https://github.com/serengil/deepface-react-ui) is a separate repository built using ReactJS depending on deepface api.
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/deepface-and-react.jpg" width="90%" height="90%"></p>
+
+**Face Anti Spoofing** - [`Demo`](https://youtu.be/UiK1aIjOBlQ)
+
+DeepFace also includes an anti-spoofing analysis module to understand given image is real or fake. To activate this feature, set the `anti_spoofing` argument to True in any DeepFace tasks.
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/face-anti-spoofing.jpg" width="40%" height="40%"></p>
+
+```python
+# anti spoofing test in face detection
+face_objs = DeepFace.extract_faces(
+  img_path="dataset/img1.jpg",
+  anti_spoofing = True
+)
+assert all(face_obj["is_real"] is True for face_obj in face_objs)
+
+# anti spoofing test in real time analysis
+DeepFace.stream(
+  db_path = "C:/User/Sefik/Desktop/database",
+  anti_spoofing = True
+)
+```
+
+**API** - [`Demo`](https://youtu.be/HeKCQ6U9XmI)
+
+DeepFace serves an API as well - see [`api folder`](https://github.com/serengil/deepface/tree/master/deepface/api/src) for more details. You can clone deepface source code and run the api with the following command. It will use gunicorn server to get a rest service up. In this way, you can call deepface from an external system such as mobile app or web.
+
+```shell
+cd scripts
+./service.sh
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/deepface-api.jpg" width="90%" height="90%"></p>
+
+Face recognition, facial attribute analysis and vector representation functions are covered in the API. You are expected to call these functions as http post methods. Default service endpoints will be `http://localhost:5005/verify` for face recognition, `http://localhost:5005/analyze` for facial attribute analysis, and `http://localhost:5005/represent` for vector representation. You can pass input images as exact image paths on your environment, base64 encoded strings or images on web. [Here](https://github.com/serengil/deepface/tree/master/deepface/api/postman), you can find a postman project to find out how these methods should be called.
+
+**Dockerized Service** - [`Demo`](https://youtu.be/9Tk9lRQareA)
+
+[![Docker Pulls](https://img.shields.io/docker/pulls/serengil/deepface?logo=docker)](https://hub.docker.com/r/serengil/deepface)
+
+The following command set will serve deepface on `localhost:5005` via docker. Then, you will be able to consume deepface services such as verify, analyze and represent. Also, if you want to build the image by your own instead of pre-built image from docker hub, [Dockerfile](https://github.com/serengil/deepface/blob/master/Dockerfile) is available in the root folder of the project.
+
+```shell
+# docker build -t serengil/deepface . # build docker image from Dockerfile
+docker pull serengil/deepface # use pre-built docker image from docker hub
+docker run -p 5005:5000 serengil/deepface
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/deepface-dockerized-v2.jpg" width="50%" height="50%"></p>
+
+**Command Line Interface** - [`Demo`](https://youtu.be/PKKTAr3ts2s)
+
+DeepFace comes with a command line interface as well. You are able to access its functions in command line as shown below. The command deepface expects the function name as 1st argument and function arguments thereafter.
+
+```shell
+#face verification
+$ deepface verify -img1_path tests/dataset/img1.jpg -img2_path tests/dataset/img2.jpg
+
+#facial analysis
+$ deepface analyze -img_path tests/dataset/img1.jpg
+```
+
+You can also run these commands if you are running deepface with docker. Please follow the instructions in the [shell script](https://github.com/serengil/deepface/blob/master/scripts/dockerize.sh#L17).
+
+**Large Scale Facial Recognition** - [`Playlist`](https://www.youtube.com/playlist?list=PLsS_1RYmYQQGSJu_Z3OVhXhGmZ86_zuIm)
+
+If your task requires facial recognition on large datasets, you should combine DeepFace with a vector index or vector database. This setup will perform [approximate nearest neighbor](https://youtu.be/c10w0Ptn_CU) searches instead of exact ones, allowing you to identify a face in a database containing billions of entries within milliseconds. Common vector index solutions include [Annoy](https://youtu.be/Jpxm914o2xk), [Faiss](https://youtu.be/6AmEvDTKT-k), [Voyager](https://youtu.be/2ZYTV9HlFdU), [NMSLIB](https://youtu.be/EVBhO8rbKbg), [ElasticSearch](https://youtu.be/i4GvuOmzKzo). For vector databases, popular options are [Postgres with its pgvector extension](https://youtu.be/Xfv4hCWvkp0) and [RediSearch](https://youtu.be/yrXlS0d6t4w).
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/deepface-big-data.jpg" width="90%" height="90%"></p>
+
+Conversely, if your task involves facial recognition on small to moderate-sized databases, you can adopt use relational databases such as [Postgres](https://youtu.be/f41sLxn1c0k) or [SQLite](https://youtu.be/_1ShBeWToPg), or NoSQL databases like [Mongo](https://youtu.be/dmprgum9Xu8), [Redis](https://youtu.be/X7DSpUMVTsw) or [Cassandra](https://youtu.be/J_yXpc3Y8Ec) to perform exact nearest neighbor search.
+
+## Contribution
+
+Pull requests are more than welcome! If you are planning to contribute a large patch, please create an issue first to get any upfront questions or design decisions out of the way first.
+
+Before creating a PR, you should run the unit tests and linting locally by running `make test && make lint` command. Once a PR sent, GitHub test workflow will be run automatically and unit test and linting jobs will be available in [GitHub actions](https://github.com/serengil/deepface/actions) before approval.
+
+## Support
+
+There are many ways to support a project - starring⭐️ the GitHub repo is just one 🙏
+
+If you do like this work, then you can support it financially on [Patreon](https://www.patreon.com/serengil?repo=deepface), [GitHub Sponsors](https://github.com/sponsors/serengil) or [Buy Me a Coffee](https://buymeacoffee.com/serengil).
+
+<a href="https://www.patreon.com/serengil?repo=deepface">
+<img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/patreon.png" width="30%" height="30%">
+</a>
+
+<a href="https://buymeacoffee.com/serengil">
+<img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/bmc-button.png" width="25%" height="25%">
+</a>
+
+Also, your company's logo will be shown on README on GitHub if you become a sponsor in gold, silver or bronze tiers.
+
+## Citation
+
+Please cite deepface in your publications if it helps your research - see [`CITATIONS`](https://github.com/serengil/deepface/blob/master/CITATION.md) for more details. Here are its BibTex entries:
+
+If you use deepface in your research for facial recogntion or face detection purposes, please cite these publications:
+
+```BibTeX
+@article{serengil2024lightface,
+  title     = {A Benchmark of Facial Recognition Pipelines and Co-Usability Performances of Modules},
+  author    = {Serengil, Sefik and Ozpinar, Alper},
+  journal   = {Journal of Information Technologies},
+  volume    = {17},
+  number    = {2},
+  pages     = {95-107},
+  year      = {2024},
+  doi       = {10.17671/gazibtd.1399077},
+  url       = {https://dergipark.org.tr/en/pub/gazibtd/issue/84331/1399077},
+  publisher = {Gazi University}
+}
+```
+
+```BibTeX
+@inproceedings{serengil2020lightface,
+  title        = {LightFace: A Hybrid Deep Face Recognition Framework},
+  author       = {Serengil, Sefik Ilkin and Ozpinar, Alper},
+  booktitle    = {2020 Innovations in Intelligent Systems and Applications Conference (ASYU)},
+  pages        = {23-27},
+  year         = {2020},
+  doi          = {10.1109/ASYU50717.2020.9259802},
+  url          = {https://ieeexplore.ieee.org/document/9259802},
+  organization = {IEEE}
+}
+```
+
+On the other hand, if you use deepface in your research for facial attribute analysis purposes such as age, gender, emotion or ethnicity prediction tasks, please cite this publication.
+
+```BibTeX
+@inproceedings{serengil2021lightface,
+  title        = {HyperExtended LightFace: A Facial Attribute Analysis Framework},
+  author       = {Serengil, Sefik Ilkin and Ozpinar, Alper},
+  booktitle    = {2021 International Conference on Engineering and Emerging Technologies (ICEET)},
+  pages        = {1-4},
+  year         = {2021},
+  doi          = {10.1109/ICEET53442.2021.9659697},
+  url          = {https://ieeexplore.ieee.org/document/9659697},
+  organization = {IEEE}
+}
+```
+
+Also, if you use deepface in your GitHub projects, please add `deepface` in the `requirements.txt`.
+
+## Licence
+
+DeepFace is licensed under the MIT License - see [`LICENSE`](https://github.com/serengil/deepface/blob/master/LICENSE) for more details.
+
+DeepFace wraps some external face recognition models: [VGG-Face](http://www.robots.ox.ac.uk/~vgg/software/vgg_face/), [Facenet](https://github.com/davidsandberg/facenet/blob/master/LICENSE.md) (both 128d and 512d), [OpenFace](https://github.com/iwantooxxoox/Keras-OpenFace/blob/master/LICENSE), [DeepFace](https://github.com/swghosh/DeepFace), [DeepID](https://github.com/Ruoyiran/DeepID/blob/master/LICENSE.md), [ArcFace](https://github.com/leondgarse/Keras_insightface/blob/master/LICENSE), [Dlib](https://github.com/davisking/dlib/blob/master/dlib/LICENSE.txt), [SFace](https://github.com/opencv/opencv_zoo/blob/master/models/face_recognition_sface/LICENSE) and [GhostFaceNet](https://github.com/HamadYA/GhostFaceNets/blob/main/LICENSE). Besides, age, gender and race / ethnicity models were trained on the backbone of VGG-Face with transfer learning. Similarly, DeepFace wraps many face detectors: [OpenCv](https://github.com/opencv/opencv/blob/4.x/LICENSE), [Ssd](https://github.com/opencv/opencv/blob/master/LICENSE), [Dlib](https://github.com/davisking/dlib/blob/master/LICENSE.txt), [MtCnn](https://github.com/ipazc/mtcnn/blob/master/LICENSE), [Fast MtCnn](https://github.com/timesler/facenet-pytorch/blob/master/LICENSE.md), [RetinaFace](https://github.com/serengil/retinaface/blob/master/LICENSE), [MediaPipe](https://github.com/google/mediapipe/blob/master/LICENSE), [YuNet](https://github.com/ShiqiYu/libfacedetection/blob/master/LICENSE), [Yolo](https://github.com/derronqi/yolov8-face/blob/main/LICENSE) and [CenterFace](https://github.com/Star-Clouds/CenterFace/blob/master/LICENSE). Finally, DeepFace is optionally using [face anti spoofing](https://github.com/minivision-ai/Silent-Face-Anti-Spoofing/blob/master/LICENSE) to determine the given images are real or fake. License types will be inherited when you intend to utilize those models. Please check the license types of those models for production purposes.
+
+DeepFace [logo](https://thenounproject.com/term/face-recognition/2965879/) is created by [Adrien Coquet](https://thenounproject.com/coquet_adrien/) and it is licensed under [Creative Commons: By Attribution 3.0 License](https://creativecommons.org/licenses/by/3.0/).

deepface/benchmarks/Perform-Experiments.ipynb

@@ -0,0 +1,352 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "8133a99d",
+   "metadata": {},
+   "source": [
+    "# Perform Experiments with DeepFace on LFW dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "5aab0cbe",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# built-in dependencies\n",
+    "import os\n",
+    "\n",
+    "# 3rd party dependencies\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "from tqdm import tqdm\n",
+    "import matplotlib.pyplot as plt\n",
+    "from sklearn.metrics import accuracy_score\n",
+    "from sklearn.datasets import fetch_lfw_pairs\n",
+    "from deepface import DeepFace"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "64c9ed9a",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "This experiment is done with pip package of deepface with 0.0.90 version\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(f\"This experiment is done with pip package of deepface with {DeepFace.__version__} version\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "feaec973",
+   "metadata": {},
+   "source": [
+    "### Configuration Sets"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "453104b4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# all configuration alternatives for 4 dimensions of arguments\n",
+    "alignment = [True, False]\n",
+    "models = [\"Facenet512\", \"Facenet\", \"VGG-Face\", \"ArcFace\", \"Dlib\", \"GhostFaceNet\", \"SFace\", \"OpenFace\", \"DeepFace\", \"DeepID\"]\n",
+    "detectors = [\"retinaface\", \"mtcnn\", \"fastmtcnn\", \"dlib\", \"yolov8\", \"yunet\", \"centerface\", \"mediapipe\", \"ssd\", \"opencv\", \"skip\"]\n",
+    "metrics = [\"euclidean\", \"euclidean_l2\", \"cosine\"]\n",
+    "expand_percentage = 0"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c9aeb57a",
+   "metadata": {},
+   "source": [
+    "### Create Required Folders if necessary"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "671d8a00",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "target_paths = [\"lfwe\", \"dataset\", \"outputs\", \"outputs/test\", \"results\"]\n",
+    "for target_path in target_paths:\n",
+    "    if not os.path.exists(target_path):\n",
+    "        os.mkdir(target_path)\n",
+    "        print(f\"{target_path} is just created\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fc31f03a",
+   "metadata": {},
+   "source": [
+    "### Load LFW Dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "721a7d70",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pairs_touch = \"outputs/test_lfwe.txt\"\n",
+    "instances = 1000 #pairs.shape[0]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "010184d8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "target_path = \"dataset/test_lfw.npy\"\n",
+    "labels_path = \"dataset/test_labels.npy\"\n",
+    "\n",
+    "if os.path.exists(target_path) != True:\n",
+    "    fetch_lfw_pairs = fetch_lfw_pairs(subset = 'test', color = True\n",
+    "                                  , resize = 2\n",
+    "                                  , funneled = False\n",
+    "                                  , slice_=None\n",
+    "                                 )\n",
+    "    pairs = fetch_lfw_pairs.pairs\n",
+    "    labels = fetch_lfw_pairs.target\n",
+    "    target_names = fetch_lfw_pairs.target_names\n",
+    "    np.save(target_path, pairs)\n",
+    "    np.save(labels_path, labels)\n",
+    "else:\n",
+    "    if not os.path.exists(pairs_touch):\n",
+    "        # loading pairs takes some time. but if we extract these pairs as image, no need to load it anymore\n",
+    "        pairs = np.load(target_path)\n",
+    "    labels = np.load(labels_path)    "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "005f582e",
+   "metadata": {},
+   "source": [
+    "### Save LFW image pairs into file system"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "5bc23313",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "100%|██████████| 1000/1000 [00:00<00:00, 190546.25it/s]\n"
+     ]
+    }
+   ],
+   "source": [
+    "for i in tqdm(range(0, instances)):\n",
+    "    img1_target = f\"lfwe/test/{i}_1.jpg\"\n",
+    "    img2_target = f\"lfwe/test/{i}_2.jpg\"\n",
+    "    \n",
+    "    if not os.path.exists(img1_target):\n",
+    "        img1 = pairs[i][0]\n",
+    "        # plt.imsave(img1_target, img1/255) #works for my mac\n",
+    "        plt.imsave(img1_target, img1) #works for my debian\n",
+    "    \n",
+    "    if not os.path.exists(img2_target):\n",
+    "        img2 = pairs[i][1]\n",
+    "        # plt.imsave(img2_target, img2/255) #works for my mac\n",
+    "        plt.imsave(img2_target, img2) #works for my debian\n",
+    "    \n",
+    "if not os.path.exists(pairs_touch):\n",
+    "    open(pairs_touch,'a').close()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6f8fa8fa",
+   "metadata": {},
+   "source": [
+    "### Perform Experiments\n",
+    "\n",
+    "This block will save the experiments results in outputs folder"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "e7fba936",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for model_name in models:\n",
+    "    for detector_backend in detectors:\n",
+    "        for distance_metric in metrics:\n",
+    "            for align in alignment:\n",
+    "                \n",
+    "                if detector_backend == \"skip\" and align is True:\n",
+    "                    # Alignment is not possible for a skipped detector configuration\n",
+    "                    continue\n",
+    "                \n",
+    "                alignment_text = \"aligned\" if align is True else \"unaligned\"\n",
+    "                task = f\"{model_name}_{detector_backend}_{distance_metric}_{alignment_text}\"\n",
+    "                output_file = f\"outputs/test/{task}.csv\"\n",
+    "                if os.path.exists(output_file):\n",
+    "                     #print(f\"{output_file} is available already\")\n",
+    "                     continue\n",
+    "                \n",
+    "                distances = []\n",
+    "                for i in tqdm(range(0, instances), desc = task):\n",
+    "                    img1_target = f\"lfwe/test/{i}_1.jpg\"\n",
+    "                    img2_target = f\"lfwe/test/{i}_2.jpg\"\n",
+    "                    result = DeepFace.verify(\n",
+    "                        img1_path=img1_target,\n",
+    "                        img2_path=img2_target,\n",
+    "                        model_name=model_name,\n",
+    "                        detector_backend=detector_backend,\n",
+    "                        distance_metric=distance_metric,\n",
+    "                        align=align,\n",
+    "                        enforce_detection=False,\n",
+    "                        expand_percentage=expand_percentage,\n",
+    "                    )\n",
+    "                    distance = result[\"distance\"]\n",
+    "                    distances.append(distance)\n",
+    "                # -----------------------------------\n",
+    "                df = pd.DataFrame(list(labels), columns = [\"actuals\"])\n",
+    "                df[\"distances\"] = distances\n",
+    "                df.to_csv(output_file, index=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a0b8dafa",
+   "metadata": {},
+   "source": [
+    "### Calculate Results\n",
+    "\n",
+    "Experiments were responsible for calculating distances. We will calculate the best accuracy scores in this block."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "67376e76",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = [[0 for _ in range(len(models))] for _ in range(len(detectors))]\n",
+    "base_df = pd.DataFrame(data, columns=models, index=detectors)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "f2cc536b",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "results/pivot_euclidean_with_alignment_True.csv saved\n",
+      "results/pivot_euclidean_l2_with_alignment_True.csv saved\n",
+      "results/pivot_cosine_with_alignment_True.csv saved\n",
+      "results/pivot_euclidean_with_alignment_False.csv saved\n",
+      "results/pivot_euclidean_l2_with_alignment_False.csv saved\n",
+      "results/pivot_cosine_with_alignment_False.csv saved\n"
+     ]
+    }
+   ],
+   "source": [
+    "for is_aligned in alignment:\n",
+    "    for distance_metric in metrics:\n",
+    "\n",
+    "        current_df = base_df.copy()\n",
+    "        \n",
+    "        target_file = f\"results/pivot_{distance_metric}_with_alignment_{is_aligned}.csv\"\n",
+    "        if os.path.exists(target_file):\n",
+    "            continue\n",
+    "        \n",
+    "        for model_name in models:\n",
+    "            for detector_backend in detectors:\n",
+    "\n",
+    "                align = \"aligned\" if is_aligned is True else \"unaligned\"\n",
+    "\n",
+    "                if detector_backend == \"skip\" and is_aligned is True:\n",
+    "                    # Alignment is not possible for a skipped detector configuration\n",
+    "                    align = \"unaligned\"\n",
+    "\n",
+    "                source_file = f\"outputs/test/{model_name}_{detector_backend}_{distance_metric}_{align}.csv\"\n",
+    "                df = pd.read_csv(source_file)\n",
+    "                  \n",
+    "                positive_mean = df[(df[\"actuals\"] == True) | (df[\"actuals\"] == 1)][\"distances\"].mean()\n",
+    "                negative_mean = df[(df[\"actuals\"] == False) | (df[\"actuals\"] == 0)][\"distances\"].mean()\n",
+    "\n",
+    "                distances = sorted(df[\"distances\"].values.tolist())\n",
+    "\n",
+    "                items = []\n",
+    "                for i, distance in enumerate(distances):\n",
+    "                    if distance >= positive_mean and distance <= negative_mean:\n",
+    "                        sandbox_df = df.copy()\n",
+    "                        sandbox_df[\"predictions\"] = False\n",
+    "                        idx = sandbox_df[sandbox_df[\"distances\"] < distance].index\n",
+    "                        sandbox_df.loc[idx, \"predictions\"] = True\n",
+    "\n",
+    "                        actuals = sandbox_df.actuals.values.tolist()\n",
+    "                        predictions = sandbox_df.predictions.values.tolist()\n",
+    "                        accuracy = 100*accuracy_score(actuals, predictions)\n",
+    "                        items.append((distance, accuracy))\n",
+    "\n",
+    "                pivot_df = pd.DataFrame(items, columns = [\"distance\", \"accuracy\"])\n",
+    "                pivot_df = pivot_df.sort_values(by = [\"accuracy\"], ascending = False)\n",
+    "                threshold = pivot_df.iloc[0][\"distance\"]\n",
+    "                # print(f\"threshold for {model_name}/{detector_backend} is {threshold}\")\n",
+    "                accuracy = pivot_df.iloc[0][\"accuracy\"]\n",
+    "\n",
+    "                # print(source_file, round(accuracy, 1))\n",
+    "                current_df.at[detector_backend, model_name] = round(accuracy, 1)\n",
+    "        \n",
+    "        current_df.to_csv(target_file)\n",
+    "        print(f\"{target_file} saved\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.16"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

deepface/benchmarks/README.md

@@ -0,0 +1,134 @@
+# Benchmarks
+
+[`🎥 Video Tutorial`](https://youtu.be/eKOZawGR3y0)
+
+DeepFace offers various configurations that significantly impact accuracy, including the facial recognition model, face detector model, distance metric, and alignment mode. Our experiments conducted on the [LFW dataset](https://sefiks.com/2020/08/27/labeled-faces-in-the-wild-for-face-recognition/) using different combinations of these configurations yield the following results.
+
+You can reproduce the results by executing the `Perform-Experiments.ipynb` and `Evaluate-Results.ipynb` notebooks, respectively.
+
+## ROC Curves
+
+ROC curves provide a valuable means of evaluating the performance of different models on a broader scale. The following illusration shows ROC curves for different facial recognition models alongside their optimal configurations yielding the highest accuracy scores.
+
+<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/benchmarks.jpg" width="95%" height="95%"></p>
+
+In summary, FaceNet-512d surpasses human-level accuracy, while FaceNet-128d reaches it, with Dlib, VGG-Face, and ArcFace closely trailing but slightly below, and GhostFaceNet and SFace making notable contributions despite not leading, while OpenFace, DeepFace, and DeepId exhibit lower performance.
+
+## Accuracy Scores
+
+Please note that humans achieve a 97.5% accuracy score on the same dataset. Configurations that outperform this benchmark are highlighted in bold.
+
+## Performance Matrix for euclidean while alignment is True
+
+| | Facenet512 |Facenet |VGG-Face |ArcFace |Dlib |GhostFaceNet |SFace |OpenFace |DeepFace |DeepID |
+| --- |  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| retinaface |95.9 |93.5 |95.8 |85.2 |88.9 |85.9 |80.2 |69.4 |67.0 |65.6 |
+| mtcnn |95.2 |93.8 |95.9 |83.7 |89.4 |83.0 |77.4 |70.2 |66.5 |63.3 |
+| fastmtcnn |96.0 |93.4 |95.8 |83.5 |91.1 |82.8 |77.7 |69.4 |66.7 |64.0 |
+| dlib |96.0 |90.8 |94.5 |88.6 |96.8 |65.7 |66.3 |75.8 |63.4 |60.4 |
+| yolov8 |94.4 |91.9 |95.0 |84.1 |89.2 |77.6 |73.4 |68.7 |69.0 |66.5 |
+| yunet |97.3 |96.1 |96.0 |84.9 |92.2 |84.0 |79.4 |70.9 |65.8 |65.2 |
+| centerface |**97.6** |95.8 |95.7 |83.6 |90.4 |82.8 |77.4 |68.9 |65.5 |62.8 |
+| mediapipe |95.1 |88.6 |92.9 |73.2 |93.1 |63.2 |72.5 |78.7 |61.8 |62.2 |
+| ssd |88.9 |85.6 |87.0 |75.8 |83.1 |79.1 |76.9 |66.8 |63.4 |62.5 |
+| opencv |88.2 |84.2 |87.3 |73.0 |84.4 |83.8 |81.1 |66.4 |65.5 |59.6 |
+| skip |92.0 |64.1 |90.6 |56.6 |69.0 |75.1 |81.4 |57.4 |60.8 |60.7 |
+
+## Performance Matrix for euclidean while alignment is False
+
+| | Facenet512 |Facenet |VGG-Face |ArcFace |Dlib |GhostFaceNet |SFace |OpenFace |DeepFace |DeepID |
+| --- |  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| retinaface |96.1 |92.8 |95.7 |84.1 |88.3 |83.2 |78.6 |70.8 |67.4 |64.3 |
+| mtcnn |95.9 |92.5 |95.5 |81.8 |89.3 |83.2 |76.3 |70.9 |65.9 |63.2 |
+| fastmtcnn |96.3 |93.0 |96.0 |82.2 |90.0 |82.7 |76.8 |71.2 |66.5 |64.3 |
+| dlib |96.0 |89.0 |94.1 |82.6 |96.3 |65.6 |73.1 |75.9 |61.8 |61.9 |
+| yolov8 |94.8 |90.8 |95.2 |83.2 |88.4 |77.6 |71.6 |68.9 |68.2 |66.3 |
+| yunet |**97.9** |96.5 |96.3 |84.1 |91.4 |82.7 |78.2 |71.7 |65.5 |65.2 |
+| centerface |97.4 |95.4 |95.8 |83.2 |90.3 |82.0 |76.5 |69.9 |65.7 |62.9 |
+| mediapipe |94.9 |87.1 |93.1 |71.1 |91.9 |61.9 |73.2 |77.6 |61.7 |62.4 |
+| ssd |97.2 |94.9 |96.7 |83.9 |88.6 |84.9 |82.0 |69.9 |66.7 |64.0 |
+| opencv |94.1 |90.2 |95.8 |89.8 |91.2 |91.0 |86.9 |71.1 |68.4 |61.1 |
+| skip |92.0 |64.1 |90.6 |56.6 |69.0 |75.1 |81.4 |57.4 |60.8 |60.7 |
+
+## Performance Matrix for euclidean_l2 while alignment is True
+
+| | Facenet512 |Facenet |VGG-Face |ArcFace |Dlib |GhostFaceNet |SFace |OpenFace |DeepFace |DeepID |
+| --- |  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| retinaface |**98.4** |96.4 |95.8 |96.6 |89.1 |90.5 |92.4 |69.4 |67.7 |64.4 |
+| mtcnn |**97.6** |96.8 |95.9 |96.0 |90.0 |89.8 |90.5 |70.2 |66.4 |64.0 |
+| fastmtcnn |**98.1** |97.2 |95.8 |96.4 |91.0 |89.5 |90.0 |69.4 |67.4 |64.1 |
+| dlib |97.0 |92.6 |94.5 |95.1 |96.4 |63.3 |69.8 |75.8 |66.5 |59.5 |
+| yolov8 |97.3 |95.7 |95.0 |95.5 |88.8 |88.9 |91.9 |68.7 |67.5 |66.0 |
+| yunet |**97.9** |97.4 |96.0 |96.7 |91.6 |89.1 |91.0 |70.9 |66.5 |63.6 |
+| centerface |**97.7** |96.8 |95.7 |96.5 |90.9 |87.5 |89.3 |68.9 |67.8 |64.0 |
+| mediapipe |96.1 |90.6 |92.9 |90.3 |92.6 |64.4 |75.4 |78.7 |64.7 |63.0 |
+| ssd |88.7 |87.5 |87.0 |86.2 |83.3 |82.2 |84.6 |66.8 |64.1 |62.6 |
+| opencv |87.6 |84.8 |87.3 |84.6 |84.0 |85.0 |83.6 |66.4 |63.8 |60.9 |
+| skip |91.4 |67.6 |90.6 |57.2 |69.3 |78.4 |83.4 |57.4 |62.6 |61.6 |
+
+## Performance Matrix for euclidean_l2 while alignment is False
+
+| | Facenet512 |Facenet |VGG-Face |ArcFace |Dlib |GhostFaceNet |SFace |OpenFace |DeepFace |DeepID |
+| --- |  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| retinaface |**98.0** |95.9 |95.7 |95.7 |88.4 |89.5 |90.6 |70.8 |67.7 |64.6 |
+| mtcnn |**97.8** |96.2 |95.5 |95.9 |89.2 |88.0 |91.1 |70.9 |67.0 |64.0 |
+| fastmtcnn |**97.7** |96.6 |96.0 |95.9 |89.6 |87.8 |89.7 |71.2 |67.8 |64.2 |
+| dlib |96.5 |89.9 |94.1 |93.8 |95.6 |63.0 |75.0 |75.9 |62.6 |61.8 |
+| yolov8 |**97.7** |95.8 |95.2 |95.0 |88.1 |88.7 |89.8 |68.9 |68.9 |65.3 |
+| yunet |**98.3** |96.8 |96.3 |96.1 |91.7 |88.0 |90.5 |71.7 |67.6 |63.2 |
+| centerface |97.4 |96.3 |95.8 |95.8 |90.2 |86.8 |89.3 |69.9 |68.4 |63.1 |
+| mediapipe |96.3 |90.0 |93.1 |89.3 |91.8 |65.6 |74.6 |77.6 |64.9 |61.6 |
+| ssd |**97.9** |97.0 |96.7 |96.6 |89.4 |91.5 |93.0 |69.9 |68.7 |64.9 |
+| opencv |96.2 |92.9 |95.8 |93.2 |91.5 |93.3 |91.7 |71.1 |68.3 |61.6 |
+| skip |91.4 |67.6 |90.6 |57.2 |69.3 |78.4 |83.4 |57.4 |62.6 |61.6 |
+
+## Performance Matrix for cosine while alignment is True
+
+| | Facenet512 |Facenet |VGG-Face |ArcFace |Dlib |GhostFaceNet |SFace |OpenFace |DeepFace |DeepID |
+| --- |  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| retinaface |**98.4** |96.4 |95.8 |96.6 |89.1 |90.5 |92.4 |69.4 |67.7 |64.4 |
+| mtcnn |**97.6** |96.8 |95.9 |96.0 |90.0 |89.8 |90.5 |70.2 |66.3 |63.0 |
+| fastmtcnn |**98.1** |97.2 |95.8 |96.4 |91.0 |89.5 |90.0 |69.4 |67.4 |63.6 |
+| dlib |97.0 |92.6 |94.5 |95.1 |96.4 |63.3 |69.8 |75.8 |66.5 |58.7 |
+| yolov8 |97.3 |95.7 |95.0 |95.5 |88.8 |88.9 |91.9 |68.7 |67.5 |65.9 |
+| yunet |**97.9** |97.4 |96.0 |96.7 |91.6 |89.1 |91.0 |70.9 |66.5 |63.5 |
+| centerface |**97.7** |96.8 |95.7 |96.5 |90.9 |87.5 |89.3 |68.9 |67.8 |63.6 |
+| mediapipe |96.1 |90.6 |92.9 |90.3 |92.6 |64.3 |75.4 |78.7 |64.8 |63.0 |
+| ssd |88.7 |87.5 |87.0 |86.2 |83.3 |82.2 |84.5 |66.8 |63.8 |62.6 |
+| opencv |87.6 |84.9 |87.2 |84.6 |84.0 |85.0 |83.6 |66.2 |63.7 |60.1 |
+| skip |91.4 |67.6 |90.6 |54.8 |69.3 |78.4 |83.4 |57.4 |62.6 |61.1 |
+
+## Performance Matrix for cosine while alignment is False
+
+| | Facenet512 |Facenet |VGG-Face |ArcFace |Dlib |GhostFaceNet |SFace |OpenFace |DeepFace |DeepID |
+| --- |  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| retinaface |**98.0** |95.9 |95.7 |95.7 |88.4 |89.5 |90.6 |70.8 |67.7 |63.7 |
+| mtcnn |**97.8** |96.2 |95.5 |95.9 |89.2 |88.0 |91.1 |70.9 |67.0 |64.0 |
+| fastmtcnn |**97.7** |96.6 |96.0 |95.9 |89.6 |87.8 |89.7 |71.2 |67.8 |62.7 |
+| dlib |96.5 |89.9 |94.1 |93.8 |95.6 |63.0 |75.0 |75.9 |62.6 |61.7 |
+| yolov8 |**97.7** |95.8 |95.2 |95.0 |88.1 |88.7 |89.8 |68.9 |68.9 |65.3 |
+| yunet |**98.3** |96.8 |96.3 |96.1 |91.7 |88.0 |90.5 |71.7 |67.6 |63.2 |
+| centerface |97.4 |96.3 |95.8 |95.8 |90.2 |86.8 |89.3 |69.9 |68.4 |62.6 |
+| mediapipe |96.3 |90.0 |93.1 |89.3 |91.8 |64.8 |74.6 |77.6 |64.9 |61.6 |
+| ssd |**97.9** |97.0 |96.7 |96.6 |89.4 |91.5 |93.0 |69.9 |68.7 |63.8 |
+| opencv |96.2 |92.9 |95.8 |93.2 |91.5 |93.3 |91.7 |71.1 |68.1 |61.1 |
+| skip |91.4 |67.6 |90.6 |54.8 |69.3 |78.4 |83.4 |57.4 |62.6 |61.1 |
+
+# Citation
+
+Please cite deepface in your publications if it helps your research - see [`CITATIONS`](https://github.com/serengil/deepface/blob/master/CITATION.md) for more details. Here is its BibTex entry:
+
+```BibTeX
+@article{serengil2024lightface,
+  title         = {A Benchmark of Facial Recognition Pipelines and Co-Usability Performances of Modules},
+  author        = {Serengil, Sefik Ilkin and Ozpinar, Alper},
+  journal       = {Bilisim Teknolojileri Dergisi},
+  volume        = {17},
+  number        = {2},
+  pages         = {95-107},
+  year          = {2024},
+  doi           = {10.17671/gazibtd.1399077},
+  url           = {https://dergipark.org.tr/en/pub/gazibtd/issue/84331/1399077},
+  publisher     = {Gazi University}
+}
+```

deepface/deepface/DeepFace.py

@@ -0,0 +1,615 @@
+# common dependencies
+import os
+import warnings
+import logging
+from typing import Any, Dict, List, Union, Optional
+
+# this has to be set before importing tensorflow
+os.environ["TF_USE_LEGACY_KERAS"] = "1"
+
+# pylint: disable=wrong-import-position
+
+# 3rd party dependencies
+import numpy as np
+import pandas as pd
+import tensorflow as tf
+
+# package dependencies
+from deepface.commons import package_utils, folder_utils
+from deepface.commons.logger import Logger
+from deepface.modules import (
+    modeling,
+    representation,
+    verification,
+    recognition,
+    demography,
+    detection,
+    streaming,
+    preprocessing,
+)
+from deepface import __version__
+
+logger = Logger()
+
+# -----------------------------------
+# configurations for dependencies
+
+# users should install tf_keras package if they are using tf 2.16 or later versions
+package_utils.validate_for_keras3()
+
+warnings.filterwarnings("ignore")
+os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"
+tf_version = package_utils.get_tf_major_version()
+if tf_version == 2:
+    tf.get_logger().setLevel(logging.ERROR)
+# -----------------------------------
+
+# create required folders if necessary to store model weights
+folder_utils.initialize_folder()
+
+
+def build_model(model_name: str, task: str = "facial_recognition") -> Any:
+    """
+    This function builds a pre-trained model
+    Args:
+        model_name (str): model identifier
+            - VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, Dlib,
+                ArcFace, SFace, GhostFaceNet for face recognition
+            - Age, Gender, Emotion, Race for facial attributes
+            - opencv, mtcnn, ssd, dlib, retinaface, mediapipe, yolov8, yunet,
+                fastmtcnn or centerface for face detectors
+            - Fasnet for spoofing
+        task (str): facial_recognition, facial_attribute, face_detector, spoofing
+            default is facial_recognition
+    Returns:
+        built_model
+    """
+    return modeling.build_model(task=task, model_name=model_name)
+
+
+def verify(
+    img1_path: Union[str, np.ndarray, List[float]],
+    img2_path: Union[str, np.ndarray, List[float]],
+    model_name: str = "VGG-Face",
+    detector_backend: str = "opencv",
+    distance_metric: str = "cosine",
+    enforce_detection: bool = True,
+    align: bool = True,
+    expand_percentage: int = 0,
+    normalization: str = "base",
+    silent: bool = False,
+    threshold: Optional[float] = None,
+    anti_spoofing: bool = False,
+) -> Dict[str, Any]:
+    """
+    Verify if an image pair represents the same person or different persons.
+    Args:
+        img1_path (str or np.ndarray or List[float]): Path to the first image.
+            Accepts exact image path as a string, numpy array (BGR), base64 encoded images
+            or pre-calculated embeddings.
+
+        img2_path (str or np.ndarray or List[float]): Path to the second image.
+            Accepts exact image path as a string, numpy array (BGR), base64 encoded images
+            or pre-calculated embeddings.
+
+        model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
+            OpenFace, DeepFace, DeepID, Dlib, ArcFace, SFace and GhostFaceNet (default is VGG-Face).
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8', 'centerface' or 'skip'
+            (default is opencv).
+
+        distance_metric (string): Metric for measuring similarity. Options: 'cosine',
+            'euclidean', 'euclidean_l2' (default is cosine).
+
+        enforce_detection (boolean): If no face is detected in an image, raise an exception.
+            Set to False to avoid the exception for low-resolution images (default is True).
+
+        align (bool): Flag to enable face alignment (default is True).
+
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
+        normalization (string): Normalize the input image before feeding it to the model.
+            Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace (default is base)
+
+        silent (boolean): Suppress or allow some log messages for a quieter analysis process
+            (default is False).
+
+        threshold (float): Specify a threshold to determine whether a pair represents the same
+            person or different individuals. This threshold is used for comparing distances.
+            If left unset, default pre-tuned threshold values will be applied based on the specified
+            model name and distance metric (default is None).
+
+        anti_spoofing (boolean): Flag to enable anti spoofing (default is False).
+
+    Returns:
+        result (dict): A dictionary containing verification results with following keys.
+
+        - 'verified' (bool): Indicates whether the images represent the same person (True)
+            or different persons (False).
+
+        - 'distance' (float): The distance measure between the face vectors.
+            A lower distance indicates higher similarity.
+
+        - 'threshold' (float): The maximum threshold used for verification.
+            If the distance is below this threshold, the images are considered a match.
+
+        - 'model' (str): The chosen face recognition model.
+
+        - 'distance_metric' (str): The chosen similarity metric for measuring distances.
+
+        - 'facial_areas' (dict): Rectangular regions of interest for faces in both images.
+            - 'img1': {'x': int, 'y': int, 'w': int, 'h': int}
+                    Region of interest for the first image.
+            - 'img2': {'x': int, 'y': int, 'w': int, 'h': int}
+                    Region of interest for the second image.
+
+        - 'time' (float): Time taken for the verification process in seconds.
+    """
+
+    return verification.verify(
+        img1_path=img1_path,
+        img2_path=img2_path,
+        model_name=model_name,
+        detector_backend=detector_backend,
+        distance_metric=distance_metric,
+        enforce_detection=enforce_detection,
+        align=align,
+        expand_percentage=expand_percentage,
+        normalization=normalization,
+        silent=silent,
+        threshold=threshold,
+        anti_spoofing=anti_spoofing,
+    )
+
+
+def analyze(
+    img_path: Union[str, np.ndarray],
+    actions: Union[tuple, list] = ("emotion", "age", "gender", "race"),
+    enforce_detection: bool = True,
+    detector_backend: str = "opencv",
+    align: bool = True,
+    expand_percentage: int = 0,
+    silent: bool = False,
+    anti_spoofing: bool = False,
+) -> List[Dict[str, Any]]:
+    """
+    Analyze facial attributes such as age, gender, emotion, and race in the provided image.
+    Args:
+        img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
+            or a base64 encoded image. If the source image contains multiple faces, the result will
+            include information for each detected face.
+
+        actions (tuple): Attributes to analyze. The default is ('age', 'gender', 'emotion', 'race').
+            You can exclude some of these attributes from the analysis if needed.
+
+        enforce_detection (boolean): If no face is detected in an image, raise an exception.
+            Set to False to avoid the exception for low-resolution images (default is True).
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8', 'centerface' or 'skip'
+            (default is opencv).
+
+        distance_metric (string): Metric for measuring similarity. Options: 'cosine',
+            'euclidean', 'euclidean_l2' (default is cosine).
+
+        align (boolean): Perform alignment based on the eye positions (default is True).
+
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
+        silent (boolean): Suppress or allow some log messages for a quieter analysis process
+            (default is False).
+
+        anti_spoofing (boolean): Flag to enable anti spoofing (default is False).
+
+    Returns:
+        results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary represents
+           the analysis results for a detected face. Each dictionary in the list contains the
+           following keys:
+
+        - 'region' (dict): Represents the rectangular region of the detected face in the image.
+            - 'x': x-coordinate of the top-left corner of the face.
+            - 'y': y-coordinate of the top-left corner of the face.
+            - 'w': Width of the detected face region.
+            - 'h': Height of the detected face region.
+
+        - 'age' (float): Estimated age of the detected face.
+
+        - 'face_confidence' (float): Confidence score for the detected face.
+            Indicates the reliability of the face detection.
+
+        - 'dominant_gender' (str): The dominant gender in the detected face.
+            Either "Man" or "Woman".
+
+        - 'gender' (dict): Confidence scores for each gender category.
+            - 'Man': Confidence score for the male gender.
+            - 'Woman': Confidence score for the female gender.
+
+        - 'dominant_emotion' (str): The dominant emotion in the detected face.
+            Possible values include "sad," "angry," "surprise," "fear," "happy,"
+            "disgust," and "neutral"
+
+        - 'emotion' (dict): Confidence scores for each emotion category.
+            - 'sad': Confidence score for sadness.
+            - 'angry': Confidence score for anger.
+            - 'surprise': Confidence score for surprise.
+            - 'fear': Confidence score for fear.
+            - 'happy': Confidence score for happiness.
+            - 'disgust': Confidence score for disgust.
+            - 'neutral': Confidence score for neutrality.
+
+        - 'dominant_race' (str): The dominant race in the detected face.
+            Possible values include "indian," "asian," "latino hispanic,"
+            "black," "middle eastern," and "white."
+
+        - 'race' (dict): Confidence scores for each race category.
+            - 'indian': Confidence score for Indian ethnicity.
+            - 'asian': Confidence score for Asian ethnicity.
+            - 'latino hispanic': Confidence score for Latino/Hispanic ethnicity.
+            - 'black': Confidence score for Black ethnicity.
+            - 'middle eastern': Confidence score for Middle Eastern ethnicity.
+            - 'white': Confidence score for White ethnicity.
+    """
+    return demography.analyze(
+        img_path=img_path,
+        actions=actions,
+        enforce_detection=enforce_detection,
+        detector_backend=detector_backend,
+        align=align,
+        expand_percentage=expand_percentage,
+        silent=silent,
+        anti_spoofing=anti_spoofing,
+    )
+
+
+def find(
+    img_path: Union[str, np.ndarray],
+    db_path: str,
+    model_name: str = "VGG-Face",
+    distance_metric: str = "cosine",
+    enforce_detection: bool = True,
+    detector_backend: str = "opencv",
+    align: bool = True,
+    expand_percentage: int = 0,
+    threshold: Optional[float] = None,
+    normalization: str = "base",
+    silent: bool = False,
+    refresh_database: bool = True,
+    anti_spoofing: bool = False,
+) -> List[pd.DataFrame]:
+    """
+    Identify individuals in a database
+    Args:
+        img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
+            or a base64 encoded image. If the source image contains multiple faces, the result will
+            include information for each detected face.
+
+        db_path (string): Path to the folder containing image files. All detected faces
+            in the database will be considered in the decision-making process.
+
+        model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
+            OpenFace, DeepFace, DeepID, Dlib, ArcFace, SFace and GhostFaceNet (default is VGG-Face).
+
+        distance_metric (string): Metric for measuring similarity. Options: 'cosine',
+            'euclidean', 'euclidean_l2' (default is cosine).
+
+        enforce_detection (boolean): If no face is detected in an image, raise an exception.
+            Set to False to avoid the exception for low-resolution images (default is True).
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8', 'centerface' or 'skip'
+            (default is opencv).
+
+        align (boolean): Perform alignment based on the eye positions (default is True).
+
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
+        threshold (float): Specify a threshold to determine whether a pair represents the same
+            person or different individuals. This threshold is used for comparing distances.
+            If left unset, default pre-tuned threshold values will be applied based on the specified
+            model name and distance metric (default is None).
+
+        normalization (string): Normalize the input image before feeding it to the model.
+            Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace (default is base).
+
+        silent (boolean): Suppress or allow some log messages for a quieter analysis process
+            (default is False).
+
+        refresh_database (boolean): Synchronizes the images representation (pkl) file with the
+            directory/db files, if set to false, it will ignore any file changes inside the db_path
+            (default is True).
+
+        anti_spoofing (boolean): Flag to enable anti spoofing (default is False).
+
+    Returns:
+        results (List[pd.DataFrame]): A list of pandas dataframes. Each dataframe corresponds
+            to the identity information for an individual detected in the source image.
+            The DataFrame columns include:
+
+        - 'identity': Identity label of the detected individual.
+
+        - 'target_x', 'target_y', 'target_w', 'target_h': Bounding box coordinates of the
+                target face in the database.
+
+        - 'source_x', 'source_y', 'source_w', 'source_h': Bounding box coordinates of the
+                detected face in the source image.
+
+        - 'threshold': threshold to determine a pair whether same person or different persons
+
+        - 'distance': Similarity score between the faces based on the
+                specified model and distance metric
+    """
+    return recognition.find(
+        img_path=img_path,
+        db_path=db_path,
+        model_name=model_name,
+        distance_metric=distance_metric,
+        enforce_detection=enforce_detection,
+        detector_backend=detector_backend,
+        align=align,
+        expand_percentage=expand_percentage,
+        threshold=threshold,
+        normalization=normalization,
+        silent=silent,
+        refresh_database=refresh_database,
+        anti_spoofing=anti_spoofing,
+    )
+
+
+def represent(
+    img_path: Union[str, np.ndarray],
+    model_name: str = "VGG-Face",
+    enforce_detection: bool = True,
+    detector_backend: str = "opencv",
+    align: bool = True,
+    expand_percentage: int = 0,
+    normalization: str = "base",
+    anti_spoofing: bool = False,
+    max_faces: Optional[int] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Represent facial images as multi-dimensional vector embeddings.
+
+    Args:
+        img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
+            or a base64 encoded image. If the source image contains multiple faces, the result will
+            include information for each detected face.
+
+        model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
+            OpenFace, DeepFace, DeepID, Dlib, ArcFace, SFace and GhostFaceNet
+            (default is VGG-Face.).
+
+        enforce_detection (boolean): If no face is detected in an image, raise an exception.
+            Default is True. Set to False to avoid the exception for low-resolution images
+            (default is True).
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8', 'centerface' or 'skip'
+            (default is opencv).
+
+        align (boolean): Perform alignment based on the eye positions (default is True).
+
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
+        normalization (string): Normalize the input image before feeding it to the model.
+            Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
+            (default is base).
+
+        anti_spoofing (boolean): Flag to enable anti spoofing (default is False).
+
+        max_faces (int): Set a limit on the number of faces to be processed (default is None).
+
+    Returns:
+        results (List[Dict[str, Any]]): A list of dictionaries, each containing the
+            following fields:
+
+        - embedding (List[float]): Multidimensional vector representing facial features.
+            The number of dimensions varies based on the reference model
+            (e.g., FaceNet returns 128 dimensions, VGG-Face returns 4096 dimensions).
+
+        - facial_area (dict): Detected facial area by face detection in dictionary format.
+            Contains 'x' and 'y' as the left-corner point, and 'w' and 'h'
+            as the width and height. If `detector_backend` is set to 'skip', it represents
+            the full image area and is nonsensical.
+
+        - face_confidence (float): Confidence score of face detection. If `detector_backend` is set
+            to 'skip', the confidence will be 0 and is nonsensical.
+    """
+    return representation.represent(
+        img_path=img_path,
+        model_name=model_name,
+        enforce_detection=enforce_detection,
+        detector_backend=detector_backend,
+        align=align,
+        expand_percentage=expand_percentage,
+        normalization=normalization,
+        anti_spoofing=anti_spoofing,
+        max_faces=max_faces,
+    )
+
+
+def stream(
+    db_path: str = "",
+    model_name: str = "VGG-Face",
+    detector_backend: str = "opencv",
+    distance_metric: str = "cosine",
+    enable_face_analysis: bool = True,
+    source: Any = 0,
+    time_threshold: int = 5,
+    frame_threshold: int = 5,
+    anti_spoofing: bool = False,
+) -> None:
+    """
+    Run real time face recognition and facial attribute analysis
+
+    Args:
+        db_path (string): Path to the folder containing image files. All detected faces
+            in the database will be considered in the decision-making process.
+
+        model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
+            OpenFace, DeepFace, DeepID, Dlib, ArcFace, SFace and GhostFaceNet (default is VGG-Face).
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8', 'centerface' or 'skip'
+            (default is opencv).
+
+        distance_metric (string): Metric for measuring similarity. Options: 'cosine',
+            'euclidean', 'euclidean_l2' (default is cosine).
+
+        enable_face_analysis (bool): Flag to enable face analysis (default is True).
+
+        source (Any): The source for the video stream (default is 0, which represents the
+            default camera).
+
+        time_threshold (int): The time threshold (in seconds) for face recognition (default is 5).
+
+        frame_threshold (int): The frame threshold for face recognition (default is 5).
+
+        anti_spoofing (boolean): Flag to enable anti spoofing (default is False).
+    Returns:
+        None
+    """
+
+    time_threshold = max(time_threshold, 1)
+    frame_threshold = max(frame_threshold, 1)
+
+    streaming.analysis(
+        db_path=db_path,
+        model_name=model_name,
+        detector_backend=detector_backend,
+        distance_metric=distance_metric,
+        enable_face_analysis=enable_face_analysis,
+        source=source,
+        time_threshold=time_threshold,
+        frame_threshold=frame_threshold,
+        anti_spoofing=anti_spoofing,
+    )
+
+
+def extract_faces(
+    img_path: Union[str, np.ndarray],
+    detector_backend: str = "opencv",
+    enforce_detection: bool = True,
+    align: bool = True,
+    expand_percentage: int = 0,
+    grayscale: bool = False,
+    color_face: str = "rgb",
+    normalize_face: bool = True,
+    anti_spoofing: bool = False,
+) -> List[Dict[str, Any]]:
+    """
+    Extract faces from a given image
+
+    Args:
+        img_path (str or np.ndarray): Path to the first image. Accepts exact image path
+            as a string, numpy array (BGR), or base64 encoded images.
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8', 'centerface' or 'skip'
+            (default is opencv).
+
+        enforce_detection (boolean): If no face is detected in an image, raise an exception.
+            Set to False to avoid the exception for low-resolution images (default is True).
+
+        align (bool): Flag to enable face alignment (default is True).
+
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
+        grayscale (boolean): (Deprecated) Flag to convert the output face image to grayscale
+            (default is False).
+
+        color_face (string): Color to return face image output. Options: 'rgb', 'bgr' or 'gray'
+            (default is 'rgb').
+
+        normalize_face (boolean): Flag to enable normalization (divide by 255) of the output
+            face image output face image normalization (default is True).
+
+        anti_spoofing (boolean): Flag to enable anti spoofing (default is False).
+
+    Returns:
+        results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary contains:
+
+        - "face" (np.ndarray): The detected face as a NumPy array.
+
+        - "facial_area" (Dict[str, Any]): The detected face's regions as a dictionary containing:
+            - keys 'x', 'y', 'w', 'h' with int values
+            - keys 'left_eye', 'right_eye' with a tuple of 2 ints as values. left and right eyes
+                are eyes on the left and right respectively with respect to the person itself
+                instead of observer.
+
+        - "confidence" (float): The confidence score associated with the detected face.
+
+        - "is_real" (boolean): antispoofing analyze result. this key is just available in the
+            result only if anti_spoofing is set to True in input arguments.
+
+        - "antispoof_score" (float): score of antispoofing analyze result. this key is
+            just available in the result only if anti_spoofing is set to True in input arguments.
+    """
+
+    return detection.extract_faces(
+        img_path=img_path,
+        detector_backend=detector_backend,
+        enforce_detection=enforce_detection,
+        align=align,
+        expand_percentage=expand_percentage,
+        grayscale=grayscale,
+        color_face=color_face,
+        normalize_face=normalize_face,
+        anti_spoofing=anti_spoofing,
+    )
+
+
+def cli() -> None:
+    """
+    command line interface function will be offered in this block
+    """
+    import fire
+
+    fire.Fire()
+
+
+# deprecated function(s)
+
+
+def detectFace(
+    img_path: Union[str, np.ndarray],
+    target_size: tuple = (224, 224),
+    detector_backend: str = "opencv",
+    enforce_detection: bool = True,
+    align: bool = True,
+) -> Union[np.ndarray, None]:
+    """
+    Deprecated face detection function. Use extract_faces for same functionality.
+
+    Args:
+        img_path (str or np.ndarray): Path to the first image. Accepts exact image path
+            as a string, numpy array (BGR), or base64 encoded images.
+
+        target_size (tuple): final shape of facial image. black pixels will be
+            added to resize the image (default is (224, 224)).
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8', 'centerface' or 'skip'
+            (default is opencv).
+
+        enforce_detection (boolean): If no face is detected in an image, raise an exception.
+            Set to False to avoid the exception for low-resolution images (default is True).
+
+        align (bool): Flag to enable face alignment (default is True).
+
+    Returns:
+        img (np.ndarray): detected (and aligned) facial area image as numpy array
+    """
+    logger.warn("Function detectFace is deprecated. Use extract_faces instead.")
+    face_objs = extract_faces(
+        img_path=img_path,
+        detector_backend=detector_backend,
+        grayscale=False,
+        enforce_detection=enforce_detection,
+        align=align,
+    )
+    extracted_face = None
+    if len(face_objs) > 0:
+        extracted_face = face_objs[0]["face"]
+        extracted_face = preprocessing.resize_image(img=extracted_face, target_size=target_size)
+    return extracted_face

deepface/deepface/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.94"

deepface/deepface/api/postman/deepface-api.postman_collection.json

@@ -0,0 +1,102 @@
+{
+	"info": {
+		"_postman_id": "4c0b144e-4294-4bdd-8072-bcb326b1fed2",
+		"name": "deepface-api",
+		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+	},
+	"item": [
+		{
+			"name": "Represent",
+			"request": {
+				"method": "POST",
+				"header": [],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n  \"model_name\": \"Facenet\",\n  \"img\": \"/Users/sefik/Desktop/deepface/tests/dataset/img1.jpg\"\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "http://127.0.0.1:5000/represent",
+					"protocol": "http",
+					"host": [
+						"127",
+						"0",
+						"0",
+						"1"
+					],
+					"port": "5000",
+					"path": [
+						"represent"
+					]
+				}
+			},
+			"response": []
+		},
+		{
+			"name": "Face verification",
+			"request": {
+				"method": "POST",
+				"header": [],
+				"body": {
+					"mode": "raw",
+					"raw": "  {\n  \t\"img1_path\": \"/Users/sefik/Desktop/deepface/tests/dataset/img1.jpg\",\n    \"img2_path\": \"/Users/sefik/Desktop/deepface/tests/dataset/img2.jpg\",\n    \"model_name\": \"Facenet\",\n    \"detector_backend\": \"mtcnn\",\n    \"distance_metric\": \"euclidean\"\n  }",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "http://127.0.0.1:5000/verify",
+					"protocol": "http",
+					"host": [
+						"127",
+						"0",
+						"0",
+						"1"
+					],
+					"port": "5000",
+					"path": [
+						"verify"
+					]
+				}
+			},
+			"response": []
+		},
+		{
+			"name": "Face analysis",
+			"request": {
+				"method": "POST",
+				"header": [],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n    \"img_path\": \"/Users/sefik/Desktop/deepface/tests/dataset/couple.jpg\",\n    \"actions\": [\"age\", \"gender\", \"emotion\", \"race\"]\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "http://127.0.0.1:5000/analyze",
+					"protocol": "http",
+					"host": [
+						"127",
+						"0",
+						"0",
+						"1"
+					],
+					"port": "5000",
+					"path": [
+						"analyze"
+					]
+				}
+			},
+			"response": []
+		}
+	]
+}

deepface/deepface/api/src/api.py

@@ -0,0 +1,9 @@
+import argparse
+import app
+
+if __name__ == "__main__":
+    deepface_app = app.create_app()
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-p", "--port", type=int, default=5000, help="Port of serving api")
+    args = parser.parse_args()
+    deepface_app.run(host="0.0.0.0", port=args.port)

deepface/deepface/api/src/app.py

@@ -0,0 +1,18 @@
+# 3rd parth dependencies
+from flask import Flask
+from flask_cors import CORS
+
+# project dependencies
+from deepface import DeepFace
+from deepface.api.src.modules.core.routes import blueprint
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+
+def create_app():
+    app = Flask(__name__)
+    CORS(app)
+    app.register_blueprint(blueprint)
+    logger.info(f"Welcome to DeepFace API v{DeepFace.__version__}!")
+    return app

deepface/deepface/api/src/modules/core/routes.py

@@ -0,0 +1,96 @@
+from flask import Blueprint, request
+from deepface import DeepFace
+from deepface.api.src.modules.core import service
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+blueprint = Blueprint("routes", __name__)
+
+
+@blueprint.route("/")
+def home():
+    return f"<h1>Welcome to DeepFace API v{DeepFace.__version__}!</h1>"
+
+
+@blueprint.route("/represent", methods=["POST"])
+def represent():
+    input_args = request.get_json()
+
+    if input_args is None:
+        return {"message": "empty input set passed"}
+
+    img_path = input_args.get("img") or input_args.get("img_path")
+    if img_path is None:
+        return {"message": "you must pass img_path input"}
+
+    obj = service.represent(
+        img_path=img_path,
+        model_name=input_args.get("model_name", "VGG-Face"),
+        detector_backend=input_args.get("detector_backend", "opencv"),
+        enforce_detection=input_args.get("enforce_detection", True),
+        align=input_args.get("align", True),
+        anti_spoofing=input_args.get("anti_spoofing", False),
+        max_faces=input_args.get("max_faces"),
+    )
+
+    logger.debug(obj)
+
+    return obj
+
+
+@blueprint.route("/verify", methods=["POST"])
+def verify():
+    input_args = request.get_json()
+
+    if input_args is None:
+        return {"message": "empty input set passed"}
+
+    img1_path = input_args.get("img1") or input_args.get("img1_path")
+    img2_path = input_args.get("img2") or input_args.get("img2_path")
+
+    if img1_path is None:
+        return {"message": "you must pass img1_path input"}
+
+    if img2_path is None:
+        return {"message": "you must pass img2_path input"}
+
+    verification = service.verify(
+        img1_path=img1_path,
+        img2_path=img2_path,
+        model_name=input_args.get("model_name", "VGG-Face"),
+        detector_backend=input_args.get("detector_backend", "opencv"),
+        distance_metric=input_args.get("distance_metric", "cosine"),
+        align=input_args.get("align", True),
+        enforce_detection=input_args.get("enforce_detection", True),
+        anti_spoofing=input_args.get("anti_spoofing", False),
+    )
+
+    logger.debug(verification)
+
+    return verification
+
+
+@blueprint.route("/analyze", methods=["POST"])
+def analyze():
+    input_args = request.get_json()
+
+    if input_args is None:
+        return {"message": "empty input set passed"}
+
+    img_path = input_args.get("img") or input_args.get("img_path")
+    if img_path is None:
+        return {"message": "you must pass img_path input"}
+
+    demographies = service.analyze(
+        img_path=img_path,
+        actions=input_args.get("actions", ["age", "gender", "emotion", "race"]),
+        detector_backend=input_args.get("detector_backend", "opencv"),
+        enforce_detection=input_args.get("enforce_detection", True),
+        align=input_args.get("align", True),
+        anti_spoofing=input_args.get("anti_spoofing", False),
+    )
+
+    logger.debug(demographies)
+
+    return demographies

deepface/deepface/api/src/modules/core/service.py

@@ -0,0 +1,88 @@
+# built-in dependencies
+import traceback
+from typing import Optional
+
+# project dependencies
+from deepface import DeepFace
+
+# pylint: disable=broad-except
+
+
+def represent(
+    img_path: str,
+    model_name: str,
+    detector_backend: str,
+    enforce_detection: bool,
+    align: bool,
+    anti_spoofing: bool,
+    max_faces: Optional[int] = None,
+):
+    try:
+        result = {}
+        embedding_objs = DeepFace.represent(
+            img_path=img_path,
+            model_name=model_name,
+            detector_backend=detector_backend,
+            enforce_detection=enforce_detection,
+            align=align,
+            anti_spoofing=anti_spoofing,
+            max_faces=max_faces,
+        )
+        result["results"] = embedding_objs
+        return result
+    except Exception as err:
+        tb_str = traceback.format_exc()
+        return {"error": f"Exception while representing: {str(err)} - {tb_str}"}, 400
+
+
+def verify(
+    img1_path: str,
+    img2_path: str,
+    model_name: str,
+    detector_backend: str,
+    distance_metric: str,
+    enforce_detection: bool,
+    align: bool,
+    anti_spoofing: bool,
+):
+    try:
+        obj = DeepFace.verify(
+            img1_path=img1_path,
+            img2_path=img2_path,
+            model_name=model_name,
+            detector_backend=detector_backend,
+            distance_metric=distance_metric,
+            align=align,
+            enforce_detection=enforce_detection,
+            anti_spoofing=anti_spoofing,
+        )
+        return obj
+    except Exception as err:
+        tb_str = traceback.format_exc()
+        return {"error": f"Exception while verifying: {str(err)} - {tb_str}"}, 400
+
+
+def analyze(
+    img_path: str,
+    actions: list,
+    detector_backend: str,
+    enforce_detection: bool,
+    align: bool,
+    anti_spoofing: bool,
+):
+    try:
+        result = {}
+        demographies = DeepFace.analyze(
+            img_path=img_path,
+            actions=actions,
+            detector_backend=detector_backend,
+            enforce_detection=enforce_detection,
+            align=align,
+            silent=True,
+            anti_spoofing=anti_spoofing,
+        )
+        result["results"] = demographies
+        return result
+    except Exception as err:
+        tb_str = traceback.format_exc()
+        return {"error": f"Exception while analyzing: {str(err)} - {tb_str}"}, 400

deepface/deepface/commons/constant.py

@@ -0,0 +1,4 @@
+import os
+
+SRC_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ROOT_DIR = os.path.dirname(SRC_DIR)

deepface/deepface/commons/folder_utils.py

@@ -0,0 +1,34 @@
+import os
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+
+def initialize_folder() -> None:
+    """
+    Initialize the folder for storing model weights.
+
+    Raises:
+        OSError: if the folder cannot be created.
+    """
+    home = get_deepface_home()
+    deepface_home_path = os.path.join(home, ".deepface")
+    weights_path = os.path.join(deepface_home_path, "weights")
+
+    if not os.path.exists(deepface_home_path):
+        os.makedirs(deepface_home_path, exist_ok=True)
+        logger.info(f"Directory {deepface_home_path} has been created")
+
+    if not os.path.exists(weights_path):
+        os.makedirs(weights_path, exist_ok=True)
+        logger.info(f"Directory {weights_path} has been created")
+
+
+def get_deepface_home() -> str:
+    """
+    Get the home directory for storing model weights
+
+    Returns:
+        str: the home directory.
+    """
+    return str(os.getenv("DEEPFACE_HOME", default=os.path.expanduser("~")))

deepface/deepface/commons/image_utils.py

@@ -0,0 +1,148 @@
+# built-in dependencies
+import os
+import io
+from typing import List, Union, Tuple
+import hashlib
+import base64
+from pathlib import Path
+
+# 3rd party dependencies
+import requests
+import numpy as np
+import cv2
+from PIL import Image
+
+
+def list_images(path: str) -> List[str]:
+    """
+    List images in a given path
+    Args:
+        path (str): path's location
+    Returns:
+        images (list): list of exact image paths
+    """
+    images = []
+    for r, _, f in os.walk(path):
+        for file in f:
+            exact_path = os.path.join(r, file)
+
+            ext_lower = os.path.splitext(exact_path)[-1].lower()
+
+            if ext_lower not in {".jpg", ".jpeg", ".png"}:
+                continue
+
+            with Image.open(exact_path) as img:  # lazy
+                if img.format.lower() in {"jpeg", "png"}:
+                    images.append(exact_path)
+    return images
+
+
+def find_image_hash(file_path: str) -> str:
+    """
+    Find the hash of given image file with its properties
+        finding the hash of image content is costly operation
+    Args:
+        file_path (str): exact image path
+    Returns:
+        hash (str): digest with sha1 algorithm
+    """
+    file_stats = os.stat(file_path)
+
+    # some properties
+    file_size = file_stats.st_size
+    creation_time = file_stats.st_ctime
+    modification_time = file_stats.st_mtime
+
+    properties = f"{file_size}-{creation_time}-{modification_time}"
+
+    hasher = hashlib.sha1()
+    hasher.update(properties.encode("utf-8"))
+    return hasher.hexdigest()
+
+
+def load_image(img: Union[str, np.ndarray]) -> Tuple[np.ndarray, str]:
+    """
+    Load image from path, url, base64 or numpy array.
+    Args:
+        img: a path, url, base64 or numpy array.
+    Returns:
+        image (numpy array): the loaded image in BGR format
+        image name (str): image name itself
+    """
+
+    # The image is already a numpy array
+    if isinstance(img, np.ndarray):
+        return img, "numpy array"
+
+    if isinstance(img, Path):
+        img = str(img)
+
+    if not isinstance(img, str):
+        raise ValueError(f"img must be numpy array or str but it is {type(img)}")
+
+    # The image is a base64 string
+    if img.startswith("data:image/"):
+        return load_image_from_base64(img), "base64 encoded string"
+
+    # The image is a url
+    if img.lower().startswith(("http://", "https://")):
+        return load_image_from_web(url=img), img
+
+    # The image is a path
+    if not os.path.isfile(img):
+        raise ValueError(f"Confirm that {img} exists")
+
+    # image must be a file on the system then
+
+    # image name must have english characters
+    if not img.isascii():
+        raise ValueError(f"Input image must not have non-english characters - {img}")
+
+    img_obj_bgr = cv2.imread(img)
+    # img_obj_rgb = cv2.cvtColor(img_obj_bgr, cv2.COLOR_BGR2RGB)
+    return img_obj_bgr, img
+
+
+def load_image_from_base64(uri: str) -> np.ndarray:
+    """
+    Load image from base64 string.
+    Args:
+        uri: a base64 string.
+    Returns:
+        numpy array: the loaded image.
+    """
+
+    encoded_data_parts = uri.split(",")
+
+    if len(encoded_data_parts) < 2:
+        raise ValueError("format error in base64 encoded string")
+
+    encoded_data = encoded_data_parts[1]
+    decoded_bytes = base64.b64decode(encoded_data)
+
+    # similar to find functionality, we are just considering these extensions
+    # content type is safer option than file extension
+    with Image.open(io.BytesIO(decoded_bytes)) as img:
+        file_type = img.format.lower()
+        if file_type not in {"jpeg", "png"}:
+            raise ValueError(f"Input image can be jpg or png, but it is {file_type}")
+
+    nparr = np.fromstring(decoded_bytes, np.uint8)
+    img_bgr = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+    # img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)
+    return img_bgr
+
+
+def load_image_from_web(url: str) -> np.ndarray:
+    """
+    Loading an image from web
+    Args:
+        url: link for the image
+    Returns:
+        img (np.ndarray): equivalent to pre-loaded image from opencv (BGR format)
+    """
+    response = requests.get(url, stream=True, timeout=60)
+    response.raise_for_status()
+    image_array = np.asarray(bytearray(response.raw.read()), dtype=np.uint8)
+    img = cv2.imdecode(image_array, cv2.IMREAD_COLOR)
+    return img

deepface/deepface/commons/logger.py

@@ -0,0 +1,57 @@
+import os
+import logging
+from datetime import datetime
+
+# pylint: disable=broad-except
+class Logger:
+    """
+    A Logger class for logging messages with a specific log level.
+
+    The class follows the singleton design pattern, ensuring that only one
+    instance of the Logger is created. The parameters of the first instance
+    are preserved across all instances.
+    """
+
+    __instance = None
+
+    def __new__(cls):
+        if cls.__instance is None:
+            cls.__instance = super(Logger, cls).__new__(cls)
+        return cls.__instance
+
+    def __init__(self):
+        if not hasattr(self, "_singleton_initialized"):
+            self._singleton_initialized = True  # to prevent multiple initializations
+            log_level = os.environ.get("DEEPFACE_LOG_LEVEL", str(logging.INFO))
+            try:
+                self.log_level = int(log_level)
+            except Exception as err:
+                self.dump_log(
+                    f"Exception while parsing $DEEPFACE_LOG_LEVEL."
+                    f"Expected int but it is {log_level} ({str(err)})."
+                    "Setting app log level to info."
+                )
+                self.log_level = logging.INFO
+
+    def info(self, message):
+        if self.log_level <= logging.INFO:
+            self.dump_log(f"{message}")
+
+    def debug(self, message):
+        if self.log_level <= logging.DEBUG:
+            self.dump_log(f"🕷️ {message}")
+
+    def warn(self, message):
+        if self.log_level <= logging.WARNING:
+            self.dump_log(f"⚠️ {message}")
+
+    def error(self, message):
+        if self.log_level <= logging.ERROR:
+            self.dump_log(f"🔴 {message}")
+
+    def critical(self, message):
+        if self.log_level <= logging.CRITICAL:
+            self.dump_log(f"💥 {message}")
+
+    def dump_log(self, message):
+        print(f"{str(datetime.now())[2:-7]} - {message}")

deepface/deepface/commons/package_utils.py

@@ -0,0 +1,65 @@
+# built-in dependencies
+import hashlib
+
+# 3rd party dependencies
+import tensorflow as tf
+
+# package dependencies
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+
+def get_tf_major_version() -> int:
+    """
+    Find tensorflow's major version
+    Returns
+        major_version (int)
+    """
+    return int(tf.__version__.split(".", maxsplit=1)[0])
+
+
+def get_tf_minor_version() -> int:
+    """
+    Find tensorflow's minor version
+    Returns
+        minor_version (int)
+    """
+    return int(tf.__version__.split(".", maxsplit=-1)[1])
+
+
+def validate_for_keras3():
+    tf_major = get_tf_major_version()
+    tf_minor = get_tf_minor_version()
+
+    # tf_keras is a must dependency after tf 2.16
+    if tf_major == 1 or (tf_major == 2 and tf_minor < 16):
+        return
+
+    try:
+        import tf_keras
+
+        logger.debug(f"tf_keras is already available - {tf_keras.__version__}")
+    except ImportError as err:
+        # you may consider to install that package here
+        raise ValueError(
+            f"You have tensorflow {tf.__version__} and this requires "
+            "tf-keras package. Please run `pip install tf-keras` "
+            "or downgrade your tensorflow."
+        ) from err
+
+
+def find_file_hash(file_path: str, hash_algorithm: str = "sha256") -> str:
+    """
+    Find the hash of a given file with its content
+    Args:
+        file_path (str): exact path of a given file
+        hash_algorithm (str): hash algorithm
+    Returns:
+        hash (str)
+    """
+    hash_func = hashlib.new(hash_algorithm)
+    with open(file_path, "rb") as f:
+        while chunk := f.read(8192):
+            hash_func.update(chunk)
+    return hash_func.hexdigest()

deepface/deepface/commons/weight_utils.py

@@ -0,0 +1,92 @@
+# built-in dependencies
+import os
+from typing import Optional
+import zipfile
+import bz2
+
+# 3rd party dependencies
+import gdown
+
+# project dependencies
+from deepface.commons import folder_utils, package_utils
+from deepface.commons.logger import Logger
+
+tf_version = package_utils.get_tf_major_version()
+if tf_version == 1:
+    from keras.models import Sequential
+else:
+    from tensorflow.keras.models import Sequential
+
+logger = Logger()
+
+
+def download_weights_if_necessary(
+    file_name: str, source_url: str, compress_type: Optional[str] = None
+) -> str:
+    """
+    Download the weights of a pre-trained model from external source if not downloaded yet.
+    Args:
+        file_name (str): target file name with extension
+        source_url (url): source url to be downloaded
+        compress_type (optional str): compress type e.g. zip or bz2
+    Returns
+        target_file (str): exact path for the target file
+    """
+    home = folder_utils.get_deepface_home()
+
+    target_file = os.path.join(home, ".deepface/weights", file_name)
+
+    if os.path.isfile(target_file):
+        logger.debug(f"{file_name} is already available at {target_file}")
+        return target_file
+
+    try:
+        logger.info(f"🔗 {file_name} will be downloaded from {source_url} to {target_file}...")
+
+        if compress_type is None:
+            gdown.download(source_url, target_file, quiet=False)
+        elif compress_type is not None:
+            gdown.download(source_url, f"{target_file}.{compress_type}", quiet=False)
+
+    except Exception as err:
+        raise ValueError(
+            f"⛓️‍💥 An exception occurred while downloading {file_name} from {source_url}. "
+            f"Consider downloading it manually to {target_file}."
+        ) from err
+
+    # uncompress downloaded file
+    if compress_type == "zip":
+        with zipfile.ZipFile(f"{target_file}.zip", "r") as zip_ref:
+            zip_ref.extractall(os.path.join(home, ".deepface/weights"))
+            logger.info(f"{target_file}.zip unzipped")
+    elif compress_type == "bz2":
+        bz2file = bz2.BZ2File(f"{target_file}.bz2")
+        data = bz2file.read()
+        with open(target_file, "wb") as f:
+            f.write(data)
+        logger.info(f"{target_file}.bz2 unzipped")
+
+    return target_file
+
+
+def load_model_weights(model: Sequential, weight_file: str) -> Sequential:
+    """
+    Load pre-trained weights for a given model
+    Args:
+        model (keras.models.Sequential): pre-built model
+        weight_file (str): exact path of pre-trained weights
+    Returns:
+        model (keras.models.Sequential): pre-built model with
+            updated weights
+    """
+    try:
+        model.load_weights(weight_file)
+    except Exception as err:
+        raise ValueError(
+            f"An exception occurred while loading the pre-trained weights from {weight_file}."
+            "This might have happened due to an interruption during the download."
+            "You may want to delete it and allow DeepFace to download it again during the next run."
+            "If the issue persists, consider downloading the file directly from the source "
+            "and copying it to the target folder."
+        ) from err
+    return model

deepface/deepface/models/Demography.py

@@ -0,0 +1,22 @@
+from typing import Union
+from abc import ABC, abstractmethod
+import numpy as np
+from deepface.commons import package_utils
+
+tf_version = package_utils.get_tf_major_version()
+if tf_version == 1:
+    from keras.models import Model
+else:
+    from tensorflow.keras.models import Model
+
+# Notice that all facial attribute analysis models must be inherited from this class
+
+
+# pylint: disable=too-few-public-methods
+class Demography(ABC):
+    model: Model
+    model_name: str
+
+    @abstractmethod
+    def predict(self, img: np.ndarray) -> Union[np.ndarray, np.float64]:
+        pass

deepface/deepface/models/Detector.py

@@ -0,0 +1,69 @@
+from typing import List, Tuple, Optional
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+import numpy as np
+
+# Notice that all facial detector models must be inherited from this class
+
+
+# pylint: disable=unnecessary-pass, too-few-public-methods
+class Detector(ABC):
+    @abstractmethod
+    def detect_faces(self, img: np.ndarray) -> List["FacialAreaRegion"]:
+        """
+        Interface for detect and align face
+
+        Args:
+            img (np.ndarray): pre-loaded image as numpy array
+
+        Returns:
+            results (List[FacialAreaRegion]): A list of FacialAreaRegion objects
+                where each object contains:
+
+            - facial_area (FacialAreaRegion): The facial area region represented
+                as x, y, w, h, left_eye and right_eye. left eye and right eye are
+                eyes on the left and right respectively with respect to the person
+                instead of observer.
+        """
+        pass
+
+
+@dataclass
+class FacialAreaRegion:
+    """
+    Initialize a Face object.
+
+    Args:
+        x (int): The x-coordinate of the top-left corner of the bounding box.
+        y (int): The y-coordinate of the top-left corner of the bounding box.
+        w (int): The width of the bounding box.
+        h (int): The height of the bounding box.
+        left_eye (tuple): The coordinates (x, y) of the left eye with respect to
+            the person instead of observer. Default is None.
+        right_eye (tuple): The coordinates (x, y) of the right eye with respect to
+            the person instead of observer. Default is None.
+        confidence (float, optional): Confidence score associated with the face detection.
+            Default is None.
+    """
+    x: int
+    y: int
+    w: int
+    h: int
+    left_eye: Optional[Tuple[int, int]] = None
+    right_eye: Optional[Tuple[int, int]] = None
+    confidence: Optional[float] = None
+
+
+@dataclass
+class DetectedFace:
+    """
+    Initialize detected face object.
+
+    Args:
+        img (np.ndarray): detected face image as numpy array
+        facial_area (FacialAreaRegion): detected face's metadata (e.g. bounding box)
+        confidence (float): confidence score for face detection
+        """
+    img: np.ndarray
+    facial_area: FacialAreaRegion
+    confidence: float

deepface/deepface/models/FacialRecognition.py

@@ -0,0 +1,29 @@
+from abc import ABC
+from typing import Any, Union, List, Tuple
+import numpy as np
+from deepface.commons import package_utils
+
+tf_version = package_utils.get_tf_major_version()
+if tf_version == 2:
+    from tensorflow.keras.models import Model
+else:
+    from keras.models import Model
+
+# Notice that all facial recognition models must be inherited from this class
+
+# pylint: disable=too-few-public-methods
+class FacialRecognition(ABC):
+    model: Union[Model, Any]
+    model_name: str
+    input_shape: Tuple[int, int]
+    output_shape: int
+
+    def forward(self, img: np.ndarray) -> List[float]:
+        if not isinstance(self.model, Model):
+            raise ValueError(
+                "You must overwrite forward method if it is not a keras model,"
+                f"but {self.model_name} not overwritten!"
+            )
+        # model.predict causes memory issue when it is called in a for loop
+        # embedding = model.predict(img, verbose=0)[0].tolist()
+        return self.model(img, training=False).numpy()[0].tolist()

deepface/deepface/models/demography/Age.py

@@ -0,0 +1,89 @@
+# 3rd party dependencies
+import numpy as np
+
+# project dependencies
+from deepface.models.facial_recognition import VGGFace
+from deepface.commons import package_utils, weight_utils
+from deepface.models.Demography import Demography
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+# ----------------------------------------
+# dependency configurations
+
+tf_version = package_utils.get_tf_major_version()
+
+if tf_version == 1:
+    from keras.models import Model, Sequential
+    from keras.layers import Convolution2D, Flatten, Activation
+else:
+    from tensorflow.keras.models import Model, Sequential
+    from tensorflow.keras.layers import Convolution2D, Flatten, Activation
+
+# ----------------------------------------
+
+# pylint: disable=too-few-public-methods
+class ApparentAgeClient(Demography):
+    """
+    Age model class
+    """
+
+    def __init__(self):
+        self.model = load_model()
+        self.model_name = "Age"
+
+    def predict(self, img: np.ndarray) -> np.float64:
+        # model.predict causes memory issue when it is called in a for loop
+        # age_predictions = self.model.predict(img, verbose=0)[0, :]
+        age_predictions = self.model(img, training=False).numpy()[0, :]
+        return find_apparent_age(age_predictions)
+
+
+def load_model(
+    url="https://github.com/serengil/deepface_models/releases/download/v1.0/age_model_weights.h5",
+) -> Model:
+    """
+    Construct age model, download its weights and load
+    Returns:
+        model (Model)
+    """
+
+    model = VGGFace.base_model()
+
+    # --------------------------
+
+    classes = 101
+    base_model_output = Sequential()
+    base_model_output = Convolution2D(classes, (1, 1), name="predictions")(model.layers[-4].output)
+    base_model_output = Flatten()(base_model_output)
+    base_model_output = Activation("softmax")(base_model_output)
+
+    # --------------------------
+
+    age_model = Model(inputs=model.input, outputs=base_model_output)
+
+    # --------------------------
+
+    # load weights
+    weight_file = weight_utils.download_weights_if_necessary(
+        file_name="age_model_weights.h5", source_url=url
+    )
+
+    age_model = weight_utils.load_model_weights(
+        model=age_model, weight_file=weight_file
+    )
+
+    return age_model
+
+def find_apparent_age(age_predictions: np.ndarray) -> np.float64:
+    """
+    Find apparent age prediction from a given probas of ages
+    Args:
+        age_predictions (?)
+    Returns:
+        apparent_age (float)
+    """
+    output_indexes = np.arange(0, 101)
+    apparent_age = np.sum(age_predictions * output_indexes)
+    return apparent_age

deepface/deepface/models/demography/Emotion.py

@@ -0,0 +1,103 @@
+# 3rd party dependencies
+import numpy as np
+import cv2
+
+# project dependencies
+from deepface.commons import package_utils, weight_utils
+from deepface.models.Demography import Demography
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+# -------------------------------------------
+# pylint: disable=line-too-long
+# -------------------------------------------
+# dependency configuration
+tf_version = package_utils.get_tf_major_version()
+
+if tf_version == 1:
+    from keras.models import Sequential
+    from keras.layers import Conv2D, MaxPooling2D, AveragePooling2D, Flatten, Dense, Dropout
+else:
+    from tensorflow.keras.models import Sequential
+    from tensorflow.keras.layers import (
+        Conv2D,
+        MaxPooling2D,
+        AveragePooling2D,
+        Flatten,
+        Dense,
+        Dropout,
+    )
+# -------------------------------------------
+
+# Labels for the emotions that can be detected by the model.
+labels = ["angry", "disgust", "fear", "happy", "sad", "surprise", "neutral"]
+
+# pylint: disable=too-few-public-methods
+class EmotionClient(Demography):
+    """
+    Emotion model class
+    """
+
+    def __init__(self):
+        self.model = load_model()
+        self.model_name = "Emotion"
+
+    def predict(self, img: np.ndarray) -> np.ndarray:
+        img_gray = cv2.cvtColor(img[0], cv2.COLOR_BGR2GRAY)
+        img_gray = cv2.resize(img_gray, (48, 48))
+        img_gray = np.expand_dims(img_gray, axis=0)
+
+        # model.predict causes memory issue when it is called in a for loop
+        # emotion_predictions = self.model.predict(img_gray, verbose=0)[0, :]
+        emotion_predictions = self.model(img_gray, training=False).numpy()[0, :]
+
+        return emotion_predictions
+
+
+def load_model(
+    url="https://github.com/serengil/deepface_models/releases/download/v1.0/facial_expression_model_weights.h5",
+) -> Sequential:
+    """
+    Consruct emotion model, download and load weights
+    """
+
+    num_classes = 7
+
+    model = Sequential()
+
+    # 1st convolution layer
+    model.add(Conv2D(64, (5, 5), activation="relu", input_shape=(48, 48, 1)))
+    model.add(MaxPooling2D(pool_size=(5, 5), strides=(2, 2)))
+
+    # 2nd convolution layer
+    model.add(Conv2D(64, (3, 3), activation="relu"))
+    model.add(Conv2D(64, (3, 3), activation="relu"))
+    model.add(AveragePooling2D(pool_size=(3, 3), strides=(2, 2)))
+
+    # 3rd convolution layer
+    model.add(Conv2D(128, (3, 3), activation="relu"))
+    model.add(Conv2D(128, (3, 3), activation="relu"))
+    model.add(AveragePooling2D(pool_size=(3, 3), strides=(2, 2)))
+
+    model.add(Flatten())
+
+    # fully connected neural networks
+    model.add(Dense(1024, activation="relu"))
+    model.add(Dropout(0.2))
+    model.add(Dense(1024, activation="relu"))
+    model.add(Dropout(0.2))
+
+    model.add(Dense(num_classes, activation="softmax"))
+
+    # ----------------------------
+
+    weight_file = weight_utils.download_weights_if_necessary(
+        file_name="facial_expression_model_weights.h5", source_url=url
+    )
+
+    model = weight_utils.load_model_weights(
+        model=model, weight_file=weight_file
+    )
+
+    return model

deepface/deepface/models/demography/Gender.py

@@ -0,0 +1,79 @@
+# 3rd party dependencies
+import numpy as np
+
+# project dependencies
+from deepface.models.facial_recognition import VGGFace
+from deepface.commons import package_utils, weight_utils
+from deepface.models.Demography import Demography
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+# -------------------------------------
+# pylint: disable=line-too-long
+# -------------------------------------
+# dependency configurations
+
+tf_version = package_utils.get_tf_major_version()
+if tf_version == 1:
+    from keras.models import Model, Sequential
+    from keras.layers import Convolution2D, Flatten, Activation
+else:
+    from tensorflow.keras.models import Model, Sequential
+    from tensorflow.keras.layers import Convolution2D, Flatten, Activation
+# -------------------------------------
+
+# Labels for the genders that can be detected by the model.
+labels = ["Woman", "Man"]
+
+# pylint: disable=too-few-public-methods
+class GenderClient(Demography):
+    """
+    Gender model class
+    """
+
+    def __init__(self):
+        self.model = load_model()
+        self.model_name = "Gender"
+
+    def predict(self, img: np.ndarray) -> np.ndarray:
+        # model.predict causes memory issue when it is called in a for loop
+        # return self.model.predict(img, verbose=0)[0, :]
+        return self.model(img, training=False).numpy()[0, :]
+
+
+def load_model(
+    url="https://github.com/serengil/deepface_models/releases/download/v1.0/gender_model_weights.h5",
+) -> Model:
+    """
+    Construct gender model, download its weights and load
+    Returns:
+        model (Model)
+    """
+
+    model = VGGFace.base_model()
+
+    # --------------------------
+
+    classes = 2
+    base_model_output = Sequential()
+    base_model_output = Convolution2D(classes, (1, 1), name="predictions")(model.layers[-4].output)
+    base_model_output = Flatten()(base_model_output)
+    base_model_output = Activation("softmax")(base_model_output)
+
+    # --------------------------
+
+    gender_model = Model(inputs=model.input, outputs=base_model_output)
+
+    # --------------------------
+
+    # load weights
+    weight_file = weight_utils.download_weights_if_necessary(
+        file_name="gender_model_weights.h5", source_url=url
+    )
+
+    gender_model = weight_utils.load_model_weights(
+        model=gender_model, weight_file=weight_file
+    )
+
+    return gender_model

deepface/deepface/models/demography/Race.py

@@ -0,0 +1,76 @@
+# 3rd party dependencies
+import numpy as np
+
+# project dependencies
+from deepface.models.facial_recognition import VGGFace
+from deepface.commons import package_utils, weight_utils
+from deepface.models.Demography import Demography
+from deepface.commons.logger import Logger
+
+logger = Logger()
+
+# --------------------------
+# pylint: disable=line-too-long
+# --------------------------
+# dependency configurations
+tf_version = package_utils.get_tf_major_version()
+
+if tf_version == 1:
+    from keras.models import Model, Sequential
+    from keras.layers import Convolution2D, Flatten, Activation
+else:
+    from tensorflow.keras.models import Model, Sequential
+    from tensorflow.keras.layers import Convolution2D, Flatten, Activation
+# --------------------------
+# Labels for the ethnic phenotypes that can be detected by the model.
+labels = ["asian", "indian", "black", "white", "middle eastern", "latino hispanic"]
+
+# pylint: disable=too-few-public-methods
+class RaceClient(Demography):
+    """
+    Race model class
+    """
+
+    def __init__(self):
+        self.model = load_model()
+        self.model_name = "Race"
+
+    def predict(self, img: np.ndarray) -> np.ndarray:
+        # model.predict causes memory issue when it is called in a for loop
+        # return self.model.predict(img, verbose=0)[0, :]
+        return self.model(img, training=False).numpy()[0, :]
+
+
+def load_model(
+    url="https://github.com/serengil/deepface_models/releases/download/v1.0/race_model_single_batch.h5",
+) -> Model:
+    """
+    Construct race model, download its weights and load
+    """
+
+    model = VGGFace.base_model()
+
+    # --------------------------
+
+    classes = 6
+    base_model_output = Sequential()
+    base_model_output = Convolution2D(classes, (1, 1), name="predictions")(model.layers[-4].output)
+    base_model_output = Flatten()(base_model_output)
+    base_model_output = Activation("softmax")(base_model_output)
+
+    # --------------------------
+
+    race_model = Model(inputs=model.input, outputs=base_model_output)
+
+    # --------------------------
+
+    # load weights
+    weight_file = weight_utils.download_weights_if_necessary(
+        file_name="race_model_single_batch.h5", source_url=url
+    )
+
+    race_model = weight_utils.load_model_weights(
+        model=race_model, weight_file=weight_file
+    )
+
+    return race_model