CondensHisto.hh

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

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


BIAS is free software; you can Sredistribute 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
*/


#ifndef _HISTO_CONDENSATION__HH_
#define _HISTO_CONDENSATION__HH_

#include <bias_config.h>

// BIAS
#include <StateEstimator/Condensation.hh>
#include <Base/Image/Image.hh>
#include <Base/Math/Vector2.hh>
#include <Base/Math/Vector3.hh>
#include <Image/ColorHistogram.hh>
#include <Image/IntegralHistogram.hh>

#define D_COND_INT      (1<<6)

namespace BIAS{

  /** 
      @class CondensHisto
      @ingroup g_stateestimation
      @brief class for tracking an object in an image

      This class is able to handle "normal" ColorHistograms, and
      MultiColorHistograms.
      Just Set a MultiColorHistogram in SetReferenceHistogram() and 
      the whole process switches to multiHistogram processing
      
      You have to call:
      - SetActiveImage(imgHSL) with an HSL image;
      - SetReferenceHistogram(chist); (colorHistogram or ColorMultiHistogram)
      - SetArea(Vector3<double>(0,0,0.5), Vector3<double>(width,height,1.5)); 
      
      - Init(*nsamples); 
      - InitPrior(); //to set samples for first frame
     
      then just call these functions in every turn
      - SetActiveImage(imgHSL)
      - PredictNewSamplePositions()
      - Process();   
      @author Ingo Schiller, March 2003, edited by grest
  */
  class BIASStateEstimator_EXPORT CondensHisto : public Condensation{
  public:
    /**
       Set the state dimension in the constructor
    */
    CondensHisto();

    virtual void InitModelDefaults();
    
    virtual void InitPriorPositions(unsigned int nrOfInitSamples);
    
    virtual void EvaluateObservationDensities();
    
    // virtual void EvaluateImportanceWeights();
   
    void UseIntegralHistogram(bool bIntHisto);

    /**
       Checks the image Quality by checking the luminance
       of the image.
       the shutter and gain of the camera has to be set
       by the returned shutter and gain in params
       @param percent = the allowed percentage of pixels, below minsat in
                        light and dark regions
       @param shutter = the shutter the camera has to be set to
       @param gain    = the gain    ------------  ------------
    */
    void CheckImageQuality(double percent, int &shutter, int &gain);

    /** The area for the initial uniform distribution.
        3-dim case
    */     
    void SetArea(Vector3<double> min, Vector3<double> max);

    /**
       Sets the minimum weight each sample is assigned,
       when < lower minWeight_
    */
    inline void SetMinWeight(double min)
    {minWeight_ = min;}
    
    /**
       Sets the scale for the diffusion,
       diffusi0nSigma = diffScale_*areaMax_
       example value would be 0.05
    */
    inline void SetDiffScale(double diff)
    {
      diffScale_ = diff;
      diffusionSigma_[0] = diffScale_*areaMax_[0];
      diffusionSigma_[1] = diffScale_*areaMax_[1];
    }
    
    /**
       Sets the scale for the diffusion for the size
       of the histogram ,
       diffusionSigma[stateDim_-1] = diffScaleSize_*areaMax_[stateDim-1]
       example value would be 0.05
    */
    inline void SetDiffScaleSize(double diff)
    {
      diffScaleSize_= diff;
      diffusionSigma_[stateDim_-1]= diffScaleSize_*areaMax_[stateDim_-1];
    }


    /**
       Sets the scale for the second order prediction,
       valid values are 0.0000..1 - 1.0
    */
    inline void SetSecondOrderScale(double scale)
    {
      if(scale > 1.0)
        scale = 1.0;
      else if(scale < 0)
        scale = 0.0;
      secondOrderScale_ = scale;
      processSecondOrderScale_.Set(secondOrderScale_); 
    }

  /**
       Sets the scale for the first order prediction,
       valid values are 0.0000..1 - 1.0
    */
    inline void SetFirstOrderScale(double scale)
    {
      if(scale > 1.0)
        scale = 1.0;
      else if(scale < 0)
        scale = 0.0;
      firstOrderScale_ = scale;
      processFirstOrderScale_.Set(firstOrderScale_); 
    }



    /** sets the present picture to compare and create new observation */
    inline void SetActiveImage(Image<unsigned char> &img)
    {img_ = &img;}

    /** sets the reference colorhistogram */
    inline
    void SetReferenceHistogram(ColorHistogram<unsigned char> &refHisto)
    {
        if(img_ != NULL){
      refHisto_=refHisto;
      m_dMaxRefHistoSize = double(img_->GetWidth() * img_->GetHeight())/
        double(refHisto.GetHeightROI() * refHisto.GetWidthROI());
      chist_.SetBinSize(refHisto_.GetBinSize(), refHisto_.GetBinSizeSat());
      useMultiHistogram_ = false;
      //  cout<<"Using Normal Histogram"<<endl;
        }
      else{
        BIASERR("No actual image, can not net reference histogram.")
      }
    }
 
    /** sets if Multihistogram is used or not, default is false */
    inline
    void SetMultiHistogram(bool multi)
    {useMultiHistogram_ = multi;}

    


    /* at every (rounded) sample position, the sampleImg is set
       to UCHAR_MAX */
    void GetSamplePositions(Image<float> &sampleImg);

    /* 
     @returns the actual position of the mean value 
     @author Ingo Schiller
     @modified 03. August 2004
    */
    void GetMeanValue(Vector<double> &mean);


    /* 
     @returns the actual position of the sample, with max weight 
     @author Ingo Schiller
     @modified 29.11.04
    */
    void GetMaxValue(Vector<double> &max);

    /**
       @param meanVar= MeanVariance is a vector of struct:
       [varPosx, varPosy, varSize, varWeight]
    */
    void GetMeanVariance(Vector<double>  &meanVar);

    /**
       @param maxVar= MaxVariance is a vector of struct:
       [varPosx, varPosy, varSize, varWeight]
    */
    void GetMaxVariance(Vector<double>  &maxVar);


    /**
       @return = the maximum weight of all samples;
       @param index = the index of which maxWeight is found
    */
    double GetMaxWeight(int &index);

  
    /**
       @returns the aktual image on which the condensation is 
       doing it's job
       @author Ingo Schiller
    */
    Image<unsigned char> GetAktImage();

  
    /**
       this draws the Sizes of the Histogram
       as arrows at their x position
       @author Ingo Schiler
     */
    void DrawHistoSizes(Image<unsigned char> &img);

    /** this draws the sample weights as circles
     */
    virtual void DrawSamples(Image<unsigned char> &img);

    /** 
        this draws the sample weights as retangeles with greyvalues
        on white base
     */
    virtual void DrawSamplesWhite(Image<unsigned char> &img);

    /** this draws the samples,
        histogram sizes as rects and weights as grey values
        @author grest / schiller
     */
    void DrawSamplesExt(Image<unsigned char> &img);

    /** this draws the samples as circles and the color indicates the 
        size of the histogram (the z-coordinate)
    */
    void DrawWeightedSamples(Image<float> &img);

    /** Draws the samples with their weight as greyvalue,
        the weight is distributed to the 4 pixels around the sample postion.
        Image has to be initialized with correct size and channelcount !
    */
    void DrawPosteriorDistribution(BIAS::Image<unsigned char> &img);
    
    /** same as above but float precision and 
        returns the maximum value also.
    */
    double DrawPosteriorDistribution(BIAS::Image<float> &img);
    
    
    /** Draws the mean as a rectangle
        which size is proportional to the histogram size
     */
    virtual void DrawMean(BIAS::Image<unsigned char> &img);
    
  protected:
    // for better readablity of EvaluateObservationDensities()
    void EvaluateFromIntegralHistoImage_();

    BIAS::Vector3<double> areaMin_, areaMax_;
    Image<unsigned char> *img_;

    // the current histogram for comparision with the old one
    ColorHistogram<unsigned char> chist_;     
     
   //the integral Histogram image
    IntegralHistogram intHisto_;

    //reference ColorHistogram 
    ColorHistogram<unsigned char> refHisto_;
    ColorHistogram<unsigned char> refHisto2_;

    // needed for DrawPosteriorDistribution()
    BIAS::Image<float> fImg_;
    //basic weight of each sample to provide a wider spread of the samples
    double minWeight_; 
    double diffScale_;
    double diffScaleSize_;
    double secondOrderScale_;
    double firstOrderScale_;
    bool useMultiHistogram_;
    double   m_dMaxRefHistoSize;

    //relative to first hist, unit is first hist size
    BIAS::Vector2<double> secondHistPos_; 

    bool bIntegralHisto_;
  };



}
#endif