HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
ChangeBackground.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2012-2017 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 ChangeBackground.h
32 ///
33 /// @brief Efficient multi-threaded replacement of the background
34 /// values in tree.
35 ///
36 /// @author Ken Museth
37 
38 #ifndef OPENVDB_TOOLS_ChangeBACKGROUND_HAS_BEEN_INCLUDED
39 #define OPENVDB_TOOLS_ChangeBACKGROUND_HAS_BEEN_INCLUDED
40 
41 #include <openvdb/math/Math.h> // for isNegative and negative
42 #include <openvdb/Types.h> // for Index typedef
44 
45 
46 namespace openvdb {
48 namespace OPENVDB_VERSION_NAME {
49 namespace tools {
50 
51 /// @brief Replace the background value in all the nodes of a tree.
52 /// @details The sign of the background value is preserved, and only
53 /// inactive values equal to the old background value are replaced.
54 ///
55 /// @note If a LeafManager is used the cached leaf nodes are reused,
56 /// resulting in slightly better overall performance.
57 ///
58 /// @param tree Tree (or LeafManager) that will have its background value changed
59 /// @param background the new background value
60 /// @param threaded enable or disable threading (threading is enabled by default)
61 /// @param grainSize used to control the threading granularity (default is 32)
62 template<typename TreeOrLeafManagerT>
63 inline void
65  TreeOrLeafManagerT& tree,
66  const typename TreeOrLeafManagerT::ValueType& background,
67  bool threaded = true,
68  size_t grainSize = 32);
69 
70 
71 /// @brief Replace the background value in all the nodes of a floating-point tree
72 /// containing a symmetric narrow-band level set.
73 /// @details All inactive values will be set to +| @a halfWidth | if outside
74 /// and -| @a halfWidth | if inside, where @a halfWidth is half the width
75 /// of the symmetric narrow band.
76 ///
77 /// @note This method is faster than changeBackground since it does not
78 /// perform tests to see if inactive values are equal to the old background value.
79 /// @note If a LeafManager is used the cached leaf nodes are reused,
80 /// resulting in slightly better overall performance.
81 ///
82 /// @param tree Tree (or LeafManager) that will have its background value changed
83 /// @param halfWidth half of the width of the symmetric narrow band
84 /// @param threaded enable or disable threading (threading is enabled by default)
85 /// @param grainSize used to control the threading granularity (default is 32)
86 ///
87 /// @throw ValueError if @a halfWidth is negative (as defined by math::isNegative)
88 template<typename TreeOrLeafManagerT>
89 inline void
91  TreeOrLeafManagerT& tree,
92  const typename TreeOrLeafManagerT::ValueType& halfWidth,
93  bool threaded = true,
94  size_t grainSize = 32);
95 
96 
97 /// @brief Replace the background values in all the nodes of a floating-point tree
98 /// containing a possibly asymmetric narrow-band level set.
99 /// @details All inactive values will be set to +| @a outsideWidth | if outside
100 /// and -| @a insideWidth | if inside, where @a outsideWidth is the outside
101 /// width of the narrow band and @a insideWidth is its inside width.
102 ///
103 /// @note This method is faster than changeBackground since it does not
104 /// perform tests to see if inactive values are equal to the old background value.
105 /// @note If a LeafManager is used the cached leaf nodes are reused,
106 /// resulting in slightly better overall performance.
107 ///
108 /// @param tree Tree (or LeafManager) that will have its background value changed
109 /// @param outsideWidth The width of the outside of the narrow band
110 /// @param insideWidth The width of the inside of the narrow band
111 /// @param threaded enable or disable threading (threading is enabled by default)
112 /// @param grainSize used to control the threading granularity (default is 32)
113 ///
114 /// @throw ValueError if @a outsideWidth is negative or @a insideWidth is
115 /// not negative (as defined by math::isNegative)
116 template<typename TreeOrLeafManagerT>
117 inline void
119  TreeOrLeafManagerT& tree,
120  const typename TreeOrLeafManagerT::ValueType& outsideWidth,
121  const typename TreeOrLeafManagerT::ValueType& insideWidth,
122  bool threaded = true,
123  size_t grainSize = 32);
124 
125 
126 //////////////////////////////////////////////////////
127 
128 
129 // Replaces the background value in a Tree of any type.
130 template<typename TreeOrLeafManagerT>
132 {
133 public:
134  typedef typename TreeOrLeafManagerT::ValueType ValueT;
135  typedef typename TreeOrLeafManagerT::RootNodeType RootT;
136  typedef typename TreeOrLeafManagerT::LeafNodeType LeafT;
137 
138 
139  ChangeBackgroundOp(const TreeOrLeafManagerT& tree, const ValueT& newValue)
140  : mOldValue(tree.root().background())
141  , mNewValue(newValue)
142  {
143  }
144  void operator()(RootT& root) const
145  {
146  for (typename RootT::ValueOffIter it = root.beginValueOff(); it; ++it) this->set(it);
147  root.setBackground(mNewValue, false);
148  }
149  void operator()(LeafT& node) const
150  {
151  for (typename LeafT::ValueOffIter it = node.beginValueOff(); it; ++it) this->set(it);
152  }
153  template<typename NodeT>
154  void operator()(NodeT& node) const
155  {
156  typename NodeT::NodeMaskType mask = node.getValueOffMask();
157  for (typename NodeT::ValueOnIter it(mask.beginOn(), &node); it; ++it) this->set(it);
158  }
159 private:
160 
161  template<typename IterT>
162  inline void set(IterT& iter) const
163  {
164  if (math::isApproxEqual(*iter, mOldValue)) {
165  iter.setValue(mNewValue);
166  } else if (math::isApproxEqual(*iter, math::negative(mOldValue))) {
167  iter.setValue(math::negative(mNewValue));
168  }
169  }
170  const ValueT mOldValue, mNewValue;
171 };// ChangeBackgroundOp
172 
173 
174 // Replaces the background value in a Tree assumed to represent a
175 // level set. It is generally faster than ChangeBackgroundOp.
176 // Note that is follows the sign-convention that outside is positive
177 // and inside is negative!
178 template<typename TreeOrLeafManagerT>
180 {
181 public:
182  typedef typename TreeOrLeafManagerT::ValueType ValueT;
183  typedef typename TreeOrLeafManagerT::RootNodeType RootT;
184  typedef typename TreeOrLeafManagerT::LeafNodeType LeafT;
185 
186  /// @brief Constructor for asymmetric narrow-bands
187  ChangeLevelSetBackgroundOp(const ValueT& outside, const ValueT& inside)
188  : mOutside(outside)
189  , mInside(inside)
190  {
191  if (math::isNegative(mOutside)) {
192  OPENVDB_THROW(ValueError,
193  "ChangeLevelSetBackgroundOp: the outside value cannot be negative!");
194  }
195  if (!math::isNegative(mInside)) {
196  OPENVDB_THROW(ValueError,
197  "ChangeLevelSetBackgroundOp: the inside value must be negative!");
198  }
199  }
200  void operator()(RootT& root) const
201  {
202  for (typename RootT::ValueOffIter it = root.beginValueOff(); it; ++it) this->set(it);
203  root.setBackground(mOutside, false);
204  }
205  void operator()(LeafT& node) const
206  {
207  for(typename LeafT::ValueOffIter it = node.beginValueOff(); it; ++it) this->set(it);
208  }
209  template<typename NodeT>
210  void operator()(NodeT& node) const
211  {
212  typedef typename NodeT::ValueOffIter IterT;
213  for (IterT it(node.getChildMask().beginOff(), &node); it; ++it) this->set(it);
214  }
215 private:
216 
217  template<typename IterT>
218  inline void set(IterT& iter) const
219  {
220  //this is safe since we know ValueType is_floating_point
221  ValueT& v = const_cast<ValueT&>(*iter);
222  v = v < 0 ? mInside : mOutside;
223  }
224  const ValueT mOutside, mInside;
225 };// ChangeLevelSetBackgroundOp
226 
227 
228 template<typename TreeOrLeafManagerT>
229 inline void
231  TreeOrLeafManagerT& tree,
232  const typename TreeOrLeafManagerT::ValueType& background,
233  bool threaded,
234  size_t grainSize)
235 {
236  tree::NodeManager<TreeOrLeafManagerT> linearTree(tree);
237  ChangeBackgroundOp<TreeOrLeafManagerT> op(tree, background);
238  linearTree.foreachTopDown(op, threaded, grainSize);
239 }
240 
241 
242 template<typename TreeOrLeafManagerT>
243 inline void
245  TreeOrLeafManagerT& tree,
246  const typename TreeOrLeafManagerT::ValueType& outsideValue,
247  const typename TreeOrLeafManagerT::ValueType& insideValue,
248  bool threaded,
249  size_t grainSize)
250 {
251  tree::NodeManager<TreeOrLeafManagerT> linearTree(tree);
252  ChangeLevelSetBackgroundOp<TreeOrLeafManagerT> op(outsideValue, insideValue);
253  linearTree.foreachTopDown(op, threaded, grainSize);
254 }
255 
256 
257 // If the narrow-band is symmetric only one background value is required
258 template<typename TreeOrLeafManagerT>
259 inline void
261  TreeOrLeafManagerT& tree,
262  const typename TreeOrLeafManagerT::ValueType& background,
263  bool threaded,
264  size_t grainSize)
265 {
267  tree, background, math::negative(background), threaded, grainSize);
268 }
269 
270 } // namespace tools
271 } // namespace OPENVDB_VERSION_NAME
272 } // namespace openvdb
273 
274 #endif // OPENVDB_TOOLS_CHANGEBACKGROUND_HAS_BEEN_INCLUDED
275 
276 // Copyright (c) 2012-2017 DreamWorks Animation LLC
277 // All rights reserved. This software is distributed under the
278 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
T negative(const T &val)
Return the unary negation of the given value.
Definition: Math.h:116
const GLdouble * v
Definition: glcorearb.h:836
png_infop png_color_16p * background
Definition: png.h:2326
void changeBackground(TreeOrLeafManagerT &tree, const typename TreeOrLeafManagerT::ValueType &background, bool threaded=true, size_t grainSize=32)
Replace the background value in all the nodes of a tree.
void changeLevelSetBackground(TreeOrLeafManagerT &tree, const typename TreeOrLeafManagerT::ValueType &halfWidth, bool threaded=true, size_t grainSize=32)
Replace the background value in all the nodes of a floating-point tree containing a symmetric narrow-...
GLint GLuint mask
Definition: glcorearb.h:123
bool isNegative(const Type &x)
Return true if x is less than zero.
Definition: Math.h:354
To facilitate threading over the nodes of a tree, cache node pointers in linear arrays, one for each level of the tree.
Definition: NodeManager.h:57
#define OPENVDB_VERSION_NAME
Definition: version.h:43
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
bool isApproxEqual(const Type &a, const Type &b)
Return true if a is equal to b to within the default floating-point comparison tolerance.
Definition: Math.h:370
ChangeLevelSetBackgroundOp(const ValueT &outside, const ValueT &inside)
Constructor for asymmetric narrow-bands.
ChangeBackgroundOp(const TreeOrLeafManagerT &tree, const ValueT &newValue)
NodeManager produces linear arrays of all tree nodes allowing for efficient threading and bottom-up p...
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:71
void foreachTopDown(const NodeOp &op, bool threaded=true, size_t grainSize=1)
Threaded method that applies a user-supplied functor to all the nodes in the tree.
Definition: NodeManager.h:498
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:101
void changeAsymmetricLevelSetBackground(TreeOrLeafManagerT &tree, const typename TreeOrLeafManagerT::ValueType &outsideWidth, const typename TreeOrLeafManagerT::ValueType &insideWidth, bool threaded=true, size_t grainSize=32)
Replace the background values in all the nodes of a floating-point tree containing a possibly asymmet...