[ADD #245] Now there is an two dimensional histogram with an foundation to...

[ADD #245] Now there is an two dimensional histogram with an foundation to extend for N-dimensional histograms.

src/core/common/WHistogram2D.cpp

+//---------------------------------------------------------------------------
+//
+// Project: OpenWalnut ( http://www.openwalnut.org )
+//
+// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
+// For more information see http://www.openwalnut.org/copying
+//
+// This file is part of OpenWalnut.
+//
+// OpenWalnut is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// OpenWalnut is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
+//
+//---------------------------------------------------------------------------
+
+#include <utility>
+
+#include "WAssert.h"
+#include "WHistogram2D.h"
+#include "WLimits.h"
+#include "WLogger.h"
+
+WHistogram2D::WHistogram2D( double minX, double maxX, double minY, double maxY, size_t bucketsX, size_t bucketsY )
+{
+    // use protecte default ctor to workaround missing initializer lists which are part of C++11 and GNU++11 only.
+    TArray min = {{ minX, minY }}; // NOLINT braces
+    TArray max = {{ maxX, maxY }}; // NOLINT braces
+    SizeArray buckets = {{ bucketsX, bucketsY }}; // NOLINT braces
+    reset( min, max, buckets );
+
+    m_intervalWidth[0] = std::abs( maxX - minX ) / static_cast< double >( bucketsX );
+    m_intervalWidth[1] = std::abs( maxY - minY ) / static_cast< double >( bucketsY );
+    m_bins = BinType::Zero( bucketsX, bucketsY );
+}
+
+WHistogram2D::~WHistogram2D()
+{
+}
+
+WHistogram2D::WHistogram2D( const WHistogram2D& other )
+    : WHistogramND( other )
+{
+    m_bins = other.m_bins;
+}
+
+size_t WHistogram2D::operator()( SizeArray index ) const
+{
+    return m_bins( index[0], index[1] );
+}
+
+size_t WHistogram2D::operator()( size_t i, size_t j ) const
+{
+    SizeArray index = {{ i, j }};
+    return operator()( index );
+}
+
+double WHistogram2D::getBucketSize( SizeArray /* index */ ) const
+{
+    return m_intervalWidth[0] * m_intervalWidth[1];
+}
+
+boost::array< std::pair< double, double >, 2 > WHistogram2D::getIntervalForIndex( SizeArray index ) const
+{
+    boost::array< std::pair< double, double >, 2 > result;
+
+    for( size_t i = 0; i < 2; ++i )
+    {
+        result[i] = std::make_pair( m_intervalWidth[i] * index[i] + m_min[i],
+                                    m_intervalWidth[i] * ( index[i] + 1 ) + m_min[i] );
+    }
+
+    return result;
+}
+
+void WHistogram2D::insert( TArray values )
+{
+    if( values[0] > m_max[0] || values[0] < m_min[0] || values[1] > m_max[1] || values[1] < m_min[1] )
+    {
+        wlog::warn( "WHistogram2D" ) << std::scientific << std::setprecision( 16 ) << "Inserted value out of bounds, thread: ("
+                                     << values[0] << "," << values[1] << ") whereas min,max are: dim0: (" << m_min[0] << "," << m_max[0] << ") "
+                                     << "dim1:(" << m_min[1] << "," << m_max[1] << ")";
+        return;
+    }
+
+    SizeArray coord = {{ 0, 0 }};
+
+    for( size_t i = 0; i < 2; ++i )
+    {
+        if( std::abs( m_min[i] - m_max[i] ) <= 2.0 * wlimits::DBL_EPS )
+        {
+            coord[i] = m_buckets[i] - 1;
+        }
+        else if( values[i] >= ( m_max[i] - m_intervalWidth[i] ) && values[i] <= m_max[i] )
+        {
+            coord[i] = m_buckets[i] - 1;
+        }
+        else
+        {
+            coord[i] = static_cast< size_t >( ( values[i] - m_min[i] ) / std::abs( m_max[i] - m_min[i] ) * ( m_buckets[i] ) );
+        }
+    }
+
+    m_bins( coord[0], coord[1] )++;
+}
+
+void WHistogram2D::insert( double x, double y )
+{
+    TArray values = {{ x, y }};
+    insert( values );
+}
+

src/core/common/WHistogram2D.h

+//---------------------------------------------------------------------------
+//
+// Project: OpenWalnut ( http://www.openwalnut.org )
+//
+// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
+// For more information see http://www.openwalnut.org/copying
+//
+// This file is part of OpenWalnut.
+//
+// OpenWalnut is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// OpenWalnut is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
+//
+//---------------------------------------------------------------------------
+
+#ifndef WHISTOGRAM2D_H
+#define WHISTOGRAM2D_H
+
+#include <utility>
+
+#include <boost/array.hpp>
+
+#include <Eigen/Core>
+
+#include "WHistogramND.h"
+
+/**
+ * Uniform two dimensional histogram for double values. The terms bin and bucket are interchangeable. For the first dimensional part often the
+ * analouge X-dimension is used and for the second, Y-dimension.
+ */
+class WHistogram2D : public WHistogramND< 2 > // NOLINT
+{
+public:
+    /**
+     * Creates a two dimensional histogram field, bounded by the given limits, containing the demanded number of buckets in each dimension.
+     *
+     * \param minX Minimal bound for X-values.
+     * \param maxX Maximal bound for X-values.
+     * \param minY Minimal bound for Y-values.
+     * \param maxY Maximal bound for Y-values.
+     * \param bucketsX Number of buckets in X direction.
+     * \param bucketsY Number of buckets in Y direction.
+     */
+    WHistogram2D( double minX, double maxX, double minY, double maxY, size_t bucketsX, size_t bucketsY );
+
+    /**
+     * Cleans up!
+     */
+    ~WHistogram2D();
+
+    /**
+     * Copy constructor, performing a deep copy.
+     *
+     * \param other The other instance to copy from.
+     */
+    WHistogram2D( const WHistogram2D& other );
+
+    /**
+     * Get the count of the specified bucket.
+     *
+     * \param index in each dimension
+     *
+     * \return elements in the bucket.
+     */
+    virtual size_t operator()( SizeArray index ) const;
+
+    /**
+     * Convenience function to easier access the buckets for 2D.
+     *
+     * \param i X-index
+     * \param j Y-index
+     *
+     * \return elements in the bucket.
+     */
+    virtual size_t operator()( size_t i, size_t j ) const;
+
+    /**
+     * Return the measure of one specific bucket. For one dimensional Histograms this is the width of the bucket, for two
+     * dimensions this is the area, for three dims this is the volume, etc.
+     *
+     * \param index the measure for this bucket is queried.
+     *
+     * \return the size of a bucket.
+     */
+    virtual double getBucketSize( SizeArray index ) const;
+
+    /**
+     * Returns the actual (right-open) interval in each dimension associated with the given index.
+     *
+     * \param index for this bucket the intervals will be returned
+     *
+     * \return the right-open interval in each dimension.
+     */
+    virtual boost::array< std::pair< double, double >, 2 > getIntervalForIndex( SizeArray index ) const;
+
+    /**
+     * Given a value the corresponding bucket is determined and incremented by one.
+     *
+     * \param values The value to count into specific bucket.
+     */
+    void insert( TArray values );
+
+    /**
+     * Shorthand to overloaded insert function where each dimension can be overhanded separately.
+     * \see insert()
+     * \param x value for the first dimension.
+     * \param y value for the second dimension.
+     */
+    void insert( double x, double y );
+
+protected:
+private:
+    /**
+     * Shorthand for data structure storing bucket information. In 2D this is a matrix.
+     */
+    typedef Eigen::Matrix< size_t, Eigen::Dynamic, Eigen::Dynamic > BinType;
+
+    /**
+     * Storing the bucket counts, how often a value occurs.
+     */
+    BinType m_bins;
+
+    /**
+     * For each dimension this stores the uniform interval width.
+     */
+    TArray m_intervalWidth;
+};
+
+#endif  // WHISTOGRAM2D_H

src/core/common/WHistogramND.cpp

+//---------------------------------------------------------------------------
+//
+// Project: OpenWalnut ( http://www.openwalnut.org )
+//
+// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
+// For more information see http://www.openwalnut.org/copying
+//
+// This file is part of OpenWalnut.
+//
+// OpenWalnut is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// OpenWalnut is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
+//
+//---------------------------------------------------------------------------
+

src/core/common/WHistogramND.h

+//---------------------------------------------------------------------------
+//
+// Project: OpenWalnut ( http://www.openwalnut.org )
+//
+// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
+// For more information see http://www.openwalnut.org/copying
+//
+// This file is part of OpenWalnut.
+//
+// OpenWalnut is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// OpenWalnut is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
+//
+//---------------------------------------------------------------------------
+
+#ifndef WHISTOGRAMND_H
+#define WHISTOGRAMND_H
+
+#include <utility>
+
+#include <boost/array.hpp>
+
+/**
+ * This template should handly arbitrary N-dimensional histograms.
+ *
+ * \tparam N specifies the dimensionality
+ * \tparam T specifies the type of data. Normally this should be double or float.
+ */
+template< std::size_t N, typename T = double >
+/**
+ * Interface for an N-dimensional histogram.
+ */
+class WHistogramND // NOLINT
+{
+public:
+    /**
+     * Shorthand for N-dimensional indices, counter, etc.
+     */
+    typedef boost::array< size_t, N > SizeArray;
+
+    /**
+     * Shorthand for N-dimensional values of type T.
+     */
+    typedef boost::array< T, N > TArray; // e.g. DoubleArray for T == double
+
+    /**
+     * Default constructor. Creates an empty N-dimensional histogram covering the specified min and max values with the specified number of buckets.
+     *
+     * \param min the smallest value(s) in each dimension
+     * \param max the largest value(s) in each dimension
+     * \param buckets the number of buckets in each direction (may be non uniform).
+     */
+    WHistogramND( TArray min, TArray max, SizeArray buckets );
+
+    /**
+     * Copy constructor. Creates a deep copy of the specified ND histogram.
+     *
+     * \param hist the HistogramND to copy.
+     */
+    WHistogramND( const WHistogramND& hist );
+
+    /**
+     * Default destructor.
+     */
+    virtual ~WHistogramND();
+
+    /**
+     * Get the count of the specified bucket.
+     *
+     * \param index in each dimension
+     *
+     * \return elements in the bucket.
+     */
+    virtual size_t operator()( SizeArray index ) const = 0;
+
+    /**
+     * Returns the number of buckets in the HistogramND with the actual mapping.
+     *
+     * \return number of buckets
+     */
+    virtual size_t size() const;
+
+    /**
+     * Returns the minimum value(s).
+     *
+     * \return minimum
+     */
+    virtual TArray getMinima() const;
+
+    /**
+     * Returns the maximum value(s).
+     *
+     * \return maximum
+     */
+    virtual TArray getMaxima() const;
+
+    /**
+     * Return the measure of one specific bucket. For one dimensional Histograms this is the width of the bucket, for two
+     * dimensions this is the area, for three dims this is the volume, etc.
+     *
+     * \param index the measure for this bucket is queried.
+     *
+     * \return the size of a bucket.
+     */
+    virtual T getBucketSize( SizeArray index ) const = 0;
+
+    /**
+     * Returns the actual (right-open) interval in each dimension associated with the given index.
+     *
+     * \param index for this bucket the intervals will be returned
+     *
+     * \return the right-open interval in each dimension.
+     */
+    virtual boost::array< std::pair< T, T >, N > getIntervalForIndex( SizeArray index ) const = 0;
+
+protected:
+    /**
+     * Default constructor is protected to allow subclassing constructors not to use initialization lists which would
+     * imply C++11 or GNU++11 style initializers for boost::array members. To workaround, reset() member function is
+     * provided.
+     */
+    WHistogramND();
+
+    /**
+     * Initializes all members. This exists because to circumvent boost::array initializers in c'tor init lists and
+     * reduces code duplication, as it is used in this abstract class as well as in its base classes.
+     *
+     * \param min Minimal values in each dimension.
+     * \param max Maximal values in each dimension.
+     * \param buckets \#buckets in each dimension.
+     */
+    void reset( TArray min, TArray max, SizeArray buckets );
+
+    /**
+     * The smallest value in each dimension.
+     */
+    TArray m_min;
+
+    /**
+     * The biggest value in each dimension.
+     */
+    TArray m_max;
+
+    /**
+     * The number of buckets.
+     */
+    SizeArray m_buckets;
+
+    /**
+     * Total number of buckets.
+     */
+    size_t m_nbBuckets;
+
+private:
+};
+
+template< std::size_t N, typename T >
+WHistogramND< N, T >::WHistogramND()
+{
+}
+
+template< std::size_t N, typename T >
+WHistogramND< N, T >::WHistogramND( TArray min, TArray max, SizeArray buckets )
+{
+    reset( min, max, buckets );
+}
+
+template< std::size_t N, typename T >
+void WHistogramND< N, T >::reset( TArray min, TArray max, SizeArray buckets )
+{
+    m_min = min;
+    m_max = max;
+
+    WAssert( min.size() == max.size(), "Error, WHistogram initialized with wrong dimensionality" );
+    for( size_t i = 0; i < min.size(); ++i )
+    {
+        WAssert( min[i] <= max[i], "Error, WHistogram has at least one dimension where max is smaller than min" );
+    }
+
+    m_buckets = buckets;
+    m_nbBuckets = 1;
+    for( typename SizeArray::const_iterator cit = buckets.begin(); cit != buckets.end(); ++cit )
+    {
+        m_nbBuckets *= *cit;
+    }
+}
+
+template< std::size_t N, typename T >
+WHistogramND< N, T >::~WHistogramND()
+{
+}
+
+template< std::size_t N, typename T >
+WHistogramND< N, T >::WHistogramND( const WHistogramND& other )
+{
+    m_min = other.m_min;
+    m_max = other.m_max;
+    m_buckets = other.m_buckets;
+    m_nbBuckets = other.m_nbBuckets;
+}
+
+template< std::size_t N, typename T >
+size_t WHistogramND< N, T >::size() const
+{
+    return m_nbBuckets;
+}
+
+template< std::size_t N, typename T >
+typename WHistogramND< N, T >::TArray WHistogramND< N, T >::getMinima() const
+{
+    return m_min;
+}
+
+template< std::size_t N, typename T >
+typename WHistogramND< N, T >::TArray WHistogramND< N, T >::getMaxima() const
+{
+    return m_max;
+}
+
+#endif  // WHISTOGRAMND_H

src/core/common/test/WHistogram2D_test.h

+//---------------------------------------------------------------------------
+//
+// Project: OpenWalnut ( http://www.openwalnut.org )
+//
+// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
+// For more information see http://www.openwalnut.org/copying
+//
+// This file is part of OpenWalnut.
+//
+// OpenWalnut is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// OpenWalnut is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
+//
+//---------------------------------------------------------------------------
+
+#ifndef WHISTOGRAM2D_TEST_H
+#define WHISTOGRAM2D_TEST_H
+
+#include <cxxtest/TestSuite.h>
+
+#include "../WHistogram2D.h"
+#include "../WLimits.h"
+#include "../WLogger.h"
+
+/**
+ * Unit tests the WHistogramBasic class.
+ */
+class WHistogram2DTest : public CxxTest::TestSuite
+{
+public:
+    /**
+     * Setup logger and other stuff for each test.
+     */
+    void setUp()
+    {
+        WLogger::startup();
+    }
+
+    /**
+     * Check when nothing was inserted every thing is empty.
+     */
+    void testInitialization( void )
+    {
+        WHistogram2D h( 0.0, 1.0, 0.0, 0.1, 10, 10 );
+        TS_ASSERT_EQUALS( h.size(), 100 );
+    }
+
+    /**
+     * Check normal insertion inside the min max boundaries.
+     */
+    void testInsert( void )
+    {
+        WHistogram2D h( 0.0, 1.0, 0.0, 1.0, 3, 3 );
+        TS_ASSERT_EQUALS( h.size(), 9 );
+        for( size_t i = 0; i < 3; ++i )
+        {
+            for( size_t j = 0; j < 3; ++j )
+            {
+                TS_ASSERT_EQUALS( h( i, j ), 0 );
+            }
+        }
+        h.insert( 0.1, 0.1 );
+        h.insert( 0.1, 0.4 );
+        h.insert( 0.1, 0.7 );
+        h.insert( 0.4, 0.1 );
+        h.insert( 0.4, 0.4 );
+        h.insert( 0.4, 0.7 );
+        h.insert( 0.7, 0.1 );
+        h.insert( 0.7, 0.4 );
+        h.insert( 0.7, 0.7 );
+        for( size_t i = 0; i < 3; ++i )
+        {
+            for( size_t j = 0; j < 3; ++j )
+            {
+                TS_ASSERT_EQUALS( h( i, j ), 1 );
+            }
+        }
+    }
+
+    /**
+     * If the value is directly on the borderline it counts to the right interval.
+     */
+    void testInsertOnIntervalBorder( void )
+    {
+        WHistogram2D h( 0.0, 1.0, 0.0, 1.0, 10, 10 );
+        h.insert( 0.0999999, 0.0 );
+        TS_ASSERT_EQUALS( h( 0, 0 ), 1 );
+        h.insert( 0.1, 0.0 );
+        TS_ASSERT_EQUALS( h( 1, 0 ), 1 );
+        h.insert( 0.1001, 0.0 );
+        TS_ASSERT_EQUALS( h( 1, 0 ), 2 );
+        h.insert( 0.39999, 0.39999 );
+        TS_ASSERT_EQUALS( h( 3, 3 ), 1 );
+    }
+
+    /**
+     * If the minimum is inserted the first bin should be incremented.