clfTVL1Flow.hh

/* 
 This file is part of the BIAS library (Basic ImageAlgorithmS).

 Copyright (C) 2003, 2004    (see file CONTACTS for details)
 Multimediale Systeme der Informationsverarbeitung
 Institut fuer Informatik
 Christian-Albrechts-Universitaet Kiel


 BIAS is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
 the Free Software Foundation; either version 2.1 of the License, or
 (at your option) any later version.

 BIAS is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public License
 along with BIAS; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

/*
@inproceedings{Zach:2007:DBA:1771530.1771554,
 author = {Zach, C. and Pock, T. and Bischof, H.},
 title = {A duality based approach for realtime TV-L1 optical flow},
 booktitle = {Proceedings of the 29th DAGM conference on Pattern recognition},
 year = {2007},
 isbn = {978-3-540-74933-2},
 location = {Heidelberg, Germany},
 pages = {214--223},
 numpages = {10},
 url = {http://dl.acm.org/citation.cfm?id=1771530.1771554},
 acmid = {1771554},
 publisher = {Springer-Verlag},
 address = {Berlin, Heidelberg},
} 
 */

#ifndef CLFTVL1FLOW_HH_
#define CLFTVL1FLOW_HH_

#include <Base/Common/BIASpragmaStart.hh>
#include <OpenCLFramework/clfContext.hh>
#include <OpenCLFramework/clfProgram.hh>
#include <OpenCLFramework/clfImage2D.hh>
#include <OpenCLFramework/Filter/clfFilter.hh>
#include <OpenCLFramework/Filter/clfSimpleFilter.hh>
#include <OpenCLFramework/Filter/clfColorConversion.hh>

namespace BIAS {

  /**
   * @brief TVL1 optical flow opencl implementation
   * 
   * "A duality based approach for realtime TV-L1 optical flow" by Zach et.al. (see file header for bibtex)
   * Implementation in OpenCL
   * @author fkellner 08/11
   */
  class BIASOpenCLFramework_EXPORT clfTVL1Flow {
    public:
      /** @brief constructor, requires valid gpu context
       * @todo create constructor with parameters for algorithm (defaults are good though)
       */
      clfTVL1Flow(clfContext *ctx);
      virtual ~clfTVL1Flow();

      void SetNumberOfIterations(unsigned int iternumber);
      void SetSmoothness(const float& smoothness);

      /** 
       * @brief call this for every new image
       * every image must be same size, width and height multiples of 16.
       * image pyramid will go down until width or height are no multiples of 16,
       * meaning that a 1024x768 image will be downsampled 4 times (64x48)
       */
      void AddImage(BIAS::Image<unsigned char> image);
      /**
       * @brief compute optical flow between images
       * compute optical flow between the last two added images, 
       * does nothing if only one or no images have been added.
       */
      void Compute();
      /**
       * @brief get flow vectors (direction u,v)
       * stores flow vectors with direction (u,v) in images first 2 color channels. 
       * note that the resulting image has 4 channels!
       */
      void GetUVW(BIAS::Image<float> &image);
      /**
       * @brief get flow vectors in color coding
       * converts the flow vectors to colors, where direction represents a color
       * in a hsv hue circle. length of the vectors scales saturation and value. 
       * note that the resulting image has 4 channels!
       */
      void GetColorCoded(BIAS::Image<float> &image);
      
    protected:
      // creates image pyramid by downscaling by 2 vector.size times
      void CreatePyramid_(std::vector<clfImage2D *> &pyramid);
      // upsample by 2, scaling the pixel values by parameter scale
      void Upsample_(clfImage2D *src, clfImage2D *dst, float scale=1.0f);
      // shorthand for creating a new image and clear to zero
      clfImage2D *newImage_(unsigned int w, unsigned int h, bool clear = false);
      // warps the second image according to already computed (u,v)s
      // will also fill the gradient images
      void Warp_(unsigned int level);
      // computation of flow on a pyramid level
      void ComputeFlow_(unsigned int level);
    private:
      clfContext *context_;
      clfProgram *programCL_;
      
      // color conversion, filters and scalers
      clfColorConversion *colorConvCL_;
      clfSimpleFilter *downsampleCL_;
      clfSimpleFilter *upsampleCL_;
      clfFilter<float, float> *clearFilter_;
      // input images
      clfImage2D *image1_, *image2_;
      // only needed for creating debug images
      clfImage2D *debug_;

      // reusable pyramids of all the different intermediate results
      std::vector<clfImage2D *> uvw_, uvwX_, uvwY_, uvw0_, uvwOld_;
      std::vector<clfImage2D *> image2warpedt_, imageDiv_, P1_, P2_, imageCopy_, imageCopy2_;
      std::vector<clfImage2D *> Ixyg_;
      std::vector<clfImage2D *> pyramid1_;
      std::vector<clfImage2D *> pyramid2_;

      // parameters for algorithm
      int maxComputeUnits_;
      int numIm_;
      float sigma_, tau_, gamma_, lambda_;
      unsigned int warps_;
      unsigned int maxIterations_;
      unsigned int levels_;
  };

} /* namespace BIAS */
#include <Base/Common/BIASpragmaEnd.hh>
#endif /* CLFTVL1FLOW_HH_ */