# opticalFlow

## PURPOSE

Coarse-to-fine optical flow using Lucas&Kanade or Horn&Schunck.

## SYNOPSIS

function [Vx,Vy,reliab] = opticalFlow( I1, I2, varargin )

## DESCRIPTION

     Coarse-to-fine optical flow using Lucas&Kanade or Horn&Schunck.

     Implemented 'type' of optical flow estimation:
      LK: http://en.wikipedia.org/wiki/Lucas-Kanade_method
      HS: http://en.wikipedia.org/wiki/Horn-Schunck_method
      SD: Simple block-based sum of absolute differences flow
     LK is a local, fast method (the implementation is fully vectorized).
     HS is a global, slower method (an SSE implementation is provided).
     SD is a simple but potentially expensive approach.

     Common parameters: 'smooth' determines smoothing prior to computing flow
     and can make flow estimation more robust. 'filt' determines amount of
     median filtering of the computed flow field which improves results but is
     costly. 'minScale' and 'maxScale' control image scales in the pyramid.
     Setting 'maxScale'<1 results in faster but lower quality results, e.g.
     maxScale=.5 makes flow computation about 4x faster. Method specific
     parameters: 'radius' controls window size (and smoothness of flow) for LK
     and SD. 'nBlock' determines number of blocks tested in each direction for
     SD, computation time is O(nBlock^2). For HS, 'alpha' controls tradeoff
     between data and smoothness term (and smoothness of flow) and 'nIter'
     determines number of gradient decent steps.

     USAGE
      [Vx,Vy,reliab] = opticalFlow( I1, I2, pFlow )

     INPUTS
      I1, I2   - input images to calculate flow between
      pFlow    - parameters (struct or name/value pairs)
       .type       - ['LK'] may be 'LK', 'HS' or 'SD'
       .smooth     - [1] smoothing radius for triangle filter (may be 0)
       .filt       - [0] median filtering radius for smoothing flow field
       .minScale   - [1/64] minimum pyramid scale (must be a power of 2)
       .maxScale   - [1] maximum pyramid scale (must be a power of 2)
       .radius     - [10] integration radius for weighted window [LK/SD only]
       .nBlock     - [5] number of tested blocks [SD only]
       .alpha      - [1] smoothness constraint [HS only]
       .nIter      - [250] number of iterations [HS only]

     OUTPUTS
      Vx, Vy   - x,y components of flow  [Vx>0->right, Vy>0->down]
      reliab   - reliability of flow in given window

     EXAMPLE - compute LK flow on test images
      load opticalFlowTest;
      [Vx,Vy]=opticalFlow(I1,I2,'smooth',1,'radius',10,'type','LK');
      figure(1); im(I1); figure(2); im(I2);
      figure(3); im([Vx Vy]); colormap jet;

     EXAMPLE - rectify I1 to I2 using computed flow
      load opticalFlowTest;
      [Vx,Vy]=opticalFlow(I1,I2,'smooth',1,'radius',10,'type','LK');
      I1=imtransform2(I1,[],'vs',-Vx,'us',-Vy,'pad','replicate');
      figure(1); im(I1); figure(2); im(I2);

     EXAMPLE - compare LK/HS/SD flows
      load opticalFlowTest;
      prm={'smooth',1,'radius',10,'alpha',20,'nIter',250,'type'};
      tic, [Vx1,Vy1]=opticalFlow(I1,I2,prm{:},'LK'); toc
      tic, [Vx2,Vy2]=opticalFlow(I1,I2,prm{:},'HS'); toc
      tic, [Vx3,Vy3]=opticalFlow(I1,I2,prm{:},'SD','minScale',1); toc
      figure(1); im([Vx1 Vy1; Vx2 Vy2; Vx3 Vy3]); colormap jet;

     See also convTri, imtransform2, medfilt2

     Piotr's Image&Video Toolbox      Version 3.24
     Copyright 2013 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]