HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Grid.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: MPL-2.0
3 
4 #ifndef OPENVDB_GRID_HAS_BEEN_INCLUDED
5 #define OPENVDB_GRID_HAS_BEEN_INCLUDED
6 
7 #include "Exceptions.h"
8 #include "MetaMap.h"
9 #include "Types.h"
10 #include "io/io.h"
11 #include "math/Transform.h"
12 #include "tree/Tree.h"
13 #include "util/logging.h"
14 #include "util/Name.h"
15 #include <cassert>
16 #include <iostream>
17 #include <set>
18 #include <type_traits>
19 #include <vector>
20 
21 
22 namespace openvdb {
24 namespace OPENVDB_VERSION_NAME {
25 
27 
28 template<typename> class Grid; // forward declaration
29 
30 
31 /// @brief Create a new grid of type @c GridType with a given background value.
32 ///
33 /// @note Calling createGrid<GridType>(background) is equivalent to calling
34 /// GridType::create(background).
35 template<typename GridType>
36 inline typename GridType::Ptr createGrid(const typename GridType::ValueType& background);
37 
38 
39 /// @brief Create a new grid of type @c GridType with background value zero.
40 ///
41 /// @note Calling createGrid<GridType>() is equivalent to calling GridType::create().
42 template<typename GridType>
43 inline typename GridType::Ptr createGrid();
44 
45 
46 /// @brief Create a new grid of the appropriate type that wraps the given tree.
47 ///
48 /// @note This function can be called without specifying the template argument,
49 /// i.e., as createGrid(tree).
50 template<typename TreePtrType>
52 
53 
54 /// @brief Create a new grid of type @c GridType classified as a "Level Set",
55 /// i.e., a narrow-band level set.
56 ///
57 /// @note @c GridType::ValueType must be a floating-point scalar.
58 ///
59 /// @param voxelSize the size of a voxel in world units
60 /// @param halfWidth the half width of the narrow band in voxel units
61 ///
62 /// @details The voxel size and the narrow band half width define the grid's
63 /// background value as halfWidth*voxelWidth. The transform is linear
64 /// with a uniform scaling only corresponding to the specified voxel size.
65 ///
66 /// @note It is generally advisable to specify a half-width of the narrow band
67 /// that is larger than one voxel unit, otherwise zero crossings are not guaranteed.
68 template<typename GridType>
69 typename GridType::Ptr createLevelSet(
70  Real voxelSize = 1.0, Real halfWidth = LEVEL_SET_HALF_WIDTH);
71 
72 
73 ////////////////////////////////////////
74 
75 
76 /// @brief Abstract base class for typed grids
78 {
79 public:
82 
83  using GridFactory = Ptr (*)();
84 
85 
86  ~GridBase() override {}
87 
88 
89  /// @name Copying
90  /// @{
91 
92  /// @brief Return a new grid of the same type as this grid whose metadata is a
93  /// deep copy of this grid's and whose tree and transform are shared with this grid.
94  virtual GridBase::Ptr copyGrid() = 0;
95  /// @brief Return a new grid of the same type as this grid whose metadata is a
96  /// deep copy of this grid's and whose tree and transform are shared with this grid.
97  virtual GridBase::ConstPtr copyGrid() const = 0;
98  /// @brief Return a new grid of the same type as this grid whose metadata and
99  /// transform are deep copies of this grid's and whose tree is default-constructed.
100  virtual GridBase::Ptr copyGridWithNewTree() const = 0;
101 
102  /// @brief Return a new grid of the same type as this grid whose tree and transform
103  /// is shared with this grid and whose metadata is provided as an argument.
104  virtual GridBase::ConstPtr copyGridReplacingMetadata(const MetaMap& meta) const = 0;
105  /// @brief Return a new grid of the same type as this grid whose tree is shared with
106  /// this grid, whose metadata is a deep copy of this grid's and whose transform is
107  /// provided as an argument.
108  /// @throw ValueError if the transform pointer is null
109  virtual GridBase::ConstPtr copyGridReplacingTransform(math::Transform::Ptr xform) const = 0;
110  /// @brief Return a new grid of the same type as this grid whose tree is shared with
111  /// this grid and whose transform and metadata are provided as arguments.
112  /// @throw ValueError if the transform pointer is null
113  virtual GridBase::ConstPtr copyGridReplacingMetadataAndTransform(const MetaMap& meta,
114  math::Transform::Ptr xform) const = 0;
115 
116  /// Return a new grid whose metadata, transform and tree are deep copies of this grid's.
117  virtual GridBase::Ptr deepCopyGrid() const = 0;
118 
119  /// @}
120 
121 
122  /// @name Registry
123  /// @{
124 
125  /// Create a new grid of the given (registered) type.
126  static Ptr createGrid(const Name& type);
127 
128  /// Return @c true if the given grid type name is registered.
129  static bool isRegistered(const Name &type);
130 
131  /// Clear the grid type registry.
132  static void clearRegistry();
133 
134  /// @}
135 
136  /// @name Type access
137  /// @{
138 
139  /// Return the name of this grid's type.
140  virtual Name type() const = 0;
141  /// Return the name of the type of a voxel's value (e.g., "float" or "vec3d").
142  virtual Name valueType() const = 0;
143 
144  /// Return @c true if this grid is of the same type as the template parameter.
145  template<typename GridType>
146  bool isType() const { return (this->type() == GridType::gridType()); }
147 
148  /// @}
149 
150  //@{
151  /// @brief Return the result of downcasting a GridBase pointer to a Grid pointer
152  /// of the specified type, or return a null pointer if the types are incompatible.
153  template<typename GridType>
154  static typename GridType::Ptr grid(const GridBase::Ptr&);
155  template<typename GridType>
156  static typename GridType::ConstPtr grid(const GridBase::ConstPtr&);
157  template<typename GridType>
158  static typename GridType::ConstPtr constGrid(const GridBase::Ptr&);
159  template<typename GridType>
160  static typename GridType::ConstPtr constGrid(const GridBase::ConstPtr&);
161  //@}
162 
163  /// @name Tree
164  /// @{
165 
166  /// @brief Return a pointer to this grid's tree, which might be
167  /// shared with other grids. The pointer is guaranteed to be non-null.
168  TreeBase::Ptr baseTreePtr();
169  /// @brief Return a pointer to this grid's tree, which might be
170  /// shared with other grids. The pointer is guaranteed to be non-null.
171  TreeBase::ConstPtr baseTreePtr() const { return this->constBaseTreePtr(); }
172  /// @brief Return a pointer to this grid's tree, which might be
173  /// shared with other grids. The pointer is guaranteed to be non-null.
174  virtual TreeBase::ConstPtr constBaseTreePtr() const = 0;
175 
176  /// @brief Return true if tree is not shared with another grid.
177  virtual bool isTreeUnique() const = 0;
178 
179  /// @brief Return a reference to this grid's tree, which might be
180  /// shared with other grids.
181  /// @note Calling @vdblink::GridBase::setTree() setTree@endlink
182  /// on this grid invalidates all references previously returned by this method.
183  TreeBase& baseTree() { return const_cast<TreeBase&>(this->constBaseTree()); }
184  /// @brief Return a reference to this grid's tree, which might be
185  /// shared with other grids.
186  /// @note Calling @vdblink::GridBase::setTree() setTree@endlink
187  /// on this grid invalidates all references previously returned by this method.
188  const TreeBase& baseTree() const { return this->constBaseTree(); }
189  /// @brief Return a reference to this grid's tree, which might be
190  /// shared with other grids.
191  /// @note Calling @vdblink::GridBase::setTree() setTree@endlink
192  /// on this grid invalidates all references previously returned by this method.
193  const TreeBase& constBaseTree() const { return *(this->constBaseTreePtr()); }
194 
195  /// @brief Associate the given tree with this grid, in place of its existing tree.
196  /// @throw ValueError if the tree pointer is null
197  /// @throw TypeError if the tree is not of the appropriate type
198  /// @note Invalidates all references previously returned by
199  /// @vdblink::GridBase::baseTree() baseTree@endlink
200  /// or @vdblink::GridBase::constBaseTree() constBaseTree@endlink.
201  virtual void setTree(TreeBase::Ptr) = 0;
202 
203  /// Set a new tree with the same background value as the previous tree.
204  virtual void newTree() = 0;
205 
206  /// @}
207 
208  /// Return @c true if this grid contains only background voxels.
209  virtual bool empty() const = 0;
210  /// Empty this grid, setting all voxels to the background.
211  virtual void clear() = 0;
212 
213 
214  /// @name Tools
215  /// @{
216 
217  /// @brief Reduce the memory footprint of this grid by increasing its sparseness
218  /// either losslessly (@a tolerance = 0) or lossily (@a tolerance > 0).
219  /// @details With @a tolerance > 0, sparsify regions where voxels have the same
220  /// active state and have values that differ by no more than the tolerance
221  /// (converted to this grid's value type).
222  virtual void pruneGrid(float tolerance = 0.0) = 0;
223 
224  /// @brief Clip this grid to the given world-space bounding box.
225  /// @details Voxels that lie outside the bounding box are set to the background.
226  /// @warning Clipping a level set will likely produce a grid that is
227  /// no longer a valid level set.
228  void clipGrid(const BBoxd&);
229 
230  /// @brief Clip this grid to the given index-space bounding box.
231  /// @details Voxels that lie outside the bounding box are set to the background.
232  /// @warning Clipping a level set will likely produce a grid that is
233  /// no longer a valid level set.
234  virtual void clip(const CoordBBox&) = 0;
235 
236  /// @}
237 
238  /// @{
239  /// @brief If this grid resolves to one of the listed grid types,
240  /// invoke the given functor on the resolved grid.
241  /// @return @c false if this grid's type is not one of the listed types
242  ///
243  /// @par Example:
244  /// @code
245  /// using AllowedGridTypes = openvdb::TypeList<
246  /// openvdb::Int32Grid, openvdb::Int64Grid,
247  /// openvdb::FloatGrid, openvdb::DoubleGrid>;
248  ///
249  /// const openvdb::CoordBBox bbox{
250  /// openvdb::Coord{0,0,0}, openvdb::Coord{10,10,10}};
251  ///
252  /// // Fill the grid if it is one of the allowed types.
253  /// myGridBasePtr->apply<AllowedGridTypes>(
254  /// [&bbox](auto& grid) { // C++14
255  /// using GridType = typename std::decay<decltype(grid)>::type;
256  /// grid.fill(bbox, typename GridType::ValueType(1));
257  /// }
258  /// );
259  /// @endcode
260  ///
261  /// @see @vdblink::TypeList TypeList@endlink
262  template<typename GridTypeListT, typename OpT> inline bool apply(OpT&) const;
263  template<typename GridTypeListT, typename OpT> inline bool apply(OpT&);
264  template<typename GridTypeListT, typename OpT> inline bool apply(const OpT&) const;
265  template<typename GridTypeListT, typename OpT> inline bool apply(const OpT&);
266  /// @}
267 
268  /// @name Metadata
269  /// @{
270 
271  /// Return this grid's user-specified name.
272  std::string getName() const;
273  /// Specify a name for this grid.
274  void setName(const std::string&);
275 
276  /// Return the user-specified description of this grid's creator.
277  std::string getCreator() const;
278  /// Provide a description of this grid's creator.
279  void setCreator(const std::string&);
280 
281  /// @brief Return @c true if this grid should be written out with floating-point
282  /// voxel values (including components of vectors) quantized to 16 bits.
283  bool saveFloatAsHalf() const;
284  void setSaveFloatAsHalf(bool);
285 
286  /// @brief Return the class of volumetric data (level set, fog volume, etc.)
287  /// that is stored in this grid.
288  /// @sa gridClassToString, gridClassToMenuName, stringToGridClass
289  GridClass getGridClass() const;
290  /// @brief Specify the class of volumetric data (level set, fog volume, etc.)
291  /// that is stored in this grid.
292  /// @sa gridClassToString, gridClassToMenuName, stringToGridClass
293  void setGridClass(GridClass);
294  /// Remove the setting specifying the class of this grid's volumetric data.
295  void clearGridClass();
296 
297  /// @}
298 
299  /// Return the metadata string value for the given class of volumetric data.
300  static std::string gridClassToString(GridClass);
301  /// Return a formatted string version of the grid class.
302  static std::string gridClassToMenuName(GridClass);
303  /// @brief Return the class of volumetric data specified by the given string.
304  /// @details If the string is not one of the ones returned by
305  /// @vdblink::GridBase::gridClassToString() gridClassToString@endlink,
306  /// return @c GRID_UNKNOWN.
307  static GridClass stringToGridClass(const std::string&);
308 
309  /// @name Metadata
310  /// @{
311 
312  /// @brief Return the type of vector data (invariant, covariant, etc.) stored
313  /// in this grid, assuming that this grid contains a vector-valued tree.
314  /// @sa vecTypeToString, vecTypeExamples, vecTypeDescription, stringToVecType
315  VecType getVectorType() const;
316  /// @brief Specify the type of vector data (invariant, covariant, etc.) stored
317  /// in this grid, assuming that this grid contains a vector-valued tree.
318  /// @sa vecTypeToString, vecTypeExamples, vecTypeDescription, stringToVecType
319  void setVectorType(VecType);
320  /// Remove the setting specifying the type of vector data stored in this grid.
321  void clearVectorType();
322 
323  /// @}
324 
325  /// Return the metadata string value for the given type of vector data.
326  static std::string vecTypeToString(VecType);
327  /// Return a string listing examples of the given type of vector data
328  /// (e.g., "Gradient/Normal", given VEC_COVARIANT).
329  static std::string vecTypeExamples(VecType);
330  /// @brief Return a string describing how the given type of vector data is affected
331  /// by transformations (e.g., "Does not transform", given VEC_INVARIANT).
332  static std::string vecTypeDescription(VecType);
333  static VecType stringToVecType(const std::string&);
334 
335  /// @name Metadata
336  /// @{
337 
338  /// Return @c true if this grid's voxel values are in world space and should be
339  /// affected by transformations, @c false if they are in local space and should
340  /// not be affected by transformations.
341  bool isInWorldSpace() const;
342  /// Specify whether this grid's voxel values are in world space or in local space.
343  void setIsInWorldSpace(bool);
344 
345  /// @}
346 
347  // Standard metadata field names
348  // (These fields should normally not be accessed directly, but rather
349  // via the accessor methods above, when available.)
350  // Note: Visual C++ requires these declarations to be separate statements.
351  static const char* const META_GRID_CLASS;
352  static const char* const META_GRID_CREATOR;
353  static const char* const META_GRID_NAME;
354  static const char* const META_SAVE_HALF_FLOAT;
355  static const char* const META_IS_LOCAL_SPACE;
356  static const char* const META_VECTOR_TYPE;
357  static const char* const META_FILE_BBOX_MIN;
358  static const char* const META_FILE_BBOX_MAX;
359  static const char* const META_FILE_COMPRESSION;
360  static const char* const META_FILE_MEM_BYTES;
361  static const char* const META_FILE_VOXEL_COUNT;
362  static const char* const META_FILE_DELAYED_LOAD;
363 
364 
365  /// @name Statistics
366  /// @{
367 
368  /// Return the number of active voxels.
369  virtual Index64 activeVoxelCount() const = 0;
370 
371  /// Return the axis-aligned bounding box of all active voxels. If
372  /// the grid is empty a default bbox is returned.
373  virtual CoordBBox evalActiveVoxelBoundingBox() const = 0;
374 
375  /// Return the dimensions of the axis-aligned bounding box of all active voxels.
376  virtual Coord evalActiveVoxelDim() const = 0;
377 
378  /// Return the number of bytes of memory used by this grid.
379  virtual Index64 memUsage() const = 0;
380 
381  /// @brief Add metadata to this grid comprising the current values
382  /// of statistics like the active voxel count and bounding box.
383  /// @note This metadata is not automatically kept up-to-date with
384  /// changes to this grid.
385  void addStatsMetadata();
386  /// @brief Return a new MetaMap containing just the metadata that
387  /// was added to this grid with @vdblink::GridBase::addStatsMetadata()
388  /// addStatsMetadata@endlink.
389  /// @details If @vdblink::GridBase::addStatsMetadata() addStatsMetadata@endlink
390  /// was never called on this grid, return an empty MetaMap.
391  MetaMap::Ptr getStatsMetadata() const;
392 
393  /// @}
394 
395 
396  /// @name Transform
397  /// @{
398 
399  //@{
400  /// @brief Return a pointer to this grid's transform, which might be
401  /// shared with other grids.
402  math::Transform::Ptr transformPtr() { return mTransform; }
403  math::Transform::ConstPtr transformPtr() const { return mTransform; }
404  math::Transform::ConstPtr constTransformPtr() const { return mTransform; }
405  //@}
406  //@{
407  /// @brief Return a reference to this grid's transform, which might be
408  /// shared with other grids.
409  /// @note Calling @vdblink::GridBase::setTransform() setTransform@endlink
410  /// on this grid invalidates all references previously returned by this method.
411  math::Transform& transform() { return *mTransform; }
412  const math::Transform& transform() const { return *mTransform; }
413  const math::Transform& constTransform() const { return *mTransform; }
414  //@}
415 
416  /// @}
417 
418  /// @name Transform
419  /// @{
420 
421  /// @brief Associate the given transform with this grid, in place of
422  /// its existing transform.
423  /// @throw ValueError if the transform pointer is null
424  /// @note Invalidates all references previously returned by
425  /// @vdblink::GridBase::transform() transform@endlink
426  /// or @vdblink::GridBase::constTransform() constTransform@endlink.
427  void setTransform(math::Transform::Ptr);
428 
429  /// Return the size of this grid's voxels.
430  Vec3d voxelSize() const { return transform().voxelSize(); }
431  /// @brief Return the size of this grid's voxel at position (x, y, z).
432  /// @note Frustum and perspective transforms have position-dependent voxel size.
433  Vec3d voxelSize(const Vec3d& xyz) const { return transform().voxelSize(xyz); }
434  /// Return true if the voxels in world space are uniformly sized cubes
435  bool hasUniformVoxels() const { return mTransform->hasUniformScale(); }
436  /// Apply this grid's transform to the given coordinates.
437  Vec3d indexToWorld(const Vec3d& xyz) const { return transform().indexToWorld(xyz); }
438  /// Apply this grid's transform to the given coordinates.
439  Vec3d indexToWorld(const Coord& ijk) const { return transform().indexToWorld(ijk); }
440  /// Apply the inverse of this grid's transform to the given coordinates.
441  Vec3d worldToIndex(const Vec3d& xyz) const { return transform().worldToIndex(xyz); }
442 
443  /// @}
444 
445 
446  /// @name I/O
447  /// @{
448 
449  /// @brief Read the grid topology from a stream.
450  /// This will read only the grid structure, not the actual data buffers.
451  virtual void readTopology(std::istream&) = 0;
452  /// @brief Write the grid topology to a stream.
453  /// This will write only the grid structure, not the actual data buffers.
454  virtual void writeTopology(std::ostream&) const = 0;
455 
456  /// Read all data buffers for this grid.
457  virtual void readBuffers(std::istream&) = 0;
458  /// Read all of this grid's data buffers that intersect the given index-space bounding box.
459  virtual void readBuffers(std::istream&, const CoordBBox&) = 0;
460  /// @brief Read all of this grid's data buffers that are not yet resident in memory
461  /// (because delayed loading is in effect).
462  /// @details If this grid was read from a memory-mapped file, this operation
463  /// disconnects the grid from the file.
464  /// @sa io::File::open, io::MappedFile
465  virtual void readNonresidentBuffers() const = 0;
466  /// Write out all data buffers for this grid.
467  virtual void writeBuffers(std::ostream&) const = 0;
468 
469  /// Read in the transform for this grid.
470  void readTransform(std::istream& is) { transform().read(is); }
471  /// Write out the transform for this grid.
472  void writeTransform(std::ostream& os) const { transform().write(os); }
473 
474  /// Output a human-readable description of this grid.
475  virtual void print(std::ostream& = std::cout, int verboseLevel = 1) const = 0;
476 
477  /// @}
478 
479 
480 protected:
481  /// @brief Initialize with an identity linear transform.
482  GridBase(): mTransform(math::Transform::createLinearTransform()) {}
483 
484  /// @brief Initialize with metadata and a transform.
485  /// @throw ValueError if the transform pointer is null
486  GridBase(const MetaMap& meta, math::Transform::Ptr xform);
487 
488  /// @brief Deep copy another grid's metadata and transform.
489  GridBase(const GridBase& other): MetaMap(other), mTransform(other.mTransform->copy()) {}
490 
491  /// @brief Copy another grid's metadata but share its transform.
492  GridBase(GridBase& other, ShallowCopy): MetaMap(other), mTransform(other.mTransform) {}
493 
494  /// Register a grid type along with a factory function.
495  static void registerGrid(const Name& type, GridFactory);
496  /// Remove a grid type from the registry.
497  static void unregisterGrid(const Name& type);
498 
499 
500 private:
501  math::Transform::Ptr mTransform;
502 }; // class GridBase
503 
504 
505 ////////////////////////////////////////
506 
507 
508 using GridPtrVec = std::vector<GridBase::Ptr>;
509 using GridPtrVecIter = GridPtrVec::iterator;
510 using GridPtrVecCIter = GridPtrVec::const_iterator;
512 
513 using GridCPtrVec = std::vector<GridBase::ConstPtr>;
514 using GridCPtrVecIter = GridCPtrVec::iterator;
515 using GridCPtrVecCIter = GridCPtrVec::const_iterator;
517 
518 using GridPtrSet = std::set<GridBase::Ptr>;
519 using GridPtrSetIter = GridPtrSet::iterator;
520 using GridPtrSetCIter = GridPtrSet::const_iterator;
522 
523 using GridCPtrSet = std::set<GridBase::ConstPtr>;
524 using GridCPtrSetIter = GridCPtrSet::iterator;
525 using GridCPtrSetCIter = GridCPtrSet::const_iterator;
527 
528 
529 /// @brief Predicate functor that returns @c true for grids that have a specified name
531 {
532  GridNamePred(const Name& _name): name(_name) {}
533  bool operator()(const GridBase::ConstPtr& g) const { return g && g->getName() == name; }
535 };
536 
537 /// Return the first grid in the given container whose name is @a name.
538 template<typename GridPtrContainerT>
539 inline typename GridPtrContainerT::value_type
540 findGridByName(const GridPtrContainerT& container, const Name& name)
541 {
542  using GridPtrT = typename GridPtrContainerT::value_type;
543  typename GridPtrContainerT::const_iterator it =
544  std::find_if(container.begin(), container.end(), GridNamePred(name));
545  return (it == container.end() ? GridPtrT() : *it);
546 }
547 
548 /// Return the first grid in the given map whose name is @a name.
549 template<typename KeyT, typename GridPtrT>
550 inline GridPtrT
551 findGridByName(const std::map<KeyT, GridPtrT>& container, const Name& name)
552 {
553  using GridPtrMapT = std::map<KeyT, GridPtrT>;
554  for (typename GridPtrMapT::const_iterator it = container.begin(), end = container.end();
555  it != end; ++it)
556  {
557  const GridPtrT& grid = it->second;
558  if (grid && grid->getName() == name) return grid;
559  }
560  return GridPtrT();
561 }
562 //@}
563 
564 
565 ////////////////////////////////////////
566 
567 
568 /// @brief Container class that associates a tree with a transform and metadata
569 template<typename _TreeType>
570 class Grid: public GridBase
571 {
572 public:
575 
576  using TreeType = _TreeType;
577  using TreePtrType = typename _TreeType::Ptr;
578  using ConstTreePtrType = typename _TreeType::ConstPtr;
579  using ValueType = typename _TreeType::ValueType;
580  using BuildType = typename _TreeType::BuildType;
581 
582  using ValueOnIter = typename _TreeType::ValueOnIter;
583  using ValueOnCIter = typename _TreeType::ValueOnCIter;
584  using ValueOffIter = typename _TreeType::ValueOffIter;
585  using ValueOffCIter = typename _TreeType::ValueOffCIter;
586  using ValueAllIter = typename _TreeType::ValueAllIter;
587  using ValueAllCIter = typename _TreeType::ValueAllCIter;
588 
593 
594  /// @brief ValueConverter<T>::Type is the type of a grid having the same
595  /// hierarchy as this grid but a different value type, T.
596  ///
597  /// For example, FloatGrid::ValueConverter<double>::Type is equivalent to DoubleGrid.
598  /// @note If the source grid type is a template argument, it might be necessary
599  /// to write "typename SourceGrid::template ValueConverter<T>::Type".
600  template<typename OtherValueType>
601  struct ValueConverter {
603  };
604 
605  /// Return a new grid with the given background value.
606  static Ptr create(const ValueType& background);
607  /// Return a new grid with background value zero.
608  static Ptr create();
609  /// @brief Return a new grid that contains the given tree.
610  /// @throw ValueError if the tree pointer is null
611  static Ptr create(TreePtrType);
612  /// @brief Return a new, empty grid with the same transform and metadata as the
613  /// given grid and with background value zero.
614  static Ptr create(const GridBase& other);
615 
616 
617  /// Construct a new grid with background value zero.
618  Grid();
619  /// Construct a new grid with the given background value.
620  explicit Grid(const ValueType& background);
621  /// @brief Construct a new grid that shares the given tree and associates with it
622  /// an identity linear transform.
623  /// @throw ValueError if the tree pointer is null
624  explicit Grid(TreePtrType);
625  /// Deep copy another grid's metadata, transform and tree.
626  Grid(const Grid&);
627  /// @brief Deep copy the metadata, transform and tree of another grid whose tree
628  /// configuration is the same as this grid's but whose value type is different.
629  /// Cast the other grid's values to this grid's value type.
630  /// @throw TypeError if the other grid's tree configuration doesn't match this grid's
631  /// or if this grid's ValueType is not constructible from the other grid's ValueType.
632  template<typename OtherTreeType>
633  explicit Grid(const Grid<OtherTreeType>&);
634  /// Deep copy another grid's metadata and transform, but share its tree.
635  Grid(Grid&, ShallowCopy);
636  /// @brief Deep copy another grid's metadata and transform, but construct a new tree
637  /// with background value zero.
638  explicit Grid(const GridBase&);
639 
640  ~Grid() override {}
641 
642  /// Disallow assignment, since it wouldn't be obvious whether the copy is deep or shallow.
643  Grid& operator=(const Grid&) = delete;
644 
645  /// @name Copying
646  /// @{
647 
648  /// @brief Return a new grid of the same type as this grid whose metadata and
649  /// transform are deep copies of this grid's and whose tree is shared with this grid.
650  Ptr copy();
651  /// @brief Return a new grid of the same type as this grid whose metadata and
652  /// transform are deep copies of this grid's and whose tree is shared with this grid.
653  ConstPtr copy() const;
654  /// @brief Return a new grid of the same type as this grid whose metadata and
655  /// transform are deep copies of this grid's and whose tree is default-constructed.
656  Ptr copyWithNewTree() const;
657 
658  /// @brief Return a new grid of the same type as this grid whose metadata is a
659  /// deep copy of this grid's and whose tree and transform are shared with this grid.
660  GridBase::Ptr copyGrid() override;
661  /// @brief Return a new grid of the same type as this grid whose metadata is a
662  /// deep copy of this grid's and whose tree and transform are shared with this grid.
663  GridBase::ConstPtr copyGrid() const override;
664  /// @brief Return a new grid of the same type as this grid whose metadata and
665  /// transform are deep copies of this grid's and whose tree is default-constructed.
666  GridBase::Ptr copyGridWithNewTree() const override;
667  //@}
668 
669  /// @name Copying
670  /// @{
671 
672  /// @brief Return a new grid of the same type as this grid whose tree and transform
673  /// is shared with this grid and whose metadata is provided as an argument.
674  ConstPtr copyReplacingMetadata(const MetaMap& meta) const;
675  /// @brief Return a new grid of the same type as this grid whose tree is shared with
676  /// this grid, whose metadata is a deep copy of this grid's and whose transform is
677  /// provided as an argument.
678  /// @throw ValueError if the transform pointer is null
680  /// @brief Return a new grid of the same type as this grid whose tree is shared with
681  /// this grid and whose transform and metadata are provided as arguments.
682  /// @throw ValueError if the transform pointer is null
684  math::Transform::Ptr xform) const;
685 
686  /// @brief Return a new grid of the same type as this grid whose tree and transform
687  /// is shared with this grid and whose metadata is provided as an argument.
688  GridBase::ConstPtr copyGridReplacingMetadata(const MetaMap& meta) const override;
689  /// @brief Return a new grid of the same type as this grid whose tree is shared with
690  /// this grid, whose metadata is a deep copy of this grid's and whose transform is
691  /// provided as an argument.
692  /// @throw ValueError if the transform pointer is null
694  /// @brief Return a new grid of the same type as this grid whose tree is shared with
695  /// this grid and whose transform and metadata are provided as arguments.
696  /// @throw ValueError if the transform pointer is null
698  math::Transform::Ptr xform) const override;
699 
700  /// @brief Return a new grid whose metadata, transform and tree are deep copies of this grid's.
701  Ptr deepCopy() const { return Ptr(new Grid(*this)); }
702  /// @brief Return a new grid whose metadata, transform and tree are deep copies of this grid's.
703  GridBase::Ptr deepCopyGrid() const override { return this->deepCopy(); }
704 
705  //@}
706 
707 
708  /// Return the name of this grid's type.
709  Name type() const override { return this->gridType(); }
710  /// Return the name of this type of grid.
711  static Name gridType() { return TreeType::treeType(); }
712 
713  /// Return the name of the type of a voxel's value (e.g., "float" or "vec3d").
714  Name valueType() const override { return tree().valueType(); }
715 
716 
717  /// @name Voxel access
718  /// @{
719 
720  /// @brief Return this grid's background value.
721  /// @note Use tools::changeBackground to efficiently modify the background value.
722  const ValueType& background() const { return mTree->background(); }
723 
724  /// Return @c true if this grid contains only inactive background voxels.
725  bool empty() const override { return tree().empty(); }
726  /// Empty this grid, so that all voxels become inactive background voxels.
727  void clear() override { tree().clear(); }
728 
729  /// @brief Return an accessor that provides random read and write access
730  /// to this grid's voxels.
731  /// @details The accessor is safe in the sense that it is registered with this grid's tree.
733  /// @brief Return an unsafe accessor that provides random read and write access
734  /// to this grid's voxels.
735  /// @details The accessor is unsafe in the sense that it is not registered
736  /// with this grid's tree. In some rare cases this can give a performance advantage
737  /// over a registered accessor, but it is unsafe if the tree topology is modified.
738  /// @warning Only use this method if you're an expert and know the
739  /// risks of using an unregistered accessor (see tree/ValueAccessor.h)
741  /// Return an accessor that provides random read-only access to this grid's voxels.
743  /// Return an accessor that provides random read-only access to this grid's voxels.
745  /// @brief Return an unsafe accessor that provides random read-only access
746  /// to this grid's voxels.
747  /// @details The accessor is unsafe in the sense that it is not registered
748  /// with this grid's tree. In some rare cases this can give a performance advantage
749  /// over a registered accessor, but it is unsafe if the tree topology is modified.
750  /// @warning Only use this method if you're an expert and know the
751  /// risks of using an unregistered accessor (see tree/ValueAccessor.h)
753 
754  /// Return an iterator over all of this grid's active values (tile and voxel).
755  ValueOnIter beginValueOn() { return tree().beginValueOn(); }
756  /// Return an iterator over all of this grid's active values (tile and voxel).
757  ValueOnCIter beginValueOn() const { return tree().cbeginValueOn(); }
758  /// Return an iterator over all of this grid's active values (tile and voxel).
759  ValueOnCIter cbeginValueOn() const { return tree().cbeginValueOn(); }
760  /// Return an iterator over all of this grid's inactive values (tile and voxel).
761  ValueOffIter beginValueOff() { return tree().beginValueOff(); }
762  /// Return an iterator over all of this grid's inactive values (tile and voxel).
763  ValueOffCIter beginValueOff() const { return tree().cbeginValueOff(); }
764  /// Return an iterator over all of this grid's inactive values (tile and voxel).
765  ValueOffCIter cbeginValueOff() const { return tree().cbeginValueOff(); }
766  /// Return an iterator over all of this grid's values (tile and voxel).
767  ValueAllIter beginValueAll() { return tree().beginValueAll(); }
768  /// Return an iterator over all of this grid's values (tile and voxel).
769  ValueAllCIter beginValueAll() const { return tree().cbeginValueAll(); }
770  /// Return an iterator over all of this grid's values (tile and voxel).
771  ValueAllCIter cbeginValueAll() const { return tree().cbeginValueAll(); }
772 
773  /// @}
774 
775  /// @name Tools
776  /// @{
777 
778  /// @brief Set all voxels within a given axis-aligned box to a constant value.
779  /// @param bbox inclusive coordinates of opposite corners of an axis-aligned box
780  /// @param value the value to which to set voxels within the box
781  /// @param active if true, mark voxels within the box as active,
782  /// otherwise mark them as inactive
783  /// @note This operation generates a sparse, but not always optimally sparse,
784  /// representation of the filled box. Follow fill operations with a prune()
785  /// operation for optimal sparseness.
786  void sparseFill(const CoordBBox& bbox, const ValueType& value, bool active = true);
787  /// @brief Set all voxels within a given axis-aligned box to a constant value.
788  /// @param bbox inclusive coordinates of opposite corners of an axis-aligned box
789  /// @param value the value to which to set voxels within the box
790  /// @param active if true, mark voxels within the box as active,
791  /// otherwise mark them as inactive
792  /// @note This operation generates a sparse, but not always optimally sparse,
793  /// representation of the filled box. Follow fill operations with a prune()
794  /// operation for optimal sparseness.
795  void fill(const CoordBBox& bbox, const ValueType& value, bool active = true);
796 
797  /// @brief Set all voxels within a given axis-aligned box to a constant value
798  /// and ensure that those voxels are all represented at the leaf level.
799  /// @param bbox inclusive coordinates of opposite corners of an axis-aligned box.
800  /// @param value the value to which to set voxels within the box.
801  /// @param active if true, mark voxels within the box as active,
802  /// otherwise mark them as inactive.
803  void denseFill(const CoordBBox& bbox, const ValueType& value, bool active = true);
804 
805  /// Reduce the memory footprint of this grid by increasing its sparseness.
806  void pruneGrid(float tolerance = 0.0) override;
807 
808  /// @brief Clip this grid to the given index-space bounding box.
809  /// @details Voxels that lie outside the bounding box are set to the background.
810  /// @warning Clipping a level set will likely produce a grid that is
811  /// no longer a valid level set.
812  void clip(const CoordBBox&) override;
813 
814  /// @brief Efficiently merge another grid into this grid using one of several schemes.
815  /// @details This operation is primarily intended to combine grids that are mostly
816  /// non-overlapping (for example, intermediate grids from computations that are
817  /// parallelized across disjoint regions of space).
818  /// @warning This operation always empties the other grid.
820 
821  /// @brief Union this grid's set of active values with the active values
822  /// of the other grid, whose value type may be different.
823  /// @details The resulting state of a value is active if the corresponding value
824  /// was already active OR if it is active in the other grid. Also, a resulting
825  /// value maps to a voxel if the corresponding value already mapped to a voxel
826  /// OR if it is a voxel in the other grid. Thus, a resulting value can only
827  /// map to a tile if the corresponding value already mapped to a tile
828  /// AND if it is a tile value in the other grid.
829  ///
830  /// @note This operation modifies only active states, not values.
831  /// Specifically, active tiles and voxels in this grid are not changed, and
832  /// tiles or voxels that were inactive in this grid but active in the other grid
833  /// are marked as active in this grid but left with their original values.
834  template<typename OtherTreeType>
835  void topologyUnion(const Grid<OtherTreeType>& other);
836 
837  /// @brief Intersect this grid's set of active values with the active values
838  /// of the other grid, whose value type may be different.
839  /// @details The resulting state of a value is active only if the corresponding
840  /// value was already active AND if it is active in the other tree. Also, a
841  /// resulting value maps to a voxel if the corresponding value
842  /// already mapped to an active voxel in either of the two grids
843  /// and it maps to an active tile or voxel in the other grid.
844  ///
845  /// @note This operation can delete branches of this grid that overlap with
846  /// inactive tiles in the other grid. Also, because it can deactivate voxels,
847  /// it can create leaf nodes with no active values. Thus, it is recommended
848  /// to prune this grid after calling this method.
849  template<typename OtherTreeType>
850  void topologyIntersection(const Grid<OtherTreeType>& other);
851 
852  /// @brief Difference this grid's set of active values with the active values
853  /// of the other grid, whose value type may be different.
854  /// @details After this method is called, voxels in this grid will be active
855  /// only if they were active to begin with and if the corresponding voxels
856  /// in the other grid were inactive.
857  ///
858  /// @note This operation can delete branches of this grid that overlap with
859  /// active tiles in the other grid. Also, because it can deactivate voxels,
860  /// it can create leaf nodes with no active values. Thus, it is recommended
861  /// to prune this grid after calling this method.
862  template<typename OtherTreeType>
863  void topologyDifference(const Grid<OtherTreeType>& other);
864 
865  /// @}
866 
867  /// @name Statistics
868  /// @{
869 
870  /// Return the number of active voxels.
871  Index64 activeVoxelCount() const override { return tree().activeVoxelCount(); }
872  /// Return the axis-aligned bounding box of all active voxels.
873  CoordBBox evalActiveVoxelBoundingBox() const override;
874  /// Return the dimensions of the axis-aligned bounding box of all active voxels.
875  Coord evalActiveVoxelDim() const override;
876  /// Return the minimum and maximum active values in this grid.
877  OPENVDB_DEPRECATED_MESSAGE("Switch from grid->evalMinMax(minVal, maxVal) to \
878 tools::minMax(grid->tree()). Use threaded = false for serial execution")
880 
881  /// Return the number of bytes of memory used by this grid.
882  /// @todo Add transform().memUsage()
883  Index64 memUsage() const override { return tree().memUsage(); }
884 
885  /// @}
886 
887 
888  /// @name Tree
889  /// @{
890 
891  //@{
892  /// @brief Return a pointer to this grid's tree, which might be
893  /// shared with other grids. The pointer is guaranteed to be non-null.
894  TreePtrType treePtr() { return mTree; }
895  ConstTreePtrType treePtr() const { return mTree; }
896  ConstTreePtrType constTreePtr() const { return mTree; }
897  TreeBase::ConstPtr constBaseTreePtr() const override { return mTree; }
898  //@}
899  /// @brief Return true if tree is not shared with another grid.
900  /// @note This is a virtual function with ABI=8
901  bool isTreeUnique() const final;
902 
903  //@{
904  /// @brief Return a reference to this grid's tree, which might be
905  /// shared with other grids.
906  /// @note Calling setTree() on this grid invalidates all references
907  /// previously returned by this method.
908  TreeType& tree() { return *mTree; }
909  const TreeType& tree() const { return *mTree; }
910  const TreeType& constTree() const { return *mTree; }
911  //@}
912 
913  /// @}
914 
915  /// @name Tree
916  /// @{
917 
918  /// @brief Associate the given tree with this grid, in place of its existing tree.
919  /// @throw ValueError if the tree pointer is null
920  /// @throw TypeError if the tree is not of type TreeType
921  /// @note Invalidates all references previously returned by baseTree(),
922  /// constBaseTree(), tree() or constTree().
923  void setTree(TreeBase::Ptr) override;
924 
925  /// @brief Associate a new, empty tree with this grid, in place of its existing tree.
926  /// @note The new tree has the same background value as the existing tree.
927  void newTree() override;
928 
929  /// @}
930 
931 
932  /// @name I/O
933  /// @{
934 
935  /// @brief Read the grid topology from a stream.
936  /// This will read only the grid structure, not the actual data buffers.
937  void readTopology(std::istream&) override;
938  /// @brief Write the grid topology to a stream.
939  /// This will write only the grid structure, not the actual data buffers.
940  void writeTopology(std::ostream&) const override;
941 
942  /// Read all data buffers for this grid.
943  void readBuffers(std::istream&) override;
944  /// Read all of this grid's data buffers that intersect the given index-space bounding box.
945  void readBuffers(std::istream&, const CoordBBox&) override;
946  /// @brief Read all of this grid's data buffers that are not yet resident in memory
947  /// (because delayed loading is in effect).
948  /// @details If this grid was read from a memory-mapped file, this operation
949  /// disconnects the grid from the file.
950  /// @sa io::File::open, io::MappedFile
951  void readNonresidentBuffers() const override;
952  /// Write out all data buffers for this grid.
953  void writeBuffers(std::ostream&) const override;
954 
955  /// Output a human-readable description of this grid.
956  void print(std::ostream& = std::cout, int verboseLevel = 1) const override;
957 
958  /// @}
959 
960  /// @brief Return @c true if grids of this type require multiple I/O passes
961  /// to read and write data buffers.
962  /// @sa HasMultiPassIO
963  static inline bool hasMultiPassIO();
964 
965 
966  /// @name Registry
967  /// @{
968 
969  /// Return @c true if this grid type is registered.
971  /// Register this grid type along with a factory function.
972  static void registerGrid() { GridBase::registerGrid(Grid::gridType(), Grid::factory); }
973  /// Remove this grid type from the registry.
975 
976  /// @}
977 
978 
979 private:
980  /// Deep copy metadata, but share tree and transform.
981  Grid(TreePtrType tree, const MetaMap& meta, math::Transform::Ptr xform);
982 
983  /// Helper function for use with registerGrid()
984  static GridBase::Ptr factory() { return Grid::create(); }
985 
986  TreePtrType mTree;
987 }; // class Grid
988 
989 
990 ////////////////////////////////////////
991 
992 
993 /// @brief Cast a generic grid pointer to a pointer to a grid of a concrete class.
994 ///
995 /// Return a null pointer if the input pointer is null or if it
996 /// points to a grid that is not of type @c GridType.
997 ///
998 /// @note Calling gridPtrCast<GridType>(grid) is equivalent to calling
999 /// GridBase::grid<GridType>(grid).
1000 template<typename GridType>
1001 inline typename GridType::Ptr
1003 {
1004  return GridBase::grid<GridType>(grid);
1005 }
1006 
1007 
1008 /// @brief Cast a generic const grid pointer to a const pointer to a grid
1009 /// of a concrete class.
1010 ///
1011 /// Return a null pointer if the input pointer is null or if it
1012 /// points to a grid that is not of type @c GridType.
1013 ///
1014 /// @note Calling gridConstPtrCast<GridType>(grid) is equivalent to calling
1015 /// GridBase::constGrid<GridType>(grid).
1016 template<typename GridType>
1017 inline typename GridType::ConstPtr
1019 {
1020  return GridBase::constGrid<GridType>(grid);
1021 }
1022 
1023 
1024 ////////////////////////////////////////
1025 
1026 
1027 /// @{
1028 /// @brief Return a pointer to a deep copy of the given grid, provided that
1029 /// the grid's concrete type is @c GridType.
1030 ///
1031 /// Return a null pointer if the input pointer is null or if it
1032 /// points to a grid that is not of type @c GridType.
1033 template<typename GridType>
1034 inline typename GridType::Ptr
1036 {
1037  if (!grid || !grid->isType<GridType>()) return typename GridType::Ptr();
1038  return gridPtrCast<GridType>(grid->deepCopyGrid());
1039 }
1040 
1041 
1042 template<typename GridType>
1043 inline typename GridType::Ptr
1045 {
1046  if (!grid.isType<GridType>()) return typename GridType::Ptr();
1047  return gridPtrCast<GridType>(grid.deepCopyGrid());
1048 }
1049 /// @}
1050 
1051 
1052 ////////////////////////////////////////
1053 
1054 
1055 //@{
1056 /// @brief This adapter allows code that is templated on a Tree type to
1057 /// accept either a Tree type or a Grid type.
1058 template<typename _TreeType>
1060 {
1061  using TreeType = _TreeType;
1063  using TreePtrType = typename TreeType::Ptr;
1064  using ConstTreePtrType = typename TreeType::ConstPtr;
1065  using NonConstTreePtrType = typename NonConstTreeType::Ptr;
1068  using GridPtrType = typename GridType::Ptr;
1071  using ValueType = typename TreeType::ValueType;
1075 
1076  static TreeType& tree(TreeType& t) { return t; }
1077  static TreeType& tree(GridType& g) { return g.tree(); }
1078  static const TreeType& tree(const TreeType& t) { return t; }
1079  static const TreeType& tree(const GridType& g) { return g.tree(); }
1080  static const TreeType& constTree(TreeType& t) { return t; }
1081  static const TreeType& constTree(GridType& g) { return g.constTree(); }
1082  static const TreeType& constTree(const TreeType& t) { return t; }
1083  static const TreeType& constTree(const GridType& g) { return g.constTree(); }
1084 };
1085 
1086 
1087 /// Partial specialization for Grid types
1088 template<typename _TreeType>
1089 struct TreeAdapter<Grid<_TreeType> >
1090 {
1091  using TreeType = _TreeType;
1093  using TreePtrType = typename TreeType::Ptr;
1094  using ConstTreePtrType = typename TreeType::ConstPtr;
1095  using NonConstTreePtrType = typename NonConstTreeType::Ptr;
1098  using GridPtrType = typename GridType::Ptr;
1101  using ValueType = typename TreeType::ValueType;
1105 
1106  static TreeType& tree(TreeType& t) { return t; }
1107  static TreeType& tree(GridType& g) { return g.tree(); }
1108  static const TreeType& tree(const TreeType& t) { return t; }
1109  static const TreeType& tree(const GridType& g) { return g.tree(); }
1110  static const TreeType& constTree(TreeType& t) { return t; }
1111  static const TreeType& constTree(GridType& g) { return g.constTree(); }
1112  static const TreeType& constTree(const TreeType& t) { return t; }
1113  static const TreeType& constTree(const GridType& g) { return g.constTree(); }
1114 };
1115 
1116 /// Partial specialization for ValueAccessor types
1117 template<typename _TreeType>
1118 struct TreeAdapter<tree::ValueAccessor<_TreeType> >
1119 {
1120  using TreeType = _TreeType;
1122  using TreePtrType = typename TreeType::Ptr;
1123  using ConstTreePtrType = typename TreeType::ConstPtr;
1124  using NonConstTreePtrType = typename NonConstTreeType::Ptr;
1127  using GridPtrType = typename GridType::Ptr;
1130  using ValueType = typename TreeType::ValueType;
1134 
1135  static TreeType& tree(TreeType& t) { return t; }
1136  static TreeType& tree(GridType& g) { return g.tree(); }
1137  static TreeType& tree(AccessorType& a) { return a.tree(); }
1138  static const TreeType& tree(const TreeType& t) { return t; }
1139  static const TreeType& tree(const GridType& g) { return g.tree(); }
1140  static const TreeType& tree(const AccessorType& a) { return a.tree(); }
1141  static const TreeType& constTree(TreeType& t) { return t; }
1142  static const TreeType& constTree(GridType& g) { return g.constTree(); }
1143  static const TreeType& constTree(const TreeType& t) { return t; }
1144  static const TreeType& constTree(const GridType& g) { return g.constTree(); }
1145 };
1146 
1147 //@}
1148 
1149 
1150 ////////////////////////////////////////
1151 
1152 
1153 /// @brief Metafunction that specifies whether a given leaf node, tree, or grid type
1154 /// requires multiple passes to read and write voxel data
1155 /// @details Multi-pass I/O allows one to optimize the data layout of leaf nodes
1156 /// for certain access patterns during delayed loading.
1157 /// @sa io::MultiPass
1158 template<typename LeafNodeType>
1161 };
1162 
1163 // Partial specialization for Tree types
1164 template<typename RootNodeType>
1165 struct HasMultiPassIO<tree::Tree<RootNodeType>> {
1166  // A tree is multi-pass if its (root node's) leaf node type is multi-pass.
1168 };
1169 
1170 // Partial specialization for Grid types
1171 template<typename TreeType>
1172 struct HasMultiPassIO<Grid<TreeType>> {
1173  // A grid is multi-pass if its tree's leaf node type is multi-pass.
1175 };
1176 
1177 
1178 ////////////////////////////////////////
1179 
1181  : MetaMap(meta)
1182  , mTransform(xform)
1183 {
1184  if (!xform) OPENVDB_THROW(ValueError, "Transform pointer is null");
1185 }
1186 
1187 template<typename GridType>
1188 inline typename GridType::Ptr
1190 {
1191  // The string comparison on type names is slower than a dynamic pointer cast, but
1192  // it is safer when pointers cross DSO boundaries, as they do in many Houdini nodes.
1193  if (grid && grid->type() == GridType::gridType()) {
1194  return StaticPtrCast<GridType>(grid);
1195  }
1196  return typename GridType::Ptr();
1197 }
1198 
1199 
1200 template<typename GridType>
1201 inline typename GridType::ConstPtr
1203 {
1204  return ConstPtrCast<const GridType>(
1205  GridBase::grid<GridType>(ConstPtrCast<GridBase>(grid)));
1206 }
1207 
1208 
1209 template<typename GridType>
1210 inline typename GridType::ConstPtr
1212 {
1213  return ConstPtrCast<const GridType>(GridBase::grid<GridType>(grid));
1214 }
1215 
1216 
1217 template<typename GridType>
1218 inline typename GridType::ConstPtr
1220 {
1221  return ConstPtrCast<const GridType>(
1222  GridBase::grid<GridType>(ConstPtrCast<GridBase>(grid)));
1223 }
1224 
1225 
1226 inline TreeBase::Ptr
1228 {
1229  return ConstPtrCast<TreeBase>(this->constBaseTreePtr());
1230 }
1231 
1232 
1233 inline void
1235 {
1236  if (!xform) OPENVDB_THROW(ValueError, "Transform pointer is null");
1237  mTransform = xform;
1238 }
1239 
1240 
1241 ////////////////////////////////////////
1242 
1243 
1244 template<typename TreeT>
1245 inline Grid<TreeT>::Grid(): mTree(new TreeType)
1246 {
1247 }
1248 
1249 
1250 template<typename TreeT>
1251 inline Grid<TreeT>::Grid(const ValueType &background): mTree(new TreeType(background))
1252 {
1253 }
1254 
1255 
1256 template<typename TreeT>
1257 inline Grid<TreeT>::Grid(TreePtrType tree): mTree(tree)
1258 {
1259  if (!tree) OPENVDB_THROW(ValueError, "Tree pointer is null");
1260 }
1261 
1262 
1263 template<typename TreeT>
1264 inline Grid<TreeT>::Grid(TreePtrType tree, const MetaMap& meta, math::Transform::Ptr xform):
1265  GridBase(meta, xform),
1266  mTree(tree)
1267 {
1268  if (!tree) OPENVDB_THROW(ValueError, "Tree pointer is null");
1269 }
1270 
1271 
1272 template<typename TreeT>
1273 inline Grid<TreeT>::Grid(const Grid& other):
1274  GridBase(other),
1275  mTree(StaticPtrCast<TreeType>(other.mTree->copy()))
1276 {
1277 }
1278 
1279 
1280 template<typename TreeT>
1281 template<typename OtherTreeType>
1283  GridBase(other),
1284  mTree(new TreeType(other.constTree()))
1285 {
1286 }
1287 
1288 
1289 template<typename TreeT>
1291  GridBase(other),
1292  mTree(other.mTree)
1293 {
1294 }
1295 
1296 
1297 template<typename TreeT>
1298 inline Grid<TreeT>::Grid(const GridBase& other):
1299  GridBase(other),
1300  mTree(new TreeType)
1301 {
1302 }
1303 
1304 
1305 //static
1306 template<typename TreeT>
1307 inline typename Grid<TreeT>::Ptr
1309 {
1310  return Grid::create(zeroVal<ValueType>());
1311 }
1312 
1313 
1314 //static
1315 template<typename TreeT>
1316 inline typename Grid<TreeT>::Ptr
1317 Grid<TreeT>::create(const ValueType& background)
1318 {
1319  return Ptr(new Grid(background));
1320 }
1321 
1322 
1323 //static
1324 template<typename TreeT>
1325 inline typename Grid<TreeT>::Ptr
1327 {
1328  return Ptr(new Grid(tree));
1329 }
1330 
1331 
1332 //static
1333 template<typename TreeT>
1334 inline typename Grid<TreeT>::Ptr
1336 {
1337  return Ptr(new Grid(other));
1338 }
1339 
1340 
1341 ////////////////////////////////////////
1342 
1343 
1344 template<typename TreeT>
1345 inline typename Grid<TreeT>::ConstPtr
1347 {
1348  return ConstPtr{new Grid{*const_cast<Grid*>(this), ShallowCopy{}}};
1349 }
1350 
1351 
1352 template<typename TreeT>
1353 inline typename Grid<TreeT>::ConstPtr
1355 {
1356  math::Transform::Ptr transformPtr = ConstPtrCast<math::Transform>(
1357  this->constTransformPtr());
1358  TreePtrType treePtr = ConstPtrCast<TreeT>(this->constTreePtr());
1359  return ConstPtr{new Grid<TreeT>{treePtr, meta, transformPtr}};
1360 }
1361 
1362 template<typename TreeT>
1363 inline typename Grid<TreeT>::ConstPtr
1365 {
1366  return this->copyReplacingMetadataAndTransform(*this, xform);
1367 }
1368 
1369 template<typename TreeT>
1370 inline typename Grid<TreeT>::ConstPtr
1372  math::Transform::Ptr xform) const
1373 {
1374  TreePtrType treePtr = ConstPtrCast<TreeT>(this->constTreePtr());
1375  return ConstPtr{new Grid<TreeT>{treePtr, meta, xform}};
1376 }
1377 
1378 
1379 template<typename TreeT>
1380 inline typename Grid<TreeT>::Ptr
1382 {
1383  return Ptr{new Grid{*this, ShallowCopy{}}};
1384 }
1385 
1386 
1387 template<typename TreeT>
1388 inline typename Grid<TreeT>::Ptr
1390 {
1391  Ptr result{new Grid{*const_cast<Grid*>(this), ShallowCopy{}}};
1392  result->newTree();
1393  return result;
1394 }
1395 
1396 
1397 template<typename TreeT>
1398 inline GridBase::Ptr
1400 {
1401  return this->copy();
1402 }
1403 
1404 template<typename TreeT>
1405 inline GridBase::ConstPtr
1407 {
1408  return this->copy();
1409 }
1410 
1411 template<typename TreeT>
1412 inline GridBase::ConstPtr
1414 {
1415  return this->copyReplacingMetadata(meta);
1416 }
1417 
1418 template<typename TreeT>
1419 inline GridBase::ConstPtr
1421 {
1422  return this->copyReplacingTransform(xform);
1423 }
1424 
1425 template<typename TreeT>
1426 inline GridBase::ConstPtr
1428  math::Transform::Ptr xform) const
1429 {
1430  return this->copyReplacingMetadataAndTransform(meta, xform);
1431 }
1432 
1433 template<typename TreeT>
1434 inline GridBase::Ptr
1436 {
1437  return this->copyWithNewTree();
1438 }
1439 
1440 
1441 ////////////////////////////////////////
1442 
1443 
1444 template<typename TreeT>
1445 inline bool
1447 {
1448  return mTree.use_count() == 1;
1449 }
1450 
1451 
1452 template<typename TreeT>
1453 inline void
1455 {
1456  if (!tree) OPENVDB_THROW(ValueError, "Tree pointer is null");
1457  if (tree->type() != TreeType::treeType()) {
1458  OPENVDB_THROW(TypeError, "Cannot assign a tree of type "
1459  + tree->type() + " to a grid of type " + this->type());
1460  }
1461  mTree = StaticPtrCast<TreeType>(tree);
1462 }
1463 
1464 
1465 template<typename TreeT>
1466 inline void
1468 {
1469  mTree.reset(new TreeType(this->background()));
1470 }
1471 
1472 
1473 ////////////////////////////////////////
1474 
1475 
1476 template<typename TreeT>
1477 inline void
1479 {
1480  tree().sparseFill(bbox, value, active);
1481 }
1482 
1483 
1484 template<typename TreeT>
1485 inline void
1487 {
1488  this->sparseFill(bbox, value, active);
1489 }
1490 
1491 template<typename TreeT>
1492 inline void
1494 {
1495  tree().denseFill(bbox, value, active);
1496 }
1497 
1498 template<typename TreeT>
1499 inline void
1500 Grid<TreeT>::pruneGrid(float tolerance)
1501 {
1502  const auto value = math::cwiseAdd(zeroVal<ValueType>(), tolerance);
1503  this->tree().prune(static_cast<ValueType>(value));
1504 }
1505 
1506 template<typename TreeT>
1507 inline void
1509 {
1510  tree().clip(bbox);
1511 }
1512 
1513 template<typename TreeT>
1514 inline void
1516 {
1517  tree().merge(other.tree(), policy);
1518 }
1519 
1520 
1521 template<typename TreeT>
1522 template<typename OtherTreeType>
1523 inline void
1525 {
1526  tree().topologyUnion(other.tree());
1527 }
1528 
1529 
1530 template<typename TreeT>
1531 template<typename OtherTreeType>
1532 inline void
1534 {
1535  tree().topologyIntersection(other.tree());
1536 }
1537 
1538 
1539 template<typename TreeT>
1540 template<typename OtherTreeType>
1541 inline void
1543 {
1544  tree().topologyDifference(other.tree());
1545 }
1546 
1547 
1548 ////////////////////////////////////////
1549 
1550 
1551 template<typename TreeT>
1552 inline void
1553 Grid<TreeT>::evalMinMax(ValueType& minVal, ValueType& maxVal) const
1554 {
1556  tree().evalMinMax(minVal, maxVal);
1558 }
1559 
1560 
1561 template<typename TreeT>
1562 inline CoordBBox
1564 {
1565  CoordBBox bbox;
1566  tree().evalActiveVoxelBoundingBox(bbox);
1567  return bbox;
1568 }
1569 
1570 
1571 template<typename TreeT>
1572 inline Coord
1574 {
1575  Coord dim;
1576  const bool nonempty = tree().evalActiveVoxelDim(dim);
1577  return (nonempty ? dim : Coord());
1578 }
1579 
1580 
1581 ////////////////////////////////////////
1582 
1583 
1584 /// @internal Consider using the stream tagging mechanism (see io::Archive)
1585 /// to specify the float precision, but note that the setting is per-grid.
1586 
1587 template<typename TreeT>
1588 inline void
1589 Grid<TreeT>::readTopology(std::istream& is)
1590 {
1591  tree().readTopology(is, saveFloatAsHalf());
1592 }
1593 
1594 
1595 template<typename TreeT>
1596 inline void
1597 Grid<TreeT>::writeTopology(std::ostream& os) const
1598 {
1599  tree().writeTopology(os, saveFloatAsHalf());
1600 }
1601 
1602 
1603 template<typename TreeT>
1604 inline void
1605 Grid<TreeT>::readBuffers(std::istream& is)
1606 {
1607  if (!hasMultiPassIO() || (io::getFormatVersion(is) < OPENVDB_FILE_VERSION_MULTIPASS_IO)) {
1608  tree().readBuffers(is, saveFloatAsHalf());
1609  } else {
1610  uint16_t numPasses = 1;
1611  is.read(reinterpret_cast<char*>(&numPasses), sizeof(uint16_t));
1613  assert(bool(meta));
1614  for (uint16_t passIndex = 0; passIndex < numPasses; ++passIndex) {
1615  uint32_t pass = (uint32_t(numPasses) << 16) | uint32_t(passIndex);
1616  meta->setPass(pass);
1617  tree().readBuffers(is, saveFloatAsHalf());
1618  }
1619  }
1620 }
1621 
1622 
1623 /// @todo Refactor this and the readBuffers() above
1624 /// once support for ABI 2 compatibility is dropped.
1625 template<typename TreeT>
1626 inline void
1627 Grid<TreeT>::readBuffers(std::istream& is, const CoordBBox& bbox)
1628 {
1629  if (!hasMultiPassIO() || (io::getFormatVersion(is) < OPENVDB_FILE_VERSION_MULTIPASS_IO)) {
1630  tree().readBuffers(is, bbox, saveFloatAsHalf());
1631  } else {
1632  uint16_t numPasses = 1;
1633  is.read(reinterpret_cast<char*>(&numPasses), sizeof(uint16_t));
1635  assert(bool(meta));
1636  for (uint16_t passIndex = 0; passIndex < numPasses; ++passIndex) {
1637  uint32_t pass = (uint32_t(numPasses) << 16) | uint32_t(passIndex);
1638  meta->setPass(pass);
1639  tree().readBuffers(is, saveFloatAsHalf());
1640  }
1641  // Cannot clip inside readBuffers() when using multiple passes,
1642  // so instead clip afterwards.
1643  tree().clip(bbox);
1644  }
1645 }
1646 
1647 
1648 template<typename TreeT>
1649 inline void
1651 {
1652  tree().readNonresidentBuffers();
1653 }
1654 
1655 
1656 template<typename TreeT>
1657 inline void
1658 Grid<TreeT>::writeBuffers(std::ostream& os) const
1659 {
1660  if (!hasMultiPassIO()) {
1661  tree().writeBuffers(os, saveFloatAsHalf());
1662  } else {
1663  // Determine how many leaf buffer passes are required for this grid
1665  assert(bool(meta));
1666  uint16_t numPasses = 1;
1667  meta->setCountingPasses(true);
1668  meta->setPass(0);
1669  tree().writeBuffers(os, saveFloatAsHalf());
1670  numPasses = static_cast<uint16_t>(meta->pass());
1671  os.write(reinterpret_cast<const char*>(&numPasses), sizeof(uint16_t));
1672  meta->setCountingPasses(false);
1673 
1674  // Save out the data blocks of the grid.
1675  for (uint16_t passIndex = 0; passIndex < numPasses; ++passIndex) {
1676  uint32_t pass = (uint32_t(numPasses) << 16) | uint32_t(passIndex);
1677  meta->setPass(pass);
1678  tree().writeBuffers(os, saveFloatAsHalf());
1679  }
1680  }
1681 }
1682 
1683 
1684 //static
1685 template<typename TreeT>
1686 inline bool
1688 {
1690 }
1691 
1692 
1693 template<typename TreeT>
1694 inline void
1695 Grid<TreeT>::print(std::ostream& os, int verboseLevel) const
1696 {
1697  tree().print(os, verboseLevel);
1698 
1699  if (metaCount() > 0) {
1700  os << "Additional metadata:" << std::endl;
1701  for (ConstMetaIterator it = beginMeta(), end = endMeta(); it != end; ++it) {
1702  os << " " << it->first;
1703  if (it->second) {
1704  const std::string value = it->second->str();
1705  if (!value.empty()) os << ": " << value;
1706  }
1707  os << "\n";
1708  }
1709  }
1710 
1711  os << "Transform:" << std::endl;
1712  transform().print(os, /*indent=*/" ");
1713  os << std::endl;
1714 }
1715 
1716 
1717 ////////////////////////////////////////
1718 
1719 
1720 template<typename GridType>
1721 inline typename GridType::Ptr
1722 createGrid(const typename GridType::ValueType& background)
1723 {
1724  return GridType::create(background);
1725 }
1726 
1727 
1728 template<typename GridType>
1729 inline typename GridType::Ptr
1731 {
1732  return GridType::create();
1733 }
1734 
1735 
1736 template<typename TreePtrType>
1737 inline typename Grid<typename TreePtrType::element_type>::Ptr
1738 createGrid(TreePtrType tree)
1739 {
1740  using TreeType = typename TreePtrType::element_type;
1741  return Grid<TreeType>::create(tree);
1742 }
1743 
1744 
1745 template<typename GridType>
1746 typename GridType::Ptr
1747 createLevelSet(Real voxelSize, Real halfWidth)
1748 {
1749  using ValueType = typename GridType::ValueType;
1750 
1751  // GridType::ValueType is required to be a floating-point scalar.
1753  "level-set grids must be floating-point-valued");
1754 
1755  typename GridType::Ptr grid = GridType::create(
1756  /*background=*/static_cast<ValueType>(voxelSize * halfWidth));
1757  grid->setTransform(math::Transform::createLinearTransform(voxelSize));
1758  grid->setGridClass(GRID_LEVEL_SET);
1759  return grid;
1760 }
1761 
1762 
1763 ////////////////////////////////////////
1764 
1765 
1766 template<typename GridTypeListT, typename OpT>
1767 inline bool
1768 GridBase::apply(OpT& op) const
1769 {
1770  return GridTypeListT::template apply<OpT&, const GridBase>(std::ref(op), *this);
1771 }
1772 
1773 template<typename GridTypeListT, typename OpT>
1774 inline bool
1776 {
1777  return GridTypeListT::template apply<OpT&, GridBase>(std::ref(op), *this);
1778 }
1779 
1780 template<typename GridTypeListT, typename OpT>
1781 inline bool
1782 GridBase::apply(const OpT& op) const
1783 {
1784  return GridTypeListT::template apply<const OpT&, const GridBase>(std::ref(op), *this);
1785 }
1786 
1787 template<typename GridTypeListT, typename OpT>
1788 inline bool
1789 GridBase::apply(const OpT& op)
1790 {
1791  return GridTypeListT::template apply<const OpT&, GridBase>(std::ref(op), *this);
1792 }
1793 
1794 
1795 } // namespace OPENVDB_VERSION_NAME
1796 } // namespace openvdb
1797 
1798 #endif // OPENVDB_GRID_HAS_BEEN_INCLUDED
SharedPtr< T > StaticPtrCast(const SharedPtr< U > &ptr)
Return a new shared pointer that points to the same object as the given pointer after a static_cast...
Definition: Types.h:146
bool isTreeUnique() const final
Return true if tree is not shared with another grid.
Definition: Grid.h:1446
typename _TreeType::ValueType ValueType
Definition: Grid.h:579
static GridType::ConstPtr constGrid(const GridBase::Ptr &)
Return the result of downcasting a GridBase pointer to a Grid pointer of the specified type...
Definition: Grid.h:1211
typename tree::ValueAccessor< const TreeType > ConstAccessorType
Definition: Grid.h:1103
typename tree::ValueAccessor< TreeType > AccessorType
Definition: Grid.h:1102
static const TreeType & tree(const TreeType &t)
Definition: Grid.h:1078
ConstUnsafeAccessor getConstUnsafeAccessor() const
Return an unsafe accessor that provides random read-only access to this grid's voxels.
Definition: Grid.h:752
Definition: ImfName.h:28
GridPtrSet::iterator GridPtrSetIter
Definition: Grid.h:519
OPENVDB_API void setGridClass(std::ios_base &, uint32_t)
Associate with the given stream the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid currently ...
GridType::Ptr createGrid(const typename GridType::ValueType &background)
Create a new grid of type GridType with a given background value.
Definition: Grid.h:1722
Vec3d indexToWorld(const Coord &ijk) const
Apply this grid's transform to the given coordinates.
Definition: Grid.h:439
Vec3d worldToIndex(const Vec3d &xyz) const
Apply the inverse of this grid's transform to the given coordinates.
Definition: Grid.h:441
SharedPtr< GridBase > Ptr
Definition: Grid.h:80
Tag dispatch class that distinguishes shallow copy constructors from deep copy constructors.
Definition: Types.h:680
hboost::math::policies::policy< hboost::math::policies::domain_error< hboost::math::policies::ignore_error >, hboost::math::policies::pole_error< hboost::math::policies::ignore_error >, hboost::math::policies::overflow_error< hboost::math::policies::ignore_error >, hboost::math::policies::underflow_error< hboost::math::policies::ignore_error >, hboost::math::policies::denorm_error< hboost::math::policies::ignore_error >, hboost::math::policies::rounding_error< hboost::math::policies::ignore_error >, hboost::math::policies::evaluation_error< hboost::math::policies::ignore_error >, hboost::math::policies::indeterminate_result_error< hboost::math::policies::ignore_error > > policy
Definition: SYS_MathCbrt.h:35
void writeTransform(std::ostream &os) const
Write out the transform for this grid.
Definition: Grid.h:472
SharedPtr< const Grid > ConstPtr
Definition: Grid.h:574
ValueAllIter beginValueAll()
Return an iterator over all of this grid's values (tile and voxel).
Definition: Grid.h:767
void topologyIntersection(const Grid< OtherTreeType > &other)
Intersect this grid's set of active values with the active values of the other grid, whose value type may be different.
Definition: Grid.h:1533
SharedPtr< const Transform > ConstPtr
Definition: Transform.h:43
Name valueType() const override
Return the name of the type of a voxel's value (e.g., "float" or "vec3d").
Definition: Grid.h:714
void readTransform(std::istream &is)
Read in the transform for this grid.
Definition: Grid.h:470
Grid & operator=(const Grid &)=delete
Disallow assignment, since it wouldn't be obvious whether the copy is deep or shallow.
void
Definition: png.h:1083
GridType
List of types that are currently supported by NanoVDB.
Definition: NanoVDB.h:294
static const char *const META_GRID_NAME
Definition: Grid.h:353
typename tree::ValueAccessor< TreeType > AccessorType
Definition: Grid.h:1072
ConstPtr copyReplacingMetadata(const MetaMap &meta) const
Return a new grid of the same type as this grid whose tree and transform is shared with this grid and...
Definition: Grid.h:1354
typename TreeType::ConstPtr ConstTreePtrType
Definition: Grid.h:1064
OIIO_UTIL_API bool copy(string_view from, string_view to, std::string &err)
static const TreeType & constTree(TreeType &t)
Definition: Grid.h:1110
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLsizei const GLfloat * value
Definition: glcorearb.h:824
ValueOnIter beginValueOn()
Return an iterator over all of this grid's active values (tile and voxel).
Definition: Grid.h:755
Mat3< Type1 > cwiseAdd(const Mat3< Type1 > &m, const Type2 s)
Definition: Mat3.h:806
Vec3d voxelSize(const Vec3d &xyz) const
Return the size of this grid's voxel at position (x, y, z).
Definition: Grid.h:433
typename _TreeType::ValueOffCIter ValueOffCIter
Definition: Grid.h:585
SharedPtr< GridCPtrVec > GridCPtrVecPtr
Definition: Grid.h:516
SharedPtr< StreamMetadata > Ptr
Definition: io.h:33
SharedPtr< GridPtrSet > GridPtrSetPtr
Definition: Grid.h:521
static const TreeType & constTree(const GridType &g)
Definition: Grid.h:1113
ValueConverter<T>::Type is the type of a grid having the same hierarchy as this grid but a different ...
Definition: Grid.h:601
Ptr copyWithNewTree() const
Return a new grid of the same type as this grid whose metadata and transform are deep copies of this ...
Definition: Grid.h:1389
GLboolean GLboolean g
Definition: glcorearb.h:1222
static const char *const META_SAVE_HALF_FLOAT
Definition: Grid.h:354
void topologyDifference(const Grid< OtherTreeType > &other)
Difference this grid's set of active values with the active values of the other grid, whose value type may be different.
Definition: Grid.h:1542
TreePtrType treePtr()
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:894
typename TreeType::ValueType ValueType
Definition: Grid.h:1071
typename tree::ValueAccessor< const TreeType > ConstAccessorType
Definition: Grid.h:1073
TreeType & tree()
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:908
SharedPtr< GridCPtrSet > GridCPtrSetPtr
Definition: Grid.h:526
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1222
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:239
GridBase::Ptr deepCopyGrid() const override
Return a new grid whose metadata, transform and tree are deep copies of this grid's.
Definition: Grid.h:703
GridCPtrSet::const_iterator GridCPtrSetCIter
Definition: Grid.h:525
bool operator()(const GridBase::ConstPtr &g) const
Definition: Grid.h:533
typename tree::ValueAccessor< _TreeType, false > UnsafeAccessor
Definition: Grid.h:591
static const char *const META_FILE_COMPRESSION
Definition: Grid.h:359
static const char *const META_IS_LOCAL_SPACE
Definition: Grid.h:355
The Value Accessor Implementation and API methods. The majoirty of the API matches the API of a compa...
Definition: ValueAccessor.h:68
typename tree::ValueAccessor< NonConstTreeType > NonConstAccessorType
Definition: Grid.h:1104
**But if you need a result
Definition: thread.h:613
static const char *const META_GRID_CLASS
Definition: Grid.h:351
tree::TreeBase TreeBase
Definition: Grid.h:26
typename tree::ValueAccessor< const TreeType > ConstAccessorType
Definition: Grid.h:1132
Ptr copy()
Return a new grid of the same type as this grid whose metadata and transform are deep copies of this ...
Definition: Grid.h:1381
ConstAccessor getConstAccessor() const
Return an accessor that provides random read-only access to this grid's voxels.
Definition: Grid.h:744
ConstPtr copyReplacingTransform(math::Transform::Ptr xform) const
Return a new grid of the same type as this grid whose tree is shared with this grid, whose metadata is a deep copy of this grid's and whose transform is provided as an argument.
Definition: Grid.h:1364
TreeBase::Ptr baseTreePtr()
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:1227
Container that maps names (strings) to values of arbitrary types.
Definition: MetaMap.h:19
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:508
uint64 value_type
Definition: GA_PrimCompat.h:29
typename std::remove_const< TreeType >::type NonConstTreeType
Definition: Grid.h:1121
std::set< GridBase::Ptr > GridPtrSet
Definition: Grid.h:518
typename _TreeType::ConstPtr ConstTreePtrType
Definition: Grid.h:578
This adapter allows code that is templated on a Tree type to accept either a Tree type or a Grid type...
Definition: Grid.h:1059
GridBase::ConstPtr copyGridReplacingTransform(math::Transform::Ptr xform) const override
Return a new grid of the same type as this grid whose tree is shared with this grid, whose metadata is a deep copy of this grid's and whose transform is provided as an argument.
Definition: Grid.h:1420
GridBase::Ptr copyGrid() override
Return a new grid of the same type as this grid whose metadata is a deep copy of this grid's and whos...
Definition: Grid.h:1399
typename tree::ValueAccessor< NonConstTreeType > NonConstAccessorType
Definition: Grid.h:1074
GridCPtrSet::iterator GridCPtrSetIter
Definition: Grid.h:524
static const char *const META_FILE_VOXEL_COUNT
Definition: Grid.h:361
ValueOffCIter cbeginValueOff() const
Return an iterator over all of this grid's inactive values (tile and voxel).
Definition: Grid.h:765
std::shared_ptr< T > SharedPtr
Definition: Types.h:114
static const TreeType & constTree(const TreeType &t)
Definition: Grid.h:1112
static const TreeType & tree(const GridType &g)
Definition: Grid.h:1109
Abstract base class for typed grids.
Definition: Grid.h:77
void clip(const CoordBBox &) override
Clip this grid to the given index-space bounding box.
Definition: Grid.h:1508
Vec3d indexToWorld(const Vec3d &xyz) const
Apply this grid's transform to the given coordinates.
Definition: Grid.h:437
static const char *const META_FILE_BBOX_MIN
Definition: Grid.h:357
typename std::remove_const< TreeType >::type NonConstTreeType
Definition: Grid.h:1092
ValueOffIter beginValueOff()
Return an iterator over all of this grid's inactive values (tile and voxel).
Definition: Grid.h:761
bool isType() const
Return true if this grid is of the same type as the template parameter.
Definition: Grid.h:146
#define OPENVDB_API
Definition: Platform.h:274
GridBase::ConstPtr copyGridReplacingMetadataAndTransform(const MetaMap &meta, math::Transform::Ptr xform) const override
Return a new grid of the same type as this grid whose tree is shared with this grid and whose transfo...
Definition: Grid.h:1427
void writeTopology(std::ostream &) const override
Write the grid topology to a stream. This will write only the grid structure, not the actual data buf...
Definition: Grid.h:1597
static void unregisterGrid()
Remove this grid type from the registry.
Definition: Grid.h:974
GLint ref
Definition: glcorearb.h:124
typename _TreeType::ValueAllCIter ValueAllCIter
Definition: Grid.h:587
static Ptr create()
Return a new grid with background value zero.
Definition: Grid.h:1308
static void registerGrid()
Register this grid type along with a factory function.
Definition: Grid.h:972
GridType::Ptr createLevelSet(Real voxelSize=1.0, Real halfWidth=LEVEL_SET_HALF_WIDTH)
Create a new grid of type GridType classified as a "Level Set", i.e., a narrow-band level set...
Definition: Grid.h:1747
GridBase(GridBase &other, ShallowCopy)
Copy another grid's metadata but share its transform.
Definition: Grid.h:492
typename tree::ValueAccessor< const _TreeType, false > ConstUnsafeAccessor
Definition: Grid.h:592
BBox< Coord > CoordBBox
Definition: NanoVDB.h:2516
virtual GridBase::Ptr deepCopyGrid() const =0
Return a new grid whose metadata, transform and tree are deep copies of this grid's.
math::Transform::ConstPtr transformPtr() const
Return a pointer to this grid's transform, which might be shared with other grids.
Definition: Grid.h:403
GridBase::Ptr copyGridWithNewTree() const override
Return a new grid of the same type as this grid whose metadata and transform are deep copies of this ...
Definition: Grid.h:1435
PXL_API const char * getName(const ColorSpace *space)
Return the name of the color space.
Accessor getAccessor()
Return an accessor that provides random read and write access to this grid's voxels.
Definition: Grid.h:732
void sparseFill(const CoordBBox &bbox, const ValueType &value, bool active=true)
Set all voxels within a given axis-aligned box to a constant value.
Definition: Grid.h:1478
ConstTreePtrType treePtr() const
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:895
GLuint GLuint end
Definition: glcorearb.h:475
bool apply(OpT &) const
If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid...
Definition: Grid.h:1768
typename GridType::Ptr GridPtrType
Definition: Grid.h:1068
CoordBBox evalActiveVoxelBoundingBox() const override
Return the axis-aligned bounding box of all active voxels.
Definition: Grid.h:1563
typename _TreeType::ValueOffIter ValueOffIter
Definition: Grid.h:584
typename NonConstGridType::Ptr NonConstGridPtrType
Definition: Grid.h:1069
Name type() const override
Return the name of this grid's type.
Definition: Grid.h:709
Index64 memUsage() const override
Definition: Grid.h:883
GridType::Ptr gridPtrCast(const GridBase::Ptr &grid)
Cast a generic grid pointer to a pointer to a grid of a concrete class.
Definition: Grid.h:1002
const TreeBase & constBaseTree() const
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:193
ValueOffCIter beginValueOff() const
Return an iterator over all of this grid's inactive values (tile and voxel).
Definition: Grid.h:763
static TreeType & tree(TreeType &t)
Definition: Grid.h:1076
#define OPENVDB_NO_DEPRECATION_WARNING_BEGIN
Bracket code with OPENVDB_NO_DEPRECATION_WARNING_BEGIN/_END, to inhibit warnings about deprecated cod...
Definition: Platform.h:194
GridBase()
Initialize with an identity linear transform.
Definition: Grid.h:482
GLuint const GLchar * name
Definition: glcorearb.h:786
static void unregisterGrid(const Name &type)
Remove a grid type from the registry.
ValueType &maxVal const
Return the number of active voxels.
Definition: Grid.h:879
typename TreeType::Ptr TreePtrType
Definition: Grid.h:1063
math::Transform::Ptr transformPtr()
Return a pointer to this grid's transform, which might be shared with other grids.
Definition: Grid.h:402
GA_API const UT_StringHolder transform
TreeBase::ConstPtr baseTreePtr() const
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:171
math::Transform & transform()
Return a reference to this grid's transform, which might be shared with other grids.
Definition: Grid.h:411
Container class that associates a tree with a transform and metadata.
Definition: Grid.h:28
that also have some descendant prim *whose name begins with which in turn has a child named baz where *the predicate active
ConstTreePtrType constTreePtr() const
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:896
void topologyUnion(const Grid< OtherTreeType > &other)
Union this grid's set of active values with the active values of the other grid, whose value type may...
Definition: Grid.h:1524
GLdouble t
Definition: glad.h:2397
SharedPtr< GridPtrVec > GridPtrVecPtr
Definition: Grid.h:511
typename _TreeType::ValueOnIter ValueOnIter
Definition: Grid.h:582
void readNonresidentBuffers() const override
Read all of this grid's data buffers that are not yet resident in memory (because delayed loading is ...
Definition: Grid.h:1650
GridPtrSet::const_iterator GridPtrSetCIter
Definition: Grid.h:520
ValueAllCIter cbeginValueAll() const
Return an iterator over all of this grid's values (tile and voxel).
Definition: Grid.h:771
static GridType::Ptr grid(const GridBase::Ptr &)
Return the result of downcasting a GridBase pointer to a Grid pointer of the specified type...
Definition: Grid.h:1189
const ValueType & background() const
Return this grid's background value.
Definition: Grid.h:722
static const TreeType & constTree(GridType &g)
Definition: Grid.h:1111
Base class for typed trees.
Definition: Tree.h:36
static const TreeType & tree(const TreeType &t)
Definition: Grid.h:1108
GridType::Ptr deepCopyTypedGrid(const GridBase::ConstPtr &grid)
Return a pointer to a deep copy of the given grid, provided that the grid's concrete type is GridType...
Definition: Grid.h:1035
typename std::remove_const< TreeType >::type NonConstTreeType
Definition: Grid.h:1062
static bool hasMultiPassIO()
Return true if grids of this type require multiple I/O passes to read and write data buffers...
Definition: Grid.h:1687
Predicate functor that returns true for grids that have a specified name.
Definition: Grid.h:530
GridCPtrVec::iterator GridCPtrVecIter
Definition: Grid.h:514
void print(std::ostream &=std::cout, int verboseLevel=1) const override
Output a human-readable description of this grid.
Definition: Grid.h:1695
ConstPtr copyReplacingMetadataAndTransform(const MetaMap &meta, math::Transform::Ptr xform) const
Return a new grid of the same type as this grid whose tree is shared with this grid and whose transfo...
Definition: Grid.h:1371
static const char *const META_FILE_MEM_BYTES
Definition: Grid.h:360
void denseFill(const CoordBBox &bbox, const ValueType &value, bool active=true)
Set all voxels within a given axis-aligned box to a constant value and ensure that those voxels are a...
Definition: Grid.h:1493
void fill(const CoordBBox &bbox, const ValueType &value, bool active=true)
Set all voxels within a given axis-aligned box to a constant value.
Definition: Grid.h:1486
GridBase::ConstPtr copyGridReplacingMetadata(const MetaMap &meta) const override
Return a new grid of the same type as this grid whose tree and transform is shared with this grid and...
Definition: Grid.h:1413
TreeBase & baseTree()
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:183
Coord evalActiveVoxelDim() const override
Return the dimensions of the axis-aligned bounding box of all active voxels.
Definition: Grid.h:1573
bool hasUniformVoxels() const
Return true if the voxels in world space are uniformly sized cubes.
Definition: Grid.h:435
OPENVDB_API uint32_t getGridClass(std::ios_base &)
Return the class (GRID_LEVEL_SET, GRID_UNKNOWN, etc.) of the grid currently being read from or writte...
typename tree::ValueAccessor< _TreeType, true > Accessor
Definition: Grid.h:589
typename _TreeType::ValueOnCIter ValueOnCIter
Definition: Grid.h:583
ValueAccessorImpl< TreeType, IsSafe, MutexType, openvdb::make_index_sequence< CacheLevels >> ValueAccessor
Default alias for a ValueAccessor. This is simply a helper alias for the generic definition but takes...
Definition: ValueAccessor.h:88
GridPtrVec::iterator GridPtrVecIter
Definition: Grid.h:509
MetadataMap::const_iterator ConstMetaIterator
Definition: MetaMap.h:28
static const char *const META_FILE_DELAYED_LOAD
Definition: Grid.h:362
ValueAllCIter beginValueAll() const
Return an iterator over all of this grid's values (tile and voxel).
Definition: Grid.h:769
static const TreeType & constTree(const TreeType &t)
Definition: Grid.h:1082
math::Transform::ConstPtr constTransformPtr() const
Return a pointer to this grid's transform, which might be shared with other grids.
Definition: Grid.h:404
void clear() override
Empty this grid, so that all voxels become inactive background voxels.
Definition: Grid.h:727
ConstAccessor getAccessor() const
Return an accessor that provides random read-only access to this grid's voxels.
Definition: Grid.h:742
SharedPtr< const GridBase > ConstPtr
Definition: Grid.h:81
void pruneGrid(float tolerance=0.0) override
Reduce the memory footprint of this grid by increasing its sparseness.
Definition: Grid.h:1500
#define OPENVDB_NO_DEPRECATION_WARNING_END
Definition: Platform.h:195
UnsafeAccessor getUnsafeAccessor()
Return an unsafe accessor that provides random read and write access to this grid's voxels...
Definition: Grid.h:740
SharedPtr< const TreeBase > ConstPtr
Definition: Tree.h:40
static const char *const META_GRID_CREATOR
Definition: Grid.h:352
void writeBuffers(std::ostream &) const override
Write out all data buffers for this grid.
Definition: Grid.h:1658
GridType::ConstPtr gridConstPtrCast(const GridBase::ConstPtr &grid)
Cast a generic const grid pointer to a const pointer to a grid of a concrete class.
Definition: Grid.h:1018
OPENVDB_API SharedPtr< StreamMetadata > getStreamMetadataPtr(std::ios_base &)
Return a shared pointer to an object that stores metadata (file format, compression scheme...
ValueOnCIter beginValueOn() const
Return an iterator over all of this grid's active values (tile and voxel).
Definition: Grid.h:757
Vec3d voxelSize() const
Return the size of this grid's voxels.
Definition: Grid.h:430
static const TreeType & tree(const GridType &g)
Definition: Grid.h:1079
static bool isRegistered()
Return true if this grid type is registered.
Definition: Grid.h:970
bool empty() const override
Return true if this grid contains only inactive background voxels.
Definition: Grid.h:725
static const TreeType & constTree(const GridType &g)
Definition: Grid.h:1083
GridBase(const GridBase &other)
Deep copy another grid's metadata and transform.
Definition: Grid.h:489
Definition: core.h:1131
Metafunction that specifies whether a given leaf node, tree, or grid type requires multiple passes to...
Definition: Grid.h:1159
Fp4 BuildType
Definition: NanoVDB.h:5565
const math::Transform & transform() const
Return a reference to this grid's transform, which might be shared with other grids.
Definition: Grid.h:412
GridPtrContainerT::value_type findGridByName(const GridPtrContainerT &container, const Name &name)
Return the first grid in the given container whose name is name.
Definition: Grid.h:540
typename _TreeType::BuildType BuildType
Definition: Grid.h:580
typename NonConstTreeType::Ptr NonConstTreePtrType
Definition: Grid.h:1065
static const char *const META_VECTOR_TYPE
Definition: Grid.h:356
virtual TreeBase::ConstPtr constBaseTreePtr() const =0
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Grid()
Construct a new grid with background value zero.
Definition: Grid.h:1245
void readBuffers(std::istream &) override
Read all data buffers for this grid.
Definition: Grid.h:1605
void merge(Grid &other, MergePolicy policy=MERGE_ACTIVE_STATES)
Efficiently merge another grid into this grid using one of several schemes.
Definition: Grid.h:1515
static Transform::Ptr createLinearTransform(double voxelSize=1.0)
Create and return a shared pointer to a new transform.
static bool isRegistered(const Name &type)
Return true if the given grid type name is registered.
std::set< GridBase::ConstPtr > GridCPtrSet
Definition: Grid.h:523
bool evalMinMax(const PointDataTreeT &points, const std::string &attribute, ValueT &min, ValueT &max, const FilterT &filter, typename PointDataTreeT::template ValueConverter< ValueT >::Type *minTree, typename PointDataTreeT::template ValueConverter< ValueT >::Type *maxTree)
Evaluates the minimum and maximum values of a point attribute and returns whether the values are vali...
void setTransform(math::Transform::Ptr)
Associate the given transform with this grid, in place of its existing transform. ...
Definition: Grid.h:1234
const math::Transform & constTransform() const
Return a reference to this grid's transform, which might be shared with other grids.
Definition: Grid.h:413
typename tree::ValueAccessor< const _TreeType, true > ConstAccessor
Definition: Grid.h:590
std::vector< GridBase::ConstPtr > GridCPtrVec
Definition: Grid.h:513
typename _TreeType::ValueAllIter ValueAllIter
Definition: Grid.h:586
static const TreeType & constTree(TreeType &t)
Definition: Grid.h:1080
type
Definition: core.h:1059
FMT_INLINE void print(format_string< T...> fmt, T &&...args)
Definition: core.h:2976
static const TreeType & constTree(GridType &g)
Definition: Grid.h:1081
static Name gridType()
Return the name of this type of grid.
Definition: Grid.h:711
const TreeType & constTree() const
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:910
IMATH_INTERNAL_NAMESPACE_HEADER_ENTER IMATH_HOSTDEVICE IMATH_CONSTEXPR14 T clip(const T &p, const Box< T > &box) IMATH_NOEXCEPT
Definition: ImathBoxAlgo.h:29
Ptr deepCopy() const
Return a new grid whose metadata, transform and tree are deep copies of this grid's.
Definition: Grid.h:701
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:119
bool ValueType
Definition: NanoVDB.h:5729
OPENVDB_API uint32_t getFormatVersion(std::ios_base &)
Return the file format version number associated with the given input stream.
TreeBase::ConstPtr constBaseTreePtr() const override
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:897
void readTopology(std::istream &) override
Read the grid topology from a stream. This will read only the grid structure, not the actual data buf...
Definition: Grid.h:1589
GridCPtrVec::const_iterator GridCPtrVecCIter
Definition: Grid.h:515
OPENVDB_DEPRECATED_MESSAGE("Switch from grid->evalMinMax(minVal, maxVal) to \ tools::minMax(grid->tree()). Use threaded = false for serial execution") void evalMinMax(ValueType &minVal
Return the minimum and maximum active values in this grid.
void newTree() override
Associate a new, empty tree with this grid, in place of its existing tree.
Definition: Grid.h:1467
ValueOnCIter cbeginValueOn() const
Return an iterator over all of this grid's active values (tile and voxel).
Definition: Grid.h:759
static TreeType & tree(GridType &g)
Definition: Grid.h:1077
static void registerGrid(const Name &type, GridFactory)
Register a grid type along with a factory function.
static const char *const META_FILE_BBOX_MAX
Definition: Grid.h:358
GridPtrVec::const_iterator GridPtrVecCIter
Definition: Grid.h:510
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:74
typename GridType::ConstPtr ConstGridPtrType
Definition: Grid.h:1070
const TreeBase & baseTree() const
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:188
typename _TreeType::Ptr TreePtrType
Definition: Grid.h:577
Index64 activeVoxelCount() const override
Return the number of active voxels.
Definition: Grid.h:871
typename tree::ValueAccessor< NonConstTreeType > NonConstAccessorType
Definition: Grid.h:1133
const TreeType & tree() const
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:909
void setTree(TreeBase::Ptr) override
Associate the given tree with this grid, in place of its existing tree.
Definition: Grid.h:1454