OpenWalnut 1.2.5

WThreadedTrackingFunction.h

00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WTHREADEDTRACKINGFUNCTION_H
00026 #define WTHREADEDTRACKINGFUNCTION_H
00027 
00028 #include <vector>
00029 #include <utility>
00030 
00031 #include <boost/array.hpp>
00032 
00033 #include "../common/math/linearAlgebra/WLinearAlgebra.h"
00034 #include "../common/WSharedObject.h"
00035 #include "../common/WThreadedJobs.h"
00036 #include "WExportDataHandler.h"
00037 #include "WDataSetSingle.h"
00038 
00039 class WThreadedTrackingFunctionTest; //! forward declaration
00040 
00041 
00042 /**
00043  * For tracking related functionality.
00044  */
00045 namespace wtracking // note that this is not final
00046 {
00047     // an epsilon value for various floating point comparisons
00048 #define TRACKING_EPS 0.0000001
00049 
00050     /**
00051      * \class WTrackingUtility
00052      *
00053      * A class that provides untility functions and typedefs for tracking algorithms.
00054      */
00055     class OWDATAHANDLER_EXPORT WTrackingUtility
00056     {
00057     public:
00058 
00059         //! define a job type for tracking algorithms
00060         typedef std::pair< WVector3d, WVector3d > JobType;
00061 
00062         //! the dataset type
00063         typedef WDataSetSingle DataSetType;
00064 
00065         //! a pointer to a dataset
00066         typedef boost::shared_ptr< DataSetType const > DataSetPtr;
00067 
00068         //! a function that calculates a direction to continue tracking
00069         typedef boost::function< WVector3d ( DataSetPtr, JobType const& ) > DirFunc;
00070 
00071         //! a pointer to a regular 3d grid
00072         // other grid types are not supported at the moment
00073         typedef boost::shared_ptr< WGridRegular3D > Grid3DPtr;
00074 
00075         /**
00076          * A function that follows a direction until leaving the current voxel.
00077          *
00078          * \param dataset A pointer to the input dataset.
00079          * \param job A pair of vectors, the position and the direction of the last integration.
00080          * \param dirFunc A function that computes the next direction.
00081          *
00082          * \return true, iff the calculated point is a valid position inside the grid
00083          */
00084         static bool followToNextVoxel( DataSetPtr dataset, JobType& job, DirFunc const& dirFunc );
00085 
00086         // one could add a runge-kutta-integrator too
00087 
00088         /**
00089          * Check if a point is on the boundary of the given grid, where boundary
00090          * means a distance less then TRACKING_EPS from any plane between
00091          * voxels. This does not check if the position is actually inside the grid.
00092          *
00093          * \param grid The grid.
00094          * \param pos The position to test.
00095          *
00096          * \return true, iff the position is on any voxel boundary
00097          */
00098         static bool onBoundary( Grid3DPtr grid, WVector3d const& pos );
00099 
00100         /**
00101          * Calculate the distance from a given position to the nearest voxel boundary
00102          * on the ray from the position along the given direction.
00103          *
00104          * \param grid The grid.
00105          * \param pos The starting position of the ray.
00106          * \param dir The normalized direction of the ray.
00107          *
00108          * \return The distance to the next voxel boundary.
00109          *
00110          * \note pos + getDistanceToBoundary( grid, pos, dir ) * dir will be a position on a voxel boundary
00111          */
00112         static double getDistanceToBoundary( Grid3DPtr grid, WVector3d const& pos, WVector3d const& dir );
00113     };
00114 
00115     //////////////////////////////////////////////////////////////////////////////////////////
00116 
00117     /**
00118      * \class WThreadedTrackingFunction
00119      *
00120      * Implements a generalized multithreaded tracking algorithm. A function that calculates the direction
00121      * and a function that calculates a new position have to be provided.
00122      *
00123      * Output values can be retrieved via two visitor functions that get called per fiber tracked and
00124      * per point calculated respectively.
00125      *
00126      * There are a certain number n of seeds per direction, this meens n*n*n seeds per voxel. For every
00127      * seed, m fibers get integrated. These two parameters are the seedPositions and seedsPerVoxel parameters
00128      * of the constructor, respectively.
00129      *
00130      * A 'cubic' region of the grid can be chosen for seeding. The v0 and v1 parameters of the constructor
00131      * are the starting/target voxel coords. Example:
00132      *
00133      * v0: 1, 1, 1
00134      * v1: 4, 5, 3
00135      *
00136      * In this case, only voxels between coords 1 to 3 in the x-direction, the voxels 1 to 4 in y- and the voxels 1 to 2
00137      * in z-direction are used for seeding.
00138      *
00139      * Note that voxels at the first (0) and last (grid->getNbCoords*()) position in any direction are
00140      * invalid seeding voxels as they are partially outside of the grid.
00141      */
00142     class OWDATAHANDLER_EXPORT WThreadedTrackingFunction : public WThreadedJobs< WTrackingUtility::DataSetType, WTrackingUtility::JobType >
00143     {
00144     //! make the test a friend
00145     friend class ::WThreadedTrackingFunctionTest;
00146 
00147     //! the job type
00148     typedef WTrackingUtility::JobType JobType;
00149 
00150     //! the dataset type
00151     typedef WTrackingUtility::DataSetType DataSetType;
00152 
00153     //! a pointer to a dataset
00154     typedef WTrackingUtility::DataSetPtr DataSetPtr;
00155 
00156     //! the grid type
00157     typedef WGridRegular3D GridType;
00158 
00159     //! a pointer to the grid
00160     typedef boost::shared_ptr< GridType > GridPtr;
00161 
00162     //! the direction calculation function
00163     typedef WTrackingUtility::DirFunc DirFunc;
00164 
00165     //! the path integration function
00166     typedef boost::function< bool ( DataSetPtr, JobType&, DirFunc const& ) > NextPositionFunc;
00167 
00168     //! a visitor function for fibers
00169     typedef boost::function< void ( std::vector< WVector3d > const& ) > FiberVisitorFunc;
00170 
00171     //! a visitor function type for points
00172     typedef boost::function< void ( WVector3d const& ) > PointVisitorFunc;
00173 
00174     //! the base class, a threaded job function
00175     typedef WThreadedJobs< DataSetType, JobType > Base;
00176 
00177     //! this type
00178     typedef WThreadedTrackingFunction This;
00179 
00180     public:
00181         /**
00182          * Constructor.
00183          *
00184          * \param dataset A pointer to a dataset.
00185          * \param dirFunc A direction calculation function.
00186          * \param nextFunc A position integration function.
00187          * \param fiberVst A visitor for fibers.
00188          * \param pointVst A visitor for points.
00189          * \param seedPositions The number of seed positions in every direction per voxel.
00190          * \param seedsPerPos The number of fibers startet from every seed position.
00191          * \param v0 A vector of starting voxel indices for every direction.
00192          * \param v1 A vector of target voxel indices for every direction.
00193          */
00194         WThreadedTrackingFunction( DataSetPtr dataset, DirFunc dirFunc, NextPositionFunc nextFunc,
00195                 FiberVisitorFunc fiberVst, PointVisitorFunc pointVst,
00196                 std::size_t seedPositions = 1, std::size_t seedsPerPos = 1,
00197                 std::vector< int > v0 = std::vector< int >(),
00198                 std::vector< int > v1 = std::vector< int >() );
00199 
00200         /**
00201          * Destructor.
00202          */
00203         virtual ~WThreadedTrackingFunction();
00204 
00205         /**
00206          * The job generator.
00207          *
00208          * \param job The next job (output).
00209          *
00210          * \return false, iff there are no more jobs.
00211          */
00212         virtual bool getJob( JobType& job ); // NOLINT
00213 
00214         /**
00215          * The calculation per job.
00216          *
00217          * \param input The input dataset.
00218          * \param job The job.
00219          */
00220         virtual void compute( DataSetPtr input, JobType const& job );
00221 
00222     private:
00223         /**
00224          * \class IndexType
00225          *
00226          * An index for seed positions.
00227          */
00228         class IndexType
00229         {
00230         friend class ::WThreadedTrackingFunctionTest;
00231         public:
00232             /**
00233              * Construct an invalid index.
00234              */
00235             IndexType();
00236 
00237             /**
00238              * Construct an index.
00239              *
00240              * \param grid The grid.
00241              * \param v0 A vector of starting voxel indices for every direction.
00242              * \param v1 A vector of target voxel indices for every direction.
00243              * \param seedPositions The number of seed positions in every direction per voxel.
00244              * \param seedsPerPosition The number of fibers startet from every seed position.
00245              */
00246             IndexType( GridPtr grid, std::vector< int > const& v0,
00247                     std::vector< int > const& v1, std::size_t seedPositions,
00248                     std::size_t seedsPerPosition );
00249 
00250             /**
00251              * Increase the index by one, effectively generating the next seed position.
00252              *
00253              * \return *this
00254              */
00255             IndexType& operator++ ();
00256 
00257             /**
00258              * Check if there aren't any more seed positions.
00259              *
00260              * \return true, iff there aren't any more seed positions.
00261              */
00262             bool done();
00263 
00264             /**
00265              * Create a job from this index.
00266              *
00267              * \return The job that is the current position.
00268              */
00269             JobType job();
00270 
00271         private:
00272             //! a pointer to the grid
00273             GridPtr m_grid;
00274 
00275             //! true, iff there are no more seeds
00276             bool m_done;
00277 
00278             //! the position in the seed space
00279             boost::array< std::size_t, 4 > m_pos;
00280 
00281             //! the minimum position in the seed space
00282             boost::array< std::size_t, 4 > m_min;
00283 
00284             //! the maximum position in the seed space
00285             boost::array< std::size_t, 4 > m_max;
00286 
00287             //! the relative (to the size of a voxel) distance between seeds
00288             double m_offset;
00289             };
00290 
00291             //! a pointer to the grid
00292             GridPtr m_grid;
00293 
00294             //! a function that returns the next direction
00295             DirFunc m_directionFunc;
00296 
00297             //! a function that calculates the next position
00298             NextPositionFunc m_nextPosFunc;
00299 
00300             //! the fiber visitor
00301             FiberVisitorFunc m_fiberVisitor;
00302 
00303             //! the point visitor
00304             PointVisitorFunc m_pointVisitor;
00305 
00306             //! the maximum number of points per forward/backward integration of a fiber
00307             std::size_t m_maxPoints;
00308 
00309             //! the current index/seed position
00310             WSharedObject< IndexType > m_currentIndex;
00311         };
00312 
00313 } /* namespace wtracking */
00314 
00315 #endif  // WTHREADEDTRACKINGFUNCTION_H
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends