Facial Landmarking Software

This facial landmarking algorithm was developed for the FaceBase 1 Tanzanian GWAS dataset (from the Genetic Determinants of Orofacial Shape and Relationship to Cleft Lip/Palate project), but it should be applicable to other facial data represented by meshes of similar structure and quality. The algorithm uses a landmarked template and transfers the landmarks to a given subject through a dense shape morph.

Download the algorithm here.

In this version, we assume that all faces are coarsely spatially aligned and roughly at the same scale, as indicated in the file `readme_image1’ that is included in this distribution. Finer alignment and scaling are done by the algorithm. We will soon release a semi-automated version that asks the user to coarsely mark three specific landmark points for faces that do not satisfy these requirements.
The mean face used as a template for the Tanzanian GWAS data is included in this distribution, but we also provide code for construction of a new template from a training set of manually (or otherwise) landmarked faces. These landmarks should be homologous to the 29 landmarks used in FaceBase 1. Our experience has been that a training set of 30-50 faces is sufficient.
The landmarking algorithm first generates a set of control points that are subsequently used to guide a dense morph of the template to the face to be landmarked.
The facial meshes should be in standard .OBJ format. The .OBJ filenames should begin with a letter rather than a number.
We also include instructions for calculating curvature maps for facial meshes using the open source software Meshlab. The curvature map is needed for the construction of a mean face, as well as for landmarking. Since batch computation is the most useful mode, we provide instructions to do it via command line for users that are not familiar with this Meshlab capability.

Step 1. Set up

In addition to this readme file, the package contains two folders named ‘Subjects’ and ‘Training’, as well as an image file ‘readme_image1’ and a file named ‘Meanshape.MAT’.
If you are going to construct a new template face, place all training meshes in .OBJ format in the folder ‘Training’. Also, create an Excel file named ‘ManualLM.xls’ with landmark data for each training face. Each row should contain data for a single subject. Begin with the subject ID, followed by the x,y,z coordinates for landmarks 1–29. Thus, each row will have 1 + 3x29 = 88 cells. An Excel template in which you can enter your data is provided in the folder ‘Training’.

IMPORTANT: In the excel file, subject IDs should be sorted in ascending order (Excel has a command that will do that for you).
Similarly, place all .OBJ files for the faces to be landmarked in the folder ’Subjects’.

IMPORTANT: The .OBJ filenames should begin with a letter rather than a number. Also, make sure that there are no files in the directory other than those needed to run the landmarking program.

Step 2. Compute curvature maps for all meshes, including training data if computing a new mean face

The output of these calculations will be a .PLY file and a .MAT file for each of the original .OBJ files. The .PLY will contain both mesh and curvature data. The .MAT will contain similar data formatted for Matlab. This file will be needed in subsequent steps.

For MAC system users:

Install Meshlab in the Applications folder
Within Matlab, set the working directory to either Training or Subjects, and execute the following Matlab command:
```
>> Get_compute_many_Mac
```
This will generate a file named ‘compute_many.sh’. Note that >> is the Matlab prompt that you do not need to type in.
With a text editor, open the file 'compute_many.sh’ and in the first line type:
```
#!/bin/sh
```
Save the file.
Open a terminal window, cd to either the Training or Subjects directory and execute the following two commands to generate the .PLY files:
```
chmod +x compute_many.sh
./compute_many.sh
```
Within Matlab execute the following command:
```
>> savemesh
```

For WINDOWS system users:

Install Meshlab in the default directory C:/Program Files/VCG/MeshLab/
Within Matlab, set the working directory to either Training or Subjects, and execute the following Matlab command:
```
>> Get_compute_many_Windows
```
This will generate a file named ‘compute_many.bat’. Note that >> is the Matlab prompt that you do not need to type in.
Open a terminal window, cd to either the Training or Subjects directory and execute the following command to generate the .PLY files:
```
compute_many.bat
```
Within Matlab execute the following command:
```
>> savemesh
```

Step 3. Construction of a Mean Shape

This is for users who wish to construct a new mean shape instead of using the template included in this distribution. Our template is a mean face of Tanzanian children, so in some cases it may be wise to construct a new landmarked mean face. Skip this step if using the Tanzanian mean face.

Within Matlab, set the working directory to Training and execute the following command:

>> comp_meanshape

The output will be a file named Meanshape.MAT

Step 4. Landmarking Faces

Within Matlab, load the file Meanshape.MAT.

If you are using the template provided in this distribution, this file can be found in the main ‘Landmark_Software’ directory. If you computed your own mean shape, the file can be found in the Training folder.
Within Matlab, set the working directory to Subjects and execute the following command:
```
>> Landmarking
```
The output will be a file named Landmarks.xls containing the IDs, and the coordinates of the 29 landmarks. Each subject will also have a .MAT file that contains all data for that subject.