Modeling body and fin shape (morphometrics)

From AnyFish

Jump to: navigation, search


Overview: geometric morphometrics and TPS grids

anyFish allows the user to implement common quantitative methods for modeling the shape of fish fins and bodies. Specifically, anyFish takes advantage of geometric morphometrics, a powerful method for representing individual, population, or hypothetical variation in fish size and shape. More information about geometric morphometrics can be found and the SUNY Stony-Brook geometric morphometrics website [1]. The remainder of this tutorial describes the process used to summarize and incorporate body and fin shape variation into the anyFish platform. We start be describing the creation of geometric morphometric thine-plate spline (TPS) files using tpsUtil (used to create TPS files with the photos you select), landmarking images using tpsDig (used to 'digitize' morphological landmarks on your fish image), and summarizing populations level body and fin shape using tpsRelw (used to generate a 'consensus' file for your populations of interest, which can be used to determine the shape of the fish with the help of TPStoConsensus). anyFish currently supports two shapes that represent much of the current laboratory research on fish behavior: a poeciliid and stickleback (gasterosteid). We will need (modest) additional resources to model other fish families like percids, cichlids, and cyprinids. The geometric morphometric process employed here allows users to use point data to define the morphology of a fish. Most poeciliids and most sticklebacks can be modeled well by just replacing the default TPS grid for fins and body with one of your own. We discuss this process in greater detail below, and in the accompanying video tutorials.

Step-by-step Instructions

1. Morphological Data: Much of the power behind anyFish is the ability for the end user to manipulate the appearance of the animated fish. Several steps are required in order to manipulate the animation size and shape. We detail each step below. Your morphometric data will only work with anyFish if you follow these instructions exactly.

  • 1.1. Gather standard geometric morphometric data to quantify body shape:

The first step required to create your fish model is to acquire standardized digital images of the fish of interest. Digital images are used both to obtain morphological data and as skin 'textures' to be applied to the 3D model (step 1.3 below). Take digital photos of the side of the fish (left side for the stickleback model, right side for the poeciliid model) in the same position and under standardized lighting conditions. A size standard (e.g., a ruler) should be visible in each photograph in order to apply a scale factor. We recommend using a color standard (e.g. a QPcard 201 to optimize image color. We also recommend (although this is not required) saving images in the raw format to optimize image manipulation. Before assigning morphological landmarks using the TPS software line, images must be saved as in the jpeg format.

  • 1.2. Generate TPS files that contain morphological landmark data:

To capture the key morphological features of the fish of interest, including fin size and shape, the end user must assign a pre-determined set of landmarks (i.e., morphological points on the lateral image of the fish). For sticklebacks, apply the 56 landmarks described in Figure 1a. For poeciliids, apply the 42 landmarks described in Figure 1b. In order to apply this set of landmarks to each image, tpsUtil (Rohlf 2004) is used to create a TPS file containing all the photos of interest (see step 1.2.1 below). tpsDig (Rohlf 2009) is then used to set the coordinates of each landmark for each image of interest (see step 1.2.2 below). It is crucial that each landmark is correctly placed on each fish image, and that these landmarks are applied in the correct order for each image. Several landmarks reference the position of a trait, such as fins, when they are fully exposed and need to be estimated if these traits are not fully visible in the photograph (e.g. landmark 52 and 53 in Fig 1a). The TPS files that are generated during this step are used to determine the shape of the animated fish. It is important to note that as long as the TPS points are in the correct order, any set of coordinates can serve as TPS input. For example, it may be desirable to apply a shape that represents a population average or a hypothetical ancestor. Such consensus shapes can be calculated using tpsRelw (Rohlf 2008; see step 1.2.3 below). The TPS file will also be used to ‘warp’ images to a standard TPS template for use as textures in the anyFish editor (see TPS-transformer for details). Multiple TPS files can be loaded into the anyFish editor to change the shape of the animated fish. This feature provides the flexibility that is required to create a variety of stimuli.

    • It is essential that your TPS file have the exact same points as indicated in the images below. Any difference in the number, landmark location, or order of points will cause serious artifacts in your model. Make sure they conform EXACTLY to the homologous points on the images below. There are some ways to supply missing points if you have fewer landmarks, which we will discuss soon.
    • The coordinate system in the TPS file must be in pixels (non-negative integers).
    • The TPS file you load must be saved with the file extension .tps [Extension MUST BE in lowercase].
    • For poeciliids, it may be useful to set the y-value of landmark 22 (lower lip) equal to the y-value of landmark 1 (upper lip) during the 'warping' process in TPStransformer. Doing so removes an artificial elongation of the face in the final animation. To edit your TPS file, open it in Notepad and manually change the landmark values. We then recommend that you revert back to the original TPS file in the anyFish editor to accurately represent the shape of the mouth.
    • For some troubleshooting tips, check here: File:AnyFish.pdf
    • IMPORTANT NOTE: The current version of anyFish has a bug related to the scale factor of the TPS file. To fix this, manually reduce the scale by a power of 10 (e.g., change 0.001 to 0.01) in the TPS document. If you think you have done everything right and you open your fish in the anyFish editor and it is unrecognizable (looks like a spiky imploded fish), then this is the problem.

Stickleback model

Figure 1a: TPS morphometric landmarks used for stickleback model.

Poeciliid model

Figure 1b: TPS morphometric landmarks used for Poeciliidae model.

  • 1.2.1 Creating a tps file in tpsUtil

tpsUtil is a useful utility program that serves numerous functions in the geometric morphometric process. For the purposes of anyFish, tpsUtil is used to build a .tps file from images that will be used in other tps software programs to summarize fish body shape. The next few steps outline the same information that is contained in the video above.

tpsUtil Main Menu

Upon opening tpsUtil, the user should select 'Build tps file from images' from the drop down menu (Figure # below) under 'Operation.'

tpsUtil: Build File from Images

The user is now ready to select the input directory. To do so, select 'Input' under 'Input directory.' The user should place all images of interest into a single file folder. Navigate to the appropriate file folder and select an image.

tpsUtil: Select 'Input' to select input photos

The user now needs to designate an output folder. This folder can be the same folder specified above, or a different folder. During this step, the user must specify a .tps file name.

Once input and output directories have been specified, click 'Setup' under 'Actions' (see Figure # below).

tpsUtil: Setup Menu

Here, the user should ensure that all the desired images are selected. Click 'Create,' and check the Output file folder to ensure that a .tps file has been created.

  • 1.2.2 Digitizing morphological landmarks in tpsDig

tpsDig allows for users to digitize morphological landmarks on digital images. For the purposes of anyFish, users must digitize landmarks described in figures 1a and 1b above. The next few steps contain the same information as the video tutorial above.

Upon opening tpsDig, the user will see the main user interface with a blank workspace (see figure below).

tpsDig: Main Menu

The user will first need to open the TPS file created above in step 1.2.1. This is done by selecting 'File,' then 'Input source,' the 'File' from the main tool bar (see figure below). If this and previous steps have been performed correctly, the first image used to build the TPS file should appear in the workspace.

tpsDig: Open TPS file

Once the TPS file has been opened correctly, the user will now digitize the morphological landmarks discussed above in section 1.2, and seen below in Figures 1a (stickleback) and 1b (poeciliid). To begin digitizing landmarks, the user should click on the 'Digitize landmarks' icon found on the main tool bar (blue crosshairs; see figure below).

tpsDig: Digitize Landmarks

Once the user has clicked the Digitize landmarks icon, the cursor will become blue crosshairs. Using the mouse to navigate the blue crosshairs, the user can left-click on their mouse or trackpad to assign a landmark. Landmarks will appear as red dots on the fish image (size and color of dots and labels can be changed under Image tools). IMPORTANT NOTE: The user must be sure to apply the landmarks in the correct sequence described in figures 1a or 1b, depending on the model selected. Failure to do so will result in errors in the later stages of model creation.

tpsDig: Digitize Landmarks

Once landmarks have been digitized, the user should apply a scale to each image. To do so, first open the Image tools menu by selecting 'Image tools' under the 'Options' menu on the main tool bar (see figure below).

tpsDig: Opening Image tools

Once the 'Image tools' menu has opened, select the 'Measure' tab at the top of the window. Assign a reference length (e.g., 1), and select the appropriate unit (e.g., centimeter). Next, click the 'Set scale' button.

tpsDig: Image tools menu

Once the 'Set scale' button has been selected, the user can select an area (e.g., a ruler segment) on the image that represents the reference length and appropriate unit. This is done by clicking, dragging, and clicking the cursor at the appropriate locations (e.g., bars on the ruler). After the first single click, the user will see a line appear that originates at the location of the first single click (see upper left of figure below).

tpsDig: Setting the scale

Once the previous step is complete, the user should click 'OK' in the Image tools window to confirm the scale (see figure below).

tpsDig: Setting the scale

The user can follow the above steps for each photo included in the TPS file by scrolling through the images using the red left and right arrows at the left side of the main tool bar. Once landmarking is complete, the use should save the data by clicking 'File' then 'Save data.' At this point, the user should select 'OVERWRITE' data file.

tpsDig: Save Data

Once the above steps are complete, the user is ready to create shape consensus files (see TPStoConsensus for information on using consensus files in anyFish), or work directly with the anyFish interface.

  • 1.2.3 Creating shape consensus files in tpsRelw

  • 1.3. Copy TPS landmark files to TPS Folder.

A ‘projects’ folder is will appear inside the anyFish Editor folder once the end user has opened the anyFish editor and created a project. The projects folder can contain multiple project subfolders, and will be named according to the end user’s specification (e.g., SwordtailProject1). Each project subfolder (e.g., SwordtailProject1) will contain a ‘paths’, ‘textures’, and ‘tps’ folder. To use either specific TPS files or a population consensus TPS file, the end user should copy TPS files to the ‘tps’ folder inside the specific project subfolder within the ‘projects’. These TPS files will the appear as options in the anyFish editor. When selected, these TPS files will generate the shape of the model fish.

Personal tools