cvrKernel2D.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   cvrKernel2D.h
 *         Contains the template class cvr::kernel1D<T>.
 * \author Pablo Alvarado
 * \date   06.04.08
 *
 * revisions ..: $Id: cvrKernel1D.h,v 1.7 2007/10/14 20:20:00 alvarado Exp $
 */

#ifndef _CVR_KERNEL_2_D_H_
#define _CVR_KERNEL_2_D_H_

#include "cvrLattice2D.h"
#include "cvrTypes.h"
#include "cvrMatrix.h"
#include "cvrTypeInfo.h"

namespace cvr {

  /**
   * Two-dimensional filter kernel
   *
   * The template type of this class should coincide with the template
   * class of the matrix to be convolved with.  For example, if you want
   * to convolve a kernel2D with a matrix<double>, you will need a
   * kernel2D<double> (@see cvr::convolution).
   *
   * If you instantiate a kernel2D of a fixed point type, like
   * kernel2D<int> or kernel2D<ubyte>, you also need to consider the
   * "norm" of the kernel (see cvr::kernel2D<T>::getNorm() and
   * cvr::kernel2D<T>::setNorm(const T&)). This "norm" allows the
   * representation of numbers less than 1.0.  You can see this norm as the
   * value to be considered as 1.0, when operating with the kernel.
   * For example, if you have a kernel2D<ubyte> with the values [64,128,64]
   * and norm=255, the the interpreted values during convolution will be
   * [0.25,0.5,0.25].  With floating-point types, the norm will be always
   * assumed to be 1.0.  For other types the default norms are the following:
   *
   * For int:              65536
   * For ubyte:              255
   * Otherwise:                1.0
   *
   * @see cvr::convolution
   */
  template<class T>
  class kernel2D : public lattice2D<T> {
  public:
    /**
     * \name Internal types and classes
     */
    //@{

    /**
     * Type of the lattice2D elements.
     */
    typedef typename lattice2D<T>::value_type value_type;

    /**
     * Return type of the size() member
     */
    typedef typename lattice2D<T>::size_type size_type;

    /**
     * Pointer to value_type
     */
    typedef typename lattice2D<T>::pointer pointer;

    /**
     * Const pointer to value_type
     */
    typedef typename lattice2D<T>::const_pointer const_pointer;
    
    /**
     * Reference to value_type
     */
    typedef typename lattice2D<T>::reference reference;

    /**
     * Const reference to value_type
     */
    typedef typename lattice2D<T>::const_reference const_reference;

    /**
     * \c iterator type (allows read and write operations).
     *
     * The use of the iterator classes is similar to the iterators of the STL
     * (Standard Template Library). See cvr::lattice2D::begin() and
     * cvr::lattice2D::inverseBegin() for examples.
     *
     * For the debugging version of the iterators, boundary check will be
     * done!  This explains the low speed of the iterators of the debug
     * version.  In the release version, no boundary check will be done,
     * and the iterators are sometimes a factor 10 faster than the
     * debug iterators.
     *
     * The use of the access operator at() is faster than the iterators in the
     * debug version only.  If you need to iterate on a lattice2D use
     * iterators instead (in the release version iterators are approximately a
     * factor 3 faster than at()).
     *
     * \warning Try to use the prefix incremental operator (i.e. ++it) instead
     * of the postfix operator (i.e. it++) to allow efficient code also in
     * debug-modus!
     *
     * @see lattice2D<T>::const_iterator
     */
    typedef typename lattice2D<T>::iterator iterator;

    /**
     * \c const_iterator type (allows read-only operations).
     *
     * The use of the iterator classes is similar to the iterators of the STL
     * (Standard Template Library). See cvr::lattice2D::begin() for an
     * example.
     *
     * For the debugging version of the iterators, boundary check will be
     * done!  This explains the low speed of the iterators of the debug
     * version.  In the release version, no boundary check will be done, and
     * the iterators are sometimes a factor 10 faster than the debug
     * iterators.
     *
     * The use of the access operator at() is faster than the iterators in the
     * debug version only.  If you need to iterate on a lattice2D use
     * iterators instead (in the release version iterators are approximately a
     * factor 3 faster than at()).
     *
     * \warning Try to use the prefix incremental operator (i.e. ++it) instead
     * of the postfix operator (i.e. it++) to allow efficient code also in
     * debug-modus!
     *
     * @see lattice2D<T>::iterator
     */
    typedef typename lattice2D<T>::const_iterator const_iterator;
    //@}

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

    /**
     * Create a kernel2D with uninitialized elements.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     */
    kernel2D(const int fromRow,
             const int fromCol,
             const int toRow,
             const int toCol);
    
    /**
     * Create a \a rows x \a cols kernel2D with uninitialized elements.
     *
     * @param from lowest index
     * @param to   highest index (inclusive)
     */
    kernel2D(const size_type& from,
             const size_type& to);

    /**
     * Create a kernel2D with uninitialized elements.
     *
     * @param rows interval used for the rows
     * @param columns interval used for the columns
     */
    kernel2D(const iinterval& rows,
             const iinterval& columns);

    /**
     * Create a kernel2D and initialize all elements with the given
     * value.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     * @param value value used for initializing the elements
     */
    kernel2D(const int fromRow,
             const int fromCol,
             const int toRow,
             const int toCol,
             const T& value);
    
    /**
     * Create a kernel2D and initialize all elements with the given
     * value.
     *
     * @param from lowest index
     * @param to   highest index (inclusive)
     * @param value value used for initializing the elements
     */
    kernel2D(const size_type& from,
             const size_type& to,
             const T& value);
    
    /**
     * Create a kernel2D and initialize all elements with the given
     * value.
     *
     * @param rows interval used for the rows
     * @param columns interval used for the columns
     * @param value value used for initializing the elements
     */
    kernel2D(const iinterval& rows,
             const iinterval& columns,
             const T& value);
    
    /**
     * Create a kernel2D and initialize all elements with the data
     * pointed by \a data.
     *
     * The first elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *             with.
     */
    kernel2D(const int fromRow,
             const int fromCol,
             const int toRow,
             const int toCol,
             const T data[]);
    
    /**
     * Create a kernel2D and initialize all elements with the data
     * pointed by \a data.
     *
     * The first elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param from lowest index
     * @param to   highest index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *             with.
     */
    kernel2D(const size_type& from,
             const size_type& to,
             const T data[]);
    
    /**
     * Create a kernel2D and initialize all elements with the data
     * pointed by \a data.
     *
     * The first elements of the data will be \b copied on the
     * first row, the next ones on the second row and so on.
     *
     * @param rows interval used for the rows
     * @param columns interval used for the columns
     * @param data pointer to the memory block with the data to be initialized
     *             with.
     */
    kernel2D(const iinterval& rows,
             const iinterval& columns,
             const T data[]);
    
    /**
     * Create a kernel2D and use the given \a data as if it was given
     * through the useExternData().
     *
     * @see useExternData()
     *
     * The first elements of the data will be copied on the first row, the next
     * ones on the second row and so on.
     *
     * \note Please observe that the last argument makes a huge difference to
     * the constructors that do not have it.  Here the data is \b not copied,
     * just a reference is kept.  Without the last argument, the data is
     * always copied.
     *
     * @param fromRow lowest row index
     * @param fromCol lowest column index
     * @param toRow highest row index (inclusive)
     * @param toCol highest column index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this value to be ConstantReference.
     */
    kernel2D(const int fromRow,
             const int fromCol,
             const int toRow,
             const int toCol,
             T data[],
             const eConstantReference constRef);
    
    /**
     * Create a kernel2D and use the given \a data as if it was given
     * through the useExternData().
     *
     * @see useExternData()
     *
     * The first elements of the data will be copied on the first row, the next
     * ones on the second row and so on.
     *
     * \note Please observe that the last argument makes a huge difference to
     * the constructors that do not have it.  Here the data is \b not copied,
     * just a reference is kept.  Without the last argument, the data is
     * always copied.
     *
     * @param from lowest index
     * @param to highest index (inclusive)
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this value to be ConstantReference.
     */
    kernel2D(const size_type& from,
             const size_type& to,
             T data[],
             const eConstantReference constRef);


    /**
     * Create a kernel2D and use the given \a data as if it was given
     * through the useExternData().
     *
     * @see useExternData()
     *
     * The first elements of the data will be copied on the first row, the next
     * ones on the second row and so on.
     *
     * \note Please observe that the last argument makes a huge difference to
     * the constructors that do not have it.  Here the data is \b not copied,
     * just a reference is kept.  Without the last argument, the data is
     * always copied.
     *
     * @param rows interval for rows
     * @param columns interval for columns
     * @param data pointer to the memory block with the data to be initialized
     *            with.
     * @param constRef usually you want this value to be ConstantReference.
     */
    kernel2D(const iinterval& rows,
             const iinterval& columns,
             T data[],
             const eConstantReference constRef);

    /**
     * Copy constructor.
     *
     * Create this kernel2D as a copy of another kernel2D.
     *
     * @param other the kernel2D to be copied.
     */
    kernel2D(const genericLattice2D<T>& other);

    /**
     * Copy constructor.
     *
     * Create this kernel2D as a copy of another kernel2D for
     * this const version, the data will be always copied!
     *
     * @param other the genericLattice2D to be copied.
     * @param fromRow initial row of the other genericLattice2D to be copied
     * @param fromCol initial column of the other genericLattice2D to be copied
     * @param toRow last row to be copied of the other genericLattice2D
     * @param toCol last column to be copied of the other genericLattice2D
     */
    kernel2D(const genericLattice2D<T>& other,
             const int fromRow,
             const int fromCol,
             const int toRow=container::MaxIndex,
             const int toCol=container::MaxIndex);
    
    /**
     * Copy constructor.
     *
     * Create this kernel2D as a copy of a section of another kernel2D
     *
     * @param other the genericLattice2D to be copied.
     * @param from initial position in the other genericLattice2D to be copied
     * @param to last position to be copied of the other genericLattice2D
     */
    kernel2D(const genericLattice2D<T>& other,
             const size_type& from,
             const size_type& to);

    /**
     * Copy constructor.
     *
     * Create this kernel2D as a copy of a sublattice2D of another
     * genericLattice2D.
     *
     * @param other the genericLattice2D to be copied.
     * @param rows interval of rows to be copied.
     * @param columns interval of columns to be copied.
     */
    kernel2D(const genericLattice2D<T>& other,
             const iinterval& rows,
             const iinterval& columns);

    /**
     * Copy constructor.
     *
     * Create this kernel2D as a copy of another genericLattice2D
     * taking only the rows indicated by the vector.
     *
     * The data will be always copied!  Multiple occurence of one row index in
     * \a rows is allowed.
     *
     * @param other the genericLattice2D to be copied.
     * @param rows indices of the rows to be copied
     */
    kernel2D(const genericLattice2D<T>& other,
             const genericLattice1D<int>& rows);



    /**
     * Copy constructor
     * @param other the one dimensional kernel to be copied
     */
    kernel2D(const kernel2D& other);

    /**
     * Destructor
     */
    virtual ~kernel2D();

    /**
     * Copy member
     * @param other the one dimensional kernel to be copied
     * @return a reference to this instance
     */
    kernel2D& copy(const kernel2D& other);

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

    /**
     * Clone member
     * @return a pointer to a copy of this object
     */
    virtual kernel2D<T>* clone() const;

    /**
     * Create a new instance.
     * @return a pointer to a new empty kernel instance
     */
    virtual kernel2D<T>* newInstance() const;

    /**
     * Copy from kernel of different type
     * @param other a one dimensional kernel of another type
     * @return a reference to this instance
     */
    template<class U>
    kernel2D& castFrom(const kernel2D<U>& other) {
      lattice2D<T>::castFrom(other);
      norm_ = T(other.getNorm());
      return (*this);
    }

    /**
     * Get normalization factor
     *
     * The normalization factor is used by the fixed point types as a
     * representation of the value 1.  For example, the norm for a
     * kernel2D<ubyte> can be 255, if the filter kernel don't need values
     * greater than 1.0.
     */
    inline const T& getNorm() const {
      return norm_;
    }

    /**
     * Set normalization factor
     * @see getNorm()
     */
    inline void setNorm(const T& n) {
      norm_=n;
    };

    /**
     * Normalize divides all elements by the norm and sets the norm to 1!
     */
    void normalize();

    /**
     * @name Symmetries
     */
    //@{
    /**
     * Mirror the other kernel and leave the result here, i.e.
     * at(x,y) = other.at(-x,-y);
     * @param other the kernel to be copied and then mirrored
     * @return a reference to this instance
     */
    kernel2D<T>& mirror(const kernel2D<T>& other);

    /**
     * Mirror this kernel, i.e.
     * at(x,y) = at(-x,-y);
     * @return a reference to this instance
     */
    kernel2D<T>& mirror();
    //@}

    /**
     * Write the object in the given ioHandler
     */
    virtual bool write(ioHandler& handler,const bool complete = true) const;

    /**
     * Read the object from the given ioHandler
     */
    virtual bool read(ioHandler& handler,const bool complete = true);

  protected:
    /**
     * Normalization factor.
     *
     * This value will be ignored for floating point formats.
     * For fixed point formats, this value corresponds to 1.0
     */
    T norm_;
  };


  // ----------------------------------------------------------
  //   Typical used types
  // ----------------------------------------------------------

  /**
   * One dimensional kernel of integers
   */
  typedef kernel2D<int32>  ikernel2D;

  /**
   * One dimensional kernel of floats
   */
  typedef kernel2D<float>  fkernel2D;

  /**
   * One dimensional kernel of doubles
   */
  typedef kernel2D<double> dkernel2D;

  /**
   * One dimensional kernel of unsigned bytes
   */
  typedef kernel2D<ubyte>  bkernel2D;


}
#endif