cvrLattice2D.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998-2004
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 * Copyright (C) 2007-2008
 * Pablo Alvarado
 *
 * 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   cvrLattice2D.h
 *         Declares the mathematical version of genericLattice2D, which also
 *         provides some arithmetical operations and extrems search methods.
 * \author Pablo Alvarado
 * \date   17.01.2008
 *
 * $Id: cvrLattice2D.h,v 1.13 2007/09/14 17:17:43 alvarado Exp $
 */

#ifndef _CVR_LATTICE_2D_H_
#define _CVR_LATTICE_2D_H_

#include "cvrTypes.h"
#include "cvrLattice1D.h"

#define _CVR_GENERIC_LATTICE_2_D_DONT_INSTANTIATE_REQUEST 1
#include "cvrGenericLattice2D.h"
#undef _CVR_GENERIC_LATTICE_2_D_DONT_INSTANTIATE_REQUEST

namespace cvr {
  /**
   * Container class for two dimensional lattices with arithmetical operations.
   *
   * The cvr::lattice2D class is a container class implemented as a
   * template, but explicitelly instantiated to a set of commonly used types:
   * - ubyte
   * - byte
   * - char
   * - uint16
   * - int16
   * - int32
   * - uint32
   * - long
   * - float
   * - double
   * - rgbaPixel
   * - frgbPixel
   * - ipoint
   * - fpoint
   * - dpoint
   * - ipoint3D
   * - fpoint3D
   * - dpoint3D
   * - fcomplex
   * - dcomplex
   *
   * If you need a container for other type, use cvr::genericLattice2D instead.
   *
   * The cvr::genericLattice2D class allows the representation of two
   * dimensional lattice, containing an element at each point of the lattice.
   * The points are inidicated with an ordered pair \e n x \e m, where n and m
   * can be taken from intervals selected at construction time, that may
   * include negative values. 
   *
   * This class is similar to a cvr::matrix, but allows indexing with negative
   * values as well, a feature useful in the representation of filter kernels
   * or image masks.  It can also be seen as a special type of
   * cvr::genericLattice2D to which a set of arithmetical and simple linear
   * algebra operations has been added.
   *
   * @ingroup gLinearAlgebra
   * @ingroup gAggregate
   */
  template<typename T>
  class lattice2D : public genericLattice2D<T> {
  public:

    /**
     * @name Internal classes and types
     */
    //@{

    /**
     * Type of the contained data
     */
    typedef typename genericLattice2D<T>::value_type value_type;

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

    /**
     * The row type of a cvr::lattice2D is a cvr::vector
     */
    typedef lattice1D<T> row_type;

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

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

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

    /**
     * Iterator
     */
    typedef typename genericLattice2D<T>::iterator iterator;

    /**
     * Const iterator
     */
    typedef typename genericLattice2D<T>::const_iterator const_iterator;

    //@}

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

    /**
     * Create a lattice2D 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)
     */
    lattice2D(const int fromRow,
              const int fromCol,
              const int toRow,
              const int toCol);
    
    /**
     * Create a \a rows x \a cols lattice2D with uninitialized elements.
     *
     * @param from lowest index
     * @param to   highest index (inclusive)
     */
    lattice2D(const size_type& from,
              const size_type& to);

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

    /**
     * Create a lattice2D 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
     */
    lattice2D(const int fromRow,
              const int fromCol,
              const int toRow,
              const int toCol,
              const T& value);
    
    /**
     * Create a lattice2D 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
     */
    lattice2D(const size_type& from,
              const size_type& to,
              const T& value);
    
    /**
     * Create a lattice2D 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
     */
    lattice2D(const iinterval& rows,
              const iinterval& columns,
              const T& value);
    
    /**
     * Create a lattice2D 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.
     */
    lattice2D(const int fromRow,
              const int fromCol,
              const int toRow,
              const int toCol,
              const T data[]);
    
    /**
     * Create a lattice2D 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.
     */
    lattice2D(const size_type& from,
              const size_type& to,
              const T data[]);
    
    /**
     * Create a lattice2D 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.
     */
    lattice2D(const iinterval& rows,
              const iinterval& columns,
              const T data[]);
    
    /**
     * Create a lattice2D 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.
     */
    lattice2D(const int fromRow,
              const int fromCol,
              const int toRow,
              const int toCol,
              T data[],
              const eConstantReference constRef);
    
    /**
     * Create a lattice2D 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.
     */
    lattice2D(const size_type& from,
              const size_type& to,
              T data[],
              const eConstantReference constRef);


    /**
     * Create a lattice2D 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.
     */
    lattice2D(const iinterval& rows,
              const iinterval& columns,
              T data[],
              const eConstantReference constRef);

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

    /**
     * Copy constructor.
     *
     * Create this lattice2D as a copy of another lattice2D 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
     */
    lattice2D(const genericLattice2D<T>& other,
              const int fromRow,
              const int fromCol,
              const int toRow=container::MaxIndex,
              const int toCol=container::MaxIndex);
    
    /**
     * Copy constructor.
     *
     * Create this lattice2D as a copy of a section of another lattice2D
     *
     * @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
     */
    lattice2D(const genericLattice2D<T>& other,
              const size_type& from,
              const size_type& to);

    /**
     * Copy constructor.
     *
     * Create this lattice2D 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.
     */
    lattice2D(const genericLattice2D<T>& other,
              const iinterval& rows,
              const iinterval& columns);

    /**
     * Copy constructor.
     *
     * Create this lattice2D 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
     */
    lattice2D(const genericLattice2D<T>& other,
              const genericLattice1D<int>& rows);

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

    /**
     * Return lattice2D-row as a vector.
     *
     * This method works fast, since it returns a reference to the row vector.
     * The data will NOT be copied.
     * @param row the row to be accessed
     * @return a reference to the vector row
     */
    inline row_type& getRow(const int row);

    /**
     * Return lattice2D-row as a const vector.
     *
     * This method works fast, since it returns a reference to the row vector.
     * The data will NOT be copied.
     * @param row the row to be accessed
     * @return a const reference to the vector row
     */
    inline const row_type& getRow(const int row) const;

    /**
     * Alias for getRow()
     */
    inline row_type& operator[](const int row);

    /**
     * Alias for getRow()
     */
    inline const row_type& operator[](const int row) const;

    /**
     * Return lattice2D-row as a vector.
     * This method copies the data of the lattice2D, therefore is not as
     * fast as getRow()
     * @param row the number of tthe row to be copied
     * @return a vector with the contents of the row of the lattice2D
     */
    inline row_type getRowCopy(const int row) const;

    /**
     * Copy a row vector in the given parameter.
     *
     * This method copies the data of a given row of the genericLattice2D
     * in the given vector.
     *
     * @param row the number of the row to be copied
     * @param theRow the vector, where the data will be copied
     * @see getRow()
     */
    inline void getRowCopy(const int row,row_type& theRow) const;

    /**
     * Return lattice2D-column as a vector.
     * This method copies the data of the lattice2D, therefore is not as
     * fast as getRow()
     * @param col the number of the column to be copied
     * @return a vector with the contents of the column of the lattice2D
     */
    inline row_type getColumnCopy(const int col) const;

    /**
     * Return genericLattice2D-column as a vector.
     * This method copies the data of the genericLattice2D, therefore is not as
     * fast as getRow()
     * @param col the number of the column to be copied
     * @param theCol a vector, where the column vector of the genericLattice2D
     *               should be copied.
     */
    inline void getColumnCopy(const int col,row_type& theCol) const;

    /**
     * Assigment operator.
     *
     * Copy the contents of \a other in this object.
     *
     * The result of the copy is always a connected lattice2D.  I.e. you cannot
     * copy the sub-lattice2D property of another lattice2D.
     *
     * @param other the other lattice2D to be copied
     */
    inline lattice2D<T>& copy(const genericLattice2D<T>& other);

    /**
     * Assigment operator.
     *
     * copy the contents of \a other in this object.
     *
     * The result of the copy is always a connected lattice2D.  I.e. you cannot
     * copy the sub-lattice2D property of another lattice2D.
     *
     * @param other the other lattice2D to be copied
     * @param fromRow initial row of the other lattice2D to be copied
     * @param fromCol initial column of the other lattice2D to be copied
     * @param toRow last row to be copied of the other lattice2D
     * @param toCol last column to be copied of the other lattice2D
     */
    inline lattice2D<T>& copy(const genericLattice2D<T>& other,
                              const int fromRow,
                              const int fromCol,
                              const int toRow=container::MaxIndex,
                              const int toCol=container::MaxIndex);

    /**
     * Assigment operator.
     *
     * copy the contents of \a other in this object.
     *
     * The result of the copy is always a connected lattice2D.  I.e. you cannot
     * copy the sub-lattice2D property of another lattice2D.
     *
     * @param other the other lattice2D to be copied
     * @param from initial indices of sublattice2D to be copied
     * @param to   final indices of sublattice2D to be copied (included)
     */
    inline lattice2D<T>& copy(const genericLattice2D<T>& other,
                              const size_type& from,
                              const size_type& to);


    /**
     * Assigment operator.
     *
     * copy the contents of \a other in this object.
     *
     * The result of the copy is always a connected lattice2D.  I.e. you cannot
     * copy the sub-lattice2D property of another lattice2D.
     *
     * @param other the other lattice2D to be copied
     * @param r interval used for the rows
     * @param c interval used for the columns
     */
    inline lattice2D<T>& copy(const genericLattice2D<T>& other,
                              const iinterval& r,
                              const iinterval& c);

    /**
     * Assigment operator.
     *
     * Copy the contents of \a other in this object.
     *
     * The result of the copy is always a connected lattice2D.  I.e. you cannot
     * copy the sub-lattice2D property of another lattice2D.
     *
     * @param other the other lattice2D to be copied
     * @param window rectangle define the copy area
     */
    inline lattice2D<T>& copy(const genericLattice2D<T>& other,
                              const irectangle& window);

    /**
     * Assigment operator.
     *
     * Copy the contents of the specified rows of
     * \a other into this object. Multiple occurence of one
     * row index in \a idx is allowed.
     *
     * @param other the other lattice2D to be copied
     * @param idx indices of the rows to be copied.
     */
    inline lattice2D<T>& copyRows(const genericLattice2D<T>& other,
                                  const genericLattice1D<int>& idx);

    /**
     * Assigment operator.
     *
     * Copy the contents of the specified columns of
     * \a other into this object. Multiple occurence of one
     * column index in \a idx is allowed.
     *
     * @param other the other lattice2D to be copied
     * @param idx indices of the rows to be copied.
     */
    inline lattice2D<T>& copyColumns(const genericLattice2D<T>& other,
                                     const genericLattice1D<int>& idx);


    /**
     * Copy the \a other lattice2D by casting each of its elements
     * Example:
     * \code
     *   cvr::lattice2D<int> matA(10,10,1);// a lattice2D of integers
     *   cvr::lattice2D<double> matB;      // a lattice2D of doubles
     *
     *   matB.castFrom(matA);          // this will copy matA in matB!!
     * \endcode
     *
     * @param other The lattice2D to be casted
     * @returns reference to this lattice2D
     */
    template<typename U>
    inline lattice2D<T>& castFrom(const genericLattice2D<U>& other);

    /**
     * Copy the \a other lattice2D by casting each of its elements. This
     * 'specialization' ensures that the copy() method is used when
     * U==T.
     *
     * @param other The lattice2D to be casted (copied)
     */
    inline lattice2D<T>& castFrom(const genericLattice2D<T>& other);

    /**
     * Copy a sublattice2D of the \a other genericLattice2D by casting each of
     * its elements.
     *
     * @param other The genericLattice2D to be casted
     * @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
     *
     * @return a reference to the current casted lattice2D.
     */
    template<typename U>
    inline lattice2D<T>& castFrom(const genericLattice2D<U>& other,
                                  const int fromRow,
                                  const int fromCol,
                                  const int toRow=container::MaxIndex,
                                  const int toCol=container::MaxIndex);

    /**
     * This is just an alias for copy(const genericLattice2D<T>&, const int
     * fromRow, const int fromCol, const int toRow, const int toCol) to
     * facilitate generic programming.
     *
     * @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
     *
     * @return a reference to the current casted lattice2D.
     */
    lattice2D<T>& castFrom(const genericLattice2D<T>& other,
                           const int fromRow,
                           const int fromCol,
                           const int toRow=container::MaxIndex,
                           const int toCol=container::MaxIndex);

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

    /**
     * Create a clone of this lattice2D
     * @return a pointer to a copy of this lattice2D
     */
    virtual lattice2D<T>* clone() const;

    /**
     * Create a new empty lattice2D
     * @return a pointer to a copy of this lattice2D
     */
    virtual lattice2D<T>* newInstance() const;

    /**
     * Compare this lattice2D with other, and use the given tolerance to
     * determine if the value of each element of the other lattice2D
     * approximately equals the values of the actual lattice2D elements.
     *
     * An element <i>x</i> is approximately equal to another element <i>y</i>
     * with a tolerance <i>t</i>, if following equation holds:
     * <i>x</i>-t < <i>y</i> < <i>x</i>+t
     *
     * This method is mainly used for matrices containing floating point
     * values.
     *
     * @param other the other lattice2D to be compared with
     * @param tolerance the tolerance to be used
     *
     * @return true if both matrices are approximatly equal
     */
    bool prettyCloseTo(const genericLattice2D<T>& other,
                       const T& tolerance) const;

    /**
     * Assigment operator (alias for copy(other)).
     * @param other the lattice2D to be copied
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& operator=(const genericLattice2D<T>& other);

    /**
     * @name Apply Methods.
     *
     * Following methods are used to apply simple functions to each element
     * of the vector.
     */
    //@{

    /**
     * Applies a C-function to each element of the lattice2D.
     * @param function a pointer to a C-function
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(T (*function)(T));

    /**
     * Applies a C-function to each element of the other lattice2D
     * @param other the lattice2D which elements will go through the given
     *              function.
     * @param function a pointer to a C-function
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(const genericLattice2D<T>& other,
                               T (*function)(T));

    /**
     * Applies a C-function to each element of the lattice2D.
     * @param function a pointer to a C-function
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(T (*function)(const T&));

    /**
     * Applies a C-function to each element of the other lattice2D
     * @param other the lattice2D which elements will go through the given
     *              function.
     * @param function a pointer to a C-function
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(const genericLattice2D<T>& other,
                               T (*function)(const T&));

    /**
     * A two-parameter C-function receives the i-th elements of this
     * and the given lattice2D and the result will be left in this
     * lattice2D.  Note that both matrices must have the same size!
     * @param other the second lattice2D to be considered (the first
     *              lattice2D will be this object!)
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(const genericLattice2D<T>& other,
                               T (*function)(const T&,const T&));

    /**
     * A two-parameter C-function receives the i-th elements of this
     * and the given lattice2D and the result will be left in this
     * lattice2D.  Note that both matrices must have the same size!
     * @param other the second lattice2D to be considered (the first
     *              lattice2D will be this object!)
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(const genericLattice2D<T>& other,
                               T (*function)(T,T));

    /**
     * A two-parameter C-function receives the i-th elements of both given
     * matrices and leaves the result here.
     * Note that both matrices must have the same size!
     * @param a the first lattice2D
     * @param b the second lattice2D
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(const genericLattice2D<T>& a,
                               const genericLattice2D<T>& b,
                               T (*function)(const T&,const T&));

    /**
     * A two-parameter C-function receives the i-th elements of both given
     * matrices and leaves the result here.
     * Note that both matrices must have the same size!
     * @param a the first lattice2D
     * @param b the second lattice2D
     * @param function a pointer to C-function with two parameters
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& apply(const genericLattice2D<T>& a,
                               const genericLattice2D<T>& b,
                               T (*function)(T,T));

    //@}

    /**
     * @name Arithmetical Operations
     */
    //@{

    /**
     * Add \a other lattice2D to this lattice2D, and leave result here
     * @param other the lattice2D to be added with
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& add(const genericLattice2D<T>& other);

    /**
     * Add  matrices \a a and \a b and write the result
     * in this lattice2D
     * @param a the first lattice2D
     * @param b the second lattice2D
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& add(const genericLattice2D<T>& a, 
                      const genericLattice2D<T>& b);

    /**
     * Add constant value to this lattice2D, and leave result here
     * @param value a constant value to be added to all lattice2D elements
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& add(const T value);

    /**
     * Add constant value to the other lattice2D and leave result here.
     * @param other the other lattice2D
     * @param value a constant value to be added to all lattice2D elements
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& add(const genericLattice2D<T>& other,const T value);

    /**
     * Alias for add(const T value)
     * @param value a constant value to be added to all lattice2D elements
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& operator+=(const T value);

    /**
     * Alias for add(const lattice2D)
     * @param other the lattice2D to be added with
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& operator+=(const genericLattice2D<T>& other);

    /**
     * Add \a other lattice2D to this lattice2D and leave the result in
     * a new lattice2D.  This object is not changed.
     * @param other the other lattice2D to be added with.
     * @return a lattice2D with the sum of this lattice2D and \a other
     *
     * \warning Note that the use of this operator is not as efficient
     * as the use of the add() methods, in which the programmer can
     * decide when to use temporal and when not...
     */
    lattice2D<T> operator+(const genericLattice2D<T>& other) const;

    /**
     * Add constant value to this lattice2D, and leave result in a new
     * lattice2D. This object is not changed.
     * @param value a constant value to be added to all lattice2D elements
     * @return a new lattice2D with the result
     */
    lattice2D<T> operator+(const T value) const;

    /**
     * Subtract \a other lattice2D from this lattice2D and leave the result in
     * a new lattice2D.  This object is not changed.
     * @param other the other lattice2D to be added with.
     * @return a lattice2D with the sum of this lattice2D and \a other
     *
     * \warning Note that the use of this operator is not as efficient
     * as the use of the add() methods, in which the programmer can
     * decide when to use temporal and when not...
     */
    lattice2D<T> operator-(const genericLattice2D<T>& other) const;

    /**
     * Subtract constant value from this lattice2D, and leave result in a new
     * lattice2D. This object is not changed.
     * @param value a constant value to be added to all lattice2D elements
     * @return a new lattice2D with the result
     */
    lattice2D<T> operator-(const T value) const;

    /**
     * Add another lattice2D scaled by \f$b\f$ to this lattice2D. The matrices
     * must be of the same types and dimensions. Let \f$A\f$ be this lattice2D
     * and \f$B\f$ the other lattice2D, then this method performs:<p>
     * \f$A=A+b\cdot B\f$
     * @param b scaling factor for <b>other</b>
     * @param other the lattice2D to be added after scaling
     * @return a reference to this lattice2D
     */
    lattice2D<T>& addScaled(const T b, const genericLattice2D<T>& other);

    /**
     * Add a lattice2D A with a lattice2D B scaled by \f$b\f$, and leave the
     * result in this lattice2D. The matrices must be of the same types
     * and dimensions. This method performs:<p> \f$A+b\cdot B\f$
     * @param matA the first lattice2D
     * @param b scaling factor for <b>matB</b>
     * @param matB the lattice2D to be added after scaling
     * @return a reference to this lattice2D
     */
    lattice2D<T>& addScaled(const genericLattice2D<T>& matA,
                            const T b,
                            const genericLattice2D<T>& matB);

    /**
     * Leave the scaled %sum of two matrices in this lattice2D. The matrices
     * must be of the same types and dimensions. Let \f$A\f$ be the
     * first lattice2D and \f$B\f$ the second lattice2D with corresponding
     * scaling factors \f$a\f$ and \f$b\f$, further \f$C\f$ this
     * lattice2D, then this method performs:<p>
     * \f$C=a\cdot A+b\cdot B\f$
     * @param a scaling factor for <b>first</b>
     * @param first the first lattice2D to be added after scaling
     * @param b scaling factor for <b>second</b>
     * @param second the second lattice2D to be added after scaling
     * @return a reference to this lattice2D
     */
    lattice2D<T>& addScaled(const T a, const genericLattice2D<T>& first,
                            const T b, const genericLattice2D<T>& second);


    /**
     * Subtract \a other lattice2D from this lattice2D, and leave result
     * here.
     * @param other the lattice2D to be subtracted
     * @return a reference to this lattice2D.
     */
    lattice2D<T>& subtract(const genericLattice2D<T>& other);

    /**
     * Subtract matrices \a b from \a a and write result
     * in this lattice2D.
     * @param a the first lattice2D
     * @param b the second lattice2D
     * @return a reference to this lattice2D, which is now a-b.
     */
    lattice2D<T>& subtract(const genericLattice2D<T>& a, 
                           const genericLattice2D<T>& b);

    /**
     * Subtract constant value from this lattice2D, and leave result here
     *
     * @param value a constant value to be subtracted from all lattice2D
     *        elements
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& subtract(const T value);

    /**
     * Subtract constant value from the other lattice2D and leave result here.
     *
     * @param other the other lattice2D
     * @param value a constant value to be subtracted from all lattice2D
     *        elements
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& subtract(const genericLattice2D<T>& other,const T value);

    /**
     * Alias for subtract(const T value)
     *
     * @param value a constant value to be subtracted from all lattice2D
     *        elements
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& operator-=(const T value);

    /**
     * Alias for subtract(const lattice2D)
     *
     * @param other the lattice2D to be subtracted
     * @return a reference to the actual lattice2D
     */
    inline lattice2D<T>& operator-=(const genericLattice2D<T>& other);

    /**
     * Multiply constant value with this lattice2D, and leave result here
     * @param value the constant value to be multiplied with
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& multiply(const T value);

    /**
     * Multiply constant value with the other lattice2D and leave result here.
     * @param other the other lattice2D
     * @param value the constant value to be multiplied with
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& multiply(const genericLattice2D<T>& other,const T value);

    /**
     * Alias for multiply(const T& value)
     * @param value the constant value to be multiplied with
     * @return a reference to this lattice2D.
     */
    inline lattice2D<T>& operator*=(const T value);

    /**
     * Divide the elements of the lattice2D by a constant value, and leave
     * the result here
     * @param value the constant value (divisor)
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& divide(const T value);

    /**
     * Divide the elements of the other lattice2D by a constant value and leave
     * the result here.
     * @param other the other lattice2D
     * @param value the constant value (divisor)
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& divide(const genericLattice2D<T>& other,const T value);

    /**
     * Alias for divide(const T& value)
     * @param value the constant value to be divided by
     * @return a reference to this lattice2D.
     */
    lattice2D<T>& operator/=(const T value);

    /**
     * Element-wise multiplication with other lattice2D
     * @param other the other lattice2D.  It should have the same dimensions of
     *              this lattice2D.
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& emultiply(const genericLattice2D<T>& other);

    /**
     * Element-wise multiplication of \a a and \a b.
     * @param a the first lattice2D
     * @param b the second lattice2D (with same dimensions of a)
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& emultiply(const genericLattice2D<T>& a,
                            const genericLattice2D<T>& b);

    /**
     * Element-wise division with other lattice2D
     * @param other the other lattice2D.  It should have the same dimensions of
     *              this lattice2D.
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& edivide(const genericLattice2D<T>& other);

    /**
     * Element-wise division of \a a and \a b.
     * @param a the first lattice2D
     * @param b the second lattice2D (with same dimensions of a)
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& edivide(const genericLattice2D<T>& a, 
                          const genericLattice2D<T>& b);

    /**
     * Outer-product of two vectors.
     *
     * The result will be left in this lattice2D.
     * The dimensions of this lattice2D will change if needed.
     * The outer product of two column vectors is defined as
     * \f$a \cdot b^T\f$
     *
     * @param a first vector (will determine the number of rows)
     * @param b second vector (will determine the number of columns)
     * @return a reference to the actual lattice2D
     */
    lattice2D<T>& outerProduct(const row_type& a,
                               const row_type& b);

    /**
     * Transpose lattice2D and leave the result here.
     *
     * If the lattice2D is square this is actually a fast on-place
     * operation. However, if the lattice2D is not square a temporary
     * lattice2D is created with the new dimensions. This can be less
     * efficient than using transpose(const lattice2D&) directly on a
     * temporary lattice2D if many matrices of the same size need to be
     * transposed.
     *
     * @return a reference to the actual (now transposed) lattice2D
     */
    lattice2D<T>& transpose();

    /**
     * Transpose the other lattice2D and leave the result here.
     *
     * If U!=T each element of \a other is static_cast<T> in the
     * process.
     *
     * @return a reference to the actual (now transposed) lattice2D
     */
    template <typename U>
    lattice2D<T>& transpose(const genericLattice2D<U>& other);

    /**
     * Calculate the sum of all elements of the lattice2D.
     * This member can be used with classes which define the operator '+='
     */
    T computeSumOfElements() const;

    /**
     * Calculate the product of all elements of the vector.
     * This member can be used with classes which define the operator '*='
     */
    T computeProductOfElements() const;
    //@}

    /**
     * @name Find extreme values
     */
    //@{

    /**
     * Get the smallest element of the lattice2D
     */
    T findMinimum() const;

    /**
     * Get the index of the smallest element of the lattice2D
     */
    size_type findIndexOfMinimum() const;

    /**
     * Get the biggest element of the lattice2D
     */
    T findMaximum() const;

    /**
     * Get the index of the biggest element of the lattice2D
     */
    size_type findIndexOfMaximum() const;

    /**
     * Get the extremes of the lattice2D (smallest and biggest elements)
     */
    void findExtremes(T& theMinimum, T& theMaximum) const;

    /**
     * Get the indices of the extremes of the lattice2D
     * (smallest and biggest elements)
     */
    void findIndexOfExtremes(size_type& theIdxMinimum,
                             size_type& theIdxMaximum) const;

    //@}
  protected:

    /**
     * @name Memory allocation and deallocation
     *
     * Restrict all memory allocation and deallocation to these functions.
     */
    //@{
    /**
     * Allocate \a n number of rows or the appropriate type.
     */
    inline virtual row_type* allocNewRows(const int fromRow,
                                          const int toRow);
    //@}

  };
}

#include "cvrLattice2D_inline.h"

namespace cvr {
  /**
   * Lattice2D of double
   */
  typedef lattice2D<double> dlattice2D;
  /**
   * Lattice2D of float
   */
  typedef lattice2D<float>  flattice2D;
  /**
   * Lattice2D of integer
   */
  typedef lattice2D<int32>  ilattice2D;

}

#endif