Facial Landmarking Software ———————————————————————————————————— This software has been tested on Matlab 2009 and newer. Note that the Matlab installation should include the Statistical Toolbox. ———————————————————————————————————— This facial landmarking algorithm was developed for a specific dataset of faces of Tanzanian children, 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. A few remarks that might be useful for users of the software: (a) In this version, we assume that all faces are coarsely spatially aligned and approximately 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. (b) A template face 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 by the NIH FaceBase Consortium projects. Our experience has been that a training set of 30-50 faces is sufficient. (c) 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. (d) The facial meshes should be in standard .OBJ format. The .OBJ filenames should begin with a letter rather than a number. (e) 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. a. 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’. b. 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) c. 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: a. Install Meshlab in the Applications folder b. 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. c. With a text editor, open the file 'compute_many.sh’ and in the first line type: #!/bin/sh d. Save the file. e. 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 f. Within Matlab execute the following command: >> savemesh For WINDOWS system users: a. Install Meshlab in the default directory C:/Program Files/VCG/MeshLab/ b. 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. c. 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 d. 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 a. 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. b. 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. ------------------------------------------------------------------------------------------------------------------------------------ Grass Pollen Classification Software This package contains all Matlab functions needed to calculate the image features used in the analysis of grass pollen described in: L. Mander, M. Li, W. Mio, C. Fowlkes, S. Punyasena, Identification of Grass Pollen Through the Quantitative Analysis of Surface Ornamentation and Texture, Proc Royal Soc B: Biological Sciences, 280(1770):20131905. DOI: 10.1098/rspb.2013.1905 A few remarks: (a) The study was based on grayscale scanning electron microscopy (SEM) images of the surface of pollen grains, but the software can be used for analyses of images exhibiting similar patterns. (b) To simplify use, place all contents of this package and all images to be analyzed in a single folder, say, Pollen. (c) Images can be in any standard format such as .png, .tiff, etc. (d) The package contains three functions that perform the following operations: (i) calculate the size and density features described in the paper; (ii) pre-process the images for computing a topological feature derived from subgraph centrality; (iii) calculate the topological feature. These are referred to as features tau1 and tau2 in the paper. ****************************************************************************************** Step 1. Computation of size and density features The output of these calculations will be a file named SD.MAT containing an Nx2 matrix, where N is the number of images. The first column gives the size features of the input images and the second column gives the density features. Note: the default file type is set to ’png’, but it can be changed to any standard image format. The window size (see paper) is set to 100, but can be changed as well. Within Matlab, set the working directory to the folder Pollen, and execute the following Matlab command: file=dir('*.png'); windowsize=100; for k=1:length(file) [SD(k,1) SD(k,2)]=csd(file(k).name,windowsize); end save SD ****************************************************************************** Step 2. Image Pre-processing Before running this pre-processing algorithm, the user should use the output of Step 1 to classify each image as one of the following two types: small granules (SG) or large granules (LG)(see paper). Once this is done, create two vectors named SG and LG containing the indexes of the small granule samples and large granule samples, respectively. For example, SG=[1 2 4] means that images 1, 2, and 4 have been labeled as having small granules and LG=[3 5] means that images 3 and 5 have been labeled as having large granules. The output H is a cell containing the resulting binary images. Within Matlab, set the working directory to Pollen and execute the following Matlab commands: windowsize=50; for s=1:length(SG) k=SG(s); H{k}=process(file(k).name,windowsize,2); end for s=1:length(LG) k=LG(s); H{k}=process(file(k).name,windowsize,3); end save H ********************************************************************************** Step 3. Computation of the topological feature based on subgraph centrality This calculation will use the information contained in the output H of the previous step. The algorithm offers three different options: topological features of the entire image (1), image foreground only (2), and image background only (3). Within Matlab, set the working directory to Pollen, and execute the following Matlab commands: Note: set flag to 1, 2, or 3 according to the three options above. The default setting is entire image (1). flag=1; for k=1:length(file) G(k,:)=pollen(H{k},flag); end save G The output will be a G.MAT file containing a Nx20 matrix. Each row represents the 20-dimensional topological feature vector of an image.