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