qmsm_key_markup: A tool to guide point annotation

A tool to guide the annotation of images, focussing first on key points, followed by remaining points.
The tool reads in information relating to the key points and their associated descriptions, along with a shape model and the full set of points.
As a user iterates through each key point, the pop-up guide window demonstrates where points should be placed.
The pop-up window shows an overview of the guide image, with all key points, and an image focussing on the key point under consideration.
Once all key points are placed, remaining points are estimated via the inputted shape model with fine tuning performed by the user.


The tool can also read in an "image list" file, containing a list of the images to be annotated and the names of the points files to which results will be saved.
Use the mouse wheel to zoom in and out.

Command line options

Run the tool use: 
qmsm_key_markup
or: 
qmsm_key_markup -l image_list.txt -p guide_summary.params
where
guide_summary.params is a parameters file describing the points to be annotated (see guidance)
image_list.txt is a text parameter file in the following format: 
// Define directories containing image and points files
image_dir: images/
points_dir: points/
images:
{
  example1.pts : example1.png
  example2.pts : example2.png
  example3.pts : example3.png
}
when this option is used (or such a list is loaded using the "File->Load Image List" option), the tool records the list of images and points, and displays the first one.
You can then step through the images using the left and right arrow keys, or the items on the View menu (for first/last).
If you edit any points, when you attempt to move to another image it will ask you if you wish to save the changes (overwritting the existing file). If you set the "Always Save Points" flag (in the Props menu), then it will always save the points, without asking, when you move to the next image.

The final argument is the list of keypoints to be considered, denoted by their integer values.

Setting up the guidance information

Two things are required to set up the guidance:
  1. A guide_summary params file pointing the tool in the direction of the shape model, the .crvs curves file and the key point image directory.
  2. A set of guide images. These can be produced by the qmsm_get_guide_patches tool.

Guidance summary file

Example describing the parameters for two key points: 
shape_model: shape_model.msm
curves: models/face_27pts.crvs
key_pt_image_dir: key_patches
key_points: {
  key_point: { name: {KeyPoint 2}
    def: {Mouth: right corner}
    image_name: patch_02.png index: 2
  }
  key_point: { name: {KeyPoint 3}
    def: {Mouth: left corner}
    image_name: patch_03.png index: 3
  }
}

Example image patches

Create an image to help the user locate the point, with a file name to match that in the guidance text file.
You can generate these automatically if you have a representative image and a set of points (eg generated using the qmsm_markup_tool.
Use the following: 
qmsm_get_guide_patches -p typical.pts -i typical_image.png -o guide_patches_6pts/ -pwp 0.4
This automatically generates images for each point (like those shown above), and saves them to the named directory.
It also generates a basic guide_summary.params file, suitable for using with qmsm_key_markup, which can be editted to add more detailed descriptions of the points.

Point State

The colours of the points indicate their state.
Unless you have changed them (using the Graph Props), they are as follows:

Menu Options

File Menu

View Menu

Props Menu

Help Menu

Interaction Modes

Drag Mode Click and drag to move viewport around
Intensity-Windowing Mode Click and drag to change the intensity windowing ranges
Add Point Mode Click to add new point
Add Curve Mode Click new position to extend point from currently highlighted point
Select Mode Press and drag to move a point. Rubber-band box to select groups.
Equal Space Mode Press to evenly space out all points between highlighted points.
UnFix points Free fixed points. Allows non-keypoints to be moved
Remove points and curves Clears image of points and curves
When in "Add Curve" mode, you can link to an existing point by clicking on it.
To start a new curve, click on the currently selected point (to deselect it), then click in a new position to create a new point and select it. A second click elsewhere with create a new point and connect to it.

Undo/Redo

The undo/redo buttons allow you to do just that.