cvrRGBPixel.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998-2004
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 *
 *
 * This file is part of the Computer Vision and Robotics Library (CVR-Lib)
 *
 * The CVR-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the BSD License.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the authors nor the names of its contributors may be
 *    used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */



/**
 * \file   cvrRGBPixel.h
 *         Contains the basic template class to represent RGB pixels (without
 *         an alpha channel)
 * \author Pablo Alvarado
 * \date   01.11.2002
 *
 * $Id: cvrRGBPixel.h,v 1.8 2007/09/10 02:49:53 alvarado Exp $
 */

#ifndef _CVR_RGB_PIXEL_H_
#define _CVR_RGB_PIXEL_H_

#include "cvrAssert.h"
#include "cvrTypes.h"
#include "cvrTypeInfo.h"
#include "cvrIoHandler.h"

#include "cvrRGBAPixel.h"

#include <iosfwd>  // Remember: instead of <iostream> we can just include
                   // iosfwd as we only need the forward declaration of the
                   // stream!  This saves compilation times!

namespace cvr {

  /**
   * Color pixel representation in RGB color space.
   *
   * This is a more general type than cvr::rgbaPixel, which is used to
   * represent points in the RGB color space with arbitrary precision,
   * specified through the template type of the class.
   *
   * The types supported for T are byte, ubyte, int16, uint16, int32, uint32,
   * float and double.
   *
   * @ingroup gColor
   */
  template <typename T>
  class rgbPixel {
  public:
    /**
     * Anonymous union to provide efficient access through three different
     * mechanism to the pixel components.
     *
     * The order of the data in this union assumes little endianness.
     */
    union {
      /**
       * Anonymous union with the three channels
       */
       __extension__ struct {
        /**
         * Red channel
         */
        T red;

        /**
         * Green channel
         */
        T green;

        /**
         * Blue channel
         */
        T blue;
      };

      /**
       * The four values as array
       */
      T data[3];
    };

    /**
     * Used for the template-based interface for pixels as vectors.
     */
    typedef T value_type;

    /**
     * Return type of the size() member
     */
    typedef int size_type;

    /**
     * Default constructor
     *
     * The default constructor of the rgbPixel<T> does \b not
     * initialize anything, in order to allow the creation of uninitialized
     * images in a more efficient way.
     */
    rgbPixel();

    /**
     * RGB constructor
     * @param r value for the red component
     * @param g value for the green component
     * @param b value for the blue component
     */
    rgbPixel(const T r,const T g,const T b);

    /**
     * Copy constructor
     */
    rgbPixel(const rgbaPixel& other);

    /**
     * Copy constructor
     */
    template<class U>
    inline rgbPixel(const rgbPixel<U>& other);

    /**
     * Set the red, green, blue values for the pixel
     */
    template<class U>
    inline void set(const U r, const U g, const U blue);

    /**
     * Sets the red component to given value
     */
    inline void setRed(const T r);

    /**
     * Sets the green component to given value
     */
    inline void setGreen(const T g);

    /**
     * Sets the blue component to given value
     */
    inline void setBlue(const T b);

    /**
     * Get the three color components and write them in the given arguments
     */
    template<class U>
    inline void get(U& r,U& g,U& b) const;

    /**
     * Returns red component
     */
    inline const T& getRed() const;

    /**
     * Returns green component
     */
    inline const T& getGreen() const;

    /**
     * Returns blue component
     */
    inline const T& getBlue() const;

    /**
     * Returns red component
     */
    inline T& getRed();

    /**
     * Returns green component
     */
    inline T& getGreen();

    /**
     * Returns blue component
     */
    inline T& getBlue();

    /**
     * Used to simulate vector access.
     *
     * The correspondence between the elements of the vector and
     * the color components is at(0) for red, at(1) for green and
     * at(2) for blue.
     */
    inline T& at(const int x);

    /**
     * Used to simulate read-only vector access.
     *
     * The correspondence between the elements of the vector and
     * the color components still depents on the endianness of the
     * system, but is usually at(0) for red, at(1) for green and
     * at(2) for blue.
     */
    inline const T& at(const int x) const;

    /**
     * Used to simulate vector access.
     *
     * The correspondence between the elements of the vector and
     * the color components is [0] for red, [1] for green and
     * [2] for blue.
     */
    inline T& operator[](const int x);

    /**
     * Used to simulate read-only vector access.
     *
     * The correspondence between the elements of the vector and
     * the color components still depents on the endianness of the
     * system, but is usually [0] for red, [1] for green and
     * [2] for blue.
     */
    inline const T& operator[](const int x) const;

    /**
     * Used to simulate the vector size.
     *
     * It returns always 3.
     */
    inline size_type size() const;

    /**
     * Copy the "other" pixel
     */
    inline rgbPixel<T>& copy(const rgbPixel<T>& other);

    /**
     * Alias for copy
     */
    inline rgbPixel<T>& operator=(const rgbPixel<T>& other);

    /**
     * Copy the "other" pixel
     */
    inline rgbPixel<T>& copy(const rgbaPixel& other);

    /**
     * Alias for copy
     */
    inline rgbPixel<T>& operator=(const rgbaPixel& other);

    /**
     * Cast To an cvr::rgbaPixel.
     *
     * The alpha value of the rgbaPixel is always set to zero
     */
    inline void castTo(rgbaPixel& other) const;

    /**
     * Get a new cvr::rgbaPixel with the contents of this pixel.
     *
     * Just a static_cast of the attributes will be made and the alpha is set
     * to zero.  No clipping of the values is made in case of under or
     * overflow.
     */
    inline rgbaPixel getRGBAPixel() const;

    /**
     * Get a new cvr::rgbaPixel with the contents of this pixel.
     *
     * Just a static_cast of the attributes will be made and the alpha is set
     * to zero.  In case of under/overflow, the values are set to zero or 255.
     */
    inline rgbaPixel getClippedRGBAPixel() const;

    /**
     * Compare two pixels (true if equal!)
     *
     * Two pixels are \e equal if all \b four components (red, green,
     * blue, and \b alpha) are equal.  It is an usual error to leave the
     * alpha channel uninizalized and then compare for equalilty.
     */
    inline bool isEqual(const rgbPixel<T>& other) const;

    /**
     * Alias for compare()
     *
     * Two pixels are \e equal if all \b four components (red, green,
     * blue, and \b alpha) are equal.  It is an usual error to leave the
     * alpha channel uninizalized and then compare for equalilty.
     */
    inline bool operator==(const rgbPixel<T>& other) const;

    /**
     * Alias for !compare()
     *
     * Two pixels are \e equal if all \b four components (red, green,
     * blue, and \b alpha) are equal.  It is an usual error to leave the
     * alpha channel uninizalized and then compare for equalilty.
     */
    inline bool operator!=(const rgbPixel<T>& other) const;

    /**
     * Less than operator.
     *
     * An rgbPixel<T> is said to be "smaller" than another one, if
     * its red component its smaller, or (if both red components are
     * equal) if the green component if smaller, or (if both green components
     * are equal) if the blue component is smaller.
     */
    inline bool operator<(const rgbPixel<T>& other) const;

    /**
     * Greater than operator.
     *
     * An rgbPixel<T> is said to be "greater" than another one, if
     * its red component its greater, or (if both red components are
     * equal) if the green component if greater, or (if both green components
     * are equal) if the blue component is greater.
     */
    inline bool operator>(const rgbPixel<T>& other) const;

    /**
     * Add this pixel with another one.
     *
     * The alpha channel is kept unchanged.
     */
    inline rgbPixel<T>& add(const rgbPixel<T>& other);

    /**
     * Add this pixel with another one.
     *
     * The alpha channel is kept unchanged.
     */
    inline rgbPixel<T>& operator+=(const rgbPixel<T>& other);

    /**
     * Add this pixel with the other one without altering anything.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator+(const rgbPixel<T>& other) const;

    /**
     * Subtract 'other' from this pixel.
     *
     * The alpha channel is kept unchanged.
     */
    inline rgbPixel<T>& subtract(const rgbPixel<T>& other);

    /**
     * Subtract 'other' from this pixel.
     *
     * The alpha channel is kept unchanged.
     */
    inline rgbPixel<T>& operator-=(const rgbPixel<T>& other);

    /**
     * Subtract 'other' from this pixel without altering anything.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator-(const rgbPixel<T>& other) const;

    /**
     * Multiply this pixel with another one.
     *
     * The pixel multiplication multiplies elementwise the elements of
     * the pixel, except the alpha channel, which is kept unchanged.
     */
    inline rgbPixel<T>& multiply(const rgbPixel<T>& other);

    /**
     * Multiply this pixel with another one.
     *
     * The pixel multiplication multiplies elementwise the elements of
     * the pixel, except the alpha channel, which is kept unchanged.
     */
    inline rgbPixel<T>& operator*=(const rgbPixel<T>& other);

    /**
     * Multiply this pixel with another one without altering anything.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator*(const rgbPixel<T>& other) const;

    /**
     * Multiply all components of this pixel with an integer, except the alpha
     * channel, which is kept unchanged.
     */
    inline rgbPixel<T>& multiply(const int other);

    /**
     * Multiply all components of this pixel with a float, except the alpha
     * channel, which is kept unchanged.
     */
    inline rgbPixel<T>& multiply(const float& other);

    /**
     * Multiply all components of this pixel with a float, except the alpha
     * channel, which is kept unchanged.
     */
    inline rgbPixel<T>& multiply(const double& other);

    /**
     * Multiply all components of this pixel with a an integer, except the
     * alpha channel, which is kept unchanged.
     */
    inline rgbPixel<T>& operator*=(const int other);

    /**
     * Multiply all components of this pixel with a a float, except the
     * alpha channel, which is kept unchanged.
     */
    inline rgbPixel<T>& operator*=(const float& other);

    /**
     * Multiply all components of this pixel with a a double, except the
     * alpha channel, which is kept unchanged.
     */
    inline rgbPixel<T>& operator*=(const double& other);

    /**
     * Multiply all components of this pixel with a an integer, except the
     * alpha channel.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator*(const int other) const;

    /**
     * Multiply all components of this pixel with a a float, except the
     * alpha channel.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator*(const float& other) const;

    /**
     * Multiply all components of this pixel with a a double, except the
     * alpha channel.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator*(const double& other) const;

    /**
     * Divide this pixel with another one.
     *
     * The pixel division divides elementwise the elements of the pixel
     * except the alpha channel, which is kept unchanged.
     */
    inline rgbPixel<T>& divide(const rgbPixel<T>& other);

    /**
     * Divide this pixel with another one.
     *
     * The pixel division divides elementwise the elements of the pixel
     * except the alpha channel, which is kept unchanged.
     */
    inline rgbPixel<T>& operator/=(const rgbPixel<T>& other);

    /**
     * Divide this pixel with another one.
     *
     * The pixel division divides elementwise the elements of the pixel
     * except the alpha channel.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator/(const rgbPixel<T>& other) const;

    /**
     * Divide all components of this pixel with an integer.
     */
    inline rgbPixel<T>& divide(const int other);

    /**
     * Divide all components of this pixel with an integer.
     */
    inline rgbPixel<T>& divide(const float& other);

    /**
     * Divide all components of this pixel with an integer.
     */
    inline rgbPixel<T>& divide(const double& other);

    /**
     * Divide all components of this pixel with an integer.
     */
    inline rgbPixel<T>& operator/=(const int other);

    /**
     * Divide all components of this pixel with an integer.
     */
    inline rgbPixel<T>& operator/=(const float& other);

    /**
     * Divide all components of this pixel with an integer.
     */
    inline rgbPixel<T>& operator/=(const double& other);

    /**
     * Divide all components of this pixel with an integer without altering
     * anything.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator/(const int other) const;

    /**
     * Divide all components of this pixel with an integer without altering
     * anything.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator/(const float& other) const;

    /**
     * Divide all components of this pixel with an integer without altering
     * anything.
     *
     * The alpha channel of the resulting pixel is equal to
     * the one of this pixel (the first operand in the binary expression)
     */
    inline rgbPixel<T> operator/(const double& other) const;

   /**
    * Compute the square of the magnitud of this pixel
    * \f$red^2+green^2+blue^2\f$.
    */
    inline typename typeInfo<T>::square_accumulation_type absSqr() const;

   /**
    * Scalar product in the 3D RGB color space.
    *
    * Get the scalar product of this pixel with another one, considering
    * them as a 3D point in the RGB color space.
    *
    * The dot product will be the sum of the
    * red*other.red + green*other.green + blue*other.blue
    */
    inline typename typeInfo<T>::square_accumulation_type
    dot(const rgbPixel<T>& other) const;

    /**
     * Square of the distance between this pixel and the other one.
     *
     * \f$(red-other.red)^2+(green-other.green)^2+(blue-other.blue)^2\f$.
     */
    inline typename typeInfo<T>::square_accumulation_type
    distanceSqr(const rgbPixel<T>& other) const;
  };

  /**
   * Multiply all components of the given pixel with an integer
   * except the alpha channel.
   */
  template <typename T>
  inline rgbPixel<T> operator*(const int p,const rgbPixel<T>& other);

  /**
   * Multiply all components of the given pixel with an integer
   * except the alpha channel.
   */
  template <typename T>
  inline rgbPixel<T> operator*(const float p,const rgbPixel<T>& other);

  /**
   * Multiply all components of the given pixel with an integer
   * except the alpha channel.
   */
  template <typename T>
  inline rgbPixel<T> operator*(const double& p,const rgbPixel<T>& other);

  /**
   * Read the vector from the given ioHandler.
   *
   * The complete flag indicates if the enclosing begin and end should be also
   * be readed
   *
   * @ingroup gStorable
   */
  template <typename T>
  bool read(ioHandler& handler,rgbPixel<T>& p,const bool complete=true);

  /**
   * Write the vector in the given ioHandler.
   *
   * The complete flag indicates if the enclosing begin and end should be also
   * be written or not
   *
   * @ingroup gStorable
   */
  template <typename T>
  bool write(ioHandler& handler,const rgbPixel<T>& p,const bool complete=true);

  /**
   * Alias for rgbPixel<int>
   */
  typedef rgbPixel<int> irgbPixel;

  /**
   * Alias for rgbPixel<float>
   */
  typedef rgbPixel<float> frgbPixel;

  /**
   * Alias for rgbPixel<double>
   */
  typedef rgbPixel<double> drgbPixel;
}

namespace std {
  template <typename T>
  ostream& operator<<(ostream& s,const cvr::rgbPixel<T>& p);

  template <typename T>
  istream& operator>>(istream& s,cvr::rgbPixel<T>& p);
}

#include "cvrRGBPixel_inline.h"

#endif