# meanShiftIm

## PURPOSE

Applies the meanShift algorithm to a joint spatial/range image.

## SYNOPSIS

function [M,Vr,Vc] = meanShiftIm( X,sigSpt,sigRng,softFlag,maxIter,minDel )

## DESCRIPTION

     Applies the meanShift algorithm to a joint spatial/range image.

     See "Mean Shift Analysis and Applications" by Comaniciu & Meer for info.

     Assumes X is an MxNxP array, where an X(i,j,:) represents the range data
     at locations (i,j).  This function runs meanShift on each of the MxN data
     points.  It takes advantage of the lattice structure of an image for
     efficiency (it only needs to calculate full distance between two points
     if they are near each other spatially).

     In the original formulation of the algorithm, after normalization of the
     data, the search window around each point x has radius 1 (ie
     corresponding to 1 std of the data). That is the search window only
     encloses 2*s+1 pixels, and of those, all which fall within 1 unit from x
     are used to calcluate the new mean.  If softFlag==0 the original
     formulation is used.  If softFlag==1, instead of using a fixed radius,
     each point p is used in the calulation of the mean with points close to x
     given significantly more weight.  Specifically, each point p is given
     weight exp(-dist(x,p)).  So instead of having a fixed cutoff at r, the
     cutoff is 'soft' (same idea as in softmax), and occurs at approximately
     r.  The implementation remains efficient by actually using a hard cutoff
     at points further then 2r spatially from x.

     The resulting matrix M is of size MxNx(P+2).  M(i,j,1) represents the
     convergent row location of X(i,j,:) - (which had initial row location i)
     and M(i,j,2) represents the final column location.  M(i,j,p+2) represents
     the convergent value for X(i,j,p).  The optionaly outputs Vr and Vc are
     2D arrays where Vr(i,j)=M(i,j,1)-i and Vc(i,j)=M(i,j,2)-j.  That is they
     represent the spatial offset between the original location of a point and
     its convergent location.  Display using quiver(Vc,Vr,0).

     USAGE
      [M,Vr,Vc] = meanShiftIm( X,sigSpt,sigRng,[softFlag],[maxIter],[minDel] )

     INPUTS
      X        - MxNxP data array, P may be 1
      sigSpt   - integer specifying spatial standard deviation
      sigRng   - value specifying the standard deviation of the range data
      softFlag - [0]- see above
      maxIter  - [100] maximum number of iterations per data point
      minDel   - [.001] minimum amount of spatial change defining convergence

     OUTPUTS
      M        - array of convergent locations [see above]
      Vr       - spatial motion in row direction
      Vc       - spatial motion in col direction

     EXAMPLE
      I=double(imread('cameraman.tif'))/255;
      [M,Vr,Vc] = meanShiftIm( I,5,.2 );
      figure(1); im(I); figure(2); im( M(:,:,3) );
      % color image:
      I=double(imread('hestain.png'))/255;
      [M,Vr,Vc] = meanShiftIm( I,5,.2 );
      figure(1); im(I); figure(2); im( M(:,:,3:end) );

     See also MEANSHIFT, MEANSHIFTIMEXPLORE

     Piotr's Image&Video Toolbox      Version 2.0
     Copyright 2008 Piotr Dollar.  [pdollar-at-caltech.edu]
     Please email me if you find bugs, or have suggestions or questions!
     Licensed under the Lesser GPL [see external/lgpl.txt]

## CROSS-REFERENCE INFORMATION

This function calls:

- c clc - clear command window.
- checkNumArgs Helper utility for checking numeric vector arguments.
- ticStatus Used to display the progress of a long process.
- tocStatus Used to display the progress of a long process.

This function is called by: