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 #include <boost/array.hpp>
34 
35 #include "../common/math/linearAlgebra/WVectorFixed.h"
36 #include "../common/WSharedObject.h"
37 #include "../common/WThreadedJobs.h"
38 
39 #include "WDataSetSingle.h"
40 
41 class WThreadedTrackingFunctionTest; //! forward declaration
42 
43 
44 /**
45  * For tracking related functionality.
46  */
47 namespace wtracking // note that this is not final
48 {
49  // an epsilon value for various floating point comparisons
50 #if INTPTR_MAX == INT32_MAX
51  #define TRACKING_EPS 0.00001
52 #else
53  #define TRACKING_EPS 0.0000001
54 #endif
55 
56  /**
57  * \class WTrackingUtility
58  *
59  * A class that provides untility functions and typedefs for tracking algorithms.
60  */
62  {
63  public:
64  //! define a job type for tracking algorithms
65  typedef std::pair< WVector3d, WVector3d > JobType;
66 
67  //! the dataset type
69 
70  //! a pointer to a dataset
71  typedef boost::shared_ptr< DataSetType const > DataSetPtr;
72 
73  //! a function that calculates a direction to continue tracking
74  typedef boost::function< WVector3d ( DataSetPtr, JobType const& ) > DirFunc;
75 
76  //! a pointer to a regular 3d grid
77  // other grid types are not supported at the moment
78  typedef boost::shared_ptr< WGridRegular3D > Grid3DPtr;
79 
80  /**
81  * A function that follows a direction until leaving the current voxel.
82  *
83  * \param dataset A pointer to the input dataset.
84  * \param job A pair of vectors, the position and the direction of the last integration.
85  * \param dirFunc A function that computes the next direction.
86  *
87  * \return true, iff the calculated point is a valid position inside the grid
88  */
89  static bool followToNextVoxel( DataSetPtr dataset, JobType& job, DirFunc const& dirFunc );
90 
91  // one could add a runge-kutta-integrator too
92 
93  /**
94  * Check if a point is on the boundary of the given grid, where boundary
95  * means a distance less then TRACKING_EPS from any plane between
96  * voxels. This does not check if the position is actually inside the grid.
97  *
98  * \param grid The grid.
99  * \param pos The position to test.
100  *
101  * \return true, iff the position is on any voxel boundary
102  */
103  static bool onBoundary( Grid3DPtr grid, WVector3d const& pos );
104 
105  /**
106  * Calculate the distance from a given position to the nearest voxel boundary
107  * on the ray from the position along the given direction.
108  *
109  * \param grid The grid.
110  * \param pos The starting position of the ray.
111  * \param dir The normalized direction of the ray.
112  *
113  * \return The distance to the next voxel boundary.
114  *
115  * \note pos + getDistanceToBoundary( grid, pos, dir ) * dir will be a position on a voxel boundary
116  */
117  static double getDistanceToBoundary( Grid3DPtr grid, WVector3d const& pos, WVector3d const& dir );
118  };
119 
120  //////////////////////////////////////////////////////////////////////////////////////////
121 
122  /**
123  * \class WThreadedTrackingFunction
124  *
125  * Implements a generalized multithreaded tracking algorithm. A function that calculates the direction
126  * and a function that calculates a new position have to be provided.
127  *
128  * Output values can be retrieved via two visitor functions that get called per fiber tracked and
129  * per point calculated respectively.
130  *
131  * There are a certain number n of seeds per direction, this meens n*n*n seeds per voxel. For every
132  * seed, m fibers get integrated. These two parameters are the seedPositions and seedsPerVoxel parameters
133  * of the constructor, respectively.
134  *
135  * A 'cubic' region of the grid can be chosen for seeding. The v0 and v1 parameters of the constructor
136  * are the starting/target voxel coords. Example:
137  *
138  * v0: 1, 1, 1
139  * v1: 4, 5, 3
140  *
141  * 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
142  * in z-direction are used for seeding.
143  *
144  * Note that voxels at the first (0) and last (grid->getNbCoords*()) position in any direction are
145  * invalid seeding voxels as they are partially outside of the grid.
146  */
147  class WThreadedTrackingFunction : public WThreadedJobs< WTrackingUtility::DataSetType, WTrackingUtility::JobType >
148  {
149  //! make the test a friend
150  friend class ::WThreadedTrackingFunctionTest;
151 
152  //! the job type
154 
155  //! the dataset type
157 
158  //! a pointer to a dataset
160 
161  //! the grid type
163 
164  //! a pointer to the grid
165  typedef boost::shared_ptr< GridType > GridPtr;
166 
167  //! the direction calculation function
169 
170  //! the path integration function
171  typedef boost::function< bool ( DataSetPtr, JobType&, DirFunc const& ) > NextPositionFunc;
172 
173  //! a visitor function for fibers
174  typedef boost::function< void ( std::vector< WVector3d > const& ) > FiberVisitorFunc;
175 
176  //! a visitor function type for points
177  typedef boost::function< void ( WVector3d const& ) > PointVisitorFunc;
178 
179  //! the base class, a threaded job function
181 
182  //! this type
184 
185  public:
186  /**
187  * Constructor.
188  *
189  * \param dataset A pointer to a dataset.
190  * \param dirFunc A direction calculation function.
191  * \param nextFunc A position integration function.
192  * \param fiberVst A visitor for fibers.
193  * \param pointVst A visitor for points.
194  * \param seedPositions The number of seed positions in every direction per voxel.
195  * \param seedsPerPos The number of fibers startet from every seed position.
196  * \param v0 A vector of starting voxel indices for every direction.
197  * \param v1 A vector of target voxel indices for every direction.
198  */
199  WThreadedTrackingFunction( DataSetPtr dataset, DirFunc dirFunc, NextPositionFunc nextFunc,
200  FiberVisitorFunc fiberVst, PointVisitorFunc pointVst,
201  std::size_t seedPositions = 1, std::size_t seedsPerPos = 1,
202  std::vector< int > v0 = std::vector< int >(),
203  std::vector< int > v1 = std::vector< int >() );
204 
205  /**
206  * Destructor.
207  */
208  virtual ~WThreadedTrackingFunction();
209 
210  /**
211  * The job generator.
212  *
213  * \param job The next job (output).
214  *
215  * \return false, iff there are no more jobs.
216  */
217  virtual bool getJob( JobType& job ); // NOLINT
218 
219  /**
220  * The calculation per job.
221  *
222  * \param input The input dataset.
223  * \param job The job.
224  */
225  virtual void compute( DataSetPtr input, JobType const& job );
226 
227  private:
228  /**
229  * \class IndexType
230  *
231  * An index for seed positions.
232  */
233  class IndexType
234  {
235  friend class ::WThreadedTrackingFunctionTest;
236  public:
237  /**
238  * Construct an invalid index.
239  */
240  IndexType();
241 
242  /**
243  * Construct an index.
244  *
245  * \param grid The grid.
246  * \param v0 A vector of starting voxel indices for every direction.
247  * \param v1 A vector of target voxel indices for every direction.
248  * \param seedPositions The number of seed positions in every direction per voxel.
249  * \param seedsPerPosition The number of fibers startet from every seed position.
250  */
251  IndexType( GridPtr grid, std::vector< int > const& v0,
252  std::vector< int > const& v1, std::size_t seedPositions,
253  std::size_t seedsPerPosition );
254 
255  /**
256  * Increase the index by one, effectively generating the next seed position.
257  *
258  * \return *this
259  */
261 
262  /**
263  * Check if there aren't any more seed positions.
264  *
265  * \return true, iff there aren't any more seed positions.
266  */
267  bool done();
268 
269  /**
270  * Create a job from this index.
271  *
272  * \return The job that is the current position.
273  */
274  JobType job();
275 
276  private:
277  //! a pointer to the grid
279 
280  //! true, iff there are no more seeds
281  bool m_done;
282 
283  //! the position in the seed space
284  boost::array< std::size_t, 4 > m_pos;
285 
286  //! the minimum position in the seed space
287  boost::array< std::size_t, 4 > m_min;
288 
289  //! the maximum position in the seed space
290  boost::array< std::size_t, 4 > m_max;
291 
292  //! the relative (to the size of a voxel) distance between seeds
293  double m_offset;
294  };
295 
296  //! a pointer to the grid
298 
299  //! a function that returns the next direction
301 
302  //! a function that calculates the next position
304 
305  //! the fiber visitor
307 
308  //! the point visitor
310 
311  //! the maximum number of points per forward/backward integration of a fiber
312  std::size_t m_maxPoints;
313 
314  //! the current index/seed position
316  };
317 
318 } /* namespace wtracking */
319 
320 #endif // WTHREADEDTRACKINGFUNCTION_H
A threaded functor base class for producer-consumer-style multithreaded computation.
Definition: WThreadedJobs.h:50
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:41
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.