PyramidImage.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 __PyramidImage_hh__
#define __PyramidImage_hh__

#include <Base/Common/BIASpragmaStart.hh>

#include <Base/Common/SharedPtr.hh>
#include <Base/Image/Image.hh>
#include <Filter/Rescale.hh>
#include <Image/PyramidImageInterface.hh>

#include <float.h>
#include <vector>

// for GetSingleImage
// border between pyramid level and fill color
#define PYRAMID_BORDER 2
#define PYRAMID_BACKGROUND 0

#define D_PYRAMID_CREATE      0x00000001
#define D_PYRAMID_SINGLE_IM  0x00000002

namespace BIAS
{
  /** @class PyramidImage
      @ingroup g_image
      @brief Class for holding multiple downsampled images

      Represent a pyramid image, i.e. multiple downsampled images.
      The image with index 0 has the original size, while each (i+1)-th image
      has half the size of the i-th image.

      @note Pointers to the images are held in this class.
      @author woelk 09/2004 */
  template <class StorageType>
  class BIASImage_EXPORT PyramidImage
    : public Debug, public PyramidImageInterface<StorageType>
  {
  public:
    PyramidImage();

    PyramidImage(const PyramidImage<StorageType>& pim);

    PyramidImage(const double factor,
                 const std::vector<SharedPtr<Image<StorageType> > > &imgs);

    ~PyramidImage();

    /** @brief copy image into level 0 and create other levels according to
        parameters set so far (pyramidsize, filter,...)
        @param py_size 0=auto, 1=only original image
        @author woelk 09/2004 */
    void Init(const Image<StorageType>& image, const unsigned py_size=0);

    /** @brief same as Init(Image) but can use different ST, e.g. construct
        float pyramid from uchar image, uses ImageConvert then.
        @param py_size 0=auto, 1=only original image
        @author koeser */
    void InitFromImageBase(const ImageBase& image, const unsigned py_size=0);

    /** @author woelk 09/2004 */
    void Init(const unsigned int width, const unsigned int height,
              const unsigned int channelcount, const unsigned py_size);

    /// initializes with empty images
    void Init(const unsigned pyramid_size);

    void Clear();
    inline void clear() { Clear(); }

    /// sets this as shallow copy of pim
    PyramidImage<StorageType>&
    ShallowCopy(const PyramidImage<StorageType>& pim);

    /// create a shallow clone
    virtual PyramidImageInterface<StorageType> *ShallowClone() const;

    /** deep copy assignement
        @author woelk 09/2004 */
    PyramidImage<StorageType>&
    operator=(const PyramidImage<StorageType>& pim);

    /** element access */
    SharedPtr<Image<StorageType> >& operator[](const unsigned index)
    { BIASASSERT(index<=_Images.size()); return _Images[index]; }

    SharedPtr<const Image<StorageType> >
      operator[](const unsigned index) const
    { BIASASSERT(index<_Images.size());
      BIASASSERT(Get(_Images[index])!=NULL);
      return _Images[index]; }

    /** @brief computes (Gaussian) expectation value across a region,
        used e.g. in anisotropic anti-aliasing */
    int GetAnisotropicImageValue(const double& xsource,
                                 const double& ysource,
                                 const Matrix2x2<double>& Cov,
                                 double &T,
                                 unsigned int channel = 0) const;



    /** @brief trilinear value from scale space: (x,y) is position in
        pyramid[0], 0<=scale<=size()-1 is pyramid level

        Slow, but correct implementation, with boundary checking,
        takes care of PositionOffset

        @author koeser 10/2007 */
    int GetTrilinearImageValue(const double& x,
                               const double& y,
                               const double& scale,
                               double& T,
                               int channel=0) const;


    /** @brief bilinear value from scale space: (x,y) is position in
        pyramid[0], 0<=scale<=size()-1 is pyramid level

        Slow, but correct implementation, with boundary checking,
        takes care of PositionOffset

        @author koeser 1/2008 */
    double GetImageValue(const double& x, const double& y,
                         unsigned int scale, int channel=0) const;

    /** downsamples from (*this)[0]
        assumes that all pointers e.g. (*this)[1] are valid
        and point to an image of correct size
        returns 0 on success, anything else on failure
        @author woelk */
    int Downsample();

    /** @brief resizes this and fills correctly with smaller images
     *
     *  Make sure that you do not change the filter type between initial
     *  pyramid creation and the call to this function, otherwise the
     *  global scalar _PositionOffset becomes inconsistent
     *
     *  No images smaller than minImageWidth will be created. I case such
     *  an image is rejected, return value is set to +1.
     *  @return =0:ok, <0:error, >0 pyramid size limited by min image width
     *  @author koeser 08/2007 */
    int CreateAdditionalLayer(unsigned int numnewLayers = 1,
                              unsigned int minImageWidth = 32);

    /** returns a single image containing all pyramid images
        @author woelk 09/2004 */
    void GetSingleImage(Image<StorageType>& im) const;

    void SetUID(BIAS::UUID uid);

    /** set the ROI for all images */
    int SetROI(unsigned minx, unsigned miny, unsigned maxx, unsigned maxy);

    /** set the ROI for all images from original ROI from Img */
    int SetROI(const ROI &roi);

    inline bool IsEmpty() const { return _Images.empty(); }
    inline unsigned Size() const { return (unsigned)_Images.size(); }

    /** @brief sets all pixels in all images to zero
        @author woelk 10/2004 */
    void SetZero();

    /** @brief writes a file in mip format per pyramid level using prefix
        @author woelk 10/2004 */
    int WriteImages(const std::string& prefix) const;

    /////////////////////////////////////////////////////////////////////////
    //              get/set functions
    /////////////////////////////////////////////////////////////////////////

    inline void SetRescaleFactor(const double factor)
    { _RescaleFactor=factor; _rescale.SetFactor(factor); }
    inline double GetRescaleFactor() const { return _RescaleFactor; }

    void SetLowPassFilter(const FilterNToN<StorageType, StorageType>& filter)
    { _rescale.SetLowPassFilter(filter); }
    inline void SetLowPassType(int lpt)
    { _rescale.SetLowPassType(lpt); }


    inline const std::vector<double>& GetFactors() const { return _vFactor; };

    inline std::vector<double> GetFactors() { return _vFactor; };


    /// @author woelk, see _PostionOffset for details
    inline double GetPositionOffset() const { return _PositionOffset; };

    // keeps images
    virtual void resize(const unsigned size);

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

    bool IsInROI(double x, double y, int layer) const;


  protected:
    std::vector<SharedPtr<Image<StorageType> > > _Images;

    // rescale filter for downsampling
    Rescale<StorageType, StorageType> _rescale;

    // the param of the rescale filter
    double _RescaleFactor;

    // _vFactor[i] is the dowsampling factor from (*this)[0] -> (*this)[i]
    std::vector<double> _vFactor;

    /** Offset which needs to be used when transferring point locations
        between pyramid levels:

        (2*xs+offset, 2*ys+offset) = (xb, yb) or
        (xs, ys) = ((xb-offset)/2.0, (yb-offset)/2.0)

        where (xs, ys) is the pixel position in pixel coo. the smaller
        destination image and (xb, yb) is the position in pixel coo. in the
        bigger source image.

        see Rescale::DowsampleBy2 for details
        @author woelk 05/2005 */
    double _PositionOffset;

    /** creates the levels by downsampling from (*this)[0] */
    void _CreateLevels();

    virtual void push_back(SharedPtr<Image<StorageType> > img)
    { _Images.push_back(img); }


  };

} // namespace BIAS


#include <Base/Common/BIASpragmaEnd.hh>

#endif