OpenWalnut  1.4.0
WThreadedTrackingFunction.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WTHREADEDTRACKINGFUNCTION_H
26 #define WTHREADEDTRACKINGFUNCTION_H
27 
28 #include <stdint.h>
29 
30 #include <vector>
31 #include <utility>
32 
33 #ifndef Q_MOC_RUN
34 #include <boost/array.hpp>
35 #endif
36 
37 #include "../common/math/linearAlgebra/WVectorFixed.h"
38 #include "../common/WSharedObject.h"
39 #include "../common/WThreadedJobs.h"
40 
41 #include "WDataSetSingle.h"
42 
43 class WThreadedTrackingFunctionTest; //! forward declaration
44 
45 
46 /**
47  * For tracking related functionality.
48  */
49 namespace wtracking // note that this is not final
50 {
51  // an epsilon value for various floating point comparisons
52 #if INTPTR_MAX == INT32_MAX
53  #define TRACKING_EPS 0.00001
54 #else
55  #define TRACKING_EPS 0.0000001
56 #endif
57 
58  /**
59  * \class WTrackingUtility
60  *
61  * A class that provides untility functions and typedefs for tracking algorithms.
62  */
64  {
65  public:
66  //! define a job type for tracking algorithms
67  typedef std::pair< WVector3d, WVector3d > JobType;
68 
69  //! the dataset type
71 
72  //! a pointer to a dataset
73  typedef boost::shared_ptr< DataSetType const > DataSetPtr;
74 
75  //! a function that calculates a direction to continue tracking
76  typedef boost::function< WVector3d ( DataSetPtr, JobType const& ) > DirFunc;
77 
78  //! a pointer to a regular 3d grid
79  // other grid types are not supported at the moment
80  typedef boost::shared_ptr< WGridRegular3D > Grid3DPtr;
81 
82  /**
83  * A function that follows a direction until leaving the current voxel.
84  *
85  * \param dataset A pointer to the input dataset.
86  * \param job A pair of vectors, the position and the direction of the last integration.
87  * \param dirFunc A function that computes the next direction.
88  *
89  * \return true, iff the calculated point is a valid position inside the grid
90  */
91  static bool followToNextVoxel( DataSetPtr dataset, JobType& job, DirFunc const& dirFunc );
92 
93  // one could add a runge-kutta-integrator too
94 
95  /**
96  * Check if a point is on the boundary of the given grid, where boundary
97  * means a distance less then TRACKING_EPS from any plane between
98  * voxels. This does not check if the position is actually inside the grid.
99  *
100  * \param grid The grid.
101  * \param pos The position to test.
102  *
103  * \return true, iff the position is on any voxel boundary
104  */
105  static bool onBoundary( Grid3DPtr grid, WVector3d const& pos );
106 
107  /**
108  * Calculate the distance from a given position to the nearest voxel boundary
109  * on the ray from the position along the given direction.
110  *
111  * \param grid The grid.
112  * \param pos The starting position of the ray.
113  * \param dir The normalized direction of the ray.
114  *
115  * \return The distance to the next voxel boundary.
116  *
117  * \note pos + getDistanceToBoundary( grid, pos, dir ) * dir will be a position on a voxel boundary
118  */
119  static double getDistanceToBoundary( Grid3DPtr grid, WVector3d const& pos, WVector3d const& dir );
120  };
121 
122  //////////////////////////////////////////////////////////////////////////////////////////
123 
124  /**
125  * \class WThreadedTrackingFunction
126  *
127  * Implements a generalized multithreaded tracking algorithm. A function that calculates the direction
128  * and a function that calculates a new position have to be provided.
129  *
130  * Output values can be retrieved via two visitor functions that get called per fiber tracked and
131  * per point calculated respectively.
132  *
133  * There are a certain number n of seeds per direction, this meens n*n*n seeds per voxel. For every
134  * seed, m fibers get integrated. These two parameters are the seedPositions and seedsPerVoxel parameters
135  * of the constructor, respectively.
136  *
137  * A 'cubic' region of the grid can be chosen for seeding. The v0 and v1 parameters of the constructor
138  * are the starting/target voxel coords. Example:
139  *
140  * v0: 1, 1, 1
141  * v1: 4, 5, 3
142  *
143  * 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
144  * in z-direction are used for seeding.
145  *
146  * Note that voxels at the first (0) and last (grid->getNbCoords*()) position in any direction are
147  * invalid seeding voxels as they are partially outside of the grid.
148  */
149  class WThreadedTrackingFunction : public WThreadedJobs< WTrackingUtility::DataSetType, WTrackingUtility::JobType >
150  {
151  //! make the test a friend
152  friend class ::WThreadedTrackingFunctionTest;
153 
154  //! the job type
156 
157  //! the dataset type
159 
160  //! a pointer to a dataset
162 
163  //! the grid type
165 
166  //! a pointer to the grid
167  typedef boost::shared_ptr< GridType > GridPtr;
168 
169  //! the direction calculation function
171 
172  //! the path integration function
173  typedef boost::function< bool ( DataSetPtr, JobType&, DirFunc const& ) > NextPositionFunc;
174 
175  //! a visitor function for fibers
176  typedef boost::function< void ( std::vector< WVector3d > const& ) > FiberVisitorFunc;
177 
178  //! a visitor function type for points
179  typedef boost::function< void ( WVector3d const& ) > PointVisitorFunc;
180 
181  //! the base class, a threaded job function
183 
184  //! this type
186 
187  public:
188  /**
189  * Constructor.
190  *
191  * \param dataset A pointer to a dataset.
192  * \param dirFunc A direction calculation function.
193  * \param nextFunc A position integration function.
194  * \param fiberVst A visitor for fibers.
195  * \param pointVst A visitor for points.
196  * \param seedPositions The number of seed positions in every direction per voxel.
197  * \param seedsPerPos The number of fibers startet from every seed position.
198  * \param v0 A vector of starting voxel indices for every direction.
199  * \param v1 A vector of target voxel indices for every direction.
200  */
201  WThreadedTrackingFunction( DataSetPtr dataset, DirFunc dirFunc, NextPositionFunc nextFunc,
202  FiberVisitorFunc fiberVst, PointVisitorFunc pointVst,
203  std::size_t seedPositions = 1, std::size_t seedsPerPos = 1,
204  std::vector< int > v0 = std::vector< int >(),
205  std::vector< int > v1 = std::vector< int >() );
206 
207  /**
208  * Destructor.
209  */
210  virtual ~WThreadedTrackingFunction();
211 
212  /**
213  * The job generator.
214  *
215  * \param job The next job (output).
216  *
217  * \return false, iff there are no more jobs.
218  */
219  virtual bool getJob( JobType& job ); // NOLINT
220 
221  /**
222  * The calculation per job.
223  *
224  * \param input The input dataset.
225  * \param job The job.
226  */
227  virtual void compute( DataSetPtr input, JobType const& job );
228 
229  private:
230  /**
231  * \class IndexType
232  *
233  * An index for seed positions.
234  */
235  class IndexType
236  {
237  friend class ::WThreadedTrackingFunctionTest;
238  public:
239  /**
240  * Construct an invalid index.
241  */
242  IndexType();
243 
244  /**
245  * Construct an index.
246  *
247  * \param grid The grid.
248  * \param v0 A vector of starting voxel indices for every direction.
249  * \param v1 A vector of target voxel indices for every direction.
250  * \param seedPositions The number of seed positions in every direction per voxel.
251  * \param seedsPerPosition The number of fibers startet from every seed position.
252  */
253  IndexType( GridPtr grid, std::vector< int > const& v0,
254  std::vector< int > const& v1, std::size_t seedPositions,
255  std::size_t seedsPerPosition );
256 
257  /**
258  * Increase the index by one, effectively generating the next seed position.
259  *
260  * \return *this
261  */
263 
264  /**
265  * Check if there aren't any more seed positions.
266  *
267  * \return true, iff there aren't any more seed positions.
268  */
269  bool done();
270 
271  /**
272  * Create a job from this index.
273  *
274  * \return The job that is the current position.
275  */
276  JobType job();
277 
278  private:
279  //! a pointer to the grid
280  GridPtr m_grid;
281 
282  //! true, iff there are no more seeds
283  bool m_done;
284 
285  //! the position in the seed space
286  boost::array< std::size_t, 4 > m_pos;
287 
288  //! the minimum position in the seed space
289  boost::array< std::size_t, 4 > m_min;
290 
291  //! the maximum position in the seed space
292  boost::array< std::size_t, 4 > m_max;
293 
294  //! the relative (to the size of a voxel) distance between seeds
295  double m_offset;
296  };
297 
298  //! a pointer to the grid
299  GridPtr m_grid;
300 
301  //! a function that returns the next direction
303 
304  //! a function that calculates the next position
305  NextPositionFunc m_nextPosFunc;
306 
307  //! the fiber visitor
309 
310  //! the point visitor
311  PointVisitorFunc m_pointVisitor;
312 
313  //! the maximum number of points per forward/backward integration of a fiber
314  std::size_t m_maxPoints;
315 
316  //! the current index/seed position
318  };
319 
320 } /* namespace wtracking */
321 
322 #endif // WTHREADEDTRACKINGFUNCTION_H
A threaded functor base class for producer-consumer-style multithreaded computation.
Definition: WThreadedJobs.h:52
WThreadedTrackingFunction This
this type
WTrackingUtility::DataSetPtr DataSetPtr
a pointer to a dataset
boost::function< bool(DataSetPtr, JobType &, DirFunc const &) > NextPositionFunc
the path integration function
A grid that has parallelepiped cells which all have the same proportion.
boost::shared_ptr< GridType > GridPtr
a pointer to the grid
boost::function< void(std::vector< WVector3d > const &) > FiberVisitorFunc
a visitor function for fibers
DirFunc m_directionFunc
a function that returns the next direction
boost::function< void(WVector3d const &) > PointVisitorFunc
a visitor function type for points
std::pair< WVector3d, WVector3d > JobType
define a job type for tracking algorithms
bool done()
Check if there aren't any more seed positions.
boost::shared_ptr< DataSetType const > DataSetPtr
a pointer to a dataset
std::size_t m_maxPoints
the maximum number of points per forward/backward integration of a fiber
boost::array< std::size_t, 4 > m_pos
the position in the seed space
A class that provides untility functions and typedefs for tracking algorithms.
PointVisitorFunc m_pointVisitor
the point visitor
virtual bool getJob(JobType &job)
The job generator.
double m_offset
the relative (to the size of a voxel) distance between seeds
virtual void compute(DataSetPtr input, JobType const &job)
The calculation per job.
WThreadedTrackingFunction(DataSetPtr dataset, DirFunc dirFunc, NextPositionFunc nextFunc, FiberVisitorFunc fiberVst, PointVisitorFunc pointVst, std::size_t seedPositions=1, std::size_t seedsPerPos=1, std::vector< int > v0=std::vector< int >(), std::vector< int > v1=std::vector< int >())
Constructor.
WTrackingUtility::DirFunc DirFunc
the direction calculation function
boost::array< std::size_t, 4 > m_max
the maximum position in the seed space
boost::array< std::size_t, 4 > m_min
the minimum position in the seed space
static bool followToNextVoxel(DataSetPtr dataset, JobType &job, DirFunc const &dirFunc)
A function that follows a direction until leaving the current voxel.
A data set consisting of a set of values based on a grid.
WSharedObject< IndexType > m_currentIndex
the current index/seed position
Wrapper around an object/type for thread safe sharing of objects among multiple threads.
Definition: WSharedObject.h:43
forward declaration
static double getDistanceToBoundary(Grid3DPtr grid, WVector3d const &pos, WVector3d const &dir)
Calculate the distance from a given position to the nearest voxel boundary on the ray from the positi...
Implements a generalized multithreaded tracking algorithm.
boost::shared_ptr< WGridRegular3D > Grid3DPtr
a pointer to a regular 3d grid
WTrackingUtility::DataSetType DataSetType
the dataset type
WThreadedJobs< DataSetType, JobType > Base
the base class, a threaded job function
NextPositionFunc m_nextPosFunc
a function that calculates the next position
Test the WThreadedTrackingFunction class.
static bool onBoundary(Grid3DPtr grid, WVector3d const &pos)
Check if a point is on the boundary of the given grid, where boundary means a distance less then TRAC...
boost::function< WVector3d(DataSetPtr, JobType const &) > DirFunc
a function that calculates a direction to continue tracking
WTrackingUtility::JobType JobType
the job type
FiberVisitorFunc m_fiberVisitor
the fiber visitor
WDataSetSingle DataSetType
the dataset type
IndexType & operator++()
Increase the index by one, effectively generating the next seed position.