OpenVDB: File Class Reference

OpenVDB 12.1.1

Loading...
Searching...
No Matches
File Class Reference

Grid archive associated with a file on disk. More...

`#include <openvdb/io/File.h>`

Inheritance diagram for File:

## Classes
class | NameIterator

## Public Types
using | NameMap = std::multimap<Name, GridDescriptor>
using | NameMapCIter = NameMap::const_iterator
using | Ptr = SharedPtr<Archive>
using | ConstPtr = SharedPtr<const Archive>

## Public Member Functions
| File (const std::string &filename)
| ~File () override
| File (const File &other)
| Copy constructor.
File & | operator= (const File &other)
| Assignment.
SharedPtr< Archive > | copy () const override
| Return a copy of this archive.
const std::string & | filename () const
| Return the name of the file with which this archive is associated.
bool | open (bool=false)
bool | isOpen () const
| Return `true` if the file has been opened for reading.
void | close ()
| Close the file once we are done reading from it.
Index64 | getSize () const
| Return this file's current size on disk in bytes.
bool | hasGrid (const Name &) const
| Return `true` if a grid of the given name exists in this file.
MetaMap::Ptr | getMetadata () const
| Return (in a newly created MetaMap) the file-level metadata.
GridPtrVecPtr | getGrids () const
| Read the entire contents of the file and return a list of grid pointers.
GridPtrVecPtr | readAllGridMetadata ()
| Read just the grid metadata and transforms from the file and return a list of pointers to grids that are empty except for their metadata and transforms.
GridBase::Ptr | readGridMetadata (const Name &)
| Read a grid's metadata and transform only.
GridBase::Ptr | readGrid (const Name &)
| Read an entire grid, including all of its data blocks.
GridBase::Ptr | readGrid (const Name &, const BBoxd &)
| Read a grid, including its data blocks, but only where it intersects the given world-space bounding box.
void | write (const GridCPtrVec &, const MetaMap &=MetaMap()) const override
| Write the grids in the given container to the file whose name was given in the constructor.
template<typename GridPtrContainerT>
void | write (const GridPtrContainerT &, const MetaMap &=MetaMap()) const
| Write the grids in the given container to the file whose name was given in the constructor.
NameIterator | beginName () const
NameIterator | endName () const
std::string | getUniqueTag () const
| Return the UUID that was most recently written (or read, if no UUID has been written yet).
bool | isIdentical (const std::string &uuidStr) const
| Return `true` if the given UUID matches this archive's UUID.
uint32_t | fileVersion () const
| Return the file format version number of the input stream.
VersionId | libraryVersion () const
| Return the (major, minor) version number of the library that was used to write the input stream.
std::string | version () const
| Return a string of the form "<major>.<minor>/<format>", giving the library and file format version numbers associated with the input stream.
bool | isInstancingEnabled () const
| Return `true` if trees shared by multiple grids are written out only once, `false` if they are written out once per grid.
void | setInstancingEnabled (bool b)
| Specify whether trees shared by multiple grids should be written out only once (`true`) or once per grid (`false`).
uint32_t | compression () const
| Return a bit mask specifying compression options for the data stream.
void | setCompression (uint32_t c)
| Specify whether and how the data stream should be compressed.
bool | isGridStatsMetadataEnabled () const
| Return `true` if grid statistics (active voxel count and bounding box, etc.) are computed and written as grid metadata.
void | setGridStatsMetadataEnabled (bool b)
| Specify whether grid statistics (active voxel count and bounding box, etc.) should be computed and written as grid metadata.

## Static Public Member Functions
static bool | hasBloscCompression ()
| Return `true` if the OpenVDB library includes support for the Blosc compressor.
static bool | hasZLibCompression ()
| Return `true` if the OpenVDB library includes support for the ZLib compressor.
static bool | isDelayedLoadingEnabled ()
| Return `true` if delayed loading is enabled.

## Static Public Attributes
static const uint32_t | DEFAULT_COMPRESSION_FLAGS

## Protected Types
using | NamedGridMap = std::map<Name , GridBase::Ptr>

## Protected Member Functions
void | write (std::ostream &, const GridPtrVec &, bool seekable, const MetaMap &=MetaMap()) const
| Write the given grids to an output stream.
void | write (std::ostream &, const GridCPtrVec &, bool seekable, const MetaMap &=MetaMap()) const
bool | inputHasGridOffsets () const
| Return `true` if the input stream contains grid offsets that allow for random access or partial reading.
void | setInputHasGridOffsets (bool b)
void | setFormatVersion (std::istream &)
| Tag the given input stream with the input file format version number.
void | setLibraryVersion (std::istream &)
| Tag the given input stream with the version number of the library with which the input stream was created.
void | setDataCompression (std::istream &)
| Tag the given input stream with flags indicating whether the input stream contains compressed data and how it is compressed.
void | setGridCompression (std::ostream &, const GridBase &) const
| Tag an output stream with flags specifying only those compression options that are applicable to the given grid.
void | connectInstance (const GridDescriptor &, const NamedGridMap &) const
| If the grid represented by the given grid descriptor is an instance, connect it with its instance parent.
void | writeGrid (GridDescriptor &, GridBase::ConstPtr, std::ostream &, bool seekable) const
void | writeGridInstance (GridDescriptor &, GridBase::ConstPtr, std::ostream &, bool seekable) const
bool | readHeader (std::istream &)
| Read the magic number, version numbers, UUID, etc. from the given input stream.
void | writeHeader (std::ostream &, bool seekable) const
| Write the magic number, version numbers, UUID, etc. to the given output stream.

## Static Protected Member Functions
static void | readGridCompression (std::istream &)
| Read in the compression flags for a grid and tag the given input stream with those flags.
static int32_t | readGridCount (std::istream &)
| Read in and return the number of grids on the input stream.
static void | readGrid (GridBase::Ptr, const GridDescriptor &, std::istream &)
| Populate the given grid from the input stream.
static void | readGrid (GridBase::Ptr, const GridDescriptor &, std::istream &, const BBoxd &)
| Populate the given grid from the input stream, but only where it intersects the given world-space bounding box.
static void | readGrid (GridBase::Ptr, const GridDescriptor &, std::istream &, const CoordBBox &)
| Populate the given grid from the input stream, but only where it intersects the given index-space bounding box.

## Friends
class | ::TestFile
class | ::TestStream

## Detailed Description

Grid archive associated with a file on disk.

## Member Typedef Documentation

## ◆ ConstPtr

using ConstPtr = SharedPtr<const Archive>
| inherited

## ◆ NamedGridMap

using NamedGridMap = std::map<Name , GridBase::Ptr>
| protectedinherited

## ◆ NameMap

using NameMap = std::multimap<Name, GridDescriptor>

## ◆ NameMapCIter

using NameMapCIter = NameMap::const_iterator

## ◆ Ptr

using Ptr = SharedPtr<Archive>
| inherited

## Constructor & Destructor Documentation

## ◆ File() [1/2]

File | ( | const std::string & | filename | ) |
| explicit

## ◆ ~File()

~File | ( |  | ) |
| override

## ◆ File() [2/2]

File | ( | const File & | other | ) |

Copy constructor.

The copy will be closed and will not reference the same file descriptor as the original.

## Member Function Documentation

## ◆ beginName()

NameIterator beginName | ( |  | ) | const

Returns
  a NameIterator to iterate over all grid names in the file.

## ◆ close()

void close | ( |  | ) |

Close the file once we are done reading from it.

## ◆ compression()

uint32_t compression | ( |  | ) | const
| inlineinherited

Return a bit mask specifying compression options for the data stream.

## ◆ connectInstance()

void connectInstance | ( | const GridDescriptor & | ,
|  | const NamedGridMap & | ) const
| protectedinherited

If the grid represented by the given grid descriptor is an instance, connect it with its instance parent.

## ◆ copy()

SharedPtr< Archive > copy | ( |  | ) | const
| overridevirtual

Return a copy of this archive.

The copy will be closed and will not reference the same file descriptor as the original.

Reimplemented from Archive.

## ◆ endName()

NameIterator endName | ( |  | ) | const

Returns
  the ending iterator for all grid names in the file.

## ◆ filename()

const std::string & filename | ( |  | ) | const

Return the name of the file with which this archive is associated.

The file does not necessarily exist on disk yet.

## ◆ fileVersion()

uint32_t fileVersion | ( |  | ) | const
| inlineinherited

Return the file format version number of the input stream.

## ◆ getGrids()

GridPtrVecPtr getGrids | ( |  | ) | const

Read the entire contents of the file and return a list of grid pointers.

## ◆ getMetadata()

MetaMap::Ptr getMetadata | ( |  | ) | const

Return (in a newly created MetaMap) the file-level metadata.

## ◆ getSize()

Index64 getSize | ( |  | ) | const

Return this file's current size on disk in bytes.

Exceptions

  IoError | if the file size cannot be determined.

## ◆ getUniqueTag()

std::string getUniqueTag | ( |  | ) | const
| inherited

Return the UUID that was most recently written (or read, if no UUID has been written yet).

## ◆ hasBloscCompression()

bool hasBloscCompression | ( |  | ) |
| staticinherited

Return `true` if the OpenVDB library includes support for the Blosc compressor.

## ◆ hasGrid()

bool hasGrid | ( | const Name & |  | ) | const

Return `true` if a grid of the given name exists in this file.

## ◆ hasZLibCompression()

bool hasZLibCompression | ( |  | ) |
| staticinherited

Return `true` if the OpenVDB library includes support for the ZLib compressor.

## ◆ inputHasGridOffsets()

bool inputHasGridOffsets | ( |  | ) | const
| inlineprotectedinherited

Return `true` if the input stream contains grid offsets that allow for random access or partial reading.

## ◆ isDelayedLoadingEnabled()

bool isDelayedLoadingEnabled | ( |  | ) |
| staticinherited

Return `true` if delayed loading is enabled.

If enabled, delayed loading can be disabled for individual files, but not vice-versa.

Note
  Define the environment variable `OPENVDB_DISABLE_DELAYED_LOAD` to disable delayed loading unconditionally.

## ◆ isGridStatsMetadataEnabled()

bool isGridStatsMetadataEnabled | ( |  | ) | const
| inlineinherited

Return `true` if grid statistics (active voxel count and bounding box, etc.) are computed and written as grid metadata.

## ◆ isIdentical()

bool isIdentical | ( | const std::string & | uuidStr | ) | const
| inherited

Return `true` if the given UUID matches this archive's UUID.

## ◆ isInstancingEnabled()

bool isInstancingEnabled | ( |  | ) | const
| inlineinherited

Return `true` if trees shared by multiple grids are written out only once, `false` if they are written out once per grid.

## ◆ isOpen()

bool isOpen | ( |  | ) | const

Return `true` if the file has been opened for reading.

## ◆ libraryVersion()

VersionId libraryVersion | ( |  | ) | const
| inlineinherited

Return the (major, minor) version number of the library that was used to write the input stream.

## ◆ open()

bool open | ( | bool | = false | ) |

## ◆ operator=()

File & operator= | ( | const File & | other | ) |

Assignment.

After assignment, this File will be closed and will not reference the same file descriptor as the source File.

## ◆ readAllGridMetadata()

GridPtrVecPtr readAllGridMetadata | ( |  | ) |

Read just the grid metadata and transforms from the file and return a list of pointers to grids that are empty except for their metadata and transforms.

Exceptions

  IoError | if this file is not open for reading.

## ◆ readGrid() [1/5]

void readGrid | ( | GridBase::Ptr | ,
|  | const GridDescriptor & | ,
|  | std::istream & | )
| staticprotectedinherited

Populate the given grid from the input stream.

## ◆ readGrid() [2/5]

void readGrid | ( | GridBase::Ptr | ,
|  | const GridDescriptor & | ,
|  | std::istream & | ,
|  | const BBoxd & | )
| staticprotectedinherited

Populate the given grid from the input stream, but only where it intersects the given world-space bounding box.

## ◆ readGrid() [3/5]

void readGrid | ( | GridBase::Ptr | ,
|  | const GridDescriptor & | ,
|  | std::istream & | ,
|  | const CoordBBox & | )
| staticprotectedinherited

Populate the given grid from the input stream, but only where it intersects the given index-space bounding box.

## ◆ readGrid() [4/5]

GridBase::Ptr readGrid | ( | const Name & |  | ) |

Read an entire grid, including all of its data blocks.

## ◆ readGrid() [5/5]

GridBase::Ptr readGrid | ( | const Name & | ,
|  | const BBoxd & | )

Read a grid, including its data blocks, but only where it intersects the given world-space bounding box.

## ◆ readGridCompression()

void readGridCompression | ( | std::istream & |  | ) |
| staticprotectedinherited

Read in the compression flags for a grid and tag the given input stream with those flags.

## ◆ readGridCount()

int32_t readGridCount | ( | std::istream & |  | ) |
| staticprotectedinherited

Read in and return the number of grids on the input stream.

## ◆ readGridMetadata()

GridBase::Ptr readGridMetadata | ( | const Name & |  | ) |

Read a grid's metadata and transform only.

Returns
  A pointer to a grid that is empty except for its metadata and transform.

Exceptions

  IoError | if this file is not open for reading.
  KeyError | if no grid with the given name exists in this file.

## ◆ readHeader()

bool readHeader | ( | std::istream & |  | ) |
| protectedinherited

Read the magic number, version numbers, UUID, etc. from the given input stream.

Returns
  `true` if the input UUID differs from the previously-read UUID.

## ◆ setCompression()

void setCompression | ( | uint32_t | c | ) |
| inlineinherited

Specify whether and how the data stream should be compressed.

Parameters

  c | bitwise OR (e.g., COMPRESS_ZIP | COMPRESS_ACTIVE_MASK) of compression option flags (see Compression.h for the available flags)

Note
  Not all combinations of compression options are supported.

## ◆ setDataCompression()

void setDataCompression | ( | std::istream & |  | ) |
| protectedinherited

Tag the given input stream with flags indicating whether the input stream contains compressed data and how it is compressed.

## ◆ setFormatVersion()

void setFormatVersion | ( | std::istream & |  | ) |
| protectedinherited

Tag the given input stream with the input file format version number.

The tag can be retrieved with getFormatVersion().

See also
  getFormatVersion()

## ◆ setGridCompression()

void setGridCompression | ( | std::ostream & | ,
|  | const GridBase & | ) const
| protectedinherited

Tag an output stream with flags specifying only those compression options that are applicable to the given grid.

## ◆ setGridStatsMetadataEnabled()

void setGridStatsMetadataEnabled | ( | bool | b | ) |
| inlineinherited

Specify whether grid statistics (active voxel count and bounding box, etc.) should be computed and written as grid metadata.

## ◆ setInputHasGridOffsets()

void setInputHasGridOffsets | ( | bool | b | ) |
| inlineprotectedinherited

## ◆ setInstancingEnabled()

void setInstancingEnabled | ( | bool | b | ) |
| inlineinherited

Specify whether trees shared by multiple grids should be written out only once (`true`) or once per grid (`false`).

Note
  Instancing is enabled by default.

## ◆ setLibraryVersion()

void setLibraryVersion | ( | std::istream & |  | ) |
| protectedinherited

Tag the given input stream with the version number of the library with which the input stream was created.

The tag can be retrieved with getLibraryVersion().

See also
  getLibraryVersion()

## ◆ version()

std::string version | ( |  | ) | const
| inherited

Return a string of the form "<major>.<minor>/<format>", giving the library and file format version numbers associated with the input stream.

## ◆ write() [1/4]

void write | ( | std::ostream & | ,
|  | const GridCPtrVec & | ,
|  | bool | seekable,
|  | const MetaMap & | = MetaMap() ) const
| protectedinherited

## ◆ write() [2/4]

void write | ( | std::ostream & | ,
|  | const GridPtrVec & | ,
|  | bool | seekable,
|  | const MetaMap & | = MetaMap() ) const
| protectedinherited

Write the given grids to an output stream.

## ◆ write() [3/4]

void write | ( | const GridCPtrVec & | grids,
|  | const MetaMap & | meta = MetaMap() ) const
| inlineoverridevirtual

Write the grids in the given container to the file whose name was given in the constructor.

Reimplemented from Archive.

## ◆ write() [4/4]

template<typename GridPtrContainerT>

void write | ( | const GridPtrContainerT & | container,
|  | const MetaMap & | meta = MetaMap() ) const
| inline

Write the grids in the given container to the file whose name was given in the constructor.

## ◆ writeGrid()

void writeGrid | ( | GridDescriptor & | ,
|  | GridBase::ConstPtr | ,
|  | std::ostream & | ,
|  | bool | seekable ) const
| protectedinherited

Write the given grid descriptor and grid to an output stream and update the GridDescriptor offsets.

Parameters

  seekable | if true, the output stream supports seek operations

## ◆ writeGridInstance()

void writeGridInstance | ( | GridDescriptor & | ,
|  | GridBase::ConstPtr | ,
|  | std::ostream & | ,
|  | bool | seekable ) const
| protectedinherited

Write the given grid descriptor and grid metadata to an output stream and update the GridDescriptor offsets, but don't write the grid's tree, since it is shared with another grid.

Parameters

  seekable | if true, the output stream supports seek operations

## ◆ writeHeader()

void writeHeader | ( | std::ostream & | ,
|  | bool | seekable ) const
| protectedinherited

Write the magic number, version numbers, UUID, etc. to the given output stream.

Parameters

  seekable | if true, the output stream supports seek operations

## Friends And Related Symbol Documentation

## ◆ ::TestFile

friend class ::TestFile
| friend

## ◆ ::TestStream

friend class ::TestStream
| friend

## Member Data Documentation

## ◆ DEFAULT_COMPRESSION_FLAGS

const uint32_t DEFAULT_COMPRESSION_FLAGS
| staticinherited