HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
LevelSetSphere.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 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 //
29 ///////////////////////////////////////////////////////////////////////////
30 ///
31 /// @file LevelSetSphere.h
32 ///
33 /// @brief Generate a narrow-band level set of sphere.
34 ///
35 /// @note By definition a level set has a fixed narrow band width
36 /// (the half width is defined by LEVEL_SET_HALF_WIDTH in Types.h),
37 /// whereas an SDF can have a variable narrow band width.
38 
39 #ifndef OPENVDB_TOOLS_LEVELSETSPHERE_HAS_BEEN_INCLUDED
40 #define OPENVDB_TOOLS_LEVELSETSPHERE_HAS_BEEN_INCLUDED
41 
42 #include <openvdb/Grid.h>
43 #include <openvdb/Types.h>
44 #include <openvdb/math/Math.h>
46 #include "SignedFloodFill.h"
47 #include <type_traits>
48 
49 #include <tbb/enumerable_thread_specific.h>
50 #include <tbb/parallel_for.h>
51 #include <tbb/parallel_reduce.h>
52 #include <tbb/blocked_range.h>
53 #include <thread>
54 
55 namespace openvdb {
57 namespace OPENVDB_VERSION_NAME {
58 namespace tools {
59 
60 /// @brief Return a grid of type @c GridType containing a narrow-band level set
61 /// representation of a sphere.
62 ///
63 /// @param radius radius of the sphere in world units
64 /// @param center center of the sphere in world units
65 /// @param voxelSize voxel size in world units
66 /// @param halfWidth half the width of the narrow band, in voxel units
67 /// @param interrupt a pointer adhering to the util::NullInterrupter interface
68 /// @param threaded if true multi-threading is enabled (true by default)
69 ///
70 /// @note @c GridType::ValueType must be a floating-point scalar.
71 /// @note The leapfrog algorithm employed in this method is best suited
72 /// for a single large sphere. For multiple small spheres consider
73 /// using the faster algorithm in ParticlesToLevelSet.h
74 template<typename GridType, typename InterruptT>
75 typename GridType::Ptr
76 createLevelSetSphere(float radius, const openvdb::Vec3f& center, float voxelSize,
77  float halfWidth = float(LEVEL_SET_HALF_WIDTH),
78  InterruptT* interrupt = nullptr, bool threaded = true);
79 
80 /// @brief Return a grid of type @c GridType containing a narrow-band level set
81 /// representation of a sphere.
82 ///
83 /// @param radius radius of the sphere in world units
84 /// @param center center of the sphere in world units
85 /// @param voxelSize voxel size in world units
86 /// @param halfWidth half the width of the narrow band, in voxel units
87 /// @param threaded if true multi-threading is enabled (true by default)
88 ///
89 /// @note @c GridType::ValueType must be a floating-point scalar.
90 /// @note The leapfrog algorithm employed in this method is best suited
91 /// for a single large sphere. For multiple small spheres consider
92 /// using the faster algorithm in ParticlesToLevelSet.h
93 template<typename GridType>
94 typename GridType::Ptr
95 createLevelSetSphere(float radius, const openvdb::Vec3f& center, float voxelSize,
96  float halfWidth = float(LEVEL_SET_HALF_WIDTH), bool threaded = true)
97 {
98  return createLevelSetSphere<GridType, util::NullInterrupter>(radius,center,voxelSize,halfWidth,nullptr,threaded);
99 }
100 
101 
102 ////////////////////////////////////////
103 
104 
105 /// @brief Generates a signed distance field (or narrow band level
106 /// set) to a single sphere.
107 ///
108 /// @note The leapfrog algorithm employed in this class is best
109 /// suited for a single large sphere. For multiple small spheres consider
110 /// using the faster algorithm in tools/ParticlesToLevelSet.h
111 template<typename GridT, typename InterruptT = util::NullInterrupter>
113 {
114 public:
115  using TreeT = typename GridT::TreeType;
116  using ValueT = typename GridT::ValueType;
117  using Vec3T = typename math::Vec3<ValueT>;
119  "level set grids must have scalar, floating-point value types");
120 
121  /// @brief Constructor
122  ///
123  /// @param radius radius of the sphere in world units
124  /// @param center center of the sphere in world units
125  /// @param interrupt pointer to optional interrupter. Use template
126  /// argument util::NullInterrupter if no interruption is desired.
127  ///
128  /// @note If the radius of the sphere is smaller than
129  /// 1.5*voxelSize, i.e. the sphere is smaller than the Nyquist
130  /// frequency of the grid, it is ignored!
131  LevelSetSphere(ValueT radius, const Vec3T &center, InterruptT* interrupt = nullptr)
132  : mRadius(radius), mCenter(center), mInterrupt(interrupt)
133  {
134  if (mRadius<=0) OPENVDB_THROW(ValueError, "radius must be positive");
135  }
136 
137  /// @return a narrow-band level set of the sphere
138  ///
139  /// @param voxelSize Size of voxels in world units
140  /// @param halfWidth Half-width of narrow-band in voxel units
141  /// @param threaded If true multi-threading is enabled (true by default)
142  typename GridT::Ptr getLevelSet(ValueT voxelSize, ValueT halfWidth, bool threaded = true)
143  {
144  mGrid = createLevelSet<GridT>(voxelSize, halfWidth);
145  this->rasterSphere(voxelSize, halfWidth, threaded);
146  mGrid->setGridClass(GRID_LEVEL_SET);
147  return mGrid;
148  }
149 
150 private:
151  void rasterSphere(ValueT dx, ValueT w, bool threaded)
152  {
153  if (!(dx>0.0f)) OPENVDB_THROW(ValueError, "voxel size must be positive");
154  if (!(w>1)) OPENVDB_THROW(ValueError, "half-width must be larger than one");
155 
156  // Define radius of sphere and narrow-band in voxel units
157  const ValueT r0 = mRadius/dx, rmax = r0 + w;
158 
159  // Radius below the Nyquist frequency
160  if (r0 < 1.5f) return;
161 
162  // Define center of sphere in voxel units
163  const Vec3T c(mCenter[0]/dx, mCenter[1]/dx, mCenter[2]/dx);
164 
165  // Define bounds of the voxel coordinates
166  const int imin=math::Floor(c[0]-rmax), imax=math::Ceil(c[0]+rmax);
167  const int jmin=math::Floor(c[1]-rmax), jmax=math::Ceil(c[1]+rmax);
168  const int kmin=math::Floor(c[2]-rmax), kmax=math::Ceil(c[2]+rmax);
169 
170  // Allocate a ValueAccessor for accelerated random access
171  typename GridT::Accessor accessor = mGrid->getAccessor();
172 
173  if (mInterrupt) mInterrupt->start("Generating level set of sphere");
174 
175  tbb::enumerable_thread_specific<TreeT> pool(mGrid->tree());
176 
177  auto kernel = [&](const tbb::blocked_range<int>& r) {
178  openvdb::Coord ijk;
179  int &i = ijk[0], &j = ijk[1], &k = ijk[2], m=1;
180  TreeT &tree = pool.local();
181  typename GridT::Accessor acc(tree);
182  // Compute signed distances to sphere using leapfrogging in k
183  for (i = r.begin(); i <= r.end(); ++i) {
184  if (util::wasInterrupted(mInterrupt)) return;
185  const auto x2 = math::Pow2(ValueT(i) - c[0]);
186  for (j = jmin; j <= jmax; ++j) {
187  const auto x2y2 = math::Pow2(ValueT(j) - c[1]) + x2;
188  for (k = kmin; k <= kmax; k += m) {
189  m = 1;
190  // Distance in voxel units to sphere
191  const auto v = math::Sqrt(x2y2 + math::Pow2(ValueT(k)-c[2]))-r0;
192  const auto d = math::Abs(v);
193  if (d < w) { // inside narrow band
194  acc.setValue(ijk, dx*v);// distance in world units
195  } else { // outside narrow band
196  m += math::Floor(d-w);// leapfrog
197  }
198  }//end leapfrog over k
199  }//end loop over j
200  }//end loop over i
201  };// kernel
202 
203  if (threaded) {
204  // The code blow is making use of a TLS container to minimize the number of concurrent trees
205  // initially populated by tbb::parallel_for and subsequently merged by tbb::parallel_reduce.
206  // Experiments have demonstrated this approach to outperform others, including serial reduction
207  // and a custom concurrent reduction implementation.
208  tbb::parallel_for(tbb::blocked_range<int>(imin, imax, 128), kernel);
209  using RangeT = tbb::blocked_range<typename tbb::enumerable_thread_specific<TreeT>::iterator>;
210  struct Op {
211  const bool mDelete;
212  TreeT *mTree;
213  Op(TreeT &tree) : mDelete(false), mTree(&tree) {}
214  Op(const Op& other, tbb::split) : mDelete(true), mTree(new TreeT(other.mTree->background())) {}
215  ~Op() { if (mDelete) delete mTree; }
216  void operator()(RangeT &r) { for (auto i=r.begin(); i!=r.end(); ++i) this->merge(*i);}
217  void join(Op &other) { this->merge(*(other.mTree)); }
218  void merge(TreeT &tree) { mTree->merge(tree, openvdb::MERGE_ACTIVE_STATES); }
219  } op( mGrid->tree() );
220  tbb::parallel_reduce(RangeT(pool.begin(), pool.end(), 4), op);
221  } else {
222  kernel(tbb::blocked_range<int>(imin, imax));//serial
223  mGrid->tree().merge(*pool.begin(), openvdb::MERGE_ACTIVE_STATES);
224  }
225 
226  // Define consistent signed distances outside the narrow-band
227  tools::signedFloodFill(mGrid->tree(), threaded);
228 
229  if (mInterrupt) mInterrupt->end();
230  }
231 
232  const ValueT mRadius;
233  const Vec3T mCenter;
234  InterruptT* mInterrupt;
235  typename GridT::Ptr mGrid;
236 };// LevelSetSphere
237 
238 
239 ////////////////////////////////////////
240 
241 
242 template<typename GridType, typename InterruptT>
243 typename GridType::Ptr
244 createLevelSetSphere(float radius, const openvdb::Vec3f& center, float voxelSize,
245  float halfWidth, InterruptT* interrupt, bool threaded)
246 {
247  // GridType::ValueType is required to be a floating-point scalar.
249  "level set grids must have scalar, floating-point value types");
250 
251  using ValueT = typename GridType::ValueType;
252  LevelSetSphere<GridType, InterruptT> factory(ValueT(radius), center, interrupt);
253  return factory.getLevelSet(ValueT(voxelSize), ValueT(halfWidth), threaded);
254 }
255 
256 } // namespace tools
257 } // namespace OPENVDB_VERSION_NAME
258 } // namespace openvdb
259 
260 #endif // OPENVDB_TOOLS_LEVELSETSPHERE_HAS_BEEN_INCLUDED
261 
262 // Copyright (c) DreamWorks Animation LLC
263 // All rights reserved. This software is distributed under the
264 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
void parallel_for(int64_t start, int64_t end, std::function< void(int64_t index)> &&task, parallel_options opt=parallel_options(0, Split_Y, 1))
Definition: parallel.h:153
int Ceil(float x)
Return the ceiling of x.
Definition: Math.h:830
*Note that the tasks the is the thread number *for the pool
Definition: thread.h:655
Type Pow2(Type x)
Return x2.
Definition: Math.h:522
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:200
const GLdouble * m
Definition: glew.h:9124
const GLdouble * v
Definition: glew.h:1391
LevelSetSphere(ValueT radius, const Vec3T &center, InterruptT *interrupt=nullptr)
Constructor.
GridT::Ptr getLevelSet(ValueT voxelSize, ValueT halfWidth, bool threaded=true)
void OIIO_API split(string_view str, std::vector< string_view > &result, string_view sep=string_view(), int maxsplit=-1)
GLclampf f
Definition: glew.h:3499
Coord Abs(const Coord &xyz)
Definition: Coord.h:542
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
GLubyte GLubyte GLubyte GLubyte w
Definition: glew.h:1890
float Sqrt(float x)
Return the square root of a floating-point value.
Definition: Math.h:735
const GLfloat * c
Definition: glew.h:16296
GridType::Ptr createLevelSetSphere(float radius, const openvdb::Vec3f &center, float voxelSize, float halfWidth=float(LEVEL_SET_HALF_WIDTH), InterruptT *interrupt=nullptr, bool threaded=true)
Return a grid of type GridType containing a narrow-band level set representation of a sphere...
Propagate the signs of distance values from the active voxels in the narrow band to the inactive valu...
Generates a signed distance field (or narrow band level set) to a single sphere.
void signedFloodFill(TreeOrLeafManagerT &tree, bool threaded=true, size_t grainSize=1, Index minLevel=0)
Set the values of all inactive voxels and tiles of a narrow-band level set from the signs of the acti...
GLdouble GLdouble GLdouble r
Definition: glew.h:1406
arg_join< It, char > join(It begin, It end, string_view sep)
Definition: format.h:3326
int Floor(float x)
Return the floor of x.
Definition: Math.h:822
bool wasInterrupted(T *i, int percent=-1)
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:146
GLsizei const GLfloat * value
Definition: glew.h:1849
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:109
math::Vec3< float > Vec3f
Definition: Types.h:81