ltiMergeYUVToImage.h

/*
 * Copyright (C) 2003, 2004, 2005, 2006, 2007
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 * 
 * This file is part of the LTI-Computer Vision Library (LTI-Lib)
 *
 * The LTI-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License (LGPL)
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * The LTI-Lib 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 the LTI-Lib; see the file LICENSE.  If
 * not, write to the Free Software Foundation, Inc., 59 Temple Place -
 * Suite 330, Boston, MA 02111-1307, USA.  
j */ 

 
/*--------------------------------------------------------------------
 * project ....: LTI-Lib: Image Processing and Computer Vision Library
 * file .......: ltiSplitImageToYUV.h
 * authors ....: Volker Schmirgel, Pablo Alvarado
 * organization: LTI, RWTH Aachen
 * creation ...: 17.10.2003
 * revisions ..: $Id: ltiMergeYUVToImage.h,v 1.8 2007/01/05 19:22:32 alvarado Exp $
 */

#ifndef _LTI_MERGE_Y_U_V_TO_IMAGE_H_
#define _LTI_MERGE_Y_U_V_TO_IMAGE_H_

#include "ltiMergeImage.h"
#include "ltiMergeYPbPrToImage.h"

namespace lti {

  /**
   * Compute RGB values from given YUV values by merging float or ubyte values
   * to an rgbPixel, merging channels(floats) or channel8s(ubytes) to an Image
   *
   * In the literature, technical and scientific, there is often confusion
   * among the color spaces YUV, YPbPr and YPbPr.  Poynton in
   * http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html explains that
   * YUV is usually never correctly meant, because the color space normally
   * used for component digital video is the YCbCr (ITU-RS601 or CCIR-601).
   * Other devices use the YPbPr, but the "real" YUV is rarely employed.
   *
   * The LTI-Lib provides all three spaces:
   *
   * - YCbCr: lti::mergeYCbCrToImage used by IEEE 1394 FireWire cameras
   * - YPbPr: lti::mergeYPbPrToImage used by some WebCams
   * - YUV:   lti::mergeYUVToImage   did they really meant to use this?
   *
   * Here, the inverse transformation of lti::splitImageToYUV is followed
   *
   * \f[
   *   \begin{bmatrix}
   *     R \\
   *     G \\
   *     B
   *   \end{bmatrix}
   *   =
   *   M^{-1}
   *   \begin{bmatrix}
   *     Y \\
   *     U \\
   *     V
   *   \end{bmatrix}
   * \f]
   * where M is the matrix given in lti::splitImageToYUV.
   *
   * If you use \c ubyte values, then this functor is equivalent to
   * lti::mergeYPbPrToImage, as the U and V values have to be linearly mapped
   * to make use of the limited range from 0 to 255.
   *
   * @ingroup gColor
   */
  class mergeYUVToImage : public mergeImage {
  public:

    /**
     * constructor
     */
    mergeYUVToImage(void);

    
    /**
     * destructor
     */
    ~mergeYUVToImage();

    /**
     * return the name of this type
     */
    virtual const char* getTypeName() const;
      
    /**
     * copy data of "other" functor.
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    mergeYUVToImage& copy(const mergeYUVToImage& other);
    
    /**
     * alias for copy member
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    mergeYUVToImage& operator=(const mergeYUVToImage& other);

    /**
     * returns a pointer to a clone of the functor.
     */
    virtual functor* clone() const;

    /**
     * merge channels Y, U, V to an image
     * @param Y the Y channel, i.e. black&white
     * @param U the U channel, chromatic 
     * @param V the V channel, chromatic
     * @param img the image to be splitted
     */
    virtual bool apply(const matrix<float>& Y,
                       const matrix<float>& U,
                       const matrix<float>& V,
                       image& img) const;

    /**
     * merge  8-bit-channels Y, U, V to an image
     * @param Y the Y channel, i.e. black&white
     * @param U the U channel, chromatic 
     * @param V the V channel, chromatic
     * @param img the image to be splitted
     */
    virtual bool apply(const channel8& Y,
                       const channel8& U,
                       const channel8& V,
                       image& img) const;

    /**
     * merge the  values Y, U and V
     * to a pixel
     * @param Y the Y value, i.e. black&white
     * @param U the U  value, chromatic 
     * @param V the V value, chromatic 
     * @param pixel the merged pixel
     */
    inline virtual bool apply(const float& Y,
           const float& U,
           const float& V,
           rgbPixel& pixel) const;

    /**
     * merge the   8-bit-values Y, U and V
     * to a pixel
     * @param Y the Y value, i.e. black&white
     * @param U the U  value, chromatic 
     * @param V the V value, chromatic 
     * @param pixel the merged pixel
     */ 
    inline virtual bool apply(const ubyte& Y,
                              const ubyte& U,
                              const ubyte& V,
                              rgbPixel& pixel) const;

  protected:

    /**
     * Clip function
     *
     * Equivalent to min(255,max(0,val)) but maybe faster
     */
    inline ubyte clip(const int val) const;
  };

  //
  // -------------------------------------
  // Implementation of inline methods
  // -------------------------------------
  //

  inline ubyte mergeYUVToImage::clip(const int val) const {
    if (val>255) {
      return 255;
    }
    if (val<0) {
      return 0;
    }
    return static_cast<ubyte>(val);
  }

  // create rgbPixel (ubyte)  from YUV float values
  inline bool mergeYUVToImage::apply(const float& c1,
                                     const float& c2,
                                     const float& c3,
                                     rgbPixel& pixel) const {

    // The following coefficients are tuned to produce 0% of error of
    // RGB -> YUV -> RGB convertions.  Please DO NOT CHANGE!
    const float Y = 255.f*c1 + 0.5f;

    pixel.set(clip(static_cast<int>(Y + c3*290.67f)),
              clip(static_cast<int>(Y - c2*100.63f 
                                      - c3*148.06f)),
              clip(static_cast<int>(Y + c2*518.18f)),
              0);

    return true;
  }

  // merge 8-bit-values to create an rgbPixel
  inline bool mergeYUVToImage::apply(const ubyte& c1,
                                     const ubyte& c2,
                                     const ubyte& c3,
                                     rgbPixel& pixel) const {
    return mergeYPbPrToImage::convert(c1,c2,c3,pixel);
  }
}
#endif