0.2 Usage - JRKalyan/affign GitHub Wiki

Step-By-Step Guide to Affign

1. Download a Release

First download a release from the releases section for 0.2.0 or above. This comes with a detector from OpenCV and a trained model from kurnianggoro. Extract the zip file after downloading.

For now only windows machines have a build available, but alternatively you could build from source using CMake and OpenCV.

2. Open the Terminal

On Windows, press WINDOWS + R to bring up the run menu and type 'cmd' to open the command prompt. Alternatively search for command prompt or type 'cmd' directly into the windows search.

On Mac, open Applications -> Utilities -> Terminal.

On Linux, you most likely know how it works for your distro.

3. Navigate to the Download Directory

Find the full path to wherever you have extracted Affign from the zip file. This is the path to the directory that contains Affign.exe on windows or just the executable Affign on Unix.

To navigate to this directory, use 'cd' or change directory, followed by the full path that you want to go to. An example is typing the following into the terminal, and pressing enter:
cd c:/users/john/desktop/affign-0.2.0/

What this does is set the 'current working directory' to the folder where we extracted Affign, allowing us to easily run the executable that is within this folder. Now we can run the tool with a command simply by typing the name of the executable file (affign.exe on windows).

4. Run the tool

To run the application, we need to pass at least two arguments to Affign, where the images are that you want to align and where you want the aligned versions of the images to end up. Note that the original images will still exist, unaltered in their original location. These two commands are "--inputdirectory" and --"outputdirectory" respectively. You need to type the tool name, followed by a space, followed by a sequence of space-separated arguments that represent commands. In any order, you can specify --inputdirectory then a space then your full path to the input images, and do the same for --outputdirectory. If you know your two paths, then typing the following works: (just make sure that you substitute my/input/path and my/output/path with the correct paths!)
affign.exe --inputdirectory "my/input/path" --outputdirectory "my/output/path"

The short forms of these commands are listed below, along with other commands you might want to check out (but might want to leave completely alone, they aren't necessary to get the tool to work fine).

After entering that into the terminal, you have started Affign and it will print out progress in the terminal window for you to see what is going on. Wait for all images to be aligned; don't close the terminal as this will stop Affign as well. You will know that it is complete when the message "[STATUS] Media Processing Complete" shows up and you can see the prompt again and begin to type (the prompt is where you were typing that appears after typing a command in the terminal. It usually displays your current working directory mentioned earlier).

Currently Supported Commands

Commands given as arguments to the executable in affign have long and short names. In the list below, the long name is listed first followed by the character '|' followed by the short name, you only need to specify one of those followed by the command parameter if necessary. For example:
affign.exe --inputdirectory "path/to the/input images" --o path/tothe/output/

As of 0.2.0 the supported commands are:

  • --inputdirectory|--o [path]
    Required argument that specifies where the images are located

  • --outputdirectory|--o [path]
    Required argument that specifies where the aligned images will be stored

  • --modelpath|--m [path]
    Path to the trained landmark detector

  • --detectorpath|--d [path]
    Path to the face detector

  • --recursive [true|false]
    When set to 'true' affign will search through sub folders for images in the input directory

  • --version

  • --help
    This one just directs you here for now