UoMApM Tutorial: Building a combined shape and texture appearance model.

An example of building a shape and texture appearance model 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, use the UoMASM tools.

Note: This assumes that you have put the various mapm and qapm tools somewhere so that they can be run from any directory. In the usual default configuration of VXL, all tools are built in the OBJ/bin directory. Thus you need to add this to your path (e.g. in your .profile or .bashrc script).

Files and Directory structure

I recommend the following general 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.
If a triangulation of the points is required (for instance by si2v_tri_region_sampler), then this can be created using the qapm_tri_editor tool.

Examples

The examples below are all stored in uomapm/examples.
To run the examples, open a command window and go into the examples/models directory.

Building the model

To build an appearance model (shape and texture), use a command with the following general form: 
mapm_build_app_model -p params.txt -o app_model.mapm
where params.txt has the following structure: 
builder: {
  shape_builder: { ... }
  tex_builder:  {
    sampler: si2v_tri_region_sampler { .. }

    tex_transform: ttfn_linear_tex_transform { }

    // Other parameters
    ...
   }

  min_modes: 0 max_modes: 77 var_prop: 0.99
  param_limiter: msm_ellipsoid_limiter { accept_prop: 0.98 }

  verbose: true
}

//: Define renumbering required under reflection
//  If defined, a reflected version of each shape is included in build
reflection_symmetry: { 1 0  3 2   7 6 5 4  13 12 11 10 9 8  14  16 15 17 18 19   21 20   23 22  26 27  24 25 }

//: When true, only use reflection. When false, use both reflection and original.
//  Only relevant when reflection_symmetry defined.
only_reflect: false


//: Number of image pyramid levels to build
max_im_pyr_levels: 4

image_dir: ../images/
points_dir: ../points_28/

images:
{
  d_image_0000.pts : d_image_0000.png
  d_image_0005.pts : d_image_0005.png
  d_image_0009.pts : d_image_0009.png
// ...etc...
}
A complete parameter file is given in build_app-tri-grey.params. Run the following command in examples/models: 
mapm_build_app_model -p build_app-tri-grey.params -o tri-grey.mapm
This builds an appearance model using a triangulated region to represent the texture.
You can view the mean and models using the following command: 
qapm_mode_viewer -m tri-grey.mapm
This should pop up a GUI which shows the first appearance mode as a static image.

Varying the parameters

The resolution of the model is controlled by the frame_width parameter. The choice of whether to build a greyscale or colour (RGB) model is controlled by the n_planes parameter.
Try building a colour model using: 
mapm_build_app_model -p build_app-tri-rgb.params -o tri-rgb.mapm
The only difference here is that in this n_planes is set to 3.

Sampling with boxes

Rather than sampling with a triangulated region, you can arrange to sample rectangular boxes around each point.
Run: 
mapm_build_app_model -p build_app-box-grey.params -o box-grey.mapm 

qapm_mode_viewer -m box-grey.mapm
In this case the sampler is set to: 
  sampler: si2v_patches_sampler { 
       frame_width: 100 
       default_grabber: si2v_box_patch_grabber { ni: 21 nj: 21 n_planes: 1 use_lin_norm: true }
    }
which samples boxes of size 21x21 around each point.

Generating images of the modes

The qapm_mode_viewer tool can be used to show the modes, and can save out individual images or frames. However, to automatically generate multiple mode images two command line tools are available:
  1. mapm_make_mode_images - Generate single images showing modes
  2. mapm_make_mode_movie - Generate sequences of images for each mode (which can be animated)

mapm_make_mode_images

Generates an image displaying the effect of varying one or more modes.
An example of use (assuming the box-grey.mapm model has been built): 
mapm_make_mode_images -apm box-grey.mapm -t app -nm 3 -o box-grey
This creates three images, box-grey_c1.png,box-grey_c2.png,box-grey_c3.png, showing the first threee modes. Similarly: 
mapm_make_mode_movie -apm box-grey.mapm -t app -mlo 1 -mhi 2 -o box-grey
creates a set of frames for modes 1 and 2, for example box-grey_c2_0XX.png, which can be played to visualise the movie of the mode (useful for creating videos for presentations).
If you have the href="https://www.imagemagick.org">ImageMagick tools installed, you can animate using 
animate box-grey_c1*.png

Extracting parameters for each example

Use 
mapm_get_apm_params -p get_apm_params.params -i box-grey.mapm -o box-grey
This will create three text files: each row of which contains the shape/tex/app. parameters. Details of what is included can be controlled by the parameter file.