Skip to main content

Python facial landmarking and analysis

Project description

pfla: Python Facial Landmark Analysis

GitHub release PyPI license PyPI version fury.io PyPI pyversions Documentation Status Build Status DOI

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 compyte 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

License

The project is licensed under the MIT license.

Contact

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pfla, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size pfla-1.0.0-py3-none-any.whl (11.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pfla-1.0.0.tar.gz (10.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page