README

Author:  N Dowson
Revised: 9 Aug 06
------------------------------------------------------------

This directory contains the entire MI testing framework used for my
PhD thesis. There are a large number of files, so I've broken them up
into categories. Files not listed below are not used.

The following files may not have been included: imgOp.cc, opt.cc,
AddTri.cc, CWarp.cc; because we are currently trying to organise a KTP
funded pproject and releasing all the code could result affect how
copyrights are assigned. Apologies. This should be rectified in time.


MATLAB EXECUTABLES AND HELP:

warthog.mexglx, warts.mexglx, wartr.mexglx: Matlab executables.
warthog.m, warts.m, wartr.m: Help files. See these .m's for more info.


COMMANDLINE TEST FRAME:

warthogNPWc.cc: Test frame for Chapter 5, on NP-windowing. See
		warthogNPWc.txt for more details.
warthogSRMIc.cc: Test frame for Chapter 4 on Super-resolution MI. See
		warthogSRMIc.txt for more details.
warthogUNIc.cc: Test frame for Chapter 3 for various similarity
		metrics. See warthogUNIc.txt for more details.


DIRECTORIES AND MISCELLANEOUS

debug/		: Storage for debug versions of files
data/		: All the datasets used for testing are stored here
fig/		: Figures outputted for use in Thesis
*Results/	: Results after running commandline test frames.

tstLoad*.m 	: Scripts to load test results
*Results/CvgBias?.m : Take results stored in matlab variable and
		generate Bias and convergence figures.
warthog*c	: Commandline executables for various tests.
warthog*c.cc 	: Code for Commandline executables for various tests. See
		corresponding .txt for more information.
W*.bin 		: Files holding the offset warp parameters used in each test
		frame.


LIBRARIES:

CImg/	: The CImg library. See http://cimg.sourceforge.net/ for more details.


MATLAB INTERFACE SOURCE CODE

These files implement the interface between the c++ source code and
matlab.

warthog.cc: Interface to optimise a cost function when varying the
warp parameter, for a given template, reference image, and initial
position(s). From the help in the m file:
% (WA)rp (R)eference to (T)emplate f(h)or (O)ptimal (G)raphic.
% Searches for the warp X giving the minimal value Y for a similarity
% function when projecting template T onto image I starting at point(s)
% W.  This is done using a choice optimisation algorithms, specified
% using P.  For MI metrics Z is used as a post-parzen window.

warts.cc: Interface to measure a cost function for a given template,
reference image, and warp parameter(s). From the help in the m file:
% (WA)rp (R)eference to (T)emlate for (S)imilarity measurement.
% Selectively measures the similarity values when projecting template T
% onto image Y using the warps W.  This is done using a choice a
% standard similarity measures, specified using P. For MI metrics Z is
% used as a\ post-parzen window.

wartr.cc: Interface to extract a region from a reference image, given
a template size and warp parameter. From the help in the m file:
% (WA)rp (R)eference to (T)emplate for common (R)egion.
% Extracts a region (T) from image (I) specified by warp (W) and size (S).


MATLAB SCRIPTS FOR DATASET CONSTRUCTION

tstMkSet.m 	: Generate all data for particular image and coordinate.
tstMkAllSets.m	: Generate datasets for all 8 images.
tstSetupBins.m	: From the stored data generate the binary data files in data/.


BASE SOURCE CODE:

AddTri.cc, AddTri.hh: Files implementing methods to render triangles
to images.

C2dBspline.hh: Inline implementation for 2d B-Spline functions.

CImgE.hh: Extensions to the CImg class. Mainly operations.

CImgI.hh: Extensions to the CImg class. Mainly optimised interpolation
functions.

cimgmatlabplugin.h: Matlab plugin for CImg class.

cmdFrame.hh: Useful functions used for commandline test executables.

CWarp.cc, CWarp.hh: Implementation of various warps (or coordinate
transformations), their Jacobians and Hessians, including
translation. Euclidean, similarity and affine warps.

imgOp.cc, imgOp.hh: Implementation of the various cost functions,
including: SSD, NC, MI(STD), PPZ, IPZ, PVE, NP-windowed MI,
Resolution aware NP-windowed MI.

sounder.hh: Multithreaded implementation of optimisation functions. (A
sounder is a collection of warthogs - hence the name ;-).

wartx.cc, wartx.hh: Implementation of basic measurement of a given
function, when warping a template to various positions in the
reference image.

warthogx.cc, warthogx.hh: Implementation of optimisation method to
minimise a given function when varying the warp parameters to
transform a template to various positions in the reference image.

warterr.hh: A collection of error messages for the Matlab modules.

makefile: File to compile all mexglx functions and 
