# imagesAlign

## PURPOSE

Fast and robust estimation of homography relating two images.

## SYNOPSIS

function [H,Ip] = imagesAlign( I, Iref, varargin )

## DESCRIPTION

     Fast and robust estimation of homography relating two images.

     The algorithm for image alignment is a simple but effective variant of
     the inverse compositional algorithm. For a thorough overview, see:
       "Lucas-kanade 20 years on A unifying framework,"
       S. Baker and I. Matthews. IJCV 2004.
     The implementation is optimized and can easily run at 20-30 fps.

     type may take on the following values:
      'translation'  - translation only
      'rigid'        - translation and rotation
      'similarity'   - translation, rotation and scale
      'affine'       - 6 parameter affine transform
      'rotation'     - pure rotation (about x, y and z)
      'projective'   - full 8 parameter homography
     Alternatively, type may be a vector of ids between 1 and 8, specifying
     exactly the types of transforms allowed. The ids correspond, to: 1:
     translate-x, 2: translate-y, 3: uniform scale, 4: shear, 5: non-uniform
     scale, 6: rotate-z, 7: rotate-x, 8: rotate-y. For example, to specify
     translation use type=[1,2]. If the transforms don't form a group, the
     returned homography may have more degrees of freedom than expected.

     Parameters (in rough order of importance): [resample] controls image
     downsampling prior to computing H. Runtime is proportional to area, so
     using resample<1 can dramatically speed up alignment, and in general not
     degrade performance much. [sig] controls image smoothing, sig=2 gives
     good performance, setting sig too low causes loss of information and too
     high will violate the linearity assumption. [epsilon] defines the
     stopping criteria, use to adjust performance versus speed tradeoff.
     [lambda] is a regularization term that causes small transforms to be
     favored, in general any small non-zero setting of lambda works well.
     [outThr] is a threshold beyond which pixels are considered outliers, be
     careful not to set too low. [minArea] determines coarsest scale beyond
     which the image is not downsampled (should not be set too low). [H0] can
     be used to specify an initial alignment. Use [show] to display results.

     USAGE
      [H,Ip] = imagesAlign( I, Iref, varargin )

     INPUTS
      I          - transformed version of I
      Iref       - reference grayscale double image
      varargin   - additional params (struct or name/value pairs)
       .type       - ['projective'] see above for options
       .resample   - [1] image resampling prior to homography estimation
       .sig        - [2] amount of Gaussian spatial smoothing to apply
       .epsilon    - [1e-3] stopping criteria (min change in error)
       .lambda     - [1e-6] regularization term favoring small transforms
       .outThr     - [inf] outlier threshold
       .minArea    - [4096] minimum image area in coarse to fine search
       .H0         - [eye(3)] optional initial homography estimate
       .show       - [0] optionally display results in figure show

     OUTPUTS
      H        - estimated homography to transform I into Iref
      Ip       - tranformed version of I (slow to compute)

     EXAMPLE
      Iref = double(imread('cameraman.tif'))/255;
      H0 = [eye(2)+randn(2)*.1 randn(2,1)*10; randn(1,2)*1e-3 1];
      I = imtransform2(Iref,H0^-1,'pad','replicate');
      o=50; P=ones(o)*1; I(150:149+o,150:149+o)=P;
      prmAlign={'outThr',.1,'resample',.5,'type',1:8,'show'};
      [H,Ip]=imagesAlign(I,Iref,prmAlign{:},1);
      tic, for i=1:30, H=imagesAlign(I,Iref,prmAlign{:},0); end;
      t=toc; fprintf('average fps: %f\n',30/t)

     See also imTransform2

     Piotr's Image&Video Toolbox      Version 2.61
     Copyright 2012 Piotr Dollar.  [pdollar-at-caltech.edu]
     Please email me if you find bugs, or have suggestions or questions!
     Licensed under the Simplified BSD License [see external/bsd.txt]