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

#ifndef _CVR_KERNEL_1_D_H_
#define _CVR_KERNEL_1_D_H_

#include <vector>
#include "cvrLattice1D.h"
#include "cvrTypes.h"
#include "cvrMatrix.h"
#include "cvrTypeInfo.h"

namespace cvr {

  /**
   * One-dimensional filter kernel
   *
   * The template type of this class should coincide with the template
   * class of the vector be convolved with.  For example, if you want
   * to convolve a kernel1D with a vector<double>, you will need a
   * kernel1D<double> (@see cvr::convolution).
   *
   * If you instantiate a kernel1D of a fixed point type, like
   * kernel1D<int> or kernel1D<ubyte>, you also need to consider the
   * "norm" of the kernel (see cvr::kernel1D<T>::getNorm() and
   * cvr::kernel1D<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 kernel1D<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 kernel1D : public lattice1D<T> {
  public:
    /**
     * \name Internal types and classes
     */
    //@{

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

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

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

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

    /**
     * Const reference to value_type
     */
    typedef typename lattice1D<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::lattice1D::begin() and
     * cvr::lattice1D::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 lattice1D 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 lattice1D<T>::const_iterator
     */
    typedef typename lattice1D<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::lattice1D::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 lattice1D 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 lattice1D<T>::iterator
     */
    typedef typename lattice1D<T>::const_iterator const_iterator;
    //@}

    /**
     * Default constructor
     */
    kernel1D();

    /**
     * Construct a filter kernel indexed from <em>from</em> to
     * <em>to</em> and initialized with the value <em>init</em>
     */
    kernel1D(const int from,
       const int to,
       const T& init);

    /**
     * Construct a uninitialization filter kernel indexed from
     * <em>from</em> to <em>to</em>
     *
     * \warning This is an interface change with the previous library.  It has
     * been done to be consistent with the more basic features of the C++
     * language.  If you write for example "int c;", the content of \c c is
     * not defined, and in the same way, if you want a kernel1D with
     * initialized data, you have to specify explicitely the value with
     * which the elements have to be initialized.
     */
    kernel1D(const int from,
       const int to);

    /**
     * Construct a kernel from a one dimensional vector
     * @param other the source vector
     * @param theOffset this is the index in the vector that corresponds to
     *                  the index '0' in the filter kernel
     */
    kernel1D(const vector<T>& other,const int theOffset);

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

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

    /**
     * Copy member
     * @param other the one dimensional kernel to be copied
     * @return a reference to this instance
     */
    kernel1D& copy(const kernel1D& 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 kernel1D<T>* clone() const;

    /**
     * Create a new instance.
     * @return a pointer to a new empty kernel instance
     */
    virtual kernel1D<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>
    kernel1D& castFrom(const kernel1D<U>& other) {
      lattice1D<T>::castFrom(other);
      norm_ = T(other.getNorm());
      return (*this);
    }

    /**
     * Copy the content of the other vector in this kernel and assign
     * the index (firstElement) to the first element of the vector.
     * For example if <code>other</code> is a 3 dimensional vector, then
     * <code>castFrom(other,-1)</code> is a 3-elements-kernel which indices
     * lay inside [-1,1].
     * @param other the vector with the data to be copied
     * @param firstElement index for the first element of the vector
     * @return a reference to this instance
     */
    kernel1D<T>& castFrom(const vector<T>& other,
                          const int firstElement = 0);


    /**
     * 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
     * kernel1D<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) = other.at(-x);
     * @param other the kernel to be copied and then mirrored
     * @return a reference to this instance
     */
    kernel1D<T>& mirror(const kernel1D<T>& other);

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

    /**
     * Check if this kernel is symmetric, i.e. if it is valid
     * at(x)==at(-x) and firstIdx() == -lastIdx()
     */
    bool isSymmetric() const;

    /**
     * Check if this kernel is asymmetric, i.e. if it is valid
     * at(x)==-at(-x) and firstIdx() == -lastIdx()
     */
    bool isAsymmetric() const;

    /**
     * Get kernel symmetric component
     *
     * Each discrete function (including kernels like this one) can be
     * decomposed into a symmetric component \f$x_e(n)\f$$ and an asymmetric
     * component \f$x_e(n)\f$ following the equation
     *
     * \f[
     *   \begin{aligned}
     *     x_e &= \frac{x(t)+x(-t)}{2} \\
     *     x_o &= \frac{x(t)-x(-t)}{2} \\
     *   \end{aligned}
     * \f]
     *
     * This method extracts the symmetric component only
     */
    void computeSymmetricComponent();

    /**
     * Get kernel symmetric component of other kernel.
     *
     * Each discrete function (including kernels like this one) can be
     * decomposed into a symmetric component \f$x_e(n)\f$$ and an asymmetric
     * component \f$x_e(n)\f$ following the equation
     *
     * \f[
     *   \begin{aligned}
     *     x_e &= \frac{x(t)+x(-t)}{2} \\
     *     x_o &= \frac{x(t)-x(-t)}{2} \\
     *   \end{aligned}
     * \f]
     *
     * This method extracts the symmetric component of the other kernel.
     *
     * @param other the kernel which will be decomposed.
     */
    void computeSymmetricComponent(const kernel1D<T>& other);

    /**
     * Get kernel asymmetric component
     *
     * Each discrete function (including kernels like this one) can be
     * decomposed into a symmetric component \f$x_e(n)\f$$ and an asymmetric
     * component \f$x_e(n)\f$ following the equation
     *
     * \f[
     *   \begin{aligned}
     *     x_e &= \frac{x(t)+x(-t)}{2} \\
     *     x_o &= \frac{x(t)-x(-t)}{2} \\
     *   \end{aligned}
     * \f]
     *
     * This method extracts the asymmetric component only
     */
    void computeAsymmetricComponent();

    /**
     * Get kernel asymmetric component of other kernel.
     *
     * Each discrete function (including kernels like this one) can be
     * decomposed into a symmetric component \f$x_e(n)\f$$ and an asymmetric
     * component \f$x_e(n)\f$ following the equation
     *
     * \f[
     *   \begin{aligned}
     *     x_e &= \frac{x(t)+x(-t)}{2} \\
     *     x_o &= \frac{x(t)-x(-t)}{2} \\
     *   \end{aligned}
     * \f]
     *
     * This method extracts the asymmetric component of the other kernel.
     *
     * @param other the kernel which will be decomposed.
     */
    void computeAsymmetricComponent(const kernel1D<T>& other);
    //@}

    /**
     * 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 kernel1D<int32>  ikernel1D;

  /**
   * One dimensional kernel of floats
   */
  typedef kernel1D<float>  fkernel1D;

  /**
   * One dimensional kernel of doubles
   */
  typedef kernel1D<double> dkernel1D;

  /**
   * One dimensional kernel of unsigned bytes
   */
  typedef kernel1D<ubyte>  bkernel1D;


}
#endif