ColourGradient.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 __COLOUR_GRADIENT_HH__
#define __COLOUR_GRADIENT_HH__

// STL
#include <vector>
#include <list>

// BIAS
#include <bias_config.h>
#include <Base/Debug/Error.hh>

namespace BIAS
{
  /**
   * @brief Represents a colour gradient.
   *
   * The ColourGradient is a function [0,1] -> YOUR_COLOUR_SPACE.
   *
   * The gradient will consist of at least two colours: one colour on the
   * "left" side (at position 0) and one on the "right" side (at position 1).
   * Intermediate colours can be added with AddColour().
   *
   * To get a linearly interpolated colour at a certain position call
   * GetColour().
   *
   * \ingroup g_utils
   * @author rwulff 04/2010
   */
  template <class StorageType>
  class BIASUtils_EXPORT ColourGradient
  {

  public:

    /**
     * @brief Different types of predefined color gradients that can be generated.
     *
     * Inspired by Matlab.
     */
    enum ColourGradientType
    {
      Gray,
      Cool,
      Hot,
      Bone,
      Jet
    };

    /**
     * @brief Default Constructor. Initialises with gray-scale gradient from
     *        black to white, assuming 3 channels and unsigned char.
     */
    ColourGradient();

    /**
     * @brief Constructor.
     *
     * @note Both colour vectors may not be empty and must have the same size.
     *
     * @param colourLeft
     *        the colour at position 0
     * @param colourRight
     *        the colour at position 1
     */
    ColourGradient(std::vector<StorageType> colourLeft,
                   std::vector<StorageType> colourRight);

    /**
     * Constructor that allows to generate from a predefined color map.
     * The color maximas are set to max e.g. blue is (0 0 max)
     */
    ColourGradient(ColourGradientType mapType, const StorageType max = 255);

    /**
     * @brief Adds a colour to this ColourGradient.
     *
     * If a colour already exists at the given pos, it is replaced by the new
     * value.
     *
     * @param pos
     *        the position where the new colour is to be set, must be in [0,1]
     * @param colour
     *        the new colour to set, must have the same size as the colours
     *        given to the constructor
     */
    void AddColour(float pos, const std::vector<StorageType> &colour);

    /**
     * @brief Convenience wrapper
     */
    void AddRGBColour(float pos,
                      const StorageType r,
                      const StorageType g,
                      const StorageType b);

    /**
     * @brief Returns the interpolated colour at a given position.
     *
     * The colour is interpolated linearly between the nearest colours that were
     * added before.
     *
     * @param pos
     *        the position for which the interpolated colour should be returned,
     *        must be in [0,1]
     * @param colour
     *        the returned interpolated colour
     */
    void GetColour(float pos, std::vector<StorageType> &colour);

  private:

    /**
     * struct to hold a single step of the colour gradient
     */
    template <class StructStorageType>
    struct GradientStep
    {
      float pos;
      std::vector<StructStorageType> colour;
    };

    // to ensure correct channel count
    unsigned int numChannels_;

    // sorted list of the colours
    std::list<GradientStep<StorageType> > gradientSteps_;

  }; // end of class
} // end of namespace

#endif // __COLOUR_GRADIENT_HH__