ltiMergeYPbPrToImage.h

/*
 * Copyright (C) 2003, 2004, 2005, 2006, 2007
 * Department of Electronics, ITCR, Costa Rica
 * 
 * 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.  
 */ 

 
/*--------------------------------------------------------------------
 * project ....: LTI-Lib: Image Processing and Computer Vision Library
 * file .......: ltiMergeYPbPrToImage.h
 * authors ....: Pablo Alvarado
 * organization: Department of Electronics, ITCR
 * creation ...: 04.01.2007
 * revisions ..: $Id: ltiMergeYPbPrToImage.h,v 1.3 2007/01/10 02:25:58 alvarado Exp $
 */

#ifndef _LTI_MERGE_Y_Pb_Pr_TO_IMAGE_H_
#define _LTI_MERGE_Y_Pb_Pr_TO_IMAGE_H_

#include "ltiMergeImage.h"

namespace lti {

  /**
   * Creates RGB values from given YPbPr 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::splitImageToYPbPr is followed:
   *
   * \f[
   *   \begin{bmatrix}
   *     R \\
   *     G \\
   *     B
   *   \end{bmatrix}
   *   =
   *   M^{-1}
   *   \begin{bmatrix}
   *     Y \\
   *     Pb \\
   *     Pr
   *   \end{bmatrix}
   * \f]
   * where M is the matrix given in lti::splitImageToYPbPr.
   *
   * If you know you have a YPbPr space but it was given to you as
   * YUV, then the equivalences are U=Pb and V=Pr.
   *
   * A way of noticing if you have a YPbPr color space is determining the range
   * of the values of each channel.  Y should be in [0,1], while Pr and Pb
   * should be in [-0.5,0.5].
   *
   * @ingroup gColor
   */
  class mergeYPbPrToImage : public mergeImage {
  public:

    /**
     * Constructor
     */
    mergeYPbPrToImage(void);

    
    /**
     * Destructor
     */
    ~mergeYPbPrToImage();

    /**
     * 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
     */
    mergeYPbPrToImage& copy(const mergeYPbPrToImage& other);
    
    /**
     * Alias for copy method.
     *
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    mergeYPbPrToImage& operator=(const mergeYPbPrToImage& other);

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

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

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

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

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

    /*
     * Merge the   8-bit-values Y, Pb and Pr to a pixel.
     *
     * This is a static method to do the conversion.  It is required by
     * other functors which need a fast access to the conversion without
     * requiring an instance.
     *
     * \waring Be careful while using this method, since its static nature
     * makes you responsible for the previous initialization of the LUTs.  For
     * that matter, just make sure that any instance of mergeYPbPrToImage is
     * created before calling this method.
     *
     * @param Y the Y value, i.e. black&white
     * @param Pb the Pb  value, chromatic 
     * @param Pr the Pr value, chromatic 
     * @param pixel the merged pixel
     */ 
    static bool convert(const ubyte& Y,
                        const ubyte& Pb,
                        const ubyte& Pr,
                        rgbPixel& pixel);
    
  protected:

    /**
     * Initialize the Look-Up-Tables
     */
    virtual void initializeLUTs();

    /**
     * Look up tables to accelerate conversion YPbPr -> RGB
     */
    //@{
    /**
     * Partial Y results
     */
    static const int* lutY;

    /**
     * Partial results with Pr (equivalent to V) for the red channel
     * computation.
     */
    static const int* lutVr;

    /**
     * Partial results with Pb (equivalent to U) for the green channel
     * computation.
     */
    static const int* lutUg;

    /**
     * Partial results with Pr (equivalent to V) for the green channel
     * computation.
     */
    static const int* lutVg;

    /**
     * Partial results with Pb (equivalent to U) for the blue channel
     * computation.
     */
    static const int* lutUb;
    //@}

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

  };

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

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

  // create rgbPixel (ubyte)  from YUV float values
  inline bool mergeYPbPrToImage::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 -> YPbPr -> RGB convertions.  Please DO NOT CHANGE!
    const float Y = c1*255.f + 0.5f;

    pixel.set(clip(static_cast<int>(Y + c3*357.509895107622f)),
              clip(static_cast<int>(Y - c2* 87.7545979321608f 
                                      - c3*182.104719673362f)),
              clip(static_cast<int>(Y + c2*451.860016848823f)),
              0);

    return true;
  }

  // merge 8-bit-values to create an rgbPixel
  inline bool mergeYPbPrToImage::convert(const ubyte& c1,
                                         const ubyte& c2,
                                         const ubyte& c3,
                                         rgbPixel& pixel) {

    // The following coefficients are tuned to produce the smallest possible
    // error of RGB -> YPbPr -> RGB convertions.  Please DO NOT CHANGE! 
   
    // The error cannot be further reduced as the ubyte precision looses many
    // information when converting RGB->YPbPr.  With the given coefficients
    // 3999903 values of all 2^24 available were perfectly retrieved (31.3%),
    // an the mean deviation error is 0.761 (RGB color space L2 distance).

    // The 32768 is half the 16 bit precision and is added to force a correct
    // rounding.
    
    // The next lines are 100% equivalent to this, but using LUT, which
    // requires approximatelly 85% of the direct computation time.
    //
    //     const int Y =  static_cast<int>(c1)*65536 + 32768;
    //     const int U = (static_cast<int>(c2)-128);
    //     const int V = (static_cast<int>(c3)-128);
    
    //     pixel.set(clip((Y              +  91881 * V)>>16),
    //               clip((Y -  22553 * U -  46802 * V)>>16),
    //               clip((Y + 116130 * U             )>>16),
    //               0);

    const int Y = lutY[c1];
    pixel.set(clip( (Y             + lutVr[c3])>>16),
              clip( (Y + lutUg[c2] + lutVg[c3])>>16),
              clip( (Y + lutUb[c2]            )>>16),
              0);

    return true;
  }

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