1

keypointExtraction/README.txt

@@ -0,0 +1,46 @@
+---=== EDIT CONTOUR ===---
+
+AUTHOR
+	Vincent Garcia
+	
+DESCRIPTION
+	The current directory contains functions allowing to extract keypoints 
+	also called "feature points", "corners", "interest points", etc.
+	The following algorithm are provided :
+		- Harris
+		- SUSAN
+		- Harris-Laplace
+		- Laplacian of Gaussian (LoG)
+		- Gilles
+	The input image must be a gray level image. The output is a matrix of
+	dimension Nx2 or Nx3 with N the number of keypoints extracted. The first
+	column gives the row poisition of the keypoints and the second column
+	gives the column position of the keypoints. The third column gives
+	the feature scale of the keypoints. This scale corresponds to the radius
+	of the local neighborhood to consider. Note that the SUSAN algorithm is 
+	a contribution of Joaquim Luis.
+	
+	Run the test function to see an example.
+	
+	The picture "door" was taken by Aleksandra Radonic'.
+	The picture "sunflower" was taken by Candy Torres.
+	The picture "patrol" was taken by Markus Schöpke.
+	
+LEGAL
+	1. The enclosed function can be freely reused under a Creative Commons
+	   License (http://creativecommons.org/licenses/by-nc-sa/2.0) :
+	   You are free:
+		    * to Share — to copy, distribute and transmit the work
+		    * to Remix — to adapt the work
+		Under the following conditions:
+		    * Attribution. You must attribute the work in the manner specified
+			  by the author or licensor (but not in any way that suggests that
+			  they endorse you or your use of the work).
+		    * Noncommercial. You may not use this work for commercial purposes.
+		    * Share Alike. If you alter, transform, or build upon this work, you
+			may distribute the resulting work only under the same or similar
+			license to this one.
+			
+	2.	The pictures provided were choosen on flickr.com. These pictures can be
+		freely reused under a Creative Commons License. The authors are Aleksandra Radonic',
+		Candy Torres, and Markus Schöpke.

keypointExtraction/findLocalMaximum.m

@@ -0,0 +1,75 @@
+function [row,col,max_local] = findLocalMaximum(val,radius)
+    % Determine the local maximum of a given value
+    %
+    % Author :: Vincent Garcia
+    % Date   :: 09/02/2007
+    %
+    % INPUT
+    % =====
+    % val    : the NxM matrix containing values
+    % radius : the radius of the neighborhood
+    %
+    % OUTPUT
+    % ======
+    % row       : the row position of the local maxima
+    % col       : the column position of the local maxima
+    % max_local	: the NxM matrix containing values of val on unique local maximum
+    %
+    % EXAMPLE
+    % =======
+    % [l,c,m] = findLocalMaximum(img,radius);
+    
+
+
+
+    % FIND LOCAL MAXIMA BY DILATION (FAST) /!\ NON UNIQUE /!\
+    % mask = fspecial('disk',radius)>0;
+    % val2 = imdilate(val,mask);
+    % index = val==val2;
+    % [row,col] = find(index==1);
+    % max_local = zeros(size(val));
+    % max_local(index) = val(index);
+
+
+    % FIND UNIQUE LOCAL MAXIMA USING FILTERING (FAST)
+    mask  = fspecial('disk',radius)>0;
+    nb    = sum(mask(:));
+    highest          = ordfilt2(val, nb, mask);
+    second_highest   = ordfilt2(val, nb-1, mask);
+    index            = highest==val & highest~=second_highest;
+    max_local        = zeros(size(val));
+    max_local(index) = val(index);
+    [row,col]        = find(index==1);
+
+
+    % FIND UNIQUE LOCAL MAXIMA (FAST)
+    % val_height  = size(val,1);
+    % val_width   = size(val,2);
+    % max_local   = zeros(val_height,val_width);
+    % val_enlarge = zeros(val_height+2*radius,val_width+2*radius);
+    % val_mask    = zeros(val_height+2*radius,val_width+2*radius);
+    % val_enlarge( (1:val_height)+radius , (1:val_width)+radius ) = val;
+    % val_mask(    (1:val_height)+radius , (1:val_width)+radius ) = 1;
+    % mask  = fspecial('disk',radius)>0;
+    % row = zeros(val_height*val_width,1);
+    % col = zeros(val_height*val_width,1);
+    % index = 0;
+    % for l = 1:val_height
+    %     for c = 1:val_width
+    %         val_ref = val(l,c);
+    %         neigh_val  = val_enlarge(l:l+2*radius,c:c+2*radius);
+    %         neigh_mask = val_mask(   l:l+2*radius,c:c+2*radius).*mask;
+    %         neigh_sort = sort(neigh_val(neigh_mask==1));
+    %         if val_ref==neigh_sort(end) && val_ref>neigh_sort(end-1)
+    %             index          = index+1;
+    %             row(index,1)   = l;
+    %             col(index,1)   = c;
+    %             max_local(l,c) = val_ref;
+    %         end
+    %     end
+    % end
+    % row(index+1:end,:) = [];
+    % col(index+1:end,:) = [];
+
+
+end

keypointExtraction/kp_gilles.m

@@ -0,0 +1,46 @@
+function points = kp_gilles(im,o_radius)
+    % Extract keypoints using Gilles algorithm
+    %
+    % Author :: Vincent Garcia
+    % Date   :: 05/12/2007
+    %
+    % INPUT
+    % =====
+    % im       : the graylevel image
+    % o_radius : (optional) the radius of blobs detected
+    %
+    % OUTPUT
+    % ======
+    % points : the interest points extracted
+    %
+    % REFERENCES
+    % ==========
+    % S. Gilles, Robust Description and Matching of Images. PhD thesis,
+    % Oxford University, Ph.D. thesis, Oxford University, 1988.
+    %
+    % EXAMPLE
+    % =======
+    % points = kp_gilles(im,10) % radius of 10 pixels
+
+    % only luminance value
+    im = im(:,:,1);
+
+    % variables
+    if nargin==1
+        radius = 10;
+    else
+        radius = o_radius;
+    end
+    mask = fspecial('disk',radius)>0;
+
+    % compute local entropy
+    loc_ent = entropyfilt(im,mask);
+
+    % find the local maxima
+    [l,c,tmp] = findLocalMaximum(loc_ent,radius);
+
+    % keep only points above a threshold
+    [l,c]     = find(tmp>0.95*max(tmp(:)));
+    points    = [l,c,repmat(radius,[size(l,1),1])];
+
+end

keypointExtraction/kp_harris.m

@@ -0,0 +1,68 @@
+function points = kp_harris(im)
+    % Extract keypoints using Harris algorithm (with an improvement
+    % version)
+    %
+    % Author :: Vincent Garcia
+    % Date   :: 05/12/2007
+    %
+    % INPUT
+    % =====
+    % im     : the graylevel image
+    %
+    % OUTPUT
+    % ======
+    % points : the interest points extracted
+    %
+    % REFERENCES
+    % ==========
+    % C.G. Harris and M.J. Stephens. "A combined corner and edge detector",
+    % Proceedings Fourth Alvey Vision Conference, Manchester.
+    % pp 147-151, 1988.
+    %
+    % Alison Noble, "Descriptions of Image Surfaces", PhD thesis, Department
+    % of Engineering Science, Oxford University 1989, p45.
+    %
+    % C. Schmid, R. Mohrand and C. Bauckhage, "Evaluation of Interest Point Detectors",
+    % Int. Journal of Computer Vision, 37(2), 151-172, 2000.
+    %
+    % EXAMPLE
+    % =======
+    % points = kp_harris(im)
+
+    % only luminance value
+    im = double(im(:,:,1));
+    sigma = 1.5;
+
+    % derivative masks
+    s_D = 0.7*sigma;
+    x  = -round(3*s_D):round(3*s_D);
+    dx = x .* exp(-x.*x/(2*s_D*s_D)) ./ (s_D*s_D*s_D*sqrt(2*pi));
+    dy = dx';
+
+    % image derivatives
+    Ix = conv2(im, dx, 'same');
+    Iy = conv2(im, dy, 'same');
+
+    % sum of the Auto-correlation matrix
+    s_I = sigma;
+    g = fspecial('gaussian',max(1,fix(6*s_I+1)), s_I);
+    Ix2 = conv2(Ix.^2, g, 'same'); % Smoothed squared image derivatives
+    Iy2 = conv2(Iy.^2, g, 'same');
+    Ixy = conv2(Ix.*Iy, g, 'same');
+
+    % interest point response
+    cim = (Ix2.*Iy2 - Ixy.^2)./(Ix2 + Iy2 + eps);				% Alison Noble measure.
+    % k = 0.06; cim = (Ix2.*Iy2 - Ixy.^2) - k*(Ix2 + Iy2).^2;	% Original Harris measure.
+
+    % find local maxima on 3x3 neighborgood
+    [r,c,max_local] = findLocalMaximum(cim,3*s_I);
+
+    % set threshold 1% of the maximum value
+    t = 0.01*max(max_local(:));
+
+    % find local maxima greater than threshold
+    [r,c] = find(max_local>=t);
+
+    % build interest points
+    points = [r,c];
+end

keypointExtraction/kp_harrislaplace.m

@@ -0,0 +1,115 @@
+function points = kp_harrislaplace(img)
+    % Extract keypoints using Harris-Laplace algorithm
+    %
+    % Author :: Vincent Garcia
+    % Date   :: 05/12/2007
+    %
+    % INPUT
+    % =====
+    % img    : the graylevel image
+    %
+    % OUTPUT
+    % ======
+    % points : the interest points extracted
+    %
+    % REFERENCES
+    % ==========
+    % K. Mikolajczyk and C. Schmid. Scale & affine invariant interest point detectors.
+    % International Journal of Computer Vision, 2004
+    %
+    % EXAMPLE
+    % =======
+    % points = kp_harrislaplace(img)
+    
+    % IMAGE PARAMETERS
+    img         = double(img(:,:,1));
+    img_height  = size(img,1);
+    img_width   = size(img,2);
+
+    % SCALE PARAMETERS
+    sigma_begin = 1.5;
+    sigma_step  = 1.2;
+    sigma_nb    = 13;
+    sigma_array = (sigma_step.^(0:sigma_nb-1))*sigma_begin;
+
+
+    % PART 1 : HARRIS
+    harris_pts = zeros(0,3);
+    for i=1:sigma_nb
+
+        % scale (standard deviation)
+        s_I = sigma_array(i);   % intégration scale
+        s_D = 0.7*s_I;          % derivative scale %0.7
+
+        % derivative mask
+        x  = -round(3*s_D):round(3*s_D);
+        dx = x .* exp(-x.*x/(2*s_D*s_D)) ./ (s_D*s_D*s_D*sqrt(2*pi));
+        dy = dx';
+
+        % image derivatives
+        Ix = conv2(img, dx, 'same');
+        Iy = conv2(img, dy, 'same');
+
+        % auto-correlation matrix
+        g   = fspecial('gaussian',max(1,fix(6*s_I+1)), s_I);
+        Ix2 = conv2(Ix.^2, g,  'same');
+        Iy2 = conv2(Iy.^2, g,  'same');
+        Ixy = conv2(Ix.*Iy, g, 'same');
+
+        % interest point response
+        %cim = (Ix2.*Iy2 - Ixy.^2)./(Ix2 + Iy2 + eps);				% Alison Noble measure.
+        k = 0.06; cim = (Ix2.*Iy2 - Ixy.^2) - k*(Ix2 + Iy2).^2;	% Original Harris measure.
+
+        % find local maxima on neighborgood
+        [l,c,max_local] = findLocalMaximum(cim,3*s_I);%3*s_I
+
+        % set threshold 1% of the maximum value
+        t = 0.2*max(max_local(:));
+
+        % find local maxima greater than threshold
+        [l,c] = find(max_local>=t);
+
+        % build interest points
+        n = size(l,1);
+        harris_pts(end+1:end+n,:) = [l,c,repmat(i,[n,1])];
+    end
+
+
+    % PART 2 : LAPLACE
+    % compute scale-normalized laplacian operator
+    laplace_snlo = zeros(img_height,img_width,sigma_nb);
+    for i=1:sigma_nb
+        s_L = sigma_array(i);   % scale
+        laplace_snlo(:,:,i) = s_L*s_L*imfilter(img,fspecial('log', floor(6*s_L+1), s_L),'replicate');
+    end
+    % verify for each of the initial points whether the LoG attains a maximum at the scale of the point
+    n   = size(harris_pts,1);
+    cpt = 0;
+    points = zeros(n,3);
+    for i=1:n
+        l = harris_pts(i,1);
+        c = harris_pts(i,2);
+        s = harris_pts(i,3);
+        val = laplace_snlo(l,c,s);
+        if s>1 && s<sigma_nb
+            if val>laplace_snlo(l,c,s-1) && val>laplace_snlo(l,c,s+1)
+                cpt = cpt+1;
+                points(cpt,:) = harris_pts(i,:);
+            end
+        elseif s==1
+            if val>laplace_snlo(l,c,2)
+                cpt = cpt+1;
+                points(cpt,:) = harris_pts(i,:);
+            end
+        elseif s==sigma_nb
+            if val>laplace_snlo(l,c,s-1)
+                cpt = cpt+1;
+                points(cpt,:) = harris_pts(i,:);
+            end
+        end
+    end
+    points(cpt+1:end,:) = [];
+    
+    % SET SCALE TO 3*SIGMA FOR DISPLAY
+    points(:,3) = 3*sigma_array(points(:,3));
+end

keypointExtraction/kp_log.m

@@ -0,0 +1,62 @@
+function [points] = kp_log(img,o_nb_blobs)
+    % Extract keypoints using Laplacian of Gaussian (LoG) algorithm
+    %
+    % Author :: Vincent Garcia
+    % Date   :: 05/12/2007
+    %
+    % INPUT
+    % =====
+    % img        : the graylevel image
+    % o_nb_blobs : (optional) number of blobs detected
+    %
+    % OUTPUT
+    % ======
+    % points : the interest points extracted
+    %
+    % REFERENCES
+    % ==========
+    % Lindeberg, T. Feature Detection with Automatic Scale Selection
+    % IEEE Transactions Pattern Analysis Machine Intelligence, 1998, 30, 77-116kp_harris(im)
+    %
+    % EXAMPLE
+    % =======
+    % points = kp_log(img)
+    
+    % input image
+    img = double(img(:,:,1));
+        
+    % number of blobs detected
+    if nargin==1
+        nb_blobs = 120;
+    else
+        nb_blobs = o_nb_blobs;
+    end
+    
+    % Laplacian of Gaussian parameters
+    sigma_begin = 2;
+    sigma_end   = 15;
+    sigma_step  = 1;
+    sigma_array = sigma_begin:sigma_step:sigma_end;
+    sigma_nb    = numel(sigma_array);
+        
+    % variable
+    img_height  = size(img,1);
+    img_width   = size(img,2);
+        
+    % calcul scale-normalized laplacian operator
+    snlo = zeros(img_height,img_width,sigma_nb);
+    for i=1:sigma_nb
+        sigma       = sigma_array(i);
+        snlo(:,:,i) = sigma*sigma*imfilter(img,fspecial('log', floor(6*sigma+1), sigma),'replicate');
+    end
+        
+    % search of local maxima
+    snlo_dil             = imdilate(snlo,ones(3,3,3));
+    blob_candidate_index = find(snlo==snlo_dil);
+    blob_candidate_value = snlo(blob_candidate_index);
+    [tmp,index]          = sort(blob_candidate_value,'descend');
+    blob_index           = blob_candidate_index( index(1:min(nb_blobs,numel(index))) );
+    [lig,col,sca]        = ind2sub([img_height,img_width,sigma_nb],blob_index);
+    points               = [lig,col,3*reshape(sigma_array(sca),[size(lig,1),1])];
+    
+end

keypointExtraction/kp_susan.m

@@ -0,0 +1,25 @@
+function points = kp_susan(img)
+    % Extract keypoints using SUSAN algorithm
+    %
+    % Author :: Vincent Garcia
+    % Date   :: 05/12/2007
+    %
+    % INPUT
+    % =====
+    % img    : the graylevel image
+    %
+    % OUTPUT
+    % ======
+    % points : the interest points extracted
+    %
+    % REFERENCES
+    % ==========
+    % Smith, S. M. & Brady, J. M. SUSAN - A New Approach to Low Level Image
+    % Processing IEEE Transactions Pattern Analysis Machine Intelligence,
+    % Kluwer Academic Publishers, 1997, 23, 45-78
+    %
+    % EXAMPLE
+    % =======
+    % points = kp_susan(img)
+	points = susan(flipud(img'),'-c','-3');
+end

keypointExtraction/susan.m

@@ -0,0 +1,49 @@
+% Edge OR Corners detecting OR image smoothing using SUSAN technique.
+%
+% There are three different types of output:
+%   1. Logical (mask) array - This is the deffault type used with the edge detection
+%   2. Uint8 array - When '-ei' or '-ci' options are used
+%   3. Mx2 array of doubles with the indice corner coordinates
+%
+% Usage:
+%   OUT = susan(GRAY, [options]);
+%
+%   Where GRAY is a MxN intensity image
+%   and [options] is any of the following '-opt' strings:
+% 
+% -e : Edges mode - output a mask (logical) edges image [default]
+% -ei: Edges Image mode (overlay edges on input image)
+% -s : Smoothing mode
+% -c : Corners mode - output a Mx2 corners matrix with (image x,y corners coordinates)
+% 
+% -ci: Corners Image mode (overlay corners on input image)
+% 
+% See source code for more information about setting the thresholds
+% -t <thresh> : Brightness threshold, all modes (default=20)
+% -d <thresh> : Distance threshold, smoothing mode, (default=4) (use next option instead for flat 3x3 mask)
+% -3 : Use flat 3x3 mask, edges or smoothing mode
+% -n : No post-processing on the binary edge map (runs much faster); edges mode
+% -q : Use faster (and usually stabler) corner mode; edge-like corner suppression not carried out; corners mode
+% -b : Mark corners/edges with single black points instead of black with white border; corners or edges mode
+% -p : Output initial enhancement image only; corners or edges mode (default is edges mode)
+% SUSAN Version 2l (C) 1995-1997 Stephen Smith, DRA UK. steve@fmrib.ox.ac.uk
+% 
+% Example1:  Show original image overlain with detected edges
+%   if IMG is a MxN image
+%   edges = susan(IMG,'-ei');
+%   image(edges)
+%
+% Example2:  Show edges only
+%   edges = susan(IMG,'-e');
+%   image(edges)        % imshow works better
+%
+% Example3:  Show original image overlain with detected corners
+%   edges = susan(IMG,'-ci');
+%   image(edges)
+
+%
+% Author (of the mexification (not so minor work))
+%       Joaquim Luis, jluis@ualg.pt
+%
+% Original C code and algorithm description at:
+%   http://www.fmrib.ox.ac.uk/~steve/susan/

keypointExtraction/test.m

@@ -0,0 +1,57 @@
+function test()
+    % The test function gives an example of keypoint extraction using the
+    % methods :
+    % - Harris
+    % - SUSAN
+    % - LoG (Laplacian of Gaussian)
+    % - Harris-Laplace
+    % - Gilles
+    %
+    % Example
+    % =======
+    % test();
+
+    % Harris
+    img = imread('test.pgm');
+    pt  = kp_harris(img);
+    draw(img,pt,'Harris');
+
+    % SUSAN
+    img = imread('test.pgm');
+    pt  = kp_susan(img);
+    draw(img,pt,'SUSAN');
+
+    % LoG Lindeberg
+    img = imread('sunflower.jpg');
+    pt  = kp_log(rgb2gray(img));
+    draw(img,pt,'LoG Lindeberg');
+
+    % Harris-Laplace
+    img = imread('door.jpg');
+    pt  = kp_harrislaplace(rgb2gray(img));
+    draw(img,pt,'Harris Laplace');
+
+    % Gilles
+    img = imread('patrol.jpg');
+    pt  = kp_gilles(rgb2gray(img));
+    draw(img,pt,'Gilles');
+
+end
+
+function draw(img,pt,str)
+    figure('Name',str);
+    imshow(img);
+    hold on;
+    axis off;
+    switch size(pt,2)
+        case 2
+            s = 2;
+            for i=1:size(pt,1)
+                rectangle('Position',[pt(i,2)-s,pt(i,1)-s,2*s,2*s],'Curvature',[0 0],'EdgeColor','b','LineWidth',2);
+            end
+        case 3
+            for i=1:size(pt,1)
+                rectangle('Position',[pt(i,2)-pt(i,3),pt(i,1)-pt(i,3),2*pt(i,3),2*pt(i,3)],'Curvature',[1,1],'EdgeColor','w','LineWidth',2);
+            end
+    end
+end