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