ImageBlenderIncremental.hh

#ifndef __ImageBlenderIncremental_hh__
#define __ImageBlenderIncremental_hh__

#include <Base/Image/Image.hh>
#include <Image/Camera.hh>
#include <Base/Image/ImageConvert.hh>
#include <Filter/Gauss.hh>
#include <Geometry/ProjectionParametersCylindric.hh>
#include <Geometry/ProjectionParametersPerspective.hh>
#include <Image/ProjectionMapping.hh>
#include <Geometry/Projection.hh>
#include <Base/Math/RGBA.hh>

#define WEIGHT_TYPE_NONE           0
#define WEIGHT_TYPE_CIRCULAR       1
#define WEIGHT_TYPE_CIRCULAR_FIT   2
#define WEIGHT_TYPE_RECTANGULAR    3
#define WEIGHT_TYPE_RECT_NONLINEAR 4
#define WEIGHT_TYPE_MIX            5 // mix between rectangular and circular
#define WEIGHT_TYPE_USERIMAGE      6


// these defines steer the orientaion of the cylinder with X/Y/Z-axes of the
// cameras or automatically
#define HORIZON_ALIGNMENT_X 0
#define HORIZON_ALIGNMENT_Y 1
#define HORIZON_ALIGNMENT_UNKNOWN 2
#define HORIZON_ALIGNMENT_AUTO 3

// DEBUG LEVELS:
// gives some output about the whole progress
#define D_IMAGEBLENDER_MINIMAL   1
// gives some output about geometry calculation
#define D_IMAGEBLENDER_GEOMETRY  2
// gives some output about the filtering process
#define D_IMAGEBLENDER_FILTERING 4
// gives some output about the blending
#define D_IMAGEBLENDER_BLENDING  8


namespace BIAS {
  
  /** @class ImageBlenderIncremental
   *  @brief maps several images into a common mosaic and blends them seamlessly
   *
   *  Blends a bunch of images seamlessly either in incremental or batch mode
   *  (in any case 64 byte RAM per output pixel are required, plus some constant,
   *   i.e. for a 10000x10000 pano you will need 6.4GB RAM). If you dont have
   *  enough RAM, tile your output image and run multiple times.
   *
   *  General usage of this class:
   *  First, specify the output parameters. For a rectilinear panorama
   *  this is a simple ProjectionParametersPerspective with wide field of view
   *  or for cylindrical panorama use  BIAS::ProjectionParametersCylindric.
   *  However, you can also blend multiple textures for surfaces by providing
   *  the depth map of the output image.
   * 
   *  When you specify the output parameters by SetOutputParameters(),
   *  a compatible output image will be generated internally.
   *  Then, for each input image (the photos you want to stitch),
   *  call Blend(image). Internally, the output image will be
   *  updated (a Kalman filter on the low frequency intensity plus the most 
   *  reliable (winner-takes-all) laplacian of all images). 
   *  Finally, call GetImage to obtain the resulting image.
   * 
   *  Originally this class was written for panoramic image stitiching and
   *  computes a cylindrical geometry automatically from the different
   *  images. However, you can specify any projection you want as an output.
   *  In case your input images do not have the same camera center as your
   *  output image and you want this to be considered, you have to provide
   *  an output depth map, which can be used for the mapping in 3D.
   *
   *  Blending is done by separating the image into high-pass and low-pass
   *  parts, where each part is blended over one wavelength, i.e. sharp edges
   *  are blended within 2 pixels, while the image mean is blended over
   *  the whole image size.
   *  @author Robert Wulff, kkoeser
   *  @date 07/2007, 06/2014
   **/
  class BIASImage_EXPORT ImageBlenderIncremental : public BIAS::Debug {
    
    public:
    
    /** @brief constructor
     *  @param blendIncremental set to true if you want to blend each added
     *         camera right away, rather than in (traditional) batch mode
     *  @author Robert Wulff
     *  @date 07/2007
    **/
    ImageBlenderIncremental(bool blendIncremental = false);


    /** @brief resets internal mosaic
        @param imagegeometry projectionparameters of output mosaic
        @param bgcolor initial background color of empty mosaic (e.g. black)
        @param pDepthmap if != NULL, this enables 3D stitching mode and
               the camera centers of the image and the final mosaic will be
               considered
    */
    void SetOutputParameters(const BIAS::ProjectionParametersBase& imagegeometry,
                             const BIAS::RGBAuc bgcolor=RGBAuc(0,0,0,0));

    /** @brief set a weight image (e.g. to ignore certain pixels or to account
     *         for funny illumination and confidence in pixel color
     *
     *         specify WEIGHT_TYPE_USERIMAGE to use this in AddCamera
     *  @param weights must be of same size as next user input image */
    void SetUserWeightImage(const BIAS::Image<float>& weights);

    /** @brief In incremental mode, the mosaic is updated using the image and
     *  the contained projection, in batch mode the image is simply added
     *  to the database and must contain a valid projection and a valid UUID.
        @return 0 = OK, -1 = error
    **/
    int AddCamera(const BIAS::Camera<unsigned char>& camera,
                  unsigned int weightType = WEIGHT_TYPE_CIRCULAR_FIT);

    /** @brief returns (current) mosaic image in incremental mode */
    void GetMosaicRGBA(Image<unsigned char>& mosaic);

    /** @brief returns (current) mosaic image in incremental mode */
    void GetMosaicRGBA(Image<float>& mosaic);

    /** @brief returns (current) mosaic image in incremental mode */
    void GetMosaicRGB(Image<unsigned char>& mosaic);

    /** @brief returns (current) mosaic image in incremental mode */
    void GetMosaicRGB(Image<float>& mosaic);

    /** @brief for interadctive visualization, show current buffer (read only) */
    const Image<float>* GetLowPassPointer() {
      return &latestMosaicLow_;
    }

    
    /** @brief compute cylindrical geometry from added images and blend all
        added images

        This function is only available in batch mode.
        wrapper function only, calls other BlendImages
        @param destination result image
        @return true iff blending succeeded or false otherwise
        @author Robert Wulff
        @date 07/2007
    **/
    inline bool BlendImages(BIAS::Camera<unsigned char> &destination,
                            double gaussSigma = 1.2) {
      // compute cyl geometry
      ProjectionParametersCylindric ppc(-cylinderHeight_, cylinderHeight_, 
                                        -M_PI, M_PI,
                                        outputImageWidth_,
                                        outputImageHeight_);
      ComputeCylCamGeometry_(ppc);
      return BlendImages(destination, ppc, NULL, gaussSigma);
    }
    

    /** @brief Blends all added images into destination with ppOut projection
     *
     *         This function is only available in batch mode.
     *  @param destination output image
     *  @param ppOut desired projection for output
     *  @param depthmap of destination, needed if input cameras do not have the
     *         same center as output camera, ignored if NULL
     *  @return true iff blending succeeded or false otherwise
     *  @author Robert Wulff
     *  @date 07/2007
    **/
    bool BlendImages(BIAS::Camera<unsigned char> &destination,
                     const ProjectionParametersBase& ppOut,
                     const BIAS::Image<float>* depthmap = NULL,
                     double gaussSigma = 1.2);

    void SetDepthMap(const BIAS::Image<float>& depthmap) {
      Depth_ = depthmap;
      plane_.SetZero();
    }
    void SetPlane(const HomgPlane3D& theplane) {
     plane_ = theplane;
     if (!Depth_.IsEmpty()) Depth_.Release();
    }


    /** @brief 
        @author Robert Wulff
        @date 10/2007
    **/
    inline void SetOuputImageSize(const unsigned int &newSize) {
      outputImageHeight_ = newSize;
      outputImageWidth_  =
        (unsigned int)(outputImageHeight_ * cylinderHeight_ / M_PI);
    };
    
    /** @brief 
        @author Robert Wulff
        @date 10/2007
    **/
    inline unsigned int GetOuputImageSize() {
      return outputImageWidth_;
    };
    
    // creates a 3d model of image planes and cyl cam
    inline void SetWriteVrml(bool flag) {writeVrml_ = flag;}
    
    inline void SetDrawImageBorders(bool flag) {drawImageBorders_ = flag;}
    
    // here come the public member variables
    
    /** @brief determines the alignment of the horizon
               possible values are:
               HORIZON_ALIGNMENT_X - horizon is in x direction (default value)
               HORIZON_ALIGNMENT_X - horizon is in y direction
               HORIZON_ALIGNMENT_UNKNOWN - horizon alignment is unknown
                                           or mixed
        @date 12/07
    **/
    inline void SetHorizonAlignment(unsigned int val) {horizonAlignment_ = val;};
    
  protected:
    /** @brief helper function for simple laplacian pyramid */
    void GetLowPassAndHighPassImage_(const Image<float>& camCyl,
                                     Image<float>& lowPassCam,
                                     Image<float>& highPassCam);

    /** @brief helper function for incremental fusion */
    void LowPassFusiondAndHighPassMax_(Image<float>& destLow, Image<float>& destHigh,
                                       Image<float>& lowPassCam, Image<float>& highPassCam);

    /** @brief helper function for extracting mosaic from laplacian pyramid */
    void AddLowPassAndHighPassImage_(Image<float>& destLow, Image<float>& destHigh,
                                     Image<unsigned char>& destination);

    /** @brief helper function for extracting mosaic from laplacian pyramid */
    void AddLowPassAndHighPassImage_(Image<float>& destLow, Image<float>& destHigh,
                                     Image<float>& destination);

    /** @brief helper for filling an image with rgba data */
    void FillBGImage_(Image<float>& BGImage, const RGBAuc& color);
    
    /** @brief copies alpha channel from first RGBA image into second */
    void CopyAlphaChannel_(const Image<float>& camCyl,
                           Image<float>& lowPassCam);

    /** @brief adds an alpha channel to RGB image, alpha can be e.g. radial
        symmetric from image center*/
    void ComputeAlphaChannelWeight_(BIAS::Image<float> &image,
                                    unsigned int weightType =
        WEIGHT_TYPE_RECTANGULAR);
    
    void ConvertImageToRGBA_(BIAS::Image<float> &image);
    
    void ComputeCylCamGeometry_(BIAS::ProjectionParametersCylindric &ppc);
    
    double CalcAngleToYAxis_(const BIAS::Vector2<double> &v,
                             bool wantDegrees = false);
    
    double CalcAngleToXAxis_(const BIAS::Vector2<double> &v,
                             bool wantDegrees = false);
    
    /** @brief Checks FOV of each cam and computes the cylinder's FOV
               If mapper tries to access pixel outside of image, nasty
               distortion effects occur. This method checks the FOV of each cam
               and blocks access to pixels that are out of scope.
        @author Robert Wulff
        @date 11/07
    **/
    void CheckFov_(BIAS::ProjectionParametersCylindric &ppc);
    
    // here come the protected member variables
    double cylinderHeight_;
    unsigned int outputImageWidth_;
    unsigned int outputImageHeight_;
    unsigned int horizonAlignment_;
    
    std::vector<BIAS::UUID> imageIDs_;
    std::map<BIAS::UUID, BIAS::Camera<float> > inputImages_;
    
    BIAS::Gauss<float, float> gaussFilter_;
    
    bool writeVrml_;
    bool drawImageBorders_;
    bool blendIncremental_; ///< incremental or batchmode

    /// weight image for user specified weighting
    BIAS::Image<float> weightimage_;
    /// output image in incremental mode
    BIAS::Image<float> latestMosaicHigh_, latestMosaicLow_;
    /// output projection
    BIAS::ProjectionParametersBase* ppOutput_;
    /// output depth
    BIAS::Image<float> Depth_;
    /// plane (alternative to depth)
    BIAS::HomgPlane3D plane_;
    /// the actual worker:
    BIAS::ProjectionMapping<float, float> pm_;


  };
}
#endif // __ImageBlender_hh__