[ADD] added hierarchical clustering module by David Moreno-Dominguez. It also...

[ADD] added hierarchical clustering module by David Moreno-Dominguez. It also provides proper documentation and the META info point to a tutorial video.

src/modules/clusterDisplay/WMClusterDisplay.h

@@ -114,6 +114,9 @@ private:
     class MainViewEventHandler : public osgGA::GUIEventHandler
     {
     public:
+        /**
+         * Signal for handling left button signals
+         */
         typedef boost::signals2::signal< bool ( WVector2f ) > LeftButtonPushSignalType;
 
         /**

src/modules/hierarchicalClustering/CMakeLists.txt

+#---------------------------------------------------------------------------
+#
+# 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/>.
+#
+#---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------------------------------------------------------------------------------
+# Some common setup
+# ---------------------------------------------------------------------------------------------------------------------------------------------------
+
+# we use the directory name as module name
+GET_FILENAME_COMPONENT( MODULE_NAME ${CMAKE_CURRENT_SOURCE_DIR} NAME )
+
+# ---------------------------------------------------------------------------------------------------------------------------------------------------
+# Search own dependencies
+# ---------------------------------------------------------------------------------------------------------------------------------------------------
+
+# 1: FindPackage( LibYouNeed )
+# 2: INCLUDE_DIRECTORIES( ${LIBYOUNEED_INCLUDE_DIR} )
+# 3: LINK_DIRECTORIES( ${LIBYOUNEED_LIBRARY_DIRS} )
+# 4: Add ${LIBYOUNEED_LIBRARY} as _MODULE_DEPENDENCIES parameter to SETUP_MODULE
+
+# ---------------------------------------------------------------------------------------------------------------------------------------------------
+# Setup for compilation
+# ---------------------------------------------------------------------------------------------------------------------------------------------------
+
+# Let this function do the job. It sets up tests and copies shaders automatically. It additionally configures the stylecheck mechanism for this
+# module.
+SETUP_MODULE( ${MODULE_NAME}                # name of the module
+             "${CMAKE_CURRENT_SOURCE_DIR}"  # where to find the source ${CMAKE_CURRENT_SOURCE_DIR} is a good idea here mostly
+             ""                             # does your module need additional libs to compile?
+             ""                             # do you want to exclude files from stylechecking? (externals for example)
+)
+

src/modules/hierarchicalClustering/WToolkit.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 "WToolkit.h"
+#include <boost/shared_ptr.hpp>
+#include <core/kernel/WModule.h>
+#include "hierchClustDisplay/WMHierchClustDisplay.h"
+#include "partition2Mesh/WMPartition2Mesh.h"
+
+
+// This file's purpose is to provide a list of modules as entry point for OpenWalnut's module loader.
+// Add your modules here. If you miss this step, OpenWalnut will not be able to load your modules.
+extern "C" void WLoadModule( WModuleList& m ) // NOLINT
+{
+    m.push_back( boost::shared_ptr< WModule >( new WMHierchClustDisplay ) );
+    m.push_back( boost::shared_ptr< WModule >( new WMPartition2Mesh ) );
+}
+

src/modules/hierarchicalClustering/WToolkit.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 WTOOLKIT_H
+#define WTOOLKIT_H
+
+// nothing to do here. Have a look at WToolkit.cpp for registration of all the modules inside the toolbox.
+
+#endif  // WTOOLKIT_H
+

src/modules/hierarchicalClustering/hierchClustDisplay/WFileParser.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/>.
+//
+//---------------------------------------------------------------------------
+
+//---------------------------------------------------------------------------
+//
+// Project: hClustering
+//
+// Whole-Brain Connectivity-Based Hierarchical Parcellation Project
+// David Moreno-Dominguez
+// d.mor.dom@gmail.com
+// moreno@cbs.mpg.de
+// www.cbs.mpg.de/~moreno//
+// This file is also part of OpenWalnut ( http://www.openwalnut.org ).
+//
+// hClustering 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.
+// http://creativecommons.org/licenses/by-nc/3.0
+//
+// hClustering 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.
+//
+//---------------------------------------------------------------------------
+
+
+#include <string>
+#include <vector>
+
+#include "WFileParser.h"
+
+
+WFileParser::WFileParser( const std::string fileName ) :
+    m_fileName( fileName ),
+    m_tagIndicator( "#" ),
+    m_endIndicator( "end" ),
+    m_delimiter( " " )
+{
+}
+
+WFileParser::~WFileParser()
+{
+}
+
+bool WFileParser::readFile()
+{
+    using namespace boost::filesystem; //NOLINT
+
+    if( !exists( m_fileName ) )
+    {
+        //debugLog() << "file doesn't exist";
+        return false;
+    }
+
+    std::ifstream ifs( m_fileName.c_str(), std::ifstream::in );
+
+    std::string line;
+
+    if( !ifs.is_open() )
+    {
+        //debugLog() << "file open failed";
+        ifs.close();
+        return false;
+    }
+
+    while( !ifs.eof() )
+    {
+        getline( ifs, line );
+
+        m_rawLines.push_back( line );
+    }
+
+    ifs.close();
+
+    return true;
+}
+
+std::vector<std::string>WFileParser::getLinesForTag( std::string tag )
+{
+    std::string startTag = m_tagIndicator + tag;
+    std::string endTag = m_tagIndicator + m_endIndicator + tag;
+
+    std::vector<std::string>returnVector;
+
+    size_t i = 0;
+    while( i < m_rawLines.size() )
+    {
+        if( m_rawLines[i] == startTag )
+        {
+            //debugLog() << "coordinates tag at line " << i;
+            ++i;
+            break;
+        }
+        else
+        {
+            ++i;
+        }
+    }
+    while( i < m_rawLines.size() )
+    {
+        if( m_rawLines[i] == endTag )
+        {
+            //debugLog() << "endcoordinates tag at line " << i;
+            ++i;
+            break;
+        }
+        else
+        {
+            returnVector.push_back( m_rawLines[i] );
+            ++i;
+        }
+    }
+    return returnVector;
+}
+
+std::vector< std::vector<std::string> >WFileParser::getLinesForTagSeparated( std::string tag )
+{
+    std::string startTag = m_tagIndicator + tag;
+    std::string endTag = m_tagIndicator + m_endIndicator + tag;
+
+    std::vector<std::vector<std::string > >returnVector;
+
+    size_t i = 0;
+    while( i < m_rawLines.size() )
+    {
+        if( m_rawLines[i] == startTag )
+        {
+            //debugLog() << "coordinates tag at line " << i;
+            ++i;
+            break;
+        }
+        else
+        {
+            ++i;
+        }
+    }
+
+    while( i < m_rawLines.size() )
+    {
+        if( m_rawLines[i] == endTag )
+        {
+            //debugLog() << "endcoordinates tag at line " << i;
+            ++i;
+            break;
+        }
+        else
+        {
+            std::vector<std::string>svec;
+            boost::regex reg( m_delimiter );
+            boost::sregex_token_iterator it( m_rawLines[i].begin(), m_rawLines[i].end(), reg, -1 );
+            boost::sregex_token_iterator end;
+            while( it != end )
+            {
+                svec.push_back( *it++ );
+            }
+
+            returnVector.push_back( svec );
+            ++i;
+        }
+    }
+    return returnVector;
+}

src/modules/hierarchicalClustering/hierchClustDisplay/WFileParser.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/>.
+//
+//---------------------------------------------------------------------------
+
+//---------------------------------------------------------------------------
+//
+// Project: hClustering
+//
+// Whole-Brain Connectivity-Based Hierarchical Parcellation Project
+// David Moreno-Dominguez
+// d.mor.dom@gmail.com
+// moreno@cbs.mpg.de
+// www.cbs.mpg.de/~moreno//
+// This file is also part of OpenWalnut ( http://www.openwalnut.org ).
+//
+// hClustering 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.
+// http://creativecommons.org/licenses/by-nc/3.0
+//
+// hClustering 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.
+//
+//---------------------------------------------------------------------------
+
+#ifndef WFILEPARSER_H
+#define WFILEPARSER_H
+
+// std library
+#include <fstream>
+#include <string>
+#include <vector>
+
+// boost library
+// Use filesystem version 2 for compatibility with newer boost versions.
+#if 0
+#ifndef BOOST_FILESYSTEM_VERSION
+    #define BOOST_FILESYSTEM_VERSION 2
+#endif
+#endif
+
+#include <boost/filesystem.hpp>
+#include <boost/regex.hpp>
+
+
+/**
+ * this class implements text file loading and several convinience methods to access the recovered text
+ */
+class WFileParser
+{
+public:
+    /**
+     * constructor
+     * \param fileName
+     */
+    explicit WFileParser( const std::string fileName );
+
+    /**
+     * destructor
+     */
+    ~WFileParser();
+
+    /**
+     * helper function to read a text file
+     * \return string containing the file
+     */
+    bool readFile();
+
+    /**
+     * getter
+     * \return the content of the loaded as vector of strings for each line
+     */
+    std::vector<std::string>getRawLines();
+
+    /**
+     * getter
+     * \param tag tag marking a certain type of content
+     * \return vector of strings for each line for the tag
+     */
+    std::vector<std::string>getLinesForTag( std::string tag );
+
+    /**
+     * getter
+     * \param tag tag marking a certain type of content
+     * \return same as getLinesForTag but each line represented as vector of strings
+     */
+    std::vector< std::vector<std::string> >getLinesForTagSeparated( std::string tag );
+
+protected:
+private:
+    std::string m_fileName; //!< the file name of the file to parse
+
+    std::vector<std::string>m_rawLines; //!< vector of every line in the file
+
+    std::string m_tagIndicator; //!< string marking a line as tag
+
+    std::string m_endIndicator; //!< string marking the end of a tagged area
+
+    std::string m_delimiter; //!< delimiter for entries in a line
+};
+
+inline std::vector<std::string> WFileParser::getRawLines()
+{
+    return m_rawLines;
+}
+
+#endif  // WFILEPARSER_H

src/modules/hierarchicalClustering/hierchClustDisplay/WHcoord.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/>.
+//
+//---------------------------------------------------------------------------
+
+//---------------------------------------------------------------------------
+//
+// Project: hClustering
+//
+// Whole-Brain Connectivity-Based Hierarchical Parcellation Project
+// David Moreno-Dominguez
+// d.mor.dom@gmail.com
+// moreno@cbs.mpg.de
+// www.cbs.mpg.de/~moreno//
+// This file is also part of OpenWalnut ( http://www.openwalnut.org ).
+//
+// hClustering 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.
+// http://creativecommons.org/licenses/by-nc/3.0
+//
+// hClustering 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.
+//
+//---------------------------------------------------------------------------
+
+
+// std library
+#include <iostream>
+#include <string>
+#include <sstream>
+#include <vector>
+#include <cmath>
+#include <algorithm>
+
+#include "WHcoord.h"
+
+WHcoord::WHcoord(): m_x( 0 ), m_y( 0 ), m_z( 0 )
+{
+}
+
+WHcoord::WHcoord( coord_t x_init, coord_t y_init, coord_t z_init ): m_x( x_init ), m_y( y_init ), m_z( z_init )
+{
+}
+
+WHcoord::WHcoord( const WHcoord &object ): m_x( object.m_x ), m_y( object.m_y ), m_z( object.m_z )
+{
+}
+
+WHcoord::~WHcoord()
+{
+    //Cleanup
+}
+
+
+// === PUBLIC MEMBER FUNCTIONS ===
+
+
+// "phys_dist()": returns the euclidean distance between this voxel and the input voxel
+float WHcoord::getPhysDist( const WHcoord voxel ) const
+{
+    float xdif( m_x-voxel.m_x ), ydif( m_y-voxel.m_y ), zdif( m_z-voxel.m_z );
+    return sqrt( ( xdif*xdif )+( ydif*ydif )+( zdif*zdif ) );
+} // end "phys_dist()" -----------------------------------------------------------------
+
+
+// "get_phys_neighbours()": returns a vector containing the coordinates of the physical neighbours adjacent to the voxel,
+// the neighbourhood level is defined by nb_level
+std::vector<WHcoord> WHcoord::getPhysNbs( const WHcoord dataSize, const unsigned int nbLevel ) const
+{
+    std::vector<WHcoord> physNeighbours;
+
+    int condition( 0 );
+    int range( 0 );
+
+    switch( nbLevel )
+    {
+    case 6:
+        range = 1;
+        condition = 1;
+        break;
+    case 18:
+        range = 1;
+        condition = 2;
+        break;
+    case 26:
+    case 32:
+        range = 1;
+        condition = 3;
+        break;
+    case 56:
+        range = 2;
+        condition = 3;
+        break;
+    case 92:
+        range = 2;
+        condition = 4;
+        break;
+    case 116:
+        range = 2;
+        condition = 5;
+        break;
+    case 124:
+        range = 2;
+        condition = 6;
+        break;
+    default:
+        std::cerr << "ERROR @ coordinate::getPhysNbs(): Unrecognized nbhood level: " << nbLevel << std::endl;
+        return physNeighbours;
+        break;
+    }
+
+    for( coord_t i = -range; i <= range ; ++i )
+    {
+        for( coord_t j = -range; j <= range ; ++j )
+        {
+            for( coord_t k = -range; k <= range ; ++k )
+            {
+                const int test( abs( i )+abs( j )+abs( k ) );
+                if( test == 0 )