qmsm_shape_editor: Tool for manipulating points on an image

A tool which allows a user to When multiple images and points are to be viewed or corrected, a file listing all the images+points files can be loaded.
Use the mouse wheel to zoom in and out.
An initial shape and associated curves can be created with the qmsm_markup_tool.

Command line options

General options:
-s shape_model.msm : Load in named shape model
-bs 1.2 : Bounds border scale used when zooming to bounding box.
-ct 0 : Curves type (see Displaying curves)

Run the tool using either: 
qmsm_shape_editor -i image.png -p points.pts [-c curves.crvs] [-s shape_model.msm] [-ct 0] [-cc curve_cols.ccol]
where curves.crvs is a curves file and shape_model.msm contains an msm_shape_model object (for instance, built by the msm_build_shape_model tool.
or: 
qmsm_shape_editor -l image_list.txt [-c curves.crvs] [-s shape_model.msm] [-pi pts_info.txt] [-ct 2] [-bs 1.2]
where 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/

// Optional: Directory containing other points to be displayed but not changed.
guide_points_dir: ./guide_points/

// Optional notes file folder. When supplied text notes files saved here with names pointsfilename.txt
notes_dir: ./notes/


// Optional list of points which are frozen (and thus cannot be moved at all)
frozen_pts: { 0:30  37:47 }



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.

Extra status information

The "-pi" option reads in information from a text file containing one line of text for each points file, in the format: 
example1.pts  Some information here
example2.pts  Some other information here.
...
The text on the line after the points name will be recorded and displayed on the status bar at the bottom of the window when those points are read in.
This is useful for displaying the quality of fit or other measurements associated with the points.
Here's a simple Python script to read a text file with information about each points file (such as that saved by some other processing tool) and writing out the "pts_name" column and "global_qof" column. 
import pandas as pd
import numpy as np

df=pd.read_csv("results.txt",delimiter=' ')
g_fit=df["global_qof"].to_numpy()
pts_name=df["pts_name"].to_numpy();

with open("pts_info.txt",'w') as f:
  for i in range(len(g_fit)):
    f.write(pts_name[i]+f" QoF: {g_fit[i]:.1f}\n")
    
print("Wrote pts_info.txt")

Displaying curves

The -c enables loading of a curves file, describing how to join the points with arcs.
The -ct (curve type) flag enables selecting options for the case when the points include varying numbers of blocks. For instance, there might be 6 points placed on each vertebra of a spine, but the number of vertebra varies from image to image. Thus the number of points is some multiple of 6. In such a case we can define a curves file for 6 points, then use it on each block of points. Set the -ct to 2 for this.
Options are:
-ct 0 : Just use the supplied curves file once
-ct 1 : Connect all the points with a single curve (ignore curves file)
-ct 2 : Use the curves on each block independently. Note that the block size is computed from the largest point index in the curve file (ie max_index+1). So the file must include the last point index in the block.

Point State

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

Multi-colour curves

Each individual curve can be given a different colour.
For instance:

The colours are defined using a separate curve colour file (.ccol) which can be loaded using the -cc flag from the command line, or via the File menu.
A curves file usually gives a name to each curve. For instance:
curves: {
  curve:  { name: Chin open: true indices: { 0:14 } } 
  curve:  { name: LEyebrow open: false indices: { 15:20 } } 
  curve:  { name: REyebrow open: false indices: { 21:26 } } 
  curve:  { name: LEye open: false indices: { 27:30 } } 
  curve:  { name: REye open: false indices: { 32:35 } } 
  curve:  { name: Nose open: true indices: { 37:45 } } 
  curve:  { name: Nostrils open: true indices: { 46 47 } } 
  curve:  { name: OuterLips open: false indices: { 48:59 } } 
  curve:  { name: TopLip open: true indices: { 48 60 61 62 54 } } 
  curve:  { name: BottomLip open: true indices: { 54 63 64 65 48 } } 
}
The curve colour file defines the colour to use for each curve: 
// Colour associated with each curve (by curve name)
default_color: green
colors:
{
  Chin : yellow
  LEyebrow : orange
  REyebrow : orange
  Nose : #0000FF
  OuterLips : red
  TopLip : red
  BottomLip : red
}
The colour is either a name (defined by QColor) or a hexadecimal code, such as "#0000FF" in the above.
The code is #RRGGBB where RR is a two digit hexadecimal defining the amount of red, GG for green, BB for blue (So #0000FF is pure blue).

Menu Options

File Menu

View Menu

Props Menu

Help Menu

Interaction Modes

Drag Mode Click and drag to move viewport around
Select Mode Press and drag to move a point. Rubber-band box to select groups.
Drag-Shape Mode Click and drag a point to move it. All un-fixed points are dragged around to satisfy shape model constraints.
Equal Space Mode Click on a point to equally space points on the curve through the point, limited by either the ends of the curve or fixed points.
The "Clear" button sets all points to not fixed.

Undo/Redo

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

Point Manipulation

Translating all the points

To drag all the points at once, either

Rotating/Scaling all the points

Two steps:

Using a Shape Model to guide the points

If you have loaded a shape model, when you are in the Drag-Shape mode it can be used to help move points around.
When you click and drag, any points which are not fixed will be moved around so that they best satisfy the shape constraints. To avoid this being over-constrained (as may be the case when there are few shape parameters available), a residual term is calculated for each point to ensure smooth deformation. This is calculated by performing a weighted least squares fit of the model to the fixed points. Any residual term at each point is recorded, and a Thin-Plate Spline used to propogate the residual to all other points. This is simple but pleasingly effective.

Notes files

When a notes directory is supplied (using the notes_dir: field in the image list file), there is the option to display or edit text notes associated with each points file. This is useful for recording arbitrary extra information about various examples.
For a given points file, say "points1.pts", the associated notes file will be found at "notes_dir/points1.pts.txt" (the name is the same as the points file name, with ".txt" appended).
When the notes editing dialog is visible (use View->Show notes to pop it up), then the contents of the notes file will be automatically loaded and displayed in the dialog.
If no notes_dir field is available, no dialog will be displayed.
If no notes file exists with the expected name, the dialog will be blank.
If the text in the dialog is editted, it will be saved to the notes file the next time one moves to a new image.
Whenever one moves to a new image, the relevant notes will be displayed.
This is useful for tagging files to indicate some information - just write a suitable keyword into the notes file. You can then scan the notes files in the folder to look for the keyword.