PMDImageProc.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 __BIAS_PMDIMAGEPROC_H__
#define __BIAS_PMDIMAGEPROC_H__

#include <bias_config.h>
#include <Base/Image/Image.hh>

#include <Base/Image/PMDImageIO.hh>  
#include <Geometry/Projection.hh>
#include <Base/Geometry/KMatrix.hh>
#include <Geometry/HMatrix.hh>
#include <Geometry/Pose.hh>
#include <Base/Common/CompareFloatingPoint.hh>


namespace BIAS {

  class BIASImage_EXPORT PMDImageProc
  {

  
  public:
  
    /** @brief convert a depth image such that the depth and the grey value 
        at the same pixel position belong to the same ray. The transformation 
        information is taken from the metadata. MetaDataDepth is changed
        for the converted depth image and is identical to MetaData2D afterwards
        @param ImgDepth is the image to convert. This image has to contain 
        depth information and is changed in size and contents.
        @param MetaData2D this is the metadata for the 2D-image.
        @param MetaDataDepth the metadata for the depth image. Is adapted 
        to reflect the image transformation.
        @author Birger Streckel **/
    static int FitDepthTo2DImage(Image<float> &ImgDepth, 
                                 const PMDImageMetaData &MetaData2D, 
                                 PMDImageMetaData &MetaDataDepth);

    static int FitDepthTo2DImage(Image<float> &ImageDepth,
                                 const BIAS::Projection &proj2D,
                                 const BIAS::Projection &projDepth,
                                 int kernelsize=0);


    static int FitModCoeffTo2DImage(Image<float> &ImgModCoeff, 
                                    const Image<float> &ImgDepth, 
                                    const PMDImageMetaData &MetaData2D, 
                                    PMDImageMetaData &MetaDataDepth);
    /**
    * \brief calculates a color image of the size of the depth image
    * by projecting every pixel of the depth image to 3D space and projecting it back
    * to the color image using the color image projection
    * \param depthImage[in] : the depth imahe to use
    * \param textureImage[in] : the original color image
    * \param depthProj[in] : projection corresponding to depthImage
    * \param textureProj[in] : projection corresponding to textureImage
    * \param newColorImage[out]: calculated new color image, same size as depthImage
    * \author ischiller
    * \date 08/2010
    */
    static void Fit2DToDepthImage(Image<float> &depthImage,
                                                                    Image<unsigned char>& textureImage,
                                                                    Projection& depthProj,Projection& textureProj,
                                                                    Image<unsigned char>& newColorImage);

    static KMatrix KFromMeta(const PMDImageMetaData &MetaData);
    static Pose PoseFromMeta(const PMDImageMetaData &MetaData);
    static PMDImageMetaData MetaFromPoseAndK(const Pose &Po,
                                             const KMatrix &K, int width, 
                                             int height, int channels); 

    /**
     * \brief use to limit the depth spread to a certain range around
     * the
     */
    static void LimitDepthSpread(BIAS::Image<float>& depthImage,
                                                                float maxDeviation);

    /** Give the standard deviation for a pixel in the depth image.
     *  Measurement precision polynome was taken from:
     *  M.Stommel K.-D.Kuhnert "Fusion of Stereo-Camera and PMD-Camera
     *  Data for Real-Time Suited Precise 3D Environment Reconstruction"
     *  @returns the sigma of the pixel depth depending on the precision
     *    formula and the surrounding pixels.
     */
    static double CalcSigmaDepth(const Image<float> &ImgDepth, 
                                 const unsigned int x, 
                                 const unsigned int y,
                                 const unsigned int HalfWinSize);


    /** @brief This function denoises a PMD-Depth image by Median and 
     *  variance filtering. Sets noise pixels to zero.
     */
    static int DenoiseDepthImage(Image<float> &ImgDepth,
                                 int size=1,
                                 double sigmaVarianz=0.5);

    /** @brief This function adds noise to a depth image.
     * The intention is to add noise to a synthetically 
     * created depth image. The noise sigma is similar to
     * that of a good conditioned PMD-measurement.
     */
    static int AddNoiseToDepthImage(Image<float> &ImgDepth);


    /** @brief This function scales the depth image with the given 
     * scale factor.
     */
    static void ScaleDepthImage(Image<float> &ImgDepth, double scaleFactor);
    
    /** @brief Deletes (sets to 0) pixels in PMD-Image with a local 
     *  variance > sigmaThresh. Eleminates depth noise.
     *  @author grest
     */
    static void DeleteHighVarianceValues(BIAS::Image<float> &img,
                                         const double sigmaThresh,
                                         const int halfwinSize=1);
    /** @brief Markes pixels in PMD-Image with a local
    *  variance > sigmaThresh. Eleminates depth noise.
    *  @author grest
    */
    static void MarkHighVarianceValues(const BIAS::Image<float> &img,
                                       BIAS::Image<float> &mark,
                                       double sigmaThresh,
                                       int halfwinSize=1);

    /**
     * \brief Projects all points != 0 in image cIm to both other images cIm1 and cIm2
     * and checks whether the 3D point projects to a valid point !=0 in the other images or if a valid
     * point !=0 exists in the neighbourhood of size searchSize. If no valid points can be
     * found in the other images in cImCheck the pixel in image cIm is invalidated (=0).
     * \param cIm[in][out]: the image to check and invalidate.
     * \param cImCheck[in]: the images to check against.
     * \param cPCheck[in]: the projections to check against, same order as in cImCheck.
     * \param searchSize[in]: the area around a projected pixel to search for neighbours (default = 3).
     * \return number of deleted pixels, -1 on error
     * \author ischiller
     * \date 08/2010
     */
    static int CrossCheck(Image<float>& cIm, const Projection& cP,
                                                std::vector<const Image<float>* >& cImCheck,
                                                std::vector<const Projection*>& cPCheck,
                                                  int searchSize=3);

  protected:

    /** @brief These methods transform the depth image to fit the 
     *  2D-image. After transformation the Depth for every 2D-point
     *  is at the same pixel position in the depth image. There are 
     *  3 steps of transformaiton complexity: Only K, Only Rot+K, Free.
     *  @author Birger Streckel
     */
    static int FitDepthTo2DImageKOnly_(Image<float> &ImgToModify,
                                       const PMDImageMetaData &MetaData2D, 
                                       PMDImageMetaData &MetaDataDepth);
    static int FitDepthTo2DImageHomogr_(Image<float> &ImgToModify,
                                        const PMDImageMetaData &MetaData2D, 
                                        PMDImageMetaData &MetaDataDepth);
    static int FitDepthTo2DImageFree_(Image<float> &ImgToModify,
                                      const Image<float> &ImgDepth, 
                                      const PMDImageMetaData &MetaData2D, 
                                      PMDImageMetaData &MetaDataDepth);

    
    /** @brief Create a H-Matrix that converts the depth image to the 2D view
     */
    static HMatrix HFromMeta_(const PMDImageMetaData &MetaData2D, 
                              const PMDImageMetaData &MetaDataDepth);
  };


}
#endif