
Readme for Warthog

Warthog collectively refers to 3 matlab mex files used for measuring
and minimising similarity values between a given template and an
image. These binaries are reasonably optimised for speed and currently
there are no outstanding bugs.  they may be updated drmo time
to time as features are added.

The three mex files are:
 * wartr.mexglx
 * warts.mexglx
 * warthog.mexglx

Each of these has an associated .m file giving a description of how to
use the file. As you may have gathered 

A brief synopsis of each file follows.


WARTR 

This extracts a warped rectangular region from an image. The region
extracted using this routine returns the region overlapped by the
warped template in WARTS and WARTHOG.

Example of use:

%% Demo 1: wartr
% Extract a 21 by 21 region from an image
% Should work in Matlab Release 2006a
mySize = [53 53];
myImage = imread('pout.tif');
myWarp = [0 0 0 0 93 110]; %Affine warp

myTemplate = wartr( myImage, myWarp, mySize );
image(myTemplate); colormap(gray(256));



WARTS

Warts measures the similarity between a template and the region it
overlaps in an image. Several similarity measures may be specified,
including Sum of Square differences, Normalised Corrlation, and four
types of Mutual Information: Standard, Partial Volume Estimation (as
per Chen03), In-Parzen Windowing (as per Thevenaz00), Post-Parzen
windowing. 

The Jacobian and Hessian may also be obtained using an analytical
derivation. The template coordinates are warped according to one of
four warp functions: translation, rotation, similarity and affine
warps. Multiple warp values may be specified at once.

Example of use:

%% Demo 2: warts
% Measure the standard mutual information between the extracted region
% and several other regions in the image. Graph the function surface.

[x1 x2] = ndgrid([-10:.5:10]); %Get a grid of positions
myWarps = [x1(:)+93 x2(:)+110]'; %And create a matrix of coordinates
[y dy ddy] = warts( myTemplate/32, myImage/32, myWarps, [2 3 1 1 1] ); %Measure
figure(1); clf; colormap(jet(256));
subplot(1,3,1); 
surf(x1,x2,reshape(y,size(x1))); %Graph the y
subplot(1,3,2);
surf(x1,x2,reshape(dy(1,:),size(x1))); %Graph the dy/dx1
subplot(1,3,3);
surf(x1,x2,reshape(dy(2,:),size(x1))); %Graph the dy.dx2
x1o = x1; x2o = x2; %Keep old points for next demo


WARTHOG

Warthog minimises (maximises) the similarity function value and
returns the lowest value found and its position, using any one of five
methods: Simplex, Powell, Conjugate Gradient, Variable Metric,
Levenberg-Marquardt. Multiple starting positions may be specified.

Example of use:


%% Demo 3: warthog
% Optimise using standard mutual information using levenberg Marquardt
% from the grid point positions established previously. Only the
% points within the

[x1 x2] = ndgrid([-2:1:2]); %Get a grid of positions
myWarps = [x1(:)+93 x2(:)+110]'; %And create a matrix of coordinates

[Y X] = warthog( myTemplate/32, myImage/32, myWarps, [2 3 1 1 1 5] ); %Optimise
figure(2); clf;
imagesc(x1o(:)+93,x2o(:)+110',reshape(y,size(x1o))); %Plot the result
hold on;
plot(x1+93,x2+110,'r+'); %Plot initial points
plot(X(1,:), X(2,:), 'ro'); %Plot end points



Legal Stuff:

I take absolutely no responsibility for your use of these files. You
use them entirely at your own risk.

(c) Nicholas Dowson, University of Surrey, May 2006