cvrChannel.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998-2005
 * 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   cvrChannel.h
 *         Contains the data structure to represent gray valued images
 *         with one float per pixel.
 * \author Pablo Alvarado
 * \date   09.04.1999
 *
 * $Id: cvrChannel.h,v 1.9 2007/04/05 22:55:43 alvarado Exp $
 */

#ifndef _CVR_CHANNEL_H_
#define _CVR_CHANNEL_H_

#include "cvrMatrix.h"
#include "cvrTypes.h"

namespace cvr {
  class channel8;
  class image;

  /**
   * A format for float channels.
   *
   * This class is identical to a matrix of floats except for the method
   * castFrom(channel8).
   *
   * The typical value range is between 0.0f and 1.0f (see cvr::image for more
   * information).
   *
   * @see cvr::image, cvr::channel8
   *
   * @ingroup gAggregate
   * @ingroup gImageProcessing
   */
  class channel : public matrix<float> {
  public:

    /**
     * Default constructor creates an empty channel
     */
    channel();

    /**
     * Create a connected \c rows x \c cols channel and leave the data
     * uninitialized.
     *
     * @param rows number of rows of the channel
     * @param cols number of columns of the channel
     */
    channel(const int rows,const int cols);

    /**
     * Create a connected \c size.y x \c size.x channel and initializes
     * all elements with \a iniValue
     *
     * @param size cvr::ipoint with the size of the channel
     *             (size.x is the number of columns and
     *              size.y the number of rows)
     */
    channel(const ipoint& size);

    /**
     * Create a connected \c rows x \c cols channel
     * and initializes all elements with \a iniValue
     *
     * @param rows number of rows of the channel
     * @param cols number of columns of the channel
     * @param iniValue all elements will be initialized with this value
     */
    channel(const int rows,const int cols,const float& iniValue);

    /**
     * Create a connected \c size.y x \c size.x channel and initializes
     * all elements with \a iniValue
     *
     * @param size cvr::ipoint with the size of the channel
     *             (size.x is the number of columns and
     *              size.y the number of rows)
     * @param iniValue all elements will be initialized with this value
     */
    channel(const ipoint& size,const float& iniValue);

    /**
     * Create a connected \c rows x \c cols channel and initializes all
     * elements with the data ipointed by \a data.  The first
     * \a cols-elements of the data will be copied on the first row,
     * the next ones on the second row and so on.
     *
     * @param rows number of rows of the channel
     * @param cols number of columns of the channel
     * @param data pointer to the memory block with the data to be initialized
     * with.
     */
    channel(const int rows,const int cols,const float data[]);

    /**
     * Copy constructor.
     *
     * Create a window from another channel.
     *
     * @param other   the channel to be copied.
     * @param fromRow initial row of the other channel to be copied
     * @param fromCol initial column of the other channel to be copied
     * @param toRow   last row to be copied of the other channel
     * @param toCol   last column to be copied of the other channel
     *
     * Example:
     * \code
     * cvr::channel m(4,6,0); // channel with 24 elements
     * // ...
     * // initialize channel with:
     * //        0  1  2  3  4  5
     * //        2  1  5  4  0  3
     * //        1  2  1  2  3  2
     * //        3  3  2  1  2  3
     *
     * cvr::channel sm(m,1,3,0,2)  // this line will lead to the
     * //                             following contents for sm:
     * //        1  2  3
     * //        1  5  4
     * //        2  1  2
     * \endcode
     *
     */
    channel(const channel& other,
            const int fromRow,
            const int fromCol=0,
            const int toRow=MaxIndex,
            const int toCol=MaxIndex);

    /**
     * Copy constructor.
     */
    channel(const channel& other);

    /**
     * Copy constructor.
     *
     * Create a window from another channel.
     *
     * @param other   the channel to be copied.
     * @param from    initial coordinates of the window.
     * @param to      final coordinates of the window.
     */
    channel(const channel& other,
            const ipoint& from,
            const ipoint& to);

    /**
     * Returns the name of this type.
     */
    virtual const std::string& name() const;

    /**
     * Create a clone of this channel
     * @return a pointer to a copy of this matrix
     */
    virtual channel* clone() const;

    /**
     * Create a new empty channel
     * @return a pointer to new channel
     */
    virtual channel* newInstance() const;

    /**
     * Copy the \a other channel8 by casting each of its elements.
     *
     * The elements of the channel8 will be also multiplied by 1/255.
     *
     * @param other the channel8 to be casted
     * @return a reference to this channel
     *
     * Example:
     * \code
     *   cvr::channel8 matA(10,10,255); // a channel8
     *   cvr::channel  matB;            // a channel
     *
     *   matB.castFrom(matA);         // this will copy matA in matB!!
     *                                // and all elements will have 1.0f
     * \endcode
     */
    channel& castFrom(const channel8& other);

    /**
     * Cast the image to an channel.
     * It extracts the intensity channel of the image, defined as
     * (R+G+B)/3, where R, G, and B are the red, green and blue components
     * of the pixel.
     *
     * The elements of the resulting channel will be between 0.0f (black) and
     * 1.0f (white).
     *
     * @param other the image to be casted
     * @return a reference to this channel
     */
    channel& castFrom(const image& other);

    /**
     * Copy the \a other matrix by casting each of its elements
     * @param other The matrix to be casted
     * @return a reference to this channel
     */
    template<typename U>
    inline channel& castFrom(const matrix<U>& other);

    /**
     * Apply a gray valued transformation which maps the given intervall to
     * [0.0,1.0] (default) or the explicitly given "destination" interval
     *
     * @param minVal the lower limit of the original data interval
     * @param maxVal the higher limit of the original data interval
     * @param minDest the lower limit of the mapped interval (default 0.0f)
     * @param maxDest the higher limit of the mapped interval (default 1.0f)
     * @return a reference to this object
     *
     * For example, if you want to map the interval [-1.0f,2.0f] to
     * the "usual" interval [0.0,1.0] just use one of following methods:
     *
     * \code
     * cvr::channel chnl;
     * // ...
     * chnl.mapLinear(-1.0f,2.0f,0.0,1.0); // map [-1,2] to  [0,1]
     * // this is equivalent to (due to default "destination" interval)
     * chnl.mapLinear(-1.0f,2.0f);
     * \endcode
     *
     * Not that you can use this method to "invert" your gray values with
     * \code
     * chnl.mapLinear(0.0f,1.0f,1,0f,0.0f); // map [0,1] to  [1,0]
     * // this is equivalent to (due to default "destination" interval)
     * chnl.mapLinear(1.0f,0.0f);
     * \endcode
     *
     */
    channel& mapLinear(const float& minVal, const float& maxVal,
                       const float& minDest=0.0f, const float& maxDest=1.0f);


    /**
     * Apply a gray valued transformation which maps the given
     * intervall of the other channel into [0.0,1.0] (default) or the
     * explicitly given "destination" interval in this channel.
     *
     * @param other the other channel which values are to be mapped into
     *              the new interval
     * @param minVal the lower limit of the original data interval
     * @param maxVal the higher limit of the original data interval
     * @param minDest the lower limit of the mapped interval (default 0.0f)
     * @param maxDest the higher limit of the mapped interval (default 1.0f)
     * @return a reference to this object
     *
     * For example, if you want to map the interval [-1.0f,2.0f] to
     * the "usual" interval [0.0,1.0] just use one of following methods:
     *
     * \code
     * cvr::channel chnl;
     * // ...
     * chnl.mapLinear(-1.0f,2.0f,0.0,1.0); // map [-1,2] to  [0,1]
     * // this is equivalent to (due to default "destination" interval)
     * chnl.mapLinear(-1.0f,2.0f);
     * \endcode
     *
     * Not that you can use this method to "invert" your gray values with
     * \code
     * chnl.mapLinear(0.0f,1.0f,1,0f,0.0f); // map [0,1] to  [1,0]
     * // this is equivalent to (due to default "destination" interval)
     * chnl.mapLinear(1.0f,0.0f);
     * \endcode
     *
     */
    template<typename U>
    channel& mapLinear(const matrix<U>& other,
                       const U& minVal, const U& maxVal,
                       const float& minDest=0.0f, const float& maxDest=1.0f);

  };

  template<class U>
  channel& channel::castFrom(const matrix<U>& other) {
    matrix<value_type>::castFrom(other);
    return *this;
  }

  /*
   * Apply a gray valued transformation which maps the given intervall to
   * [0.0,1.0] (default) or the explicitly given "destination" interval
   * @param minVal the lower limit of the original data interval
   * @param maxVal the higher limit of the original data interval
   * @param minDest the lower limit of the mapped interval (default 0.0f)
   * @param maxDest the higher limit of the mapped interval (default 1.0f)
   * @return a reference to this object
   */
  template<class U>
  channel& channel::mapLinear(const matrix<U>& other,
                              const U& minVal, const U& maxVal,
                              const float& minDest,const float& maxDest) {

    allocate(other.size());

    iterator it;
    typename vector<U>::const_iterator cit,eit;
    int y;

    float tm,tb;

    if (maxVal != minVal) {
      tm = (maxDest-minDest)/static_cast<float>(maxVal-minVal);
    } else {
      tm = 1.0f;
    }

    tb = maxDest-maxVal*tm;

    const float m=tm;
    const float b=tb;

    // check possible speed improvements (unnecessary computations avoided)

    if (b == 0.0f) {
      for (y=0,it=begin();y<other.rows();++y) {
        const vector<U>& vct=other.getRow(y);
        for (cit=vct.begin(),eit=vct.end();cit!=eit;++cit,++it) {
          (*it)=static_cast<float>((*cit)*m);
        }
      }
    } else if (m == 1.0f) {
      for (y=0,it=begin();y<other.rows();++y) {
        const vector<U>& vct=other.getRow(y);
        for (cit=vct.begin(),eit=vct.end();cit!=eit;++cit,++it) {
          (*it)=static_cast<float>((*cit)+b);
        }
      }
    } else {
      for (y=0,it=begin();y<other.rows();++y) {
        const vector<U>& vct=other.getRow(y);
        for (cit=vct.begin(),eit=vct.end();cit!=eit;++cit,++it) {
          (*it)=static_cast<float>((*cit)*m+b);
        }
      }
    }
    return (*this);
  }



}

#endif