pfla: Python Facial Landmark Analysis

A simple command line interface to automate facial analysis. pfla uses a pre-trained neural networks to detect faces and annotate them with 68 landmarks. The program also compute four commonly used facial metrics. The output is saved to a file to allow for easy statistical analysis by the user.

Publication

This software was published in JOSS. Since version 1.0.0, the packaged has changed considerably. The publication release is still available here.

Citing

If you use this software please use this citation:

@article{Rousseau_2018,
doi = {10.21105/joss.00855},
url = {https://doi.org/10.21105%2Fjoss.00855},
year = 2018,
month = {dec},
publisher = {The Open Journal},
volume = {3},
number = {32},
pages = {855},
author = {Maxime Rousseau and Jean-Marc Retrouvey},
title = {pfla: A Python Package for Dental Facial Analysis using Computer Vision and Statistical Shape Analysis},
journal = {Journal of Open Source Software}}

Features

• Face detection using mtcnn
• Landmark placement
• Facial metric calculations

Requirements and Dependencies

• Python 3.5 (or higher)
• Python packages:
  • numpy
  • pandas
  • pytest
  • pillow
  • facenet-pytorch
  • face-alignment
  • pytest-cov
  • pytorch

Installation

Install with pip:

pip install -r requirements-pytorch.txt \ # pytorch for CPU
	 -f https://download.pytorch.org/whl/torch_stable.html
pip install -r requirements.txt # other dependencies
pip install pfla

Usage

usage: pfla [-h] [-d] [-l] [-m] [-o OUTPUT] [-v] path

PFLA: python facial landmark analysis. This program will read the image(s)
given as input and can apply a face detection algorithm, landmark placement
and computation of metrics. The results are returned as a text stream.

positional arguments:
  path                  path to the image or directory of images

optional arguments:
  -h, --help            show this help message and exit
  -d, --detect          detect faces and output bounding box
  -l, --landmark        annotate detected faces and output coordinates
  -m, --metrics         compute metrics and output results
  -o OUTPUT, --output OUTPUT
                        specify output filename and format/filetype of the
                        data
  -v, --verbose         increase output verbosity

AUTHOR: Maxime Rousseau LICENSE: MIT

Testing

To test your installation run the following commands:

cd [PATH_TO_PACKAGE_INSTALLATION]
pytest

Documentation

Documentation of the package can be found here: https://pfla.readthedocs.io/en/master

Contribute

• Contribution guidelines: https://github.com/maxrousseau/pfla/blob/master/contributing.md
• Issue Tracker: https://github.com/maxrousseau/pfla/issues
• Source Code: https://github.com/maxrousseau/pfla

License

The project is licensed under the MIT license.

Contact

Maxime Rousseau, DMD candidate 2020 McGill University, Faculty of Dentistry

• Email: [email protected]
• Website: https://maxrousseau.github.io/portfolio/