Metadata-Version: 2.1
Name: pfla
Version: 0.1.2
Summary: Python facial landmarking and analysis
Home-page: https://github.com/maxrousseau/pfla
Author: Maxime Rousseau
Author-email: maximerousseau08@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Dist: opencv-python
Requires-Dist: dlib
Requires-Dist: imutils
Requires-Dist: numpy
Requires-Dist: argparse
Requires-Dist: pandas
Requires-Dist: rpy2
Requires-Dist: progress

pfla: Python Facial Landmark Analysis
=====================================

[![PyPI
license](https://img.shields.io/pypi/l/pfla.svg)](https://pypi.org/project/pfla/)
[![PyPI version fury.io](https://badge.fury.io/py/pfla.svg)](https://pypi.org/project/pfla/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/pfla.svg)](https://pypi.org/project/pfla/)
[![Read the Docs](https://img.shields.io/readthedocs/pip.svg)](https://pfla.readthedocs.io/en/latest/index.html#)

![example](paper/collage.png)

Advances in artificial intelligence have enhanced the usability of these
technologies in a clinical setting. This python package introduces the use of a
Detection Outline Analysis (DOA) methodology for facial analysis in
dentistry. This package uses [Haar cascades](https://github.com/opencv/opencv/tree/master/data/haarcascades) for face detection, a trained
68-facial-landmark model and statistical shape analysis ([300 Faces In-The-Wild](https://ibug.doc.ic.ac.uk/resources/300-W/)). The software
uses an R script to conduct statistical [shape](https://cran.r-project.org/web/packages/shape/index.html<Paste>) analysis through a
generalized Procrustes analysis (GPA), principal component analysis
(PCA) and non-parametric Goodall test, which compares mean shapes of
each group for significance. The script also computes mean Euclidean
distance from a baseline shape for each landmark.

This package was written to conduct automated facial analyses of patients
affected by Osteogenesis Imperfecta and controls under the BBDC 7701 study. Its
use may also be extended to the study of other dental and/or craniofacial
conditions or to compare different study groups while examining variables such
as sex, ethnicity, etc. 

If you use this program or a modified version of it for research purposes please cite as follows:

    @mybibtexref{

    :   title author year journal

    }

Features
--------

-   Takes 2 directories as input containing .jpg (anteroposterior
    clinical photographs)
-   Image Processing: scales images, transformation to grayscale
-   Detection: haar cascade face bounding, 68 facial landmark placement
-   Statistical Shape Analysis: GPA, PCA, Goodall's F-test, Euclidean
    distance per landmark from baseline shape

Requirements and Dependencies
-----------------------------

-   python 3.5
-   opencv
-   linux (or unix operating system)
-   R 3.3 (or more recent)
-   R packages: shapes, foreach

Installation
------------

```shell
$ pip install pfla
```


Additionnal steps, the 68 landmark dat file is too large for pip packaging.
You can download it [here](pfla/data/shape_predictor_68_face_landmarks.dat).


Place the downloaded dat file in the following directory:

```shell
$ ~/.local/lib/python3.5/site-packages/pfla/data/
```

Usage
-----

The program is run through the terminal as follows:

```shell
$ pfla -g1 /path/to/first/group -g2 /path/to/second/group
```

The resulting output from the analysis will be printed out into the
terminal like so:

```shell
[ INFO:0] Initialize OpenCL runtime...
Processing Images |###############################| 68/68
g1 processing completed without errors
Processing Images |###############################| 32/32
g2 processing completed without errors

*Bootstrap - sampling with replacement within each group under H0: No of resamples =  10 
****************************** 
null device 
          1 
[1] --------------------------------------------------------------------------------
[1] Goodall Statistical Test P-Value:  0.0909090909090909
[1] --------------------------------------------------------------------------------
[1] Summary of Mean Euclidean Distance:
[1] Group 1:
[1] Mean:  0.0049944135958874 | Standard Deviation:  0.00156292696370281
[1] Group 2:
[1] Mean:  0.00590442732720643 | Standard Deviation:  0.0018474508985488
[1] --------------------------------------------------------------------------------
```

A histogram summarizing the mean Euclidean distances per landmark will
also be save in the data/ directory.

![Mean Euclidean Distance Histogram](paper/histo_02.png)

Testing
-------

To test your installation run the following commands:
```shell
cd ~/.local/lib/python3.5/site-packages/pfla/
python3 test.py
```
Documentation
-------------

Documentation of the package can be found here: <https://pfla.readthedocs.io/en/latest/index.html#>

Contribute
----------

-   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 II McGill University, Faculty of Dentistry
- Email: <maximerousseau08@gmail.com>



