OpenVDB 9.0.0
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
22namespace openvdb {
24namespace OPENVDB_VERSION_NAME {
25
27
28template<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).
35template<typename GridType>
36inline 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().
42template<typename GridType>
43inline 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).
50template<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.
68template<typename GridType>
69typename 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{
79public:
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.
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.
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
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
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.
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;
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
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
298 /// Remove the setting specifying the class of this grid's volumetric data.
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
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
324 /// Remove the setting specifying the type of vector data stored in this grid.
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.
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.
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.
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.
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
484protected:
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
506private:
507 math::Transform::Ptr mTransform;
508}; // class GridBase
509
510
511////////////////////////////////////////
512
513
514using GridPtrVec = std::vector<GridBase::Ptr>;
515using GridPtrVecIter = GridPtrVec::iterator;
516using GridPtrVecCIter = GridPtrVec::const_iterator;
518
519using GridCPtrVec = std::vector<GridBase::ConstPtr>;
520using GridCPtrVecIter = GridCPtrVec::iterator;
521using GridCPtrVecCIter = GridCPtrVec::const_iterator;
523
524using GridPtrSet = std::set<GridBase::Ptr>;
525using GridPtrSetIter = GridPtrSet::iterator;
526using GridPtrSetCIter = GridPtrSet::const_iterator;
528
529using GridCPtrSet = std::set<GridBase::ConstPtr>;
530using GridCPtrSetIter = GridCPtrSet::iterator;
531using 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.
544template<typename GridPtrContainerT>
545inline typename GridPtrContainerT::value_type
546findGridByName(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.
555template<typename KeyT, typename GridPtrT>
556inline GridPtrT
557findGridByName(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
575template<typename _TreeType>
576class Grid: public GridBase
577{
578public:
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>
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.
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
686 ConstPtr copyReplacingTransform(math::Transform::Ptr xform) const;
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
690 ConstPtr copyReplacingMetadataAndTransform(const MetaMap& meta,
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
700 GridBase::ConstPtr copyGridReplacingTransform(math::Transform::Ptr xform) const override;
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
704 GridBase::ConstPtr copyGridReplacingMetadataAndTransform(const MetaMap& meta,
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.
740 Accessor getAccessor() { return Accessor(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.
750 ConstAccessor getAccessor() const { return ConstAccessor(tree()); }
751 /// Return an accessor that provides random read-only access to this grid's voxels.
752 ConstAccessor getConstAccessor() const { return ConstAccessor(tree()); }
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.
827 void merge(Grid& other, MergePolicy policy = MERGE_ACTIVE_STATES);
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
988private:
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).
1011template<typename GridType>
1012inline 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).
1027template<typename GridType>
1028inline 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.
1044template<typename GridType>
1045inline typename GridType::Ptr
1047{
1048 if (!grid || !grid->isType<GridType>()) return typename GridType::Ptr();
1049 return gridPtrCast<GridType>(grid->deepCopyGrid());
1050}
1051
1052
1053template<typename GridType>
1054inline 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.
1069template<typename _TreeType>
1071{
1072 using TreeType = _TreeType;
1073 using NonConstTreeType = typename std::remove_const<TreeType>::type;
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
1099template<typename _TreeType>
1100struct TreeAdapter<Grid<_TreeType> >
1101{
1102 using TreeType = _TreeType;
1103 using NonConstTreeType = typename std::remove_const<TreeType>::type;
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
1128template<typename _TreeType>
1129struct TreeAdapter<tree::ValueAccessor<_TreeType> >
1130{
1131 using TreeType = _TreeType;
1132 using NonConstTreeType = typename std::remove_const<TreeType>::type;
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
1169template<typename LeafNodeType>
1172};
1173
1174// Partial specialization for Tree types
1175template<typename RootNodeType>
1176struct 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
1182template<typename TreeType>
1183struct 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
1200template<typename GridType>
1201inline 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
1213template<typename GridType>
1214inline typename GridType::ConstPtr
1216{
1217 return ConstPtrCast<const GridType>(
1218 GridBase::grid<GridType>(ConstPtrCast<GridBase>(grid)));
1219}
1220
1221
1222template<typename GridType>
1223inline typename GridType::ConstPtr
1225{
1226 return ConstPtrCast<const GridType>(GridBase::grid<GridType>(grid));
1227}
1228
1229
1230template<typename GridType>
1231inline typename GridType::ConstPtr
1233{
1234 return ConstPtrCast<const GridType>(
1235 GridBase::grid<GridType>(ConstPtrCast<GridBase>(grid)));
1236}
1237
1238
1239inline TreeBase::Ptr
1241{
1242 return ConstPtrCast<TreeBase>(this->constBaseTreePtr());
1243}
1244
1245
1246inline void
1248{
1249 if (!xform) OPENVDB_THROW(ValueError, "Transform pointer is null");
1250 mTransform = xform;
1251}
1252
1253
1254////////////////////////////////////////
1255
1256
1257template<typename TreeT>
1258inline Grid<TreeT>::Grid(): mTree(new TreeType)
1259{
1260}
1261
1262
1263template<typename TreeT>
1264inline Grid<TreeT>::Grid(const ValueType &background): mTree(new TreeType(background))
1265{
1266}
1267
1268
1269template<typename TreeT>
1270inline 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
1277template<typename TreeT>
1278inline 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
1287template<typename TreeT>
1288inline Grid<TreeT>::Grid(const Grid& other):
1289 GridBase(other),
1290 mTree(StaticPtrCast<TreeType>(other.mTree->copy()))
1291{
1292}
1293
1294
1295template<typename TreeT>
1296template<typename OtherTreeType>
1298 GridBase(other),
1299 mTree(new TreeType(other.constTree()))
1300{
1301}
1302
1303
1304template<typename TreeT>
1306 GridBase(other),
1307 mTree(other.mTree)
1308{
1309}
1310
1311
1312template<typename TreeT>
1313inline Grid<TreeT>::Grid(const GridBase& other):
1314 GridBase(other),
1315 mTree(new TreeType)
1316{
1317}
1318
1319
1320//static
1321template<typename TreeT>
1322inline typename Grid<TreeT>::Ptr
1324{
1325 return Grid::create(zeroVal<ValueType>());
1326}
1327
1328
1329//static
1330template<typename TreeT>
1331inline typename Grid<TreeT>::Ptr
1333{
1334 return Ptr(new Grid(background));
1335}
1336
1337
1338//static
1339template<typename TreeT>
1340inline typename Grid<TreeT>::Ptr
1342{
1343 return Ptr(new Grid(tree));
1344}
1345
1346
1347//static
1348template<typename TreeT>
1349inline typename Grid<TreeT>::Ptr
1351{
1352 return Ptr(new Grid(other));
1353}
1354
1355
1356////////////////////////////////////////
1357
1358
1359template<typename TreeT>
1360inline 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
1368template<typename TreeT>
1369inline 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
1378template<typename TreeT>
1379inline typename Grid<TreeT>::ConstPtr
1381{
1382 return this->copyReplacingMetadataAndTransform(*this, xform);
1383}
1384
1385template<typename TreeT>
1386inline 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
1396template<typename TreeT>
1397inline typename Grid<TreeT>::Ptr
1399{
1400 return Ptr{new Grid{*this, ShallowCopy{}}};
1401}
1402
1403
1404template<typename TreeT>
1405inline typename Grid<TreeT>::Ptr
1407{
1408 Ptr result{new Grid{*const_cast<Grid*>(this), ShallowCopy{}}};
1409 result->newTree();
1410 return result;
1411}
1412
1413
1414template<typename TreeT>
1415inline GridBase::Ptr
1417{
1418 return this->copy();
1419}
1420
1421template<typename TreeT>
1422inline GridBase::ConstPtr
1424{
1425 return this->copy();
1426}
1427
1428#if OPENVDB_ABI_VERSION_NUMBER >= 7
1429template<typename TreeT>
1430inline GridBase::ConstPtr
1432{
1433 return this->copyReplacingMetadata(meta);
1434}
1435
1436template<typename TreeT>
1437inline GridBase::ConstPtr
1439{
1440 return this->copyReplacingTransform(xform);
1441}
1442
1443template<typename TreeT>
1444inline GridBase::ConstPtr
1446 math::Transform::Ptr xform) const
1447{
1448 return this->copyReplacingMetadataAndTransform(meta, xform);
1449}
1450#endif
1451
1452template<typename TreeT>
1453inline GridBase::Ptr
1455{
1456 return this->copyWithNewTree();
1457}
1458
1459
1460////////////////////////////////////////
1461
1462
1463template<typename TreeT>
1464inline bool
1466{
1467 return mTree.use_count() == 1;
1468}
1469
1470
1471template<typename TreeT>
1472inline 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
1484template<typename TreeT>
1485inline void
1487{
1488 mTree.reset(new TreeType(this->background()));
1489}
1490
1491
1492////////////////////////////////////////
1493
1494
1495template<typename TreeT>
1496inline void
1497Grid<TreeT>::sparseFill(const CoordBBox& bbox, const ValueType& value, bool active)
1498{
1499 tree().sparseFill(bbox, value, active);
1500}
1501
1502
1503template<typename TreeT>
1504inline void
1505Grid<TreeT>::fill(const CoordBBox& bbox, const ValueType& value, bool active)
1506{
1507 this->sparseFill(bbox, value, active);
1508}
1509
1510template<typename TreeT>
1511inline void
1512Grid<TreeT>::denseFill(const CoordBBox& bbox, const ValueType& value, bool active)
1513{
1514 tree().denseFill(bbox, value, active);
1515}
1516
1517template<typename TreeT>
1518inline void
1520{
1521 const auto value = math::cwiseAdd(zeroVal<ValueType>(), tolerance);
1522 this->tree().prune(static_cast<ValueType>(value));
1523}
1524
1525template<typename TreeT>
1526inline void
1528{
1529 tree().clip(bbox);
1530}
1531
1532template<typename TreeT>
1533inline void
1535{
1536 tree().merge(other.tree(), policy);
1537}
1538
1539
1540template<typename TreeT>
1541template<typename OtherTreeType>
1542inline void
1544{
1545 tree().topologyUnion(other.tree());
1546}
1547
1548
1549template<typename TreeT>
1550template<typename OtherTreeType>
1551inline void
1553{
1554 tree().topologyIntersection(other.tree());
1555}
1556
1557
1558template<typename TreeT>
1559template<typename OtherTreeType>
1560inline void
1562{
1563 tree().topologyDifference(other.tree());
1564}
1565
1566
1567////////////////////////////////////////
1568
1569
1570template<typename TreeT>
1571inline void
1573{
1574 tree().evalMinMax(minVal, maxVal);
1575}
1576
1577
1578template<typename TreeT>
1579inline CoordBBox
1581{
1582 CoordBBox bbox;
1583 tree().evalActiveVoxelBoundingBox(bbox);
1584 return bbox;
1585}
1586
1587
1588template<typename TreeT>
1589inline 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
1604template<typename TreeT>
1605inline void
1607{
1608 tree().readTopology(is, saveFloatAsHalf());
1609}
1610
1611
1612template<typename TreeT>
1613inline void
1614Grid<TreeT>::writeTopology(std::ostream& os) const
1615{
1616 tree().writeTopology(os, saveFloatAsHalf());
1617}
1618
1619
1620template<typename TreeT>
1621inline void
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.
1642template<typename TreeT>
1643inline void
1644Grid<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
1665template<typename TreeT>
1666inline void
1668{
1669 tree().readNonresidentBuffers();
1670}
1671
1672
1673template<typename TreeT>
1674inline void
1675Grid<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
1702template<typename TreeT>
1703inline bool
1705{
1707}
1708
1709
1710template<typename TreeT>
1711inline void
1712Grid<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
1737template<typename GridType>
1738inline typename GridType::Ptr
1739createGrid(const typename GridType::ValueType& background)
1740{
1741 return GridType::create(background);
1742}
1743
1744
1745template<typename GridType>
1746inline typename GridType::Ptr
1748{
1749 return GridType::create();
1750}
1751
1752
1753template<typename TreePtrType>
1755createGrid(TreePtrType tree)
1756{
1757 using TreeType = typename TreePtrType::element_type;
1758 return Grid<TreeType>::create(tree);
1759}
1760
1761
1762template<typename GridType>
1763typename GridType::Ptr
1764createLevelSet(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
1784namespace internal {
1785
1786/// @private
1787template<typename OpT, typename GridBaseT, typename T, typename ...Ts>
1788struct GridApplyImpl { static bool apply(GridBaseT&, OpT&) { return false; } };
1789
1790// Partial specialization for (nonempty) TypeLists
1791/// @private
1792template<typename OpT, typename GridBaseT, typename GridT, typename ...GridTs>
1793struct 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
1809template<typename GridTypeListT, typename OpT>
1810inline bool
1811GridBase::apply(OpT& op) const
1812{
1813 return internal::GridApplyImpl<OpT, const GridBase, GridTypeListT>::apply(*this, op);
1814}
1815
1816template<typename GridTypeListT, typename OpT>
1817inline bool
1819{
1820 return internal::GridApplyImpl<OpT, GridBase, GridTypeListT>::apply(*this, op);
1821}
1822
1823template<typename GridTypeListT, typename OpT>
1824inline bool
1825GridBase::apply(const OpT& op) const
1826{
1827 return internal::GridApplyImpl<const OpT, const GridBase, GridTypeListT>::apply(*this, op);
1828}
1829
1830template<typename GridTypeListT, typename OpT>
1831inline bool
1832GridBase::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
ValueT value
Definition: GridBuilder.h:1287
#define OPENVDB_API
Definition: Platform.h:254
OpenVDB AX Exceptions.
Consolidated llvm types for most supported types.
Abstract base class for typed grids.
Definition: Grid.h:78
virtual Name valueType() const =0
Return the name of the type of a voxel's value (e.g., "float" or "vec3d").
virtual GridBase::Ptr copyGrid()=0
Return a new grid of the same type as this grid whose metadata is a deep copy of this grid's and whos...
virtual GridBase::ConstPtr copyGridReplacingMetadataAndTransform(const MetaMap &meta, math::Transform::Ptr xform) const =0
Return a new grid of the same type as this grid whose tree is shared with this grid and whose transfo...
virtual GridBase::ConstPtr copyGridReplacingMetadata(const MetaMap &meta) const =0
Return a new grid of the same type as this grid whose tree and transform is shared with this grid and...
static const char *const META_FILE_MEM_BYTES
Definition: Grid.h:364
Ptr(*)() GridFactory
Definition: Grid.h:83
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
static const char *const META_FILE_BBOX_MAX
Definition: Grid.h:362
virtual void readBuffers(std::istream &)=0
Read all data buffers for this grid.
virtual void writeBuffers(std::ostream &) const =0
Write out all data buffers for this grid.
static std::string gridClassToMenuName(GridClass)
Return a formatted string version of the grid class.
bool hasUniformVoxels() const
Return true if the voxels in world space are uniformly sized cubes.
Definition: Grid.h:439
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 setSaveFloatAsHalf(bool)
Return this grid's user-specified name.
~GridBase() override
Definition: Grid.h:86
virtual GridBase::ConstPtr copyGridReplacingTransform(math::Transform::Ptr xform) const =0
Return a new grid of the same type as this grid whose tree is shared with this grid,...
Vec3d indexToWorld(const Coord &ijk) const
Apply this grid's transform to the given coordinates.
Definition: Grid.h:443
Vec3d voxelSize() const
Return the size of this grid's voxels.
Definition: Grid.h:434
static std::string vecTypeDescription(VecType)
Return a string describing how the given type of vector data is affected by transformations (e....
const math::Transform & constTransform() const
Return a pointer to this grid's transform, which might be shared with other grids.
Definition: Grid.h:417
void setName(const std::string &)
Specify a name for this grid.
static const char *const META_FILE_DELAYED_LOAD
Definition: Grid.h:366
Vec3d indexToWorld(const Vec3d &xyz) const
Apply this grid's transform to the given coordinates.
Definition: Grid.h:441
void clearGridClass()
Remove the setting specifying the class of this grid's volumetric data.
virtual bool isTreeUnique() const =0
Return true if tree is not shared with another grid.
bool isType() const
Return true if this grid is of the same type as the template parameter.
Definition: Grid.h:148
static std::string vecTypeToString(VecType)
Return the metadata string value for the given type of vector data.
static const char *const META_IS_LOCAL_SPACE
Definition: Grid.h:359
Vec3d worldToIndex(const Vec3d &xyz) const
Apply the inverse of this grid's transform to the given coordinates.
Definition: Grid.h:445
SharedPtr< const GridBase > ConstPtr
Definition: Grid.h:81
virtual GridBase::Ptr copyGridWithNewTree() const =0
Return a new grid of the same type as this grid whose metadata and transform are deep copies of this ...
math::Transform & transform()
Return a reference to this grid's transform, which might be shared with other grids.
Definition: Grid.h:415
GridBase(GridBase &other, ShallowCopy)
Copy another grid's metadata but share its transform.
Definition: Grid.h:498
static const char *const META_SAVE_HALF_FLOAT
Definition: Grid.h:358
virtual void clear()=0
Empty this grid, setting all voxels to the background.
void setGridClass(GridClass)
Specify the class of volumetric data (level set, fog volume, etc.) that is stored in this grid.
virtual void writeTopology(std::ostream &) const =0
Write the grid topology to a stream. This will write only the grid structure, not the actual data buf...
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
void addStatsMetadata()
Add metadata to this grid comprising the current values of statistics like the active voxel count and...
const TreeBase & baseTree() const
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:192
void clearVectorType()
Remove the setting specifying the type of vector data stored in this grid.
virtual void newTree()=0
Set a new tree with the same background value as the previous tree.
static const char *const META_FILE_COMPRESSION
Definition: Grid.h:363
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...
static std::string vecTypeExamples(VecType)
void clipGrid(const BBoxd &)
Clip this grid to the given world-space bounding box.
virtual CoordBBox evalActiveVoxelBoundingBox() const =0
static const char *const META_FILE_BBOX_MIN
Definition: Grid.h:361
virtual Index64 memUsage() const =0
Return the number of bytes of memory used by this grid.
void setVectorType(VecType)
Specify the type of vector data (invariant, covariant, etc.) stored in this grid, assuming that this ...
virtual Index64 activeVoxelCount() const =0
Return the number of active voxels.
static bool isRegistered(const Name &type)
Return true if the given grid type name is registered.
Vec3d voxelSize(const Vec3d &xyz) const
Return the size of this grid's voxel at position (x, y, z).
Definition: Grid.h:437
std::string getName() const
Return this grid's user-specified name.
virtual void print(std::ostream &=std::cout, int verboseLevel=1) const =0
Output a human-readable description of this grid.
void setTransform(math::Transform::Ptr)
Associate the given transform with this grid, in place of its existing transform.
Definition: Grid.h:1247
virtual void pruneGrid(float tolerance=0.0)=0
Reduce the memory footprint of this grid by increasing its sparseness either losslessly (tolerance = ...
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
static GridType::ConstPtr constGrid(const GridBase::Ptr &)
Definition: Grid.h:1224
GridClass getGridClass() const
Return the class of volumetric data (level set, fog volume, etc.) that is stored in this grid.
static VecType stringToVecType(const std::string &)
static void unregisterGrid(const Name &type)
Remove a grid type from the registry.
virtual void readNonresidentBuffers() const =0
Read all of this grid's data buffers that are not yet resident in memory (because delayed loading is ...
static const char *const META_GRID_CREATOR
Definition: Grid.h:356
void readTransform(std::istream &is)
Read in the transform for this grid.
Definition: Grid.h:474
static const char *const META_GRID_NAME
Definition: Grid.h:357
static const char *const META_GRID_CLASS
Definition: Grid.h:355
GridBase(const GridBase &other)
Deep copy another grid's metadata and transform.
Definition: Grid.h:495
math::Transform::Ptr transformPtr()
Return a pointer to this grid's transform, which might be shared with other grids.
Definition: Grid.h:406
static const char *const META_VECTOR_TYPE
Definition: Grid.h:360
static GridClass stringToGridClass(const std::string &)
Return the class of volumetric data specified by the given string.
virtual Coord evalActiveVoxelDim() const =0
Return the dimensions of the axis-aligned bounding box of all active voxels.
void setCreator(const std::string &)
Provide a description of this grid's creator.
bool saveFloatAsHalf() const
Return true if this grid should be written out with floating-point voxel values (including components...
MetaMap::Ptr getStatsMetadata() const
Return a new MetaMap containing just the metadata that was added to this grid with addStatsMetadata.
const math::Transform & transform() const
Return a pointer to this grid's transform, which might be shared with other grids.
Definition: Grid.h:416
static std::string gridClassToString(GridClass)
Return the metadata string value for the given class of volumetric data.
virtual void clip(const CoordBBox &)=0
Clip this grid to the given index-space bounding box.
virtual Name type() const =0
Return the name of this grid's type.
TreeBase & baseTree()
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:187
virtual void readTopology(std::istream &)=0
Read the grid topology from a stream. This will read only the grid structure, not the actual data buf...
virtual void readBuffers(std::istream &, const CoordBBox &)=0
Read all of this grid's data buffers that intersect the given index-space bounding box.
const TreeBase & constBaseTree() const
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:197
static void clearRegistry()
Clear the grid type registry.
std::string getCreator() const
Return the user-specified description of this grid's creator.
void writeTransform(std::ostream &os) const
Write out the transform for this grid.
Definition: Grid.h:476
VecType getVectorType() const
Return the type of vector data (invariant, covariant, etc.) stored in this grid, assuming that this g...
static Ptr createGrid(const Name &type)
Create a new grid of the given (registered) type.
SharedPtr< GridBase > Ptr
Definition: Grid.h:80
static void registerGrid(const Name &type, GridFactory)
Register a grid type along with a factory function.
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
virtual bool empty() const =0
Return true if this grid contains only background voxels.
static const char *const META_FILE_VOXEL_COUNT
Definition: Grid.h:365
virtual void setTree(TreeBase::Ptr)=0
Associate the given tree with this grid, in place of its existing tree.
virtual GridBase::Ptr deepCopyGrid() const =0
Return a new grid whose metadata, transform and tree are deep copies of this grid's.
virtual GridBase::ConstPtr copyGrid() const =0
Return a new grid of the same type as this grid whose metadata is a deep copy of this grid's and whos...
GridBase()
Initialize with an identity linear transform.
Definition: Grid.h:486
bool isInWorldSpace() const
math::Transform::ConstPtr transformPtr() const
Return a pointer to this grid's transform, which might be shared with other grids.
Definition: Grid.h:407
void setIsInWorldSpace(bool)
Specify whether this grid's voxel values are in world space or in local space.
Container class that associates a tree with a transform and metadata.
Definition: Grid.h:577
const TreeType & tree() const
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:918
typename tree::ValueAccessor< const _TreeType, false > ConstUnsafeAccessor
Definition: Grid.h:598
typename _TreeType::Ptr TreePtrType
Definition: Grid.h:583
Grid()
Construct a new grid with background value zero.
Definition: Grid.h:1258
typename _TreeType::ValueOffCIter ValueOffCIter
Definition: Grid.h:591
void evalMinMax(ValueType &minVal, ValueType &maxVal) const
Return the minimum and maximum active values in this grid.
Definition: Grid.h:1572
typename tree::ValueAccessor< _TreeType, false > UnsafeAccessor
Definition: Grid.h:597
bool empty() const override
Return true if this grid contains only inactive background voxels.
Definition: Grid.h:733
typename _TreeType::ValueOffIter ValueOffIter
Definition: Grid.h:590
TreeType & tree()
Return a reference to this grid's tree, which might be shared with other grids.
Definition: Grid.h:917
void topologyIntersection(const Grid< OtherTreeType > &other)
Intersect this grid's set of active values with the active values of the other grid,...
Definition: Grid.h:1552
ValueOffCIter cbeginValueOff() const
Return an iterator over all of this grid's inactive values (tile and voxel).
Definition: Grid.h:773
void readBuffers(std::istream &) override
Read all data buffers for this grid.
Definition: Grid.h:1622
static Name gridType()
Return the name of this type of grid.
Definition: Grid.h:719
Index64 memUsage() const override
Definition: Grid.h:889
void writeBuffers(std::ostream &) const override
Write out all data buffers for this grid.
Definition: Grid.h:1675
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
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,...
Definition: Grid.h:1380
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
bool isTreeUnique() const final
Return true if tree is not shared with another grid.
Definition: Grid.h:1465
void pruneGrid(float tolerance=0.0) override
Reduce the memory footprint of this grid by increasing its sparseness.
Definition: Grid.h:1519
void clip(const CoordBBox &) override
Clip this grid to the given index-space bounding box.
Definition: Grid.h:1527
ValueAllCIter cbeginValueAll() const
Return an iterator over all of this grid's values (tile and voxel).
Definition: Grid.h:779
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
Coord evalActiveVoxelDim() const override
Return the dimensions of the axis-aligned bounding box of all active voxels.
Definition: Grid.h:1590
ValueOnCIter beginValueOn() const
Return an iterator over all of this grid's active values (tile and voxel).
Definition: Grid.h:765
typename tree::ValueAccessor< _TreeType, true > Accessor
Definition: Grid.h:595
void setTree(TreeBase::Ptr) override
Associate the given tree with this grid, in place of its existing tree.
Definition: Grid.h:1473
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
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
typename tree::ValueAccessor< const _TreeType, true > ConstAccessor
Definition: Grid.h:596
~Grid() override
Definition: Grid.h:646
Name type() const override
Return the name of this grid's type.
Definition: Grid.h:717
void print(std::ostream &=std::cout, int verboseLevel=1) const override
Output a human-readable description of this grid.
Definition: Grid.h:1712
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
typename _TreeType::ValueAllCIter ValueAllCIter
Definition: Grid.h:593
Index64 activeVoxelCount() const override
Return the number of active voxels.
Definition: Grid.h:879
ConstAccessor getAccessor() const
Return an accessor that provides random read-only access to this grid's voxels.
Definition: Grid.h:750
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
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
ValueOffCIter beginValueOff() const
Return an iterator over all of this grid's inactive values (tile and voxel).
Definition: Grid.h:771
UnsafeAccessor getUnsafeAccessor()
Return an unsafe accessor that provides random read and write access to this grid's voxels.
Definition: Grid.h:748
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 _TreeType::ValueType ValueType
Definition: Grid.h:585
typename _TreeType::ConstPtr ConstTreePtrType
Definition: Grid.h:584
ValueOnIter beginValueOn()
Return an iterator over all of this grid's active values (tile and voxel).
Definition: Grid.h:763
typename _TreeType::ValueOnCIter ValueOnCIter
Definition: Grid.h:589
SharedPtr< const Grid > ConstPtr
Definition: Grid.h:580
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
static void registerGrid()
Register this grid type along with a factory function.
Definition: Grid.h:981
ValueOnCIter cbeginValueOn() const
Return an iterator over all of this grid's active values (tile and voxel).
Definition: Grid.h:767
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 bool isRegistered()
Return true if this grid type is registered.
Definition: Grid.h:979
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
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
typename _TreeType::BuildType BuildType
Definition: Grid.h:586
ConstAccessor getConstAccessor() const
Return an accessor that provides random read-only access to this grid's voxels.
Definition: Grid.h:752
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
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
void topologyDifference(const Grid< OtherTreeType > &other)
Difference this grid's set of active values with the active values of the other grid,...
Definition: Grid.h:1561
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
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,...
Definition: Grid.h:1438
CoordBBox evalActiveVoxelBoundingBox() const override
Return the axis-aligned bounding box of all active voxels.
Definition: Grid.h:1580
Ptr deepCopy() const
Return a new grid whose metadata, transform and tree are deep copies of this grid's.
Definition: Grid.h:709
const ValueType & background() const
Return this grid's background value.
Definition: Grid.h:730
ValueOffIter beginValueOff()
Return an iterator over all of this grid's inactive values (tile and voxel).
Definition: Grid.h:769
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
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
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
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 void unregisterGrid()
Remove this grid type from the registry.
Definition: Grid.h:983
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::ValueAllIter ValueAllIter
Definition: Grid.h:592
_TreeType TreeType
Definition: Grid.h:582
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 clear() override
Empty this grid, so that all voxels become inactive background voxels.
Definition: Grid.h:735
const TreeType & constTree() const
Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guarante...
Definition: Grid.h:919
ValueAllCIter beginValueAll() const
Return an iterator over all of this grid's values (tile and voxel).
Definition: Grid.h:777
void newTree() override
Associate a new, empty tree with this grid, in place of its existing tree.
Definition: Grid.h:1486
Grid & operator=(const Grid &)=delete
Disallow assignment, since it wouldn't be obvious whether the copy is deep or shallow.
ConstUnsafeAccessor getConstUnsafeAccessor() const
Return an unsafe accessor that provides random read-only access to this grid's voxels.
Definition: Grid.h:760
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< Grid > Ptr
Definition: Grid.h:579
Accessor getAccessor()
Return an accessor that provides random read and write access to this grid's voxels.
Definition: Grid.h:740
ValueAllIter beginValueAll()
Return an iterator over all of this grid's values (tile and voxel).
Definition: Grid.h:775
static Ptr create()
Return a new grid with background value zero.
Definition: Grid.h:1323
Container that maps names (strings) to values of arbitrary types.
Definition: MetaMap.h:20
MetadataMap::const_iterator ConstMetaIterator
Definition: MetaMap.h:28
SharedPtr< MetaMap > Ptr
Definition: MetaMap.h:22
Tag dispatch class that distinguishes shallow copy constructors from deep copy constructors.
Definition: Types.h:561
Definition: Exceptions.h:64
Definition: Exceptions.h:65
SharedPtr< StreamMetadata > Ptr
Definition: io.h:33
Axis-aligned bounding box of signed integer coordinates.
Definition: Coord.h:248
Signed (x, y, z) 32-bit integer coordinates.
Definition: Coord.h:25
Definition: Transform.h:40
SharedPtr< const Transform > ConstPtr
Definition: Transform.h:43
SharedPtr< Transform > Ptr
Definition: Transform.h:42
static Transform::Ptr createLinearTransform(double voxelSize=1.0)
Create and return a shared pointer to a new transform.
Base class for typed trees.
Definition: Tree.h:37
SharedPtr< TreeBase > Ptr
Definition: Tree.h:39
SharedPtr< const TreeBase > ConstPtr
Definition: Tree.h:40
Definition: ValueAccessor.h:183
GridType
List of types that are currently supported by NanoVDB.
Definition: NanoVDB.h:216
void print(const ast::Node &node, const bool numberStatements=true, std::ostream &os=std::cout, const char *indent=" ")
Writes a descriptive printout of a Node hierarchy into a target stream.
OPENVDB_API uint32_t getFormatVersion(std::ios_base &)
Return the file format version number associated with the given input stream.
OPENVDB_API SharedPtr< StreamMetadata > getStreamMetadataPtr(std::ios_base &)
Return a shared pointer to an object that stores metadata (file format, compression scheme,...
Mat3< Type1 > cwiseAdd(const Mat3< Type1 > &m, const Type2 s)
Definition: Mat3.h:820
GridType::Ptr clip(const GridType &grid, const BBoxd &bbox, bool keepInterior=true)
Clip the given grid against a world-space bounding box and return a new grid containing the result.
Definition: Clip.h:352
std::string Name
Definition: Name.h:17
static const Real LEVEL_SET_HALF_WIDTH
Definition: Types.h:343
GridPtrVec::const_iterator GridPtrVecCIter
Definition: Grid.h:516
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:514
SharedPtr< GridPtrSet > GridPtrSetPtr
Definition: Grid.h:527
GridCPtrSet::iterator GridCPtrSetIter
Definition: Grid.h:530
SharedPtr< GridCPtrSet > GridCPtrSetPtr
Definition: Grid.h:532
GridType::Ptr deepCopyTypedGrid(const GridBase &grid)
Return a pointer to a deep copy of the given grid, provided that the grid's concrete type is GridType...
Definition: Grid.h:1055
GridPtrT findGridByName(const std::map< KeyT, GridPtrT > &container, const Name &name)
Return the first grid in the given map whose name is name.
Definition: Grid.h:557
Grid< typenameTreePtrType::element_type >::Ptr createGrid(TreePtrType)
Create a new grid of the appropriate type that wraps the given tree.
Definition: Grid.h:1755
double Real
Definition: Types.h:60
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
GridClass
Definition: Types.h:335
@ GRID_LEVEL_SET
Definition: Types.h:337
std::set< GridBase::ConstPtr > GridCPtrSet
Definition: Grid.h:529
std::set< GridBase::Ptr > GridPtrSet
Definition: Grid.h:524
SharedPtr< GridCPtrVec > GridCPtrVecPtr
Definition: Grid.h:522
GridCPtrVec::iterator GridCPtrVecIter
Definition: Grid.h:520
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
SharedPtr< GridPtrVec > GridPtrVecPtr
Definition: Grid.h:517
GridCPtrVec::const_iterator GridCPtrVecCIter
Definition: Grid.h:521
GridPtrSet::iterator GridPtrSetIter
Definition: Grid.h:525
GridCPtrSet::const_iterator GridCPtrSetCIter
Definition: Grid.h:531
GridPtrSet::const_iterator GridPtrSetCIter
Definition: Grid.h:526
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
GridType::Ptr createGrid(const typename GridType::ValueType &background)
Create a new grid of type GridType with a given background value.
Definition: Grid.h:1739
uint64_t Index64
Definition: Types.h:53
tree::TreeBase TreeBase
Definition: Grid.h:26
GridPtrVec::iterator GridPtrVecIter
Definition: Grid.h:515
std::shared_ptr< T > SharedPtr
Definition: Types.h:114
MergePolicy
Definition: Types.h:388
@ MERGE_ACTIVE_STATES
Definition: Types.h:389
@ OPENVDB_FILE_VERSION_MULTIPASS_IO
Definition: version.h.in:249
VecType
Definition: Types.h:365
std::vector< GridBase::ConstPtr > GridCPtrVec
Definition: Grid.h:519
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
openvdb::GridBase Grid
Definition: Utils.h:34
Definition: Exceptions.h:13
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:74
typename std::remove_const< ToType >::type Type
Definition: Types.h:321
Predicate functor that returns true for grids that have a specified name.
Definition: Grid.h:537
Name name
Definition: Grid.h:540
GridNamePred(const Name &_name)
Definition: Grid.h:538
bool operator()(const GridBase::ConstPtr &g) const
Definition: Grid.h:539
ValueConverter<T>::Type is the type of a grid having the same hierarchy as this grid but a different ...
Definition: Grid.h:607
Metafunction that specifies whether a given leaf node, tree, or grid type requires multiple passes to...
Definition: Grid.h:1170
static TreeType & tree(GridType &g)
Definition: Grid.h:1118
typename std::remove_const< TreeType >::type NonConstTreeType
Definition: Grid.h:1103
typename TreeType::ValueType ValueType
Definition: Grid.h:1112
static const TreeType & constTree(GridType &g)
Definition: Grid.h:1122
typename tree::ValueAccessor< NonConstTreeType > NonConstAccessorType
Definition: Grid.h:1115
typename tree::ValueAccessor< const TreeType > ConstAccessorType
Definition: Grid.h:1114
static const TreeType & tree(const GridType &g)
Definition: Grid.h:1120
typename NonConstTreeType::Ptr NonConstTreePtrType
Definition: Grid.h:1106
typename TreeType::ConstPtr ConstTreePtrType
Definition: Grid.h:1105
static TreeType & tree(TreeType &t)
Definition: Grid.h:1117
static const TreeType & constTree(const GridType &g)
Definition: Grid.h:1124
typename GridType::Ptr GridPtrType
Definition: Grid.h:1109
static const TreeType & tree(const TreeType &t)
Definition: Grid.h:1119
static const TreeType & constTree(TreeType &t)
Definition: Grid.h:1121
typename GridType::ConstPtr ConstGridPtrType
Definition: Grid.h:1111
typename TreeType::Ptr TreePtrType
Definition: Grid.h:1104
_TreeType TreeType
Definition: Grid.h:1102
static const TreeType & constTree(const TreeType &t)
Definition: Grid.h:1123
typename NonConstGridType::Ptr NonConstGridPtrType
Definition: Grid.h:1110
typename tree::ValueAccessor< TreeType > AccessorType
Definition: Grid.h:1113
static TreeType & tree(GridType &g)
Definition: Grid.h:1147
typename std::remove_const< TreeType >::type NonConstTreeType
Definition: Grid.h:1132
typename TreeType::ValueType ValueType
Definition: Grid.h:1141
static const TreeType & constTree(GridType &g)
Definition: Grid.h:1153
typename tree::ValueAccessor< NonConstTreeType > NonConstAccessorType
Definition: Grid.h:1144
typename tree::ValueAccessor< const TreeType > ConstAccessorType
Definition: Grid.h:1143
static const TreeType & tree(const GridType &g)
Definition: Grid.h:1150
static const TreeType & tree(const AccessorType &a)
Definition: Grid.h:1151
typename NonConstTreeType::Ptr NonConstTreePtrType
Definition: Grid.h:1135
typename TreeType::ConstPtr ConstTreePtrType
Definition: Grid.h:1134
static TreeType & tree(TreeType &t)
Definition: Grid.h:1146
static const TreeType & constTree(const GridType &g)
Definition: Grid.h:1155
typename GridType::Ptr GridPtrType
Definition: Grid.h:1138
static const TreeType & tree(const TreeType &t)
Definition: Grid.h:1149
static const TreeType & constTree(TreeType &t)
Definition: Grid.h:1152
static TreeType & tree(AccessorType &a)
Definition: Grid.h:1148
typename GridType::ConstPtr ConstGridPtrType
Definition: Grid.h:1140
typename TreeType::Ptr TreePtrType
Definition: Grid.h:1133
static const TreeType & constTree(const TreeType &t)
Definition: Grid.h:1154
typename NonConstGridType::Ptr NonConstGridPtrType
Definition: Grid.h:1139
typename tree::ValueAccessor< TreeType > AccessorType
Definition: Grid.h:1142
This adapter allows code that is templated on a Tree type to accept either a Tree type or a Grid type...
Definition: Grid.h:1071
static TreeType & tree(GridType &g)
Definition: Grid.h:1088
typename std::remove_const< TreeType >::type NonConstTreeType
Definition: Grid.h:1073
typename TreeType::ValueType ValueType
Definition: Grid.h:1082
static const TreeType & constTree(GridType &g)
Definition: Grid.h:1092
typename tree::ValueAccessor< NonConstTreeType > NonConstAccessorType
Definition: Grid.h:1085
typename tree::ValueAccessor< const TreeType > ConstAccessorType
Definition: Grid.h:1084
static const TreeType & tree(const GridType &g)
Definition: Grid.h:1090
typename NonConstTreeType::Ptr NonConstTreePtrType
Definition: Grid.h:1076
typename TreeType::ConstPtr ConstTreePtrType
Definition: Grid.h:1075
static TreeType & tree(TreeType &t)
Definition: Grid.h:1087
static const TreeType & constTree(const GridType &g)
Definition: Grid.h:1094
typename GridType::Ptr GridPtrType
Definition: Grid.h:1079
static const TreeType & tree(const TreeType &t)
Definition: Grid.h:1089
static const TreeType & constTree(TreeType &t)
Definition: Grid.h:1091
typename GridType::ConstPtr ConstGridPtrType
Definition: Grid.h:1081
typename TreeType::Ptr TreePtrType
Definition: Grid.h:1074
_TreeType TreeType
Definition: Grid.h:1072
static const TreeType & constTree(const TreeType &t)
Definition: Grid.h:1093
typename NonConstGridType::Ptr NonConstGridPtrType
Definition: Grid.h:1080
typename tree::ValueAccessor< TreeType > AccessorType
Definition: Grid.h:1083
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:116
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:202