Skip to content

Model to recognize celebrities using a face matching algorithm.

License

Notifications You must be signed in to change notification settings

shobhit9618/celeb_recognition

Repository files navigation

Celebrity Recognition PyPI version Documentation Status Anaconda-Server Badge

Model to recognize celebrities using a face matching algorithm.

Refer this for detailed documentation.

You can also read my article on medium here.

Basic working of the algorithm includes the following:

  • Face detection is done using MTCNN face detection model.

  • Face encodings are created using VGGFace model in keras.

  • Face matching is done using annoy library (spotify).

Installing dependencies

  • Run pip install -r requirements.txt to install all the dependencies (preferably in a virtual environment).

PyPI package

Installation

  • To ensure you have all the required additional packages, run pip install -r requirements.txt first.
  • To install pip package, run:
    # pip release version
    pip install celeb-detector
    # also install additional dependencies with this (if not installed via requirements.txt file)
    pip install annoy keras-vggface keras-applications
    # Directly from repo
    pip install git+https://github.com/shobhit9618/celeb_recognition.git
  • If you are using conda on linux or ubuntu, you can use the following commands to create and use a new environment called celeb-detector:
    conda env create shobhit9618/celeb-detector
    conda activate celeb-detector
    This will install all the required dependencies. To ensure you are using the latest version of the package, also run (inside the environment):
    pip install --upgrade celeb-detector

Using pip pakcage

  • For using my model for predictions, use the following lines of code after installation:

    import celeb_detector # on running for the first time, this will download vggface model
    img_path = 'sample_image.jpg' # this supports both local path and web url like https://sample/sample_image_url.jpg
    celeb_detector.celeb_recognition(img_path) # on running for the first time, 2 files (celeb_mapping.json and celeb_index_60.ann) will downloaded to your home directory

    This returns a list of dictionaries, each dictionary contains bbox coordinates, celeb name and confidence for each face detected in the image (celeb name will be unknown if no matching face detected).

  • For using your own custom model, also provide path to json and ann files as shown below:

    import celeb_detector
    img_path = 'sample_image.jpg'
    ann_path = 'sample_index.ann'
    celeb_map = 'sample_mapping.json'
    celeb_detector.celeb_recognition(img_path, ann_path, celeb_map)
  • For creating your own model (refer this for more details on usage) and run as follows:

    import celeb_detector
    folder_path = 'celeb_images'
    celeb_detector.create_celeb_model(folder_path)

Create your own celeb model

  • Create a dataset of celebs in the following directory structure:
    celeb_images/
        celeb-a/
            celeb-a_1.jpg
            celeb-a_2.jpg
            ...
        celeb-b/
            celeb-b_1.jpg
            celeb-b_1.jpg
            ...
        ...
  • Each folder name will be considered as the corresponding celeb name for the model (WARNING: Do not provide any special characters or spaces in the names).
  • Make sure each image has only 1 face (of the desired celebrity), if there are multiple faces, only the first detected face will be considered.
  • Provide path to the dataset folder (for example, celeb_images folder) in the create_celeb_model.py file.
  • Run create_celeb_model.py file.
  • Upon successful completion of the code, we get celeb_mapping.json (for storing indexes vs celeb names), celeb_index.ann (ann file for searching encodings) and celeb_name_encoding.pkl files (for storing encodings vs indexes for each celeb). (WARNING: You need to provide paths for storing each of these files, default is to store in the current directory)

Model predictions in jupyter

  • Provide paths to celeb_mapping.json and celeb_index.ann files in celeb_recognition.ipynb file. If you want to try my model, ignore this step.
  • Run all the cells in the celeb_recognition.ipynb file, the final cell will provide widgets for uploading images and making predictions (this will also download the necessary model files).
  • NOTE: celeb_recognition.ipynb is a standalone file and does not require any other files from the repo for running.

Model predictions in python

  • Provide paths to celeb_mapping.json and celeb_index.ann files in celeb_recognition.py and celeb_utils.py files. If you want to try my model, ignore this step.
  • Run celeb_recognition.py file, provide path to image in the file.
  • Output includes a list of the identified faces, bounding boxes and the predicted celeb name (unknown if not found).
  • It also displays the output with bounding boxes.

Sample image output

Image

Binder

You can run a binder application by clicking the following link:

Binder

You can also launch a voila binder application (which only has widgets for image upload and celeb prediction) by clicking here.

Google Colab

To open and run celeb_recognition.ipynb file in google colab, click the following link:

Open In Colab