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