Morphometrics

Morphometrics Workflow

Photogrammetry and Slicer Workflow for 3D Geometric Morphometrics

Software

3D Slicer

Extensions

- SlicerIGT
- SlicerMorph

The following walkthrough provides instructions on how to import, align, fix landmarks to, and analyze data from the models created in Reality Capture. Before any of this is achieved, it is important to load the correct modules into 3D Slicer.

Loading Modules

  1. On the main task ribbon, find the icon for Extensions Manager
    • Blue icon with a puzzlepiece and capital ‘E’
    • This will pull open a window with a Manage Extensions tab and a Install Extensions tab
  2. Navigate to the Install Extensions window
    • You can either scroll through the available extensions to find the ones needed or use the search window in the top right corner
  3. Once the extensions are installed, navigate back to the Welcome to Slicer screen Fig.1
Figure 1: Welcome to Slicer

Importing Data

This step specifies the process of loading data for a single model with no associated landmark data. For more details on how to import multiple files for alignment and landmark configuration see the Alignment and ALPACA sections below

  1. To import the Reality Capture models, click on the Add Data button
    • This button can be found twice on the welcome screen or under the File dropdown menu
  2. Select Choose File(s) to Add
    • Files for this project can be found under Photogrammetry/Lightroom/Dcusimano
    • Select both the Model (OBJ) file and the Texture (JPEG) file Fig.2
    • Give the software a moment to load your data and you should see two images loaded Fig.2
    • To keep track of what files are loaded in Slicer, navigate to the Data window from the Modules dropdown menu. See Below
  3. While not important for this step, you can check to see that your Texture file works with the model by opening the Texture Model modules
    • This can be done by either scrolling through the Modules dropdown menu to the Surface Models tab and then to the Texture Model module or by clicking on the magnifying class in the task ribbon and searching for Texture Model
    • In either case you will open a window with three boxes for data and parameters.
      • In the Model box, make sure your Reality Capture OBJ file is selected
      • In the Texture box, make sure your resized PNG texture file is selected
      • The last box provides the option to save color information as point data. My practice is to set this as RGB Vector
    • Click on Apply to see your textured model Fig.3

Figure 2: Loading Data
Figure 3: Textured Model

Model Alignment

When working with multiple models it becomes important to make sure that each is in the same alignment within a 3D cartesian plane. To accomplish this we make use of the FastModelAlign module available through slicer morph.

This step requires at least two models. We recommend establishing one model as the template for this step as well as for the landmark configuration process in future steps.

  1. Load in an additional model.
    • follow the steps from above and check that you have two models loaded in the Data window
  2. Find the SlicerMorph tab under the Modules dropdown menu
    • Select SlicerMorph Utilities
      • Select FastModelAlign
  3. The options in this model are somewhat misleading
    • Under Source Model select the model that you are trying to align to a template
    • Under Target Model select the model that you will use as a template
    • Click on the box that says Skip Scaling
    • For the Output registered model select the same model as you used for Source Model
  4. Click on the Test pointcloud subsampling button
    • Give it a moment to generate a point cloud. Typically between 5000-5500 points
  5. Click on Run rigid registration

Once the rigid registration is completed both models will be overlapping. To see the differences between the two models you can choose to have one textured and the other not or you can navigate back to the Data window and change the colors of either model.

Figure 4: Aligned Models
  1. With this complete, click on the Save button
    • This will open a Save Scene window with multiple files selected
    • Make sure that only the file you need to save is selected, in this case the model that was being aligned.

Landmark Configuration

The process of placing landmarks in 3D Slicer is not overly complicated as long as the user has the following:

  • A list of desired landmarks
  • Definitions of each landmark with instructions on how to find it this sometimes differs if taking the landmark manually or digitally
  • A clear method of organizing landmarks so that each landmarking sequence is the same for every specimen
  • A clear way of lablling landmarks and format for saving landmark files
  1. The module used for configuring Geometric Morphometric landmarks is called Markups and can be found either in the modules dropdown menu or on the primary task ribbon.
    • In either case, the module wile be associated with an icon that looks like three red asteristks arranged in a triangle.
  2. Once in the Markups module, select the Point List button to establish your coordinate file.
    • Slicer will give this list a priliminary name which should be changed to suit suit the researchers needs
      • I use the prefix LM followed by an underscore* and the specimen number
      • Ex. LM_####
      • *The underscore becomes important latter when using this landmark data in R. This is because R does not like spaces in file names.
  3. After naming the Point List, open the Display and Control Points menus below.
    • When hovering the cursor over the model, a potential point will display with an icon and specimen/point number
    • For ease of use, the size of both or either of these features can be changed in the display menu
    • Set this to your preference (often a touch smaller than the default)
    • It is good to follow what point number you are on. For each specimen assessed through this workflow, the point numbers should match. For example, if point one on specimen one is Left Alare, point one on all specimens should be Left Alare. Do Not Rearrange the Points for Different Specimens
Figure 5: Placing Landmarks
Figure 6: Landmark Set
  1. A couple of notes on using Markups
    • To place a Control Point, make sure the Place control point button is selected
    • While placing control points, left clicking anywhere will place a point. If you need to rotate the model, right click to switch back to the cursor. Then click the Place control point button above to switch back.
    • If a control point is placed in the wrong spot (inevitable in this process) it is better to move it than to delete it.
      • If it is in the wrong order (i.e. you placed the right before the left) you can either move multiple points or rename the points. Either case is better than deleting the control point.
    • When developing your Point List it is good practice to name each point in the corresponding description box
      • This will become even more useful later
  2. Craniometric Points in Slicer
    • Placing points in Slicer has it’s advantages and disadvantages
    • Advantages
      • The R, A, S (Right, Anterior, Superior) fields can allow one to find the most lateral, anterior, superior, and etcetera surfaces on the model.
      • If your scale was set appropriately in Reality Capture, finding points such as Opisthocranion become simple by using the line tool to measure the distance from Glabella to the farthest surface on the posterior aspect of the skull
      • The model is easily rotated to establish points such as Basion on the inferior aspect of the skull
      • It is easy to visually keep track of data along the way by keeping each control point viewable
    • Disadvantages
      • There is no question that some detail is lost
        • Faint suture lines, for example, that may be visible with appropriate light and magnification are occassionally lost in the digital format
        • Features that are sometimes easier to feel (i.e., temporal lines) are more difficult to discern
        • To clarify how each of the landmarks used in this study were obtained, a Data Dictionary with descriptive text and images will be generated soon.
  3. Saving Data
    • Once all points have been established, click on the Save button in the primary task ribbon
    • Be sure to only select the file that you intended (Slicer will auto-select multiple files) and establish the proper directory for it
      • Since we modified the cloned landmark set, Slicer attempts to save this file with the original template data
    • When you click on Save from this window, Slicer will alert you to warnings which occured while saving. Ignore this and save away.

ALPACA!

Once a primary Point List is established with one model, SlicerMorph provides a wonderful shortcut for establishing the same point list for other specimens. This is done through the ALPACA module.

  1. Find SlicerMorph from the modules dropdown menu.
    • Hover over Geometric Morphometrics
      • Select ALPACA
  2. There are a few data fields to fill in
    • Under Source Model select the model you are using for a template
      • This will likely be the same template model used for Alignment
      • Be sure that you have the necessary landmark data associated with this model
    • Under Source Landmark Set select the .fcsv file (Point List) you saved with the coordinate data
    • Under Target Model select the model file that does not have associated coordinate data
    • Make sure that Scaling and Projection are not chaecked
    • Leave the Target Landmark Set (Optional) field blank
  3. Select Run subsampling
    • *Be aware that if you have the texture data loaded for any of the models when running APACA, the subsampling process will not work. Make sure you only have Model and Landmark data loaded
    • You will generate a pointcloud (similar to the alignment process) that sits somewhere between 5000-5500 points
  4. Select Run ALPACA
    • When ALPACA is complete you will be provided with a clone of the landmark data that can be modified over your target model.
    • There are a couple of different files generated after running ALPACA. You can review these when navigating back to the Data module or, better for our purposes, back to the Markups module
    • In Markups you should see 3 Point Lists
      • The original template file
      • The cloned template file
      • The ALPACA extimate file
    • Despite the ALPACA effort, these files can never be perfectly placed on the new model. Thus, the next step is to manually adjust each control point to best match the landmark definition.
    • The main benefit of running ALPACA then becomes the transfer of the point list and the increased efficiency gained by adjusting points rather than placing new points.
    • __Be sure that you are adjusting the correct point list. I work with the Source_Landmarks_clone file
Figure 7: ALPACA Overlay
  1. Rename the Point List you are adjusting
    • Match the file format from above (i.e., LM_####)
  2. Load in the Texture data
    • Follow the instructions listed under Importing Data above
  3. Adjust Landmarks and save as described in the Landmark Configuration section above.

Consolidating Landmark Data

  1. Thus far, each Model, Texture, and Landmark file has been saved in its own folder.
    • Ex. Dcusimano -> Skull ###, Skull ###, Skull ###
    • With the incoming Landmark Data, I found it conveneient to have an additional folder for only this information
    • Ex. Dcusimano -> Coordinate Data
    • This will help tremendously when running our analyses in the next step

Generalized Procrustes Analysis in SlicerMorph

The last step for a typical Geometric Morphometric analysis in Slicer is to run the Generalized Procrustes Analysis (GPA). With a decent sample of Landmark data, this step is super simple.

  1. Navigate to the GPA module under the SlicerMorph tab in the modules dropdown menu SlicerMorph->Geometric Morphometrics->GPA
  2. Click on Select Landmark Files -If you consolidated your files into one folder, you can simply select all -It is possible to select the individual files from multiple folders, but far more tedious -Click the ... button next to the Select Output Directory field -I keep the output directory as the Coordinate Data folder -I choose to select the Use Boas coordinates for GPA button
  3. Select Execute GPA + PCA
    • When the analysis is complete, Slicer will provide you a few windows to explore your data
    • One option is to Navigate to the Explore Data/Results window from the GPA task ribbon
    • As a general assessment, I like to use the Plot LM Variance tool to see where most of the landmark variation is coming from

Figure 8: Generalized Procrustes Analysis
  1. Analysis files
    • While fun to explore the results in Slicer, the most important product of the GPA is the output files it provides.
      • These are viewable in the folder that was selected for Output Directory or by selecting View output files below the Execute GPA + PCA button
Figure 9: Output Files

The next processing steps can be found on the R_Analysis page.