OpenVDB  1.1.0
LevelSetTracker.h
Go to the documentation of this file.
1 
2 //
3 // Copyright (c) 2012-2013 DreamWorks Animation LLC
4 //
5 // All rights reserved. This software is distributed under the
6 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
7 //
8 // Redistributions of source code must retain the above copyright
9 // and license notice and the following restrictions and disclaimer.
10 //
11 // * Neither the name of DreamWorks Animation nor the names of
12 // its contributors may be used to endorse or promote products derived
13 // from this software without specific prior written permission.
14 //
15 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
19 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
20 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 // IN NO EVENT SHALL THE COPYRIGHT HOLDERS' AND CONTRIBUTORS' AGGREGATE
27 // LIABILITY FOR ALL CLAIMS REGARDLESS OF THEIR BASIS EXCEED US$250.00.
28 //
30 //
38 
39 #ifndef OPENVDB_TOOLS_LEVEL_SET_TRACKER_HAS_BEEN_INCLUDED
40 #define OPENVDB_TOOLS_LEVEL_SET_TRACKER_HAS_BEEN_INCLUDED
41 
42 #include <tbb/parallel_reduce.h>
43 #include <tbb/parallel_for.h>
44 #include <boost/bind.hpp>
45 #include <boost/function.hpp>
46 #include <boost/type_traits/is_floating_point.hpp>
47 #include <openvdb/Types.h>
48 #include <openvdb/math/Math.h>
49 #include <openvdb/math/FiniteDifference.h>
50 #include <openvdb/math/Operators.h>
51 #include <openvdb/math/Stencils.h>
52 #include <openvdb/math/Transform.h>
53 #include <openvdb/Grid.h>
54 #include <openvdb/util/NullInterrupter.h>
55 #include "Morphology.h"//for tools::dilateVoxels
56 
57 namespace openvdb {
59 namespace OPENVDB_VERSION_NAME {
60 namespace tools {
61 
63 template<typename GridT, typename InterruptT = util::NullInterrupter>
65 {
66 public:
67  typedef GridT GridType;
68  typedef typename GridT::TreeType TreeType;
69  typedef typename TreeType::LeafNodeType LeafType;
70  typedef typename TreeType::ValueType ValueType;
71  typedef typename tree::LeafManager<TreeType> LeafManagerType; // leafs + buffers
74  BOOST_STATIC_ASSERT(boost::is_floating_point<ValueType>::value);
75 
77  LevelSetTracker(GridT& grid, InterruptT* interrupt = NULL);
78 
80  LevelSetTracker(const LevelSetTracker& other);
81 
82  virtual ~LevelSetTracker() { if (mIsMaster) delete mLeafs; }
83 
85  void normalize();
86 
89  void track();
90 
92  void prune();
93 
95  math::BiasedGradientScheme getSpatialScheme() const { return mSpatialScheme; }
97  void setSpatialScheme(math::BiasedGradientScheme scheme) { mSpatialScheme = scheme; }
98 
100  math::TemporalIntegrationScheme getTemporalScheme() const { return mTemporalScheme; }
102  void setTemporalScheme(math::TemporalIntegrationScheme scheme) { mTemporalScheme = scheme; }
103 
106  int getNormCount() const { return mNormCount; }
109  void setNormCount(int n) { mNormCount = n; }
110 
112  int getGrainSize() const { return mGrainSize; }
115  void setGrainSize(int grainsize) { mGrainSize = grainsize; }
116 
117  ValueType voxelSize() const { return mDx; }
118 
119  void startInterrupter(const char* msg);
120  void endInterrupter();
122  bool checkInterrupter();
123 
124  const GridType& grid() const { return mGrid; }
125 
128  void operator()(const RangeType& r) const
129  {
130  if (mTask) mTask(const_cast<LevelSetTracker*>(this), r);
131  else OPENVDB_THROW(ValueError, "task is undefined - call track(), etc");
132  }
133 
134 protected:
135 
136  template<math::BiasedGradientScheme SpatialScheme,
137  math::TemporalIntegrationScheme TemporalScheme>
138  struct Normalizer
139  {
140  Normalizer(LevelSetTracker& tracker): mTracker(tracker), mTask(0) {}
141  void normalize();
142  void operator()(const RangeType& r) const {mTask(const_cast<Normalizer*>(this), r);}
143  typedef typename boost::function<void (Normalizer*, const RangeType&)> FuncType;
146  void cook(int swapBuffer=0);
147  void euler1(const RangeType& range, ValueType dt, Index resultBuffer);
148  void euler2(const RangeType& range, ValueType dt, ValueType alpha,
149  Index phiBuffer, Index resultBuffer);
150  }; // end of protected Normalizer class
151 
152  // required to access mLeafs
153  template<typename, typename, typename>
154  friend class LevelSetAdvection;
155 
157  // Throughout the methods below mLeafs is always assumed to contain
158  // a list of the current LeafNodes! The auxiliary buffers on the
159  // other hand always have to be allocated locally, since some
160  // methods need them and others don't!
162  InterruptT* mInterrupter;
163  const ValueType mDx;
164 
165 private:
166  typedef typename boost::function<void (LevelSetTracker*, const RangeType&)> FuncType;
167 
168  void trim(const RangeType& r);
169 
170  template<math::BiasedGradientScheme SpatialScheme>
171  void normalize1();
172 
173  template<math::BiasedGradientScheme SpatialScheme,
174  math::TemporalIntegrationScheme TemporalScheme>
175  void normalize2();
176 
177  math::BiasedGradientScheme mSpatialScheme;
178  math::TemporalIntegrationScheme mTemporalScheme;
179  int mNormCount;// Number of iteratations of normalization
180  int mGrainSize;
181  FuncType mTask;
182  const bool mIsMaster;
183 
184  // disallow copy by assignment
185  void operator=(const LevelSetTracker& other) {}
186 
187 }; // end of LevelSetTracker class
188 
189 template<typename GridT, typename InterruptT>
190 LevelSetTracker<GridT, InterruptT>::LevelSetTracker(GridT& grid, InterruptT* interrupt):
191  mGrid(grid),
192  mLeafs(new LeafManagerType(grid.tree())),
193  mInterrupter(interrupt),
194  mDx(grid.voxelSize()[0]),
195  mSpatialScheme(math::HJWENO5_BIAS),
196  mTemporalScheme(math::TVD_RK1),
197  mNormCount(static_cast<int>(LEVEL_SET_HALF_WIDTH)),
198  mGrainSize(1),
199  mTask(0),
200  mIsMaster(true)// N.B.
201 {
202  if ( !grid.hasUniformVoxels() ) {
204  "The transform must have uniform scale for the LevelSetTracker to function");
205  }
206  if ( grid.getGridClass() != GRID_LEVEL_SET) {
208  "LevelSetTracker only supports level sets!\n"
209  "However, only level sets are guaranteed to work!\n"
210  "Hint: Grid::setGridClass(openvdb::GRID_LEVEL_SET)");
211  }
212 }
213 
214 template<typename GridT, typename InterruptT>
216  mGrid(other.mGrid),
217  mLeafs(other.mLeafs),
218  mInterrupter(other.mInterrupter),
219  mDx(other.mDx),
220  mSpatialScheme(other.mSpatialScheme),
221  mTemporalScheme(other.mTemporalScheme),
222  mNormCount(other.mNormCount),
223  mGrainSize(other.mGrainSize),
224  mTask(other.mTask),
225  mIsMaster(false)// N.B.
226 {
227 }
228 
229 template<typename GridT, typename InterruptT>
230 inline void
232 {
233  this->startInterrupter("Pruning Level Set");
234  // Prune voxels that are too far away from the zero-crossing
235  mTask = boost::bind(&LevelSetTracker::trim, _1, _2);
236  if (mGrainSize>0) {
237  tbb::parallel_for(mLeafs->getRange(mGrainSize), *this);
238  } else {
239  (*this)(mLeafs->getRange());
240  }
241 
242  // Remove inactive nodes from tree
243  mGrid.tree().pruneLevelSet();
244 
245  // The tree topology has changes so rebuild the list of leafs
246  mLeafs->rebuildLeafArray();
247  this->endInterrupter();
248 }
249 
250 template<typename GridT, typename InterruptT>
251 inline void
253 {
254  // Dilate narrow-band (this also rebuilds the leaf array!)
255  tools::dilateVoxels(*mLeafs);
256 
257  // Compute signed distances in dilated narrow-band
258  this->normalize();
259 
260  // Remove voxels that are outside the narrow band
261  this->prune();
262 }
263 
264 template<typename GridT, typename InterruptT>
265 inline void
267 {
268  if (mInterrupter) mInterrupter->start(msg);
269 }
270 
271 template<typename GridT, typename InterruptT>
272 inline void
274 {
275  if (mInterrupter) mInterrupter->end();
276 }
277 
278 template<typename GridT, typename InterruptT>
279 inline bool
281 {
282  if (util::wasInterrupted(mInterrupter)) {
283  tbb::task::self().cancel_group_execution();
284  return false;
285  }
286  return true;
287 }
288 
290 template<typename GridT, typename InterruptT>
291 inline void
292 LevelSetTracker<GridT, InterruptT>::trim(const RangeType& range)
293 {
294  typedef typename LeafType::ValueOnIter VoxelIterT;
295  const_cast<LevelSetTracker*>(this)->checkInterrupter();
296  const ValueType gamma = mGrid.background();
297  for (size_t n=range.begin(), e=range.end(); n != e; ++n) {
298  LeafType &leaf = mLeafs->leaf(n);
299  for (VoxelIterT iter = leaf.beginValueOn(); iter; ++iter) {
300  const ValueType val = *iter;
301  if (val < -gamma)
302  leaf.setValueOff(iter.pos(), -gamma);
303  else if (val > gamma)
304  leaf.setValueOff(iter.pos(), gamma);
305  }
306  }
307 }
308 
309 template<typename GridT, typename InterruptT>
310 inline void
312 {
313  switch (mSpatialScheme) {
314  case math::FIRST_BIAS:
315  this->normalize1<math::FIRST_BIAS >(); break;
316  case math::SECOND_BIAS:
317  this->normalize1<math::SECOND_BIAS >(); break;
318  case math::THIRD_BIAS:
319  this->normalize1<math::THIRD_BIAS >(); break;
320  case math::WENO5_BIAS:
321  this->normalize1<math::WENO5_BIAS >(); break;
322  case math::HJWENO5_BIAS:
323  this->normalize1<math::HJWENO5_BIAS>(); break;
324  default:
325  OPENVDB_THROW(ValueError, "Spatial difference scheme not supported!");
326  }
327 }
328 
329 template<typename GridT, typename InterruptT>
330 template<math::BiasedGradientScheme SpatialScheme>
331 inline void
333 {
334  switch (mTemporalScheme) {
335  case math::TVD_RK1:
336  this->normalize2<SpatialScheme, math::TVD_RK1>(); break;
337  case math::TVD_RK2:
338  this->normalize2<SpatialScheme, math::TVD_RK2>(); break;
339  case math::TVD_RK3:
340  this->normalize2<SpatialScheme, math::TVD_RK3>(); break;
341  default:
342  OPENVDB_THROW(ValueError, "Temporal integration scheme not supported!");
343  }
344 }
345 
346 template<typename GridT, typename InterruptT>
347 template<math::BiasedGradientScheme SpatialScheme,
348  math::TemporalIntegrationScheme TemporalScheme>
349 inline void
350 LevelSetTracker<GridT, InterruptT>::normalize2()
351 {
352  Normalizer<SpatialScheme, TemporalScheme> tmp(*this);
353  tmp.normalize();
354 }
355 
356 template<typename GridT, typename InterruptT>
357 template<math::BiasedGradientScheme SpatialScheme,
358  math::TemporalIntegrationScheme TemporalScheme>
359 inline void
362 {
364  mTracker.mLeafs->rebuildAuxBuffers(TemporalScheme == math::TVD_RK3 ? 2 : 1);
365 
366  const ValueType dt = (TemporalScheme == math::TVD_RK1 ? ValueType(0.3) :
367  TemporalScheme == math::TVD_RK2 ? ValueType(0.9) : ValueType(1.0))
368  * ValueType(mTracker.voxelSize());
369 
370  for (int n=0, e=mTracker.getNormCount(); n < e; ++n) {
371 
372  switch(TemporalScheme) {//switch is resolved at compile-time
373  case math::TVD_RK1:
374  //std::cerr << "1";
375  // Perform one explicit Euler step: t1 = t0 + dt
376  // Phi_t1(0) = Phi_t0(0) - dt * VdotG_t0(1)
377  mTask = boost::bind(&Normalizer::euler1, _1, _2, dt, /*result=*/1);
378  // Cook and swap buffer 0 and 1 such that Phi_t1(0) and Phi_t0(1)
379  this->cook(1);
380  break;
381  case math::TVD_RK2:
382  //std::cerr << "2";
383  // Perform one explicit Euler step: t1 = t0 + dt
384  // Phi_t1(1) = Phi_t0(0) - dt * VdotG_t0(1)
385  mTask = boost::bind(&Normalizer::euler1, _1, _2, dt, /*result=*/1);
386  // Cook and swap buffer 0 and 1 such that Phi_t1(0) and Phi_t0(1)
387  this->cook(1);
388 
389  // Convex combine explict Euler step: t2 = t0 + dt
390  // Phi_t2(1) = 1/2 * Phi_t0(1) + 1/2 * (Phi_t1(0) - dt * V.Grad_t1(0))
391  mTask = boost::bind(&Normalizer::euler2,
392  _1, _2, dt, ValueType(0.5), /*phi=*/1, /*result=*/1);
393  // Cook and swap buffer 0 and 1 such that Phi_t2(0) and Phi_t1(1)
394  this->cook(1);
395  break;
396  case math::TVD_RK3:
397  //std::cerr << "3";
398  // Perform one explicit Euler step: t1 = t0 + dt
399  // Phi_t1(1) = Phi_t0(0) - dt * VdotG_t0(1)
400  mTask = boost::bind(&Normalizer::euler1, _1, _2, dt, /*result=*/1);
401  // Cook and swap buffer 0 and 1 such that Phi_t1(0) and Phi_t0(1)
402  this->cook(1);
403 
404  // Convex combine explict Euler step: t2 = t0 + dt/2
405  // Phi_t2(2) = 3/4 * Phi_t0(1) + 1/4 * (Phi_t1(0) - dt * V.Grad_t1(0))
406  mTask = boost::bind(&Normalizer::euler2,
407  _1, _2, dt, ValueType(0.75), /*phi=*/1, /*result=*/2);
408  // Cook and swap buffer 0 and 2 such that Phi_t2(0) and Phi_t1(2)
409  this->cook(2);
410 
411  // Convex combine explict Euler step: t3 = t0 + dt
412  // Phi_t3(2) = 1/3 * Phi_t0(1) + 2/3 * (Phi_t2(0) - dt * V.Grad_t2(0)
413  mTask = boost::bind(&Normalizer::euler2,
414  _1, _2, dt, ValueType(1.0/3.0), /*phi=*/1, /*result=*/2);
415  // Cook and swap buffer 0 and 2 such that Phi_t3(0) and Phi_t2(2)
416  this->cook(2);
417  break;
418  default:
419  OPENVDB_THROW(ValueError, "Temporal integration scheme not supported!");
420  }
421  }
422  mTracker.mLeafs->removeAuxBuffers();
423 }
424 
427 template<typename GridT, typename InterruptT>
428 template<math::BiasedGradientScheme SpatialScheme,
429  math::TemporalIntegrationScheme TemporalScheme>
430 inline void
432 cook(int swapBuffer)
433 {
434  mTracker.startInterrupter("Normalizing Level Set");
435 
436  if (mTracker.getGrainSize()>0) {
437  tbb::parallel_for(mTracker.mLeafs->getRange(mTracker.getGrainSize()), *this);
438  } else {
439  (*this)(mTracker.mLeafs->getRange());
440  }
441 
442  mTracker.mLeafs->swapLeafBuffer(swapBuffer, mTracker.getGrainSize()==0);
443 
444  mTracker.endInterrupter();
445 }
446 
447 
451 template<typename GridT, typename InterruptT>
452 template<math::BiasedGradientScheme SpatialScheme,
453  math::TemporalIntegrationScheme TemporalScheme>
454 inline void
456 euler1(const RangeType &range, ValueType dt, Index resultBuffer)
457 {
458  typedef math::BIAS_SCHEME<SpatialScheme> Scheme;
459  typedef typename Scheme::template ISStencil<GridType>::StencilType Stencil;
460  typedef typename LeafType::ValueOnCIter VoxelIterT;
461  mTracker.checkInterrupter();
462  const ValueType one(1.0), invDx = one/mTracker.voxelSize();
463  Stencil stencil(mTracker.grid());
464  for (size_t n=range.begin(), e=range.end(); n != e; ++n) {
465  BufferType& result = mTracker.mLeafs->getBuffer(n, resultBuffer);
466  const LeafType& leaf = mTracker.mLeafs->leaf(n);
467  for (VoxelIterT iter = leaf.cbeginValueOn(); iter; ++iter) {
468  stencil.moveTo(iter);
469  const ValueType normSqGradPhi =
471  const ValueType phi0 = stencil.getValue();
472  const ValueType diff = math::Sqrt(normSqGradPhi)*invDx - one;
473  const ValueType S = phi0 / (math::Sqrt(math::Pow2(phi0) + normSqGradPhi));
474  result.setValue(iter.pos(), phi0 - dt * S * diff);
475  }
476  }
477 }
478 
479 template<typename GridT, typename InterruptT>
480 template<math::BiasedGradientScheme SpatialScheme,
481  math::TemporalIntegrationScheme TemporalScheme>
482 inline void
484 euler2(const RangeType& range, ValueType dt, ValueType alpha, Index phiBuffer, Index resultBuffer)
485 {
486  typedef math::BIAS_SCHEME<SpatialScheme> Scheme;
487  typedef typename Scheme::template ISStencil<GridType>::StencilType Stencil;
488  typedef typename LeafType::ValueOnCIter VoxelIterT;
489  mTracker.checkInterrupter();
490  const ValueType one(1.0), beta = one - alpha, invDx = one/mTracker.voxelSize();
491  Stencil stencil(mTracker.grid());
492  for (size_t n=range.begin(), e=range.end(); n != e; ++n) {
493  const BufferType& phi = mTracker.mLeafs->getBuffer(n, phiBuffer);
494  BufferType& result = mTracker.mLeafs->getBuffer(n, resultBuffer);
495  const LeafType& leaf = mTracker.mLeafs->leaf(n);
496  for (VoxelIterT iter = leaf.cbeginValueOn(); iter; ++iter) {
497  stencil.moveTo(iter);
498  const ValueType normSqGradPhi =
500  const ValueType phi0 = stencil.getValue();
501  const ValueType diff = math::Sqrt(normSqGradPhi)*invDx - one;
502  const ValueType S = phi0 / (math::Sqrt(math::Pow2(phi0) + normSqGradPhi));
503  result.setValue(iter.pos(), alpha*phi[iter.pos()] + beta*(phi0 - dt * S * diff));
504  }
505  }
506 }
507 
508 } // namespace tools
509 } // namespace OPENVDB_VERSION_NAME
510 } // namespace openvdb
511 
512 #endif // OPENVDB_TOOLS_LEVEL_SET_TRACKER_HAS_BEEN_INCLUDED
513 
514 // Copyright (c) 2012-2013 DreamWorks Animation LLC
515 // All rights reserved. This software is distributed under the
516 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )