HistogramImage.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 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
*/


#ifndef __HistogramImage_HH__
#define __HistogramImage_HH__

#include <Base/Common/BIASpragmaStart.hh>

#include <vector>

#include <Base/Image/Image.hh>
#include <Base/Math/Math.hh>

// start from big bits, because small bits are used in Image
#define D_HIST_VEC 0x8000000

namespace BIAS{


  enum HistMode {HIST_POINTS, HIST_BARS, HIST_LINES};

  /** @class HistogramImage
      @ingroup g_image
      @brief Class for easy histogram image generation.

      Automatically generate and draw some histograms in one image.

      The histogram image has size bincount*zoomfactor+border by
      bincount*zoomfactor+border and can display some histograms simultanously.
      The zoomfactor represents the size of one point in the histogram image in
      pixel units. It can be set via the constructor HistogramImage().
      The Border is fixed to 2 pixel.

      For usage, see ExampleHistogram.cpp or call successivly
      - InitHist()

      - AddHist()

      - Draw()

      Two styles are possible: point (HIST_POINTS) and bar (HIST_BARS) style.
      Use SetDrawMode() for choosing a style.

      Colors can be set for each histogram via SetColor().

      see also ExampleHistogram.cpp

      Since HistogramImage is derived from Image<unsigned char>, any drawing
      function working on Image<unsigned char> can be used on HistogramImage
      as well.

      @author woelk */

  class BIASImage_EXPORT HistogramImage : public Image<unsigned char>
  {
  public:
    ///
    HistogramImage(unsigned short int zoomfactor = 2);
    ~HistogramImage();

    /// resizes Hist_
    void SetBinCount(unsigned int bincount);

    inline unsigned int GetBinCount()
    { return BinCount_; };

    inline unsigned int GetHistCount()
    { return HistCount_; };

    /// sets the zoomfactor
    /** @todo factor also scales the y axis, this is most probably not desired*/
    void SetFactor(unsigned short Factor);

    /// dummy function to avoid swapping color model in this class
    void SetColorModel();

    /// Select drawing style. Default is HIST_POINTS
    void SetDrawMode(HistMode m) {Mode_ = m;};

    /** Reserves internal data structures for histcount histograms. */
    void SetHistCount(unsigned int histcount);

    /** reserves the internal data structures for histcount histograms with
        bincount bins in each in one image
        @author woelk */
    int InitHist(unsigned int bincount = 256, unsigned int histcount = 1);

    /// releases internal data structures (Hist_)
    int ReleaseHist();

    // calculates the Shannon Entropy and treats entries in HistogramImage as
    // probabilities
    float CalcShannonEntropy(unsigned int hist=0);

    // calculates the Renyi Entropy and treats entries in HistogramImage as
    // probabilities
    float CalcRenyiEntropy(unsigned int hist=0, double alpha=1.0);


    /** calculates the histogram of image and adds them to the internal data
        structures
        @author woelk */
    template <class StorageType>
    int AddHist(const Image<StorageType>& Image, unsigned int hist = 0);

    /** Calcluates the histogram from data and adds them to the internal data
        structures. Minimum and maximum data values are determined
        automatically and BinCount_ bins are calculated evenspaced between min
        and max.
        @author woelk */
    template <class DataType>
    int AddHist(const std::vector<DataType>& data, unsigned int hist = 0);



    /* BinCount_ bins are deteremined between min and max
       @author woelk 07 2004 */
    template <class DataType>
    int AddHist(const std::vector<DataType>& data, DataType min, DataType max,
                unsigned int hist = 0);

    /** for data[i] increase according bin about weight[i]
        @author woelk */
    template <class DataType>
    int AddWeightedHist(const std::vector<DataType>& data,
                        const std::vector<double>& weight, unsigned int hist = 0);

    // sets color in which to draw hist num hist
    int SetColor(unsigned char R, unsigned char G, unsigned char B,
                 unsigned int hist = 0);

    /// returns the range of the histogram, i.e. the data value associated
    /// with bin[0] and bin[bincount-1]
    inline void GetDataRange(double& min, double& max, unsigned int hist = 0)
    { min=MinBinVal_[hist] ; max=MaxBinVal_[hist]; }

    /// returns the biggest bin in histogram hist
    inline void GetMaxHistEntry(double& maxentry, unsigned int hist = 0)
    { maxentry=MaxHistEntry_[hist]; }

    /// if true, the upper border of histogram is MaxHistEntry, otherwise the
    /// upper border of histogram k is \sum_i Hist[k][i] = NumData_[k]
    inline void SetScaleYToMaxEntry(bool s)
    { ScaleYToMaxEntry_ = s; }

    /** actually draws histogram(s) from the internal data structures */
    int Draw();

    /** actually draws histogram(s) from the internal data structures
        uses a logarithmic y axis */
    int DrawLog();

    /// zeros existing histogram
    int ZeroHist(unsigned int hist = 0);

    /// Get the counted number of bin from hist, -1 for invalid bin/hist
    double GetBin(unsigned int bin, unsigned int hist=0);

    /// Set the counted number of bin from hist to manipulate the histogram
    int SetBin(unsigned int bin, double value, unsigned int hist=0);

    void Dump(std::ostream& os=std::cout);

    /// writes ascii data to stream, can be used later e.g. with gnuplot
    void WriteASCII(std::ostream& os=std::cout);

    /// opens file and calls  WriteASCII() with it
    int WriteASCII(const std::string& filename);

    /** transforms data coordinates to image coordinates
        does automatic clipping */
    void CooTransf(double datacoo[2], double imcoo[2], unsigned hist=0);
    /** transforms data coordinates to image coordinates
        does automatic clipping and rounding */
    void CooTransf(double datacoo[2], unsigned imcoo[2], unsigned hist=0);

    /** returns true if MaxHistEntry==0 for all histograms
        @author woelk 10/2004 */
    bool IsEmpty();

  protected:
    unsigned short int HistCount_;
    unsigned int BinCount_; // number of bins in histogram
    double **Hist_; // array containing the histogram
    unsigned char **Color_; // array containing rgb values for every histogram
    unsigned int HistSize_; // height of histogram
    double *MaxHistEntry_; // contains the biggest entry in every histograms
    double *NumData_; // contains the number of data in each histogram
    unsigned short int Factor_; // scaling factor for drawing histogram
    double *Average_; // Average value for each hist
    HistMode Mode_;
    unsigned int _uiBorder; // border of the histogram
    unsigned char _ucBorderColor;
    double *MinBinVal_, *MaxBinVal_, *BinSize_;
    // should the upper border be MaxHistEntry, otherwise the
    // upper border of histogram k is \sum_i Hist[k][i]
    bool ScaleYToMaxEntry_;


    // only calls DeleteHist_ and DrawHist_
    int RedrawHist_(unsigned int hist);

    // removes all image point with color of hist
    int DeleteHist_(unsigned int hist);

    // draws histogram
    int DrawHist_(unsigned int hist);

    // draws histogram
    int DrawHistLog_(unsigned int hist);

    int CalcAverage_(unsigned int hist);

  }; // class

  class BIASImage_EXPORT Histogram2D : public Image<unsigned char>
  {
  public:
    Histogram2D(unsigned short zoomfactor = 2);
    ~Histogram2D();

    /// dummy function to avoid swapping color model in this class
    void SetColorModel();

    /// sets the zoomfactor
    void SetFactor(unsigned short Factor);

    void InitHist(unsigned xbincount=256, unsigned ybincount=256);

    template <class DataType>
    void AddHist(const std::vector<DataType>& xdata,const std::vector<DataType>& ydata);

    void Draw();

    void DrawLog();

    void ZeroHist();

    void Dump(std::ostream& os=std::cout);

    /// writes ascii data to stream, can be used later e.g. with gnuplot
    void WriteASCII(std::ostream& os=std::cout);

    /** transforms data coordinates to image coordinates
        automatic clipping of imcoo is performed */
    void CooTransf(double datacoo[2], double imcoo[2]);
    /** transforms data coordinates to image coordinates
        automatic clipping of imcoo is performed */
    void CooTransf(double datacoo[2], unsigned imcoo[2]);

  protected:
    unsigned XBinCount_, YBinCount_;
    double **Hist_; // array containing the histogram
    double MaxHistEntry_; // contains the biggest entry in each histogram
    double XMinBinVal_, XMaxBinVal_, XBinSize_, YMinBinVal_, YMaxBinVal_,
      YBinSize_;
    unsigned int _uiBorder; // border of the histogram
    unsigned char _ucBorderColor;
    unsigned short int Factor_; // scaling factor for drawing histogram

    void _ReleaseHist();

  }; // class

} // namespace BIAS

#include <Base/Common/BIASpragmaEnd.hh>

#endif // __HistogramImage_HH__