cvrChannel8.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   cvrChannel8.h
 *         Contains the data structure to represent gray valued images
 *         with one byte per pixel.
 * \author Pablo Alvarado
 * \date   09.04.1999
 *
 * $Id: cvrChannel8.h,v 1.7 2006/06/13 09:25:38 doerfler Exp $
 */

#ifndef _CVR_CHANNEL8_H_
#define _CVR_CHANNEL8_H_

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

namespace cvr {

  class channel;
  class image;

  /**
   * A format for 8-bit channels.
   *
   * This class is identical to a matrix of bytes except for the method
   * castFrom(channel)
   *
   * The typical value range is between 0 and 255 (see cvr::image for more
   * information).
   *
   * @see cvr::image, cvr::channel
   *
   * @ingroup gAggregate
   * @ingroup gImageProcessing
   */
  class channel8 : public matrix<ubyte> {
  public:
    /**
     * Default constructor creates an empty channel8
     */
    channel8();

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

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

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

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

    /**
     * Create a connected \c rows x \c cols Channel8 and initializes
     * all elements with the data pointed 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 channel8
     * @param cols number of columns of the channel8
     * @param data pointer to the memory block with the data to be initialized
     *             with.
     */
    channel8(const int rows,const int cols,const ubyte data[]);

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

    /**
     * Copy constructor.
     *
     * Create this channel8 as a connected copy of a submatrix of another
     * channel8.
     */
    channel8(const channel8& other,
             const ipoint& from,
             const ipoint& to);

    /**
     * Copy constructor.
     *
     * Create this channel8 as a connected copy of another channel8
     * for this const version, the data will be always copied!
     * It is also possible to create a copy of a subchannel of another
     * channel.
     *
     * @param other the channel8 to be copied.
     * @param fromRow initial row of the other channel8 to be copied
     * @param fromCol initial column of the other channel8 to be copied
     * @param toRow   last row to be copied of the other channel8
     * @param toCol   last column to be copied of the other channel8
     *
     * Example:
     * \code
     * cvr::channel8 m(4,6,0); // channel8 with 24 elements
     * // ...
     * // initialize channel8 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::channel8 sm(m,1,3,0,2)  // last line will leat to
     * //                              following contents in sm:
     * //        1  2  3
     * //        1  5  4
     * //        2  1  2
     * \endcode
     *
     */
    channel8(const channel8& other,
             const int fromRow,
             const int fromCol=0,
             const int toRow=MaxIndex,
             const int toCol=MaxIndex);

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

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

    /**
     * Create a new empty channel8
     * @return a pointer to a copy of this matrix
     */
    virtual channel8* newInstance() const;

    /**
     * Compute the sum of all elements in the channel
     */
    int computeSumOfElements() const;

    /**
     * Copy the \a other channel by casting each of its elements.
     *
     * The elements of the channel will be multiplied by 255 if no
     * other %parameter but the channel is given..
     *
     * @param other the channel to be cast from
     *
     * @param minToBlack if minToBlack is true, a linear gray-valued
     * tranformation will be applied, which maps the minimal value in
     * the channel to zero.  If false, the value zero will be mapped
     * to zero.
     *
     * @param maxToWhite if maxToWhite is true, a linear gray-valued
     * transformation will be applied, which maps the maximal value in
     * the channel to 255.  If false, the value 1.0f will be mapped to
     * 255.
     *
     * @return a reference to this channel
     * Example:
     * \code
     *   cvr::channel matA(10,10,1); // a channel
     *   cvr::channel8  matB;          // a channel8
     *
     *   matB.castFrom(matA);         // this will copy matA in matB!!
     *                                // and all elements will have 255
     * \endcode */
    channel8& castFrom(const channel& other,
                       const bool minToBlack = false,
                       const bool maxToWhite = false);

    /**
     * Cast the image to an channel8.
     *
     * 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 (black) and
     * 255 (white).
     *
     * @param other the image to be cast
     * @return a reference to this channel
     */
    channel8& castFrom(const image& other);

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

    /**
     * Apply a gray valued transformation which maps the given intervall to
     * [0,255] (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)
     * @param maxDest the higher limit of the mapped interval (default 255)
     * @return a reference to this object
     *
     * For example, if you want to map the interval [20,200] to
     * the "usual" interval [0,255] just use one of following methods:
     *
     * \code
     * cvr::channel8 chnl;
     * // ...
     * chnl.mapLinear(20,200,0,255); // map [20,200] to  [0,255]
     * // this is equivalent to (due to default "destination" interval)
     * chnl.mapLinear(20,200);
     * \endcode
     *
     * Not that you can use this method to "invert" your gray values with
     * \code
     * chnl.mapLinear(0,255,255,0); // map [0,255] to  [255,0]
     * // this is equivalent to (due to default "destination" interval)
     * chnl.mapLinear(255,0);
     * \endcode
     *
     */
    channel8& mapLinear(const ubyte& minVal, const ubyte& maxVal,
                        const ubyte& minDest=0, const ubyte& maxDest=255);
  };

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

}


#endif