UoMASM Tutorial 1: Building from existing points

An example of building and using Active Shape Models, assuming we have a set of images and associated points.
See for example, the data in the uomasm/examples directory.
If you do not have points for your images, see Tutorial 2.

Files and Directory structure

We will assume the following directory structure: 
- images   : Contains images
- points   : Contains associated points files
- models   : Contains parameter files and models
For convenience, we assume that for every image, images/imageX.jpg, there is an associated points file, points/imageX.pts.
Many of the parameter files contain image lists defining the images and associated points to use.
The basic image list format is as follows: 
image_dir: ../images/
points_dir: ../points/
images: {
  image00.pts : image00.jpg
  image01.pts : image01.jpg
  image02.pts : image02.jpg
  image03.pts : image03.jpg
  image04.pts : image04.jpg
}
To describe the lines connecting the points, we use a msm_curves file.

Building a shape model

To build a shape model from the data, create a parameter file in the models director, for example: build_shape_model.params.
From within the models directory, run: 
msm_build_shape_model -p build_shape_model.params
this will create a binary file, shape_model.bfs containing a msm_shape_model.

Displaying the modes of the model (command line)

You can use the tool msm_draw_shape_modes to create one or more EPS files showing the modes.
First create a parameter file, for example draw_shape_modes.params.
Then call: 
msm_draw_shape_modes -p draw_shape_modes.params
This will generate one file per mode, showing the mean shape and the effect of varying each parameter by +/-3SDs.
If you change the parameter make_movie to true, it will generate a sequence of movie frames, which can be collected and displayed with your favourite animation tool.

Displaying the modes of the model (GUI)

Use the GUI tool, qmsm_shape_mode_viewer: 
qmsm_shape_mode_viewer -s shape_model.bfs -c face_68pts.crvs

Building a single ASM

To build a single ASM, create a parameter file in the models directory, for example: build_asm1.params.
From within the models directory, run: 
masm_build_asm -p build_asm1.params
This builds a binary file, face1.masm, containing an ASM object.

Building a series of ASMs

First build a second ASM.
Create a second parameter file, for example build_asm2.params.
Run: 
masm_build_asm -p build_asm2.params
Set up a new parameter file defining which single ASMs to combine.
For instance, make_asm_series.params: 
// Directory for the models
model_dir: ./

// List of built models
model_files: {
  face1.masm
  face2.masm
}
Run: 
masm_make_asm_series -p make_asm_series.params -o face_series.masms

Searching new images using a GUI

You can use the qasm_markup_tool to search new images with the model you have just built.

Testing performance of ASMs

Use the masm_test_search tool.
Set up a parameter file, for instance test_search.params.
The tool allows you to initialise the shape model points with examples from one directory (initial_points_dir), run the series of ASMs, then compare the result with points defined in a second directory (points_dir).
If initial_points_dir=points_dir then this just gives an idea of whether the model converges given the correct starting point. Run: 
masm_test_search -p test_search.params
UoMASM Index