OpenVDB: GridBase Class Reference

OpenVDB 9.0.0

Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | List of all members
GridBase Class Referenceabstract

Abstract base class for typed grids. More...

`#include <openvdb/Grid.h>`

Inherits MetaMap.

Inherited by Grid< _TreeType >.

## Public Types
using | Ptr = SharedPtr< GridBase >
using | ConstPtr = SharedPtr< const GridBase >
using | GridFactory = Ptr(*)()
using | MetadataMap = std::map< Name, Metadata::Ptr >
using | MetaIterator = MetadataMap::iterator
using | ConstMetaIterator = MetadataMap::const_iterator

## Public Member Functions
| ~GridBase () override
virtual bool | empty () const =0
| Return `true` if this grid contains only background voxels. More...
virtual void | clear ()=0
| Empty this grid, setting all voxels to the background. More...
MetaMap::Ptr | copyMeta () const
| Return a copy of this map whose fields are shared with this map. More...
MetaMap::Ptr | deepCopyMeta () const
| Return a deep copy of this map that shares no data with this map. More...
void | readMeta (std::istream &)
| Unserialize metadata from the given stream. More...
void | writeMeta (std::ostream &) const
| Serialize metadata to the given stream. More...
void | insertMeta (const Name &, const Metadata &value)
| Insert a new metadata field or overwrite the value of an existing field. More...
void | insertMeta (const MetaMap &)
| Deep copy all of the metadata fields from the given map into this map. More...
void | removeMeta (const Name &)
| Remove the given metadata field if it exists. More...
Metadata::Ptr | operator[] (const Name &)
| Return a pointer to the metadata with the given name. If no such field exists, return a null pointer. More...
Metadata::ConstPtr | operator[] (const Name &) const
template<typename T >
T::Ptr | getMetadata (const Name &)
| Return a pointer to a TypedMetadata object of type `T` and with the given name. If no such field exists or if there is a type mismatch, return a null pointer. More...
template<typename T >
T::ConstPtr | getMetadata (const Name &) const
template<typename T >
T & | metaValue (const Name &)
| Return a reference to the value of type `T` stored in the given metadata field. More...
template<typename T >
const T & | metaValue (const Name &) const
MetaIterator | beginMeta ()
ConstMetaIterator | beginMeta () const
MetaIterator | endMeta ()
ConstMetaIterator | endMeta () const
void | clearMetadata ()
size_t | metaCount () const
std::string | str (const std::string &indent="") const
| Return a string describing this metadata map. Prefix each line with indent. More...
bool | operator== (const MetaMap &other) const
| Return `true` if the given map is equivalent to this map. More...
bool | operator!= (const MetaMap &other) const
| Return `true` if the given map is different from this map. More...
Copying
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 whose tree and transform are shared with this grid. More...
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 whose tree and transform are shared with this grid. More...
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 grid's and whose tree is default-constructed. More...
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 whose metadata is provided as an argument. More...
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, whose metadata is a deep copy of this grid's and whose transform is provided as an argument. More...
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 transform and metadata are provided as arguments. More...
virtual GridBase::Ptr | deepCopyGrid () const =0
| Return a new grid whose metadata, transform and tree are deep copies of this grid's. More...
Type access
virtual Name | type () const =0
| Return the name of this grid's type. More...
virtual Name | valueType () const =0
| Return the name of the type of a voxel's value (e.g., "float" or "vec3d"). More...
template<typename GridType >
bool | isType () const
| Return `true` if this grid is of the same type as the template parameter. More...
Tree
TreeBase::Ptr | baseTreePtr ()
| Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guaranteed to be non-null. More...
TreeBase::ConstPtr | baseTreePtr () const
| Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guaranteed to be non-null. More...
virtual TreeBase::ConstPtr | constBaseTreePtr () const =0
| Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guaranteed to be non-null. More...
virtual bool | isTreeUnique () const =0
| Return true if tree is not shared with another grid. More...
TreeBase & | baseTree ()
| Return a reference to this grid's tree, which might be shared with other grids. More...
const TreeBase & | baseTree () const
| Return a reference to this grid's tree, which might be shared with other grids. More...
const TreeBase & | constBaseTree () const
| Return a reference to this grid's tree, which might be shared with other grids. More...
virtual void | setTree (TreeBase::Ptr)=0
| Associate the given tree with this grid, in place of its existing tree. More...
virtual void | newTree ()=0
| Set a new tree with the same background value as the previous tree. More...
Tools
virtual void | pruneGrid (float tolerance=0.0)=0
| Reduce the memory footprint of this grid by increasing its sparseness either losslessly (tolerance = 0) or lossily (tolerance > 0). More...
void | clipGrid (const BBoxd &)
| Clip this grid to the given world-space bounding box. More...
virtual void | clip (const CoordBBox &)=0
| Clip this grid to the given index-space bounding box. More...
template<typename GridTypeListT , typename OpT >
bool | apply (OpT &) const
| If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid. More...
template<typename GridTypeListT , typename OpT >
bool | apply (OpT &)
| If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid. More...
template<typename GridTypeListT , typename OpT >
bool | apply (const OpT &) const
| If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid. More...
template<typename GridTypeListT , typename OpT >
bool | apply (const OpT &)
| If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid. More...
Metadata
std::string | getName () const
| Return this grid's user-specified name. More...
void | setName (const std::string &)
| Specify a name for this grid. More...
std::string | getCreator () const
| Return the user-specified description of this grid's creator. More...
void | setCreator (const std::string &)
| Provide a description of this grid's creator. More...
bool | saveFloatAsHalf () const
| Return `true` if this grid should be written out with floating-point voxel values (including components of vectors) quantized to 16 bits. More...
void | setSaveFloatAsHalf (bool)
| Return this grid's user-specified name. More...
GridClass | getGridClass () const
| Return the class of volumetric data (level set, fog volume, etc.) that is stored in this grid. More...
void | setGridClass (GridClass)
| Specify the class of volumetric data (level set, fog volume, etc.) that is stored in this grid. More...
void | clearGridClass ()
| Remove the setting specifying the class of this grid's volumetric data. More...
VecType | getVectorType () const
| Return the type of vector data (invariant, covariant, etc.) stored in this grid, assuming that this grid contains a vector-valued tree. More...
void | setVectorType (VecType)
| Specify the type of vector data (invariant, covariant, etc.) stored in this grid, assuming that this grid contains a vector-valued tree. More...
void | clearVectorType ()
| Remove the setting specifying the type of vector data stored in this grid. More...
bool | isInWorldSpace () const
void | setIsInWorldSpace (bool)
| Specify whether this grid's voxel values are in world space or in local space. More...
Statistics
virtual Index64 | activeVoxelCount () const =0
| Return the number of active voxels. More...
virtual CoordBBox | evalActiveVoxelBoundingBox () const =0
virtual Coord | evalActiveVoxelDim () const =0
| Return the dimensions of the axis-aligned bounding box of all active voxels. More...
virtual Index64 | memUsage () const =0
| Return the number of bytes of memory used by this grid. More...
void | addStatsMetadata ()
| Add metadata to this grid comprising the current values of statistics like the active voxel count and bounding box. More...
MetaMap::Ptr | getStatsMetadata () const
| Return a new MetaMap containing just the metadata that was added to this grid with addStatsMetadata. More...
Transform
math::Transform::Ptr | transformPtr ()
| Return a pointer to this grid's transform, which might be shared with other grids. More...
math::Transform::ConstPtr | transformPtr () const
| Return a pointer to this grid's transform, which might be shared with other grids. More...
math::Transform::ConstPtr | constTransformPtr () const
| Return a pointer to this grid's transform, which might be shared with other grids. More...
math::Transform & | transform ()
| Return a reference to this grid's transform, which might be shared with other grids. More...
const math::Transform & | transform () const
| Return a pointer to this grid's transform, which might be shared with other grids. More...
const math::Transform & | constTransform () const
| Return a pointer to this grid's transform, which might be shared with other grids. More...
void | setTransform (math::Transform::Ptr)
| Associate the given transform with this grid, in place of its existing transform. More...
Vec3d | voxelSize () const
| Return the size of this grid's voxels. More...
Vec3d | voxelSize (const Vec3d &xyz) const
| Return the size of this grid's voxel at position (x, y, z). More...
bool | hasUniformVoxels () const
| Return true if the voxels in world space are uniformly sized cubes. More...
Vec3d | indexToWorld (const Vec3d &xyz) const
| Apply this grid's transform to the given coordinates. More...
Vec3d | indexToWorld (const Coord &ijk) const
| Apply this grid's transform to the given coordinates. More...
Vec3d | worldToIndex (const Vec3d &xyz) const
| Apply the inverse of this grid's transform to the given coordinates. More...
I/O
virtual void | readTopology (std::istream &)=0
| Read the grid topology from a stream. This will read only the grid structure, not the actual data buffers. More...
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 buffers. More...
virtual void | readBuffers (std::istream &)=0
| Read all data buffers for this grid. More...
virtual void | readBuffers (std::istream &, const CoordBBox &)=0
| Read all of this grid's data buffers that intersect the given index-space bounding box. More...
virtual void | readNonresidentBuffers () const =0
| Read all of this grid's data buffers that are not yet resident in memory (because delayed loading is in effect). More...
virtual void | writeBuffers (std::ostream &) const =0
| Write out all data buffers for this grid. More...
void | readTransform (std::istream &is)
| Read in the transform for this grid. More...
void | writeTransform (std::ostream &os) const
| Write out the transform for this grid. More...
virtual void | print (std::ostream &=std::cout, int verboseLevel=1) const =0
| Output a human-readable description of this grid. More...

## Static Public Member Functions
template<typename GridType >
static GridType::Ptr | grid (const GridBase::Ptr &)
| Return the result of downcasting a GridBase pointer to a Grid pointer of the specified type, or return a null pointer if the types are incompatible. More...
template<typename GridType >
static GridType::ConstPtr | grid (const GridBase::ConstPtr &)
template<typename GridType >
static GridType::ConstPtr | constGrid (const GridBase::Ptr &)
template<typename GridType >
static GridType::ConstPtr | constGrid (const GridBase::ConstPtr &)
static std::string | gridClassToString (GridClass)
| Return the metadata string value for the given class of volumetric data. More...
static std::string | gridClassToMenuName (GridClass)
| Return a formatted string version of the grid class. More...
static GridClass | stringToGridClass (const std::string &)
| Return the class of volumetric data specified by the given string. More...
static std::string | vecTypeToString (VecType)
| Return the metadata string value for the given type of vector data. More...
static std::string | vecTypeExamples (VecType)
static std::string | vecTypeDescription (VecType)
| Return a string describing how the given type of vector data is affected by transformations (e.g., "Does not transform", given VEC_INVARIANT). More...
static VecType | stringToVecType (const std::string &)
Registry
static Ptr | createGrid (const Name &type)
| Create a new grid of the given (registered) type. More...
static bool | isRegistered (const Name &type)
| Return `true` if the given grid type name is registered. More...
static void | clearRegistry ()
| Clear the grid type registry. More...

## Static Public Attributes
static const char *const | META_GRID_CLASS
static const char *const | META_GRID_CREATOR
static const char *const | META_GRID_NAME
static const char *const | META_SAVE_HALF_FLOAT
static const char *const | META_IS_LOCAL_SPACE
static const char *const | META_VECTOR_TYPE
static const char *const | META_FILE_BBOX_MIN
static const char *const | META_FILE_BBOX_MAX
static const char *const | META_FILE_COMPRESSION
static const char *const | META_FILE_MEM_BYTES
static const char *const | META_FILE_VOXEL_COUNT
static const char *const | META_FILE_DELAYED_LOAD

## Protected Member Functions
| GridBase ()
| Initialize with an identity linear transform. More...
| GridBase (const MetaMap &meta, math::Transform::Ptr xform)
| Initialize with metadata and a transform. More...
| GridBase (const GridBase &other)
| Deep copy another grid's metadata and transform. More...
| GridBase (GridBase &other, ShallowCopy)
| Copy another grid's metadata but share its transform. More...

## Static Protected Member Functions
static void | registerGrid (const Name &type, GridFactory)
| Register a grid type along with a factory function. More...
static void | unregisterGrid (const Name &type)
| Remove a grid type from the registry. More...

## Detailed Description

Abstract base class for typed grids.

## Member Typedef Documentation

## ◆ ConstMetaIterator

using ConstMetaIterator = MetadataMap::const_iterator
| inherited

## ◆ ConstPtr

using ConstPtr = SharedPtr<const GridBase>

## ◆ GridFactory

using GridFactory = Ptr (*)()

## ◆ MetadataMap

using MetadataMap = std::map<Name, Metadata::Ptr>
| inherited

## ◆ MetaIterator

using MetaIterator = MetadataMap::iterator
| inherited

## ◆ Ptr

using Ptr = SharedPtr<GridBase>

## Constructor & Destructor Documentation

## ◆ ~GridBase()

~GridBase | ( |  | ) |
| inlineoverride

## ◆ GridBase() [1/4]

GridBase | ( |  | ) |
| inlineprotected

Initialize with an identity linear transform.

## ◆ GridBase() [2/4]

GridBase | ( | const MetaMap & | meta,
|  | math::Transform::Ptr | xform
| ) |  |
| inlineprotected

Initialize with metadata and a transform.

Exceptions

  ValueError | if the transform pointer is null

## ◆ GridBase() [3/4]

GridBase | ( | const GridBase & | other | ) |
| inlineprotected

Deep copy another grid's metadata and transform.

## ◆ GridBase() [4/4]

GridBase | ( | GridBase & | other,
|  | ShallowCopy |
| ) |  |
| inlineprotected

Copy another grid's metadata but share its transform.

## Member Function Documentation

## ◆ activeVoxelCount()

virtual Index64 activeVoxelCount | ( |  | ) | const
| pure virtual

Return the number of active voxels.

Implemented in Grid< _TreeType >.

## ◆ addStatsMetadata()

void addStatsMetadata | ( |  | ) |

Add metadata to this grid comprising the current values of statistics like the active voxel count and bounding box.

Note
  This metadata is not automatically kept up-to-date with changes to this grid.

## ◆ apply() [1/4]

bool apply | ( | const OpT & | op | ) |
| inline

If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid.

Returns
  `false` if this grid's type is not one of the listed types

Example:
  using AllowedGridTypes = openvdb::TypeList<
  openvdb::Int32Grid, openvdb::Int64Grid,
  openvdb::FloatGrid, openvdb::DoubleGrid>;
  const openvdb::CoordBBox bbox{
  openvdb::Coord{0,0,0}, openvdb::Coord{10,10,10}};
  // Fill the grid if it is one of the allowed types.
  myGridBasePtr->apply<AllowedGridTypes>(
  [&bbox](auto& grid) { // C++14
  using GridType = typename std::decay<decltype(grid)>::type;
  grid.fill(bbox, typename GridType::ValueType(1));
  }
  );
  openvdb::v9_0::GridBase::grid
  static GridType::Ptr grid(const GridBase::Ptr &)
  Return the result of downcasting a GridBase pointer to a Grid pointer of the specified type,...
  Definition: Grid.h:1202
  openvdb::v9_0::GridBase::type
  virtual Name type() const =0
  Return the name of this grid's type.
  openvdb::v9_0::Grid
  Container class that associates a tree with a transform and metadata.
  Definition: Grid.h:577
  openvdb::v9_0::math::CoordBBox
  Axis-aligned bounding box of signed integer coordinates.
  Definition: Coord.h:248
  openvdb::v9_0::math::Coord
  Signed (x, y, z) 32-bit integer coordinates.
  Definition: Coord.h:25
  nanovdb::FloatGrid
  Grid< FloatTree > FloatGrid
  Definition: NanoVDB.h:3974
  nanovdb::GridType
  GridType
  List of types that are currently supported by NanoVDB.
  Definition: NanoVDB.h:216
  nanovdb::Int64Grid
  Grid< Int64Tree > Int64Grid
  Definition: NanoVDB.h:3978
  nanovdb::Int32Grid
  Grid< Int32Tree > Int32Grid
  Definition: NanoVDB.h:3976
  openvdb::v9_0::TypeList
  A list of types (not necessarily unique)
  Definition: TypeList.h:366

See also
  TypeList

## ◆ apply() [2/4]

bool apply | ( | const OpT & | op | ) | const
| inline

If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid.

Returns
  `false` if this grid's type is not one of the listed types

Example:
  using AllowedGridTypes = openvdb::TypeList<
  openvdb::Int32Grid, openvdb::Int64Grid,
  openvdb::FloatGrid, openvdb::DoubleGrid>;
  const openvdb::CoordBBox bbox{
  openvdb::Coord{0,0,0}, openvdb::Coord{10,10,10}};
  // Fill the grid if it is one of the allowed types.
  myGridBasePtr->apply<AllowedGridTypes>(
  [&bbox](auto& grid) { // C++14
  using GridType = typename std::decay<decltype(grid)>::type;
  grid.fill(bbox, typename GridType::ValueType(1));
  }
  );

See also
  TypeList

## ◆ apply() [3/4]

bool apply | ( | OpT & | op | ) |
| inline

If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid.

Returns
  `false` if this grid's type is not one of the listed types

Example:
  using AllowedGridTypes = openvdb::TypeList<
  openvdb::Int32Grid, openvdb::Int64Grid,
  openvdb::FloatGrid, openvdb::DoubleGrid>;
  const openvdb::CoordBBox bbox{
  openvdb::Coord{0,0,0}, openvdb::Coord{10,10,10}};
  // Fill the grid if it is one of the allowed types.
  myGridBasePtr->apply<AllowedGridTypes>(
  [&bbox](auto& grid) { // C++14
  using GridType = typename std::decay<decltype(grid)>::type;
  grid.fill(bbox, typename GridType::ValueType(1));
  }
  );

See also
  TypeList

## ◆ apply() [4/4]

bool apply | ( | OpT & | op | ) | const
| inline

If this grid resolves to one of the listed grid types, invoke the given functor on the resolved grid.

Returns
  `false` if this grid's type is not one of the listed types

Example:
  using AllowedGridTypes = openvdb::TypeList<
  openvdb::Int32Grid, openvdb::Int64Grid,
  openvdb::FloatGrid, openvdb::DoubleGrid>;
  const openvdb::CoordBBox bbox{
  openvdb::Coord{0,0,0}, openvdb::Coord{10,10,10}};
  // Fill the grid if it is one of the allowed types.
  myGridBasePtr->apply<AllowedGridTypes>(
  [&bbox](auto& grid) { // C++14
  using GridType = typename std::decay<decltype(grid)>::type;
  grid.fill(bbox, typename GridType::ValueType(1));
  }
  );

See also
  TypeList

## ◆ baseTree() [1/2]

TreeBase & baseTree | ( |  | ) |
| inline

Return a reference to this grid's tree, which might be shared with other grids.

Note
  Calling setTree on this grid invalidates all references previously returned by this method.

## ◆ baseTree() [2/2]

const TreeBase & baseTree | ( |  | ) | const
| inline

Return a reference to this grid's tree, which might be shared with other grids.

Note
  Calling setTree on this grid invalidates all references previously returned by this method.

## ◆ baseTreePtr() [1/2]

TreeBase::Ptr baseTreePtr | ( |  | ) |
| inline

Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guaranteed to be non-null.

## ◆ baseTreePtr() [2/2]

TreeBase::ConstPtr baseTreePtr | ( |  | ) | const
| inline

Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guaranteed to be non-null.

## ◆ beginMeta() [1/2]

MetaIterator beginMeta | ( |  | ) |
| inlineinherited

## ◆ beginMeta() [2/2]

ConstMetaIterator beginMeta | ( |  | ) | const
| inlineinherited

## ◆ clear()

virtual void clear | ( |  | ) |
| pure virtual

Empty this grid, setting all voxels to the background.

Implemented in Grid< _TreeType >.

## ◆ clearGridClass()

void clearGridClass | ( |  | ) |

Remove the setting specifying the class of this grid's volumetric data.

## ◆ clearMetadata()

void clearMetadata | ( |  | ) |
| inlineinherited

## ◆ clearRegistry()

static void clearRegistry | ( |  | ) |
| static

Clear the grid type registry.

## ◆ clearVectorType()

void clearVectorType | ( |  | ) |

Remove the setting specifying the type of vector data stored in this grid.

## ◆ clip()

virtual void clip | ( | const CoordBBox & |  | ) |
| pure virtual

Clip this grid to the given index-space bounding box.

Voxels that lie outside the bounding box are set to the background.

Warning
  Clipping a level set will likely produce a grid that is no longer a valid level set.

Implemented in Grid< _TreeType >.

## ◆ clipGrid()

void clipGrid | ( | const BBoxd & |  | ) |

Clip this grid to the given world-space bounding box.

Voxels that lie outside the bounding box are set to the background.

Warning
  Clipping a level set will likely produce a grid that is no longer a valid level set.

## ◆ constBaseTree()

const TreeBase & constBaseTree | ( |  | ) | const
| inline

Return a reference to this grid's tree, which might be shared with other grids.

Note
  Calling setTree on this grid invalidates all references previously returned by this method.

## ◆ constBaseTreePtr()

virtual TreeBase::ConstPtr constBaseTreePtr | ( |  | ) | const
| pure virtual

Return a pointer to this grid's tree, which might be shared with other grids. The pointer is guaranteed to be non-null.

Implemented in Grid< _TreeType >.

## ◆ constGrid() [1/2]

GridType::ConstPtr constGrid | ( | const GridBase::ConstPtr & | grid | ) |
| inlinestatic

## ◆ constGrid() [2/2]

GridType::ConstPtr constGrid | ( | const GridBase::Ptr & | grid | ) |
| inlinestatic

## ◆ constTransform()

const math::Transform & constTransform | ( |  | ) | const
| inline

Return a pointer to this grid's transform, which might be shared with other grids.

## ◆ constTransformPtr()

math::Transform::ConstPtr constTransformPtr | ( |  | ) | const
| inline

Return a pointer to this grid's transform, which might be shared with other grids.

## ◆ copyGrid() [1/2]

virtual GridBase::ConstPtr copyGrid | ( |  | ) | const
| pure virtual

Return a new grid of the same type as this grid whose metadata is a deep copy of this grid's and whose tree and transform are shared with this grid.

Implemented in Grid< _TreeType >.

## ◆ copyGrid() [2/2]

virtual GridBase::Ptr copyGrid | ( |  | ) |
| pure virtual

Return a new grid of the same type as this grid whose metadata is a deep copy of this grid's and whose tree and transform are shared with this grid.

Implemented in Grid< _TreeType >.

## ◆ copyGridReplacingMetadata()

virtual GridBase::ConstPtr copyGridReplacingMetadata | ( | const MetaMap & | meta | ) | const
| pure virtual

Return a new grid of the same type as this grid whose tree and transform is shared with this grid and whose metadata is provided as an argument.

Implemented in Grid< _TreeType >.

## ◆ copyGridReplacingMetadataAndTransform()

virtual GridBase::ConstPtr copyGridReplacingMetadataAndTransform | ( | const MetaMap & | meta,
|  | math::Transform::Ptr | xform
| ) |  | const
| pure virtual

Return a new grid of the same type as this grid whose tree is shared with this grid and whose transform and metadata are provided as arguments.

Exceptions

  ValueError | if the transform pointer is null

Implemented in Grid< _TreeType >.

## ◆ copyGridReplacingTransform()

virtual GridBase::ConstPtr copyGridReplacingTransform | ( | math::Transform::Ptr | xform | ) | const
| pure virtual

Return a new grid of the same type as this grid whose tree is shared with this grid, whose metadata is a deep copy of this grid's and whose transform is provided as an argument.

Exceptions

  ValueError | if the transform pointer is null

Implemented in Grid< _TreeType >.

## ◆ copyGridWithNewTree()

virtual GridBase::Ptr copyGridWithNewTree | ( |  | ) | const
| pure virtual

Return a new grid of the same type as this grid whose metadata and transform are deep copies of this grid's and whose tree is default-constructed.

Implemented in Grid< _TreeType >.

## ◆ copyMeta()

MetaMap::Ptr copyMeta | ( |  | ) | const
| inherited

Return a copy of this map whose fields are shared with this map.

## ◆ createGrid()

static Ptr createGrid | ( | const Name & | type | ) |
| static

Create a new grid of the given (registered) type.

## ◆ deepCopyGrid()

virtual GridBase::Ptr deepCopyGrid | ( |  | ) | const
| pure virtual

Return a new grid whose metadata, transform and tree are deep copies of this grid's.

Implemented in Grid< _TreeType >.

## ◆ deepCopyMeta()

MetaMap::Ptr deepCopyMeta | ( |  | ) | const
| inherited

Return a deep copy of this map that shares no data with this map.

## ◆ empty()

virtual bool empty | ( |  | ) | const
| pure virtual

Return `true` if this grid contains only background voxels.

Implemented in Grid< _TreeType >.

## ◆ endMeta() [1/2]

MetaIterator endMeta | ( |  | ) |
| inlineinherited

## ◆ endMeta() [2/2]

ConstMetaIterator endMeta | ( |  | ) | const
| inlineinherited

## ◆ evalActiveVoxelBoundingBox()

virtual CoordBBox evalActiveVoxelBoundingBox | ( |  | ) | const
| pure virtual

Return the axis-aligned bounding box of all active voxels. If the grid is empty a default bbox is returned.

Implemented in Grid< _TreeType >.

## ◆ evalActiveVoxelDim()

virtual Coord evalActiveVoxelDim | ( |  | ) | const
| pure virtual

Return the dimensions of the axis-aligned bounding box of all active voxels.

Implemented in Grid< _TreeType >.

## ◆ getCreator()

std::string getCreator | ( |  | ) | const

Return the user-specified description of this grid's creator.

## ◆ getGridClass()

GridClass getGridClass | ( |  | ) | const

Return the class of volumetric data (level set, fog volume, etc.) that is stored in this grid.

See also
  gridClassToString, gridClassToMenuName, stringToGridClass

## ◆ getMetadata() [1/2]

T::Ptr getMetadata | ( | const Name & | name | ) |
| inlineinherited

Return a pointer to a TypedMetadata object of type `T` and with the given name. If no such field exists or if there is a type mismatch, return a null pointer.

## ◆ getMetadata() [2/2]

T::ConstPtr getMetadata | ( | const Name & | name | ) | const
| inlineinherited

## ◆ getName()

std::string getName | ( |  | ) | const

Return this grid's user-specified name.

## ◆ getStatsMetadata()

MetaMap::Ptr getStatsMetadata | ( |  | ) | const

Return a new MetaMap containing just the metadata that was added to this grid with addStatsMetadata.

If addStatsMetadata was never called on this grid, return an empty MetaMap.

## ◆ getVectorType()

VecType getVectorType | ( |  | ) | const

Return the type of vector data (invariant, covariant, etc.) stored in this grid, assuming that this grid contains a vector-valued tree.

See also
  vecTypeToString, vecTypeExamples, vecTypeDescription, stringToVecType

## ◆ grid() [1/2]

GridType::ConstPtr grid | ( | const GridBase::ConstPtr & | grid | ) |
| inlinestatic

## ◆ grid() [2/2]

GridType::Ptr grid | ( | const GridBase::Ptr & | grid | ) |
| inlinestatic

Return the result of downcasting a GridBase pointer to a Grid pointer of the specified type, or return a null pointer if the types are incompatible.

## ◆ gridClassToMenuName()

static std::string gridClassToMenuName | ( | GridClass |  | ) |
| static

Return a formatted string version of the grid class.

## ◆ gridClassToString()

static std::string gridClassToString | ( | GridClass |  | ) |
| static

Return the metadata string value for the given class of volumetric data.

## ◆ hasUniformVoxels()

bool hasUniformVoxels | ( |  | ) | const
| inline

Return true if the voxels in world space are uniformly sized cubes.

## ◆ indexToWorld() [1/2]

Vec3d indexToWorld | ( | const Coord & | ijk | ) | const
| inline

Apply this grid's transform to the given coordinates.

## ◆ indexToWorld() [2/2]

Vec3d indexToWorld | ( | const Vec3d & | xyz | ) | const
| inline

Apply this grid's transform to the given coordinates.

## ◆ insertMeta() [1/2]

void insertMeta | ( | const MetaMap & |  | ) |
| inherited

Deep copy all of the metadata fields from the given map into this map.

Exceptions

  TypeError | if any field in the given map has the same name as but a different value type than one of this map's fields.

## ◆ insertMeta() [2/2]

void insertMeta | ( | const Name & | ,
|  | const Metadata & | value
| ) |  |
| inherited

Insert a new metadata field or overwrite the value of an existing field.

If a field with the given name doesn't already exist, add a new field. Otherwise, if the new value's type is the same as the existing field's value type, overwrite the existing value with new value.

Exceptions

  TypeError | if a field with the given name already exists, but its value type is not the same as the new value's
  ValueError | if the given field name is empty.

## ◆ isInWorldSpace()

bool isInWorldSpace | ( |  | ) | const

Return `true` if this grid's voxel values are in world space and should be affected by transformations, `false` if they are in local space and should not be affected by transformations.

## ◆ isRegistered()

static bool isRegistered | ( | const Name & | type | ) |
| static

Return `true` if the given grid type name is registered.

## ◆ isTreeUnique()

virtual bool isTreeUnique | ( |  | ) | const
| pure virtual

Return true if tree is not shared with another grid.

Implemented in Grid< _TreeType >.

## ◆ isType()

bool isType | ( |  | ) | const
| inline

Return `true` if this grid is of the same type as the template parameter.

## ◆ memUsage()

virtual Index64 memUsage | ( |  | ) | const
| pure virtual

Return the number of bytes of memory used by this grid.

Implemented in Grid< _TreeType >.

## ◆ metaCount()

size_t metaCount | ( |  | ) | const
| inlineinherited

## ◆ metaValue() [1/2]

T & metaValue | ( | const Name & | name | ) |
| inlineinherited

Return a reference to the value of type `T` stored in the given metadata field.

Exceptions

  LookupError | if no field with the given name exists.
  TypeError | if the given field is not of type `T`.

## ◆ metaValue() [2/2]

const T & metaValue | ( | const Name & | name | ) | const
| inlineinherited

## ◆ newTree()

virtual void newTree | ( |  | ) |
| pure virtual

Set a new tree with the same background value as the previous tree.

Implemented in Grid< _TreeType >.

## ◆ operator!=()

bool operator!= | ( | const MetaMap & | other | ) | const
| inlineinherited

Return `true` if the given map is different from this map.

## ◆ operator==()

bool operator== | ( | const MetaMap & | other | ) | const
| inherited

Return `true` if the given map is equivalent to this map.

## ◆ operator[]() [1/2]

Metadata::Ptr operator[] | ( | const Name & | name | ) |
| inlineinherited

Return a pointer to the metadata with the given name. If no such field exists, return a null pointer.

## ◆ operator[]() [2/2]

Metadata::ConstPtr operator[] | ( | const Name & | name | ) | const
| inlineinherited

## ◆ print()

virtual void print | ( | std::ostream & | = `std::cout`,
|  | int | verboseLevel = `1`
| ) |  | const
| pure virtual

Output a human-readable description of this grid.

Implemented in Grid< _TreeType >.

## ◆ pruneGrid()

virtual void pruneGrid | ( | float | tolerance = `0.0` | ) |
| pure virtual

Reduce the memory footprint of this grid by increasing its sparseness either losslessly (tolerance = 0) or lossily (tolerance > 0).

With tolerance > 0, sparsify regions where voxels have the same active state and have values that differ by no more than the tolerance (converted to this grid's value type).

Implemented in Grid< _TreeType >.

## ◆ readBuffers() [1/2]

virtual void readBuffers | ( | std::istream & |  | ) |
| pure virtual

Read all data buffers for this grid.

Implemented in Grid< _TreeType >.

## ◆ readBuffers() [2/2]

virtual void readBuffers | ( | std::istream & | ,
|  | const CoordBBox & |
| ) |  |
| pure virtual

Read all of this grid's data buffers that intersect the given index-space bounding box.

Implemented in Grid< _TreeType >.

## ◆ readMeta()

void readMeta | ( | std::istream & |  | ) |
| inherited

Unserialize metadata from the given stream.

## ◆ readNonresidentBuffers()

virtual void readNonresidentBuffers | ( |  | ) | const
| pure virtual

Read all of this grid's data buffers that are not yet resident in memory (because delayed loading is in effect).

If this grid was read from a memory-mapped file, this operation disconnects the grid from the file.

See also
  io::File::open, io::MappedFile

Implemented in Grid< _TreeType >.

## ◆ readTopology()

virtual void readTopology | ( | std::istream & |  | ) |
| pure virtual

Read the grid topology from a stream. This will read only the grid structure, not the actual data buffers.

Implemented in Grid< _TreeType >.

## ◆ readTransform()

void readTransform | ( | std::istream & | is | ) |
| inline

Read in the transform for this grid.

## ◆ registerGrid()

static void registerGrid | ( | const Name & | type,
|  | GridFactory |
| ) |  |
| staticprotected

Register a grid type along with a factory function.

## ◆ removeMeta()

void removeMeta | ( | const Name & |  | ) |
| inherited

Remove the given metadata field if it exists.

## ◆ saveFloatAsHalf()

bool saveFloatAsHalf | ( |  | ) | const

Return `true` if this grid should be written out with floating-point voxel values (including components of vectors) quantized to 16 bits.

## ◆ setCreator()

void setCreator | ( | const std::string & |  | ) |

Provide a description of this grid's creator.

## ◆ setGridClass()

void setGridClass | ( | GridClass |  | ) |

Specify the class of volumetric data (level set, fog volume, etc.) that is stored in this grid.

See also
  gridClassToString, gridClassToMenuName, stringToGridClass

## ◆ setIsInWorldSpace()

void setIsInWorldSpace | ( | bool |  | ) |

Specify whether this grid's voxel values are in world space or in local space.

## ◆ setName()

void setName | ( | const std::string & |  | ) |

Specify a name for this grid.

## ◆ setSaveFloatAsHalf()

void setSaveFloatAsHalf | ( | bool |  | ) |

Return this grid's user-specified name.

## ◆ setTransform()

void setTransform | ( | math::Transform::Ptr | xform | ) |
| inline

Associate the given transform with this grid, in place of its existing transform.

Exceptions

  ValueError | if the transform pointer is null

Note
  Invalidates all references previously returned by transform or Transform.

## ◆ setTree()

virtual void setTree | ( | TreeBase::Ptr |  | ) |
| pure virtual

Associate the given tree with this grid, in place of its existing tree.

Exceptions

  ValueError | if the tree pointer is null
  TypeError | if the tree is not of the appropriate type

Note
  Invalidates all references previously returned by baseTree or BaseTree.

Implemented in Grid< _TreeType >.

## ◆ setVectorType()

void setVectorType | ( | VecType |  | ) |

Specify the type of vector data (invariant, covariant, etc.) stored in this grid, assuming that this grid contains a vector-valued tree.

See also
  vecTypeToString, vecTypeExamples, vecTypeDescription, stringToVecType

## ◆ str()

std::string str | ( | const std::string & | indent = `""` | ) | const
| inherited

Return a string describing this metadata map. Prefix each line with indent.

## ◆ stringToGridClass()

static GridClass stringToGridClass | ( | const std::string & |  | ) |
| static

Return the class of volumetric data specified by the given string.

If the string is not one of the ones returned by gridClassToString, return `GRID_UNKNOWN`.

## ◆ stringToVecType()

static VecType stringToVecType | ( | const std::string & |  | ) |
| static

## ◆ transform() [1/2]

math::Transform & transform | ( |  | ) |
| inline

Return a reference to this grid's transform, which might be shared with other grids.

Note
  Calling setTransform on this grid invalidates all references previously returned by this method.

## ◆ transform() [2/2]

const math::Transform & transform | ( |  | ) | const
| inline

Return a pointer to this grid's transform, which might be shared with other grids.

## ◆ transformPtr() [1/2]

math::Transform::Ptr transformPtr | ( |  | ) |
| inline

Return a pointer to this grid's transform, which might be shared with other grids.

## ◆ transformPtr() [2/2]

math::Transform::ConstPtr transformPtr | ( |  | ) | const
| inline

Return a pointer to this grid's transform, which might be shared with other grids.

## ◆ type()

virtual Name type | ( |  | ) | const
| pure virtual

Return the name of this grid's type.

Implemented in Grid< _TreeType >.

## ◆ unregisterGrid()

static void unregisterGrid | ( | const Name & | type | ) |
| staticprotected

Remove a grid type from the registry.

## ◆ valueType()

virtual Name valueType | ( |  | ) | const
| pure virtual

Return the name of the type of a voxel's value (e.g., "float" or "vec3d").

Implemented in Grid< _TreeType >.

## ◆ vecTypeDescription()

static std::string vecTypeDescription | ( | VecType |  | ) |
| static

Return a string describing how the given type of vector data is affected by transformations (e.g., "Does not transform", given VEC_INVARIANT).

## ◆ vecTypeExamples()

static std::string vecTypeExamples | ( | VecType |  | ) |
| static

Return a string listing examples of the given type of vector data (e.g., "Gradient/Normal", given VEC_COVARIANT).

## ◆ vecTypeToString()

static std::string vecTypeToString | ( | VecType |  | ) |
| static

Return the metadata string value for the given type of vector data.

## ◆ voxelSize() [1/2]

Vec3d voxelSize | ( |  | ) | const
| inline

Return the size of this grid's voxels.

## ◆ voxelSize() [2/2]

Vec3d voxelSize | ( | const Vec3d & | xyz | ) | const
| inline

Return the size of this grid's voxel at position (x, y, z).

Note
  Frustum and perspective transforms have position-dependent voxel size.

## ◆ worldToIndex()

Vec3d worldToIndex | ( | const Vec3d & | xyz | ) | const
| inline

Apply the inverse of this grid's transform to the given coordinates.

## ◆ writeBuffers()

virtual void writeBuffers | ( | std::ostream & |  | ) | const
| pure virtual

Write out all data buffers for this grid.

Implemented in Grid< _TreeType >.

## ◆ writeMeta()

void writeMeta | ( | std::ostream & |  | ) | const
| inherited

Serialize metadata to the given stream.

## ◆ writeTopology()

virtual void writeTopology | ( | std::ostream & |  | ) | const
| pure virtual

Write the grid topology to a stream. This will write only the grid structure, not the actual data buffers.

Implemented in Grid< _TreeType >.

## ◆ writeTransform()

void writeTransform | ( | std::ostream & | os | ) | const
| inline

Write out the transform for this grid.

## Member Data Documentation

## ◆ META_FILE_BBOX_MAX

const char* const META_FILE_BBOX_MAX
| static

## ◆ META_FILE_BBOX_MIN

const char* const META_FILE_BBOX_MIN
| static

## ◆ META_FILE_COMPRESSION

const char* const META_FILE_COMPRESSION
| static

## ◆ META_FILE_DELAYED_LOAD

const char* const META_FILE_DELAYED_LOAD
| static

## ◆ META_FILE_MEM_BYTES

const char* const META_FILE_MEM_BYTES
| static

## ◆ META_FILE_VOXEL_COUNT

const char* const META_FILE_VOXEL_COUNT
| static

## ◆ META_GRID_CLASS

const char* const META_GRID_CLASS
| static

## ◆ META_GRID_CREATOR

const char* const META_GRID_CREATOR
| static

## ◆ META_GRID_NAME

const char* const META_GRID_NAME
| static

## ◆ META_IS_LOCAL_SPACE

const char* const META_IS_LOCAL_SPACE
| static

## ◆ META_SAVE_HALF_FLOAT

const char* const META_SAVE_HALF_FLOAT
| static

## ◆ META_VECTOR_TYPE

const char* const META_VECTOR_TYPE
| static