shape = mean + P*bwhere mean is the mean shape, P is a matrix of modes of variation and b is a vector of shape parameters.
All the tools assume that points are provided in text files in one of the two formats shown below.
The msm_points class encodes a set of points which can be read from/written to a text file in the format shown below.
version: 1 n_points: 3 { 316.069 201.255 410.593 206.549 333.881 320.539 }Note that points in a simpler two column format can also be read in:
3 316.069 201.255 410.593 206.549 333.881 320.539The first line indicates how many points follow.
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 elements of each curve are:
// Directories containing data: points_dir: ../points/ image_dir: ../images/ images: { image001.pts : image001.png image002.pts : image002.png image003.pts : image003.png // ... }Comments can be added using "//" - anything after this on the line will be ignored (C++ style).
msm_subset_points pt_index.txt in.pts out.ptsThis loads in a list of point indices from pt_index.txt and a set of points from in.pts. It then saves only the subset into out.pts.
0 1 // Eyes 5 6 7 8 9 // MouthIt can be used to process all the files in a directory with a (bash) script such as:
mkdir new_points for i in *.pts do msm_subset_points pt_index.txt $i new_points/$i done
msm_concat_points points1.pts points2.pts ... output.ptsLoad in two or more of points, write out a file containing all points (in the order listed).
msm_concat_curves shape1.crvs shape2.crvs all_shapes.crvsThis assumes that each curves file includes the point with the largest index (which it uses to work out how many points are in the set).
msm_reflect_points -i input.pts -x 511 -o output.ptsLoad in a set of points, reflect about line x=value, save to output.pts
msm_equally_space_points -p param_file [-c curves][-od output_dir]For each curve, fit a cubic bezier, then move internal points so that they are equally spaced along the curve.
// Curves file (or curves themselves) defining which points to be moved. // All internal points on a curve are slid along the cubic bezier through // the points so that they are equally spaced. curves: equal_spacing.crvs //: Directory to new points out_points_dir: /home/equal_spaced_points/ //: Smallest separation of points on bezier curve min_bez_sep: 0.5 image_dir: /home/images/ points_dir: /home/points/ images: { image1.pts : image1.jpg image2.pts : image2.jpg }
msm_apply_tps_warp -sc src_control.pts -dc dest_control.pts -sp src.pts -dp new_dest.ptsUses a Thin Plate Spline, constructed from src_control points and dest_control points to warp src points.
msm_build_shape_model -p build_shape_model.paramsThe parameter file should look something like this:
/: Aligner for shape model aligner: msm_similarity_aligner //: Define how to align mean shape in reference frame // Options: { first_shape, mean_pose } ref_pose_source: first_shape //: Object to apply limits to parameters param_limiter: msm_ellipsoid_limiter { accept_prop: 0.98 } // Minimum number of shape modes min_modes: 0 // Maximum number of shape modes max_modes: 99 // Proportion of shape variation to explain var_prop: 0.95 //: File to save model to shape_model_path: shape_model.msm image_dir: ../images/ points_dir: ../points/ images: { image1.pts : image1.jpg image2.pts : image2.jpg // ... }This will build a linear statistical shape model from the supplied examples (image1.pts etc) and save it to the named file (shape_model.msm) The main choices to be made are
msm_draw_shape_modes -p draw_shape_modes.paramswhere draw_shape_modes.params looks something like this:
//: File to load model from shape_model_path: face_68pts.msm curves_path: face_68pts.crvs // Maximum number of shape modes max_modes: 5 //: Number of SDs to vary mode by n_sds: 3.0 //: Current number of shapes per mode n_per_mode: 3 //: When true, generate 2*n_per_mode frames of a movie for each mode make_movie: false //: When true, overlap all the shapes to highlight changes // Shapes on one side of mean are drawn with dashes, on the other with dots. overlap_shapes: false //: Radius of points to display (if <0, then don't draw points) point_radius: 2 //: Line width line-width: 1 line_colour: black point_colour: red //: Colour of background (or "none" for transparent) background_colour: white // Approximate width of region to display shape width: 200 base_name: face output_dir: ./This will generate one file per mode, showing the mean shape and the effect of varying each parameter by +/-3SDs.
msm_get_shape_params -p param_file.txt -o params.txtparam_file.txt should contain:
shape_model_path: shape_model.msm image_dir: ./images points_dir: ./points images: { image1.pts : image1.png // ... }Parameters are saved to params.txt, one line per example.
msm_get_shape_params -p param_file.txt -o params.txt -h histoThis will then save histogram information to histo_b1.txt, bisto_b2.txt etc
plot "histo_b1.txt" with boxesBy default the parameters are in units defined in the model frame.
msm_get_shape_params -p param_file.txt -o params.txt -h histo -rel_pIn that case the histograms can easily be compared to that of a unit gaussian in gnuplot:
plot "histo_b1.txt" with boxes, exp(-0.5*x*x)/sqrt(2*pi)The range of the histo can be set with" -hr 4.0", and the number of bins with "-hn 101".
3 7 2 0 4 8 1 6 5 9when reflected, this becomes:
7 3 6 1 8 4 0 2 9 5To construct the permutation list, identify the new index for each point:
Original : 0 1 2 3 4 5 6 7 8 9 Reflected: 1 0 6 7 8 9 2 3 4 5The lower line gives the list describing the permutation required.
msm_guess_ref_sym -i image_list.txt -r0 1 -r1 7 -o ref_sym.txtThis information can be used in the parameter files by adding the line:
reflection_symmetry: { 1 0 6:9 2:5 }When this is supplied the tool will generate a reflected version of the shape and include it in the set, doubling the number of examples available.