completely update repo with auto-face-align-toml

.gitignore

@@ -0,0 +1,164 @@
+# -----------------------------------------------------------------------------
+# Boilerplate stuff adapted from https://github.com/github/gitignore/blob/master/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.cache
+.pytest_cache/
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# -----------------------------------------------------------------------------
+# Other stuff specific to my package
+quick_install_for_debugging.sh
+.DS_Store
+
+/results/KUFD-DC/*jpg
+/results/KUFD-ID/*jpg
+
+/results/KUFD-DC-aligned/*jpg
+/results/KUFD-ID-aligned/*jpg
+
+/results/CAS-female/*tif
+/results/CAS-male/*tif
+/results/GUFD-female/*jpg
+/results/GUFD-male/*jpg
+
+/results/CAS-female-aligned/*tif
+/results/CAS-male-aligned/*tif
+/results/GUFD-female-aligned/*jpg
+/results/GUFD-male-aligned/*jpg
+
+results/NIM-an-c/*bmp
+results/NIM-an-o/*bmp
+results/NIM-an-c-aligned/*bmp
+results/NIM-an-o-aligned/*bmp
+
+results/NIM-ca-c/*bmp
+results/NIM-ca-o/*bmp
+results/NIM-ca-c-aligned/*bmp
+results/NIM-ca-o-aligned/*bmp
+
+results/NIM-di-c/*bmp
+results/NIM-di-o/*bmp
+results/NIM-di-c-aligned/*bmp
+results/NIM-di-o-aligned/*bmp
+
+results/NIM-fe-c/*bmp
+results/NIM-fe-o/*bmp
+results/NIM-fe-c-aligned/*bmp
+results/NIM-fe-o-aligned/*bmp
+
+results/NIM-ha-c/*bmp
+results/NIM-ha-o/*bmp
+results/NIM-ha-c-aligned/*bmp
+results/NIM-ha-o-aligned/*bmp
+
+results/NIM-ne-c/*bmp
+results/NIM-ne-o/*bmp
+results/NIM-ne-c-aligned/*bmp
+results/NIM-ne-o-aligned/*bmp
+
+results/NIM-sa-c/*bmp
+results/NIM-sa-o/*bmp
+results/NIM-sa-c-aligned/*bmp
+results/NIM-sa-o-aligned/*bmp
+
+results/NIM-sp-c/*bmp
+results/NIM-sp-o/*bmp
+results/NIM-sp-c-aligned/*bmp
+results/NIM-sp-o-aligned/*bmp
+
+results_temporary.dat
+landmarks.txt
+specs.csv
+
+demos/demo_1_alignment/faces-aligned/*jpg
+demos/demo_1_alignment/faces-aligned-windowed/*jpg
+
+demos/demo_2_morphing/an-unusual-pair-aligned/*jpg
+demos/demo_2_morphing/an-unusual-pair-aligned-morphed/*png
+demos/demo_2_morphing/an-unusual-pair-aligned-morphed-windowed/*png
+
+demos/demo_3_averaging/faces-of-merkel-aligned/*jpg
+demos/demo_3_averaging/faces-of-merkel-aligned-warp-to-mean/*.png
+demos/demo_3_averaging/faces-of-merkel-aligned-warp-to-mean-windowed/
+demos/demo_3_averaging/faces-of-merkel-aligned-aligned-windowed/
+
+# History files
+.Rhistory
+.Rapp.history
+
+# Session Data files
+.RData
+
+# User-specific files
+.Ruserdata
+
+# -----------------------------------------------------------------------------
+# Manuscript
+manuscript/~$-journ.dot
+manuscript/~$spar-garrod-brm-2021-v2.docx
+
+# END
+# -----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------

LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright 2021 Carl Michael Gaspar
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,99 @@
+Automatic Face Alignment (AFA)
+================
+Carl M. Gaspar & Oliver G.B. Garrod
+
+#### You have lots of photos of faces like this:
+![](demos/demo_1_alignment/collage_originals.png)
+
+#### But you want to line up all of the faces like this:
+![](demos/demo_1_alignment/collage_aligned.png)
+
+#### Perhaps you would also like to window the faces to show only inner facial features like this:
+![](demos/demo_1_alignment/collage_aligned_windowed.png)
+
+#### All of the above can be done using AFA like this:
+```python
+import alignfaces as afa
+
+faces_path = "/Users/Me/faces_for_my_study/"
+afa.get_landmarks(faces_path)
+aligned_path = afa.align_procrustes(faces_path)
+afa.get_landmarks(aligned_path)
+the_aperture, aperture_path = afa.place_aperture(aligned_path)
+```
+To better understand how to write a script for your specific purposes, we direct you to [demo 1](demos/demo_1_alignment/README.md). [Demo 1](demos/demo_1_alignment/README.md) also describes how AFA alignment works.
+
+All of these functions depend on reliable detection of facial landmarks, which is provided by the [DLIB](http://dlib.net) library. Alignment is based on generalized Procrustes analysis (GPA), which extensively unit tested.
+
+# Additional functions (warping)
+Automatic landmark detection means that it is also easy to separate **shape** and **texture** in order to produce various kinds of **warped** images.
+
+AFA provides functions for two types of face-warping manipulations common in face perception research.
+
+### Morphing between faces
+To learn how to do this please see [demo 2](demos/demo_2_morphing/README.md).
+
+### Enhanced average of facial identity
+To learn how to do this please see [demo 3](demos/demo_3_averaging/README.md).
+
+# Setup
+
+It is highly recommended that you have **conda** installed, preferably **miniconda** rather than full fat **anaconda**.
+
+If you do have **conda**, then this is the easiest way to install:
+
+```bash
+conda create --name myenv conda-forge::dlib "python>=3.9" scikit-image
+
+conda activate myenv
+
+conda install -c conda-forge matplotlib
+```
+
+To install AFA next you have two options:
+
+You either do this:
+
+```bash
+pip install "alignfaces @ git+https://[email protected]/SourCherries/auto-face-align.git"
+```
+
+Or if instead you want a readable and editable copy of AFA on your local machine, then first clone this repository, go to the root folder `auto-face-align`, and then do this:
+
+```bash
+pip install .
+```
+
+Regardless of how you installed AFA, the above process will create a new virtual environment called `myenv`. You can use another name for that. You'll need to activate this environment using `conda activate myenv` whenever you want to use AFA. To deactivate, simply type `conda deactivate myenv`.
+
+If you have a readable/editable copy of AFA on your local machine, you will have copies of all the demos. Most users will want those demo scripts to get started on their projects.
+
+Other users may want a readable/editable copy of AFA to contribute to AFA, or to evaluate AFA by running the analyses under `results` or the unit tests. To run the unit tests, go to the root folder `auto-face-align` then do this:
+
+```bash
+pip install -U pytest
+pytest -v src/alignfaces/tests/
+```
+
+# How well does this work?
+In addition to unit-testing critical computations, I evaluated both landmark estimation (DLIB) and the outcome of the entire alignment procedure using various face databases. The results are described [here](results/README.md).
+
+<!-- ## Ensure that you have the proper C compiler
+On Linux, you will already have an appropriate C compiler.
+
+On Windows, you need to install Microsoft Visual Studio.
+
+On Mac, you need to install Xcode Command Line Tools.
+1. Find an Xcode version compatible with your [macOS version](https://en.wikipedia.org/wiki/Xcode).
+2. Get the right version of [Xcode Command Line Tools](https://developer.apple.com/downloads/index.action).
+``` -->
+
+# Citation
+If you use this package for your research, please cite the following preprint:
+>Gaspar, C. M., & Garrod, O. G. B. (2021, November 8). A Python toolbox for Automatic Face Alignment (AFA). Retrieved from psyarxiv.com/erc8a
+
+DOI:
+>10.31234/osf.io/erc8a
+
+# License
+This module is under an Apache-2.0 license.

demos/demo_1_alignment/LICENSE_COLLAGE_MAKER

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Dmitry Alimov
+
+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.