File Class Reference

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

#include <openvdb/io/File.h>

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 ()
	Open the file, read the file header and the file-level metadata, and populate the grid descriptors, but do not load any grids into memory.
bool	open (bool)
bool	open (bool, const MappedFile::Notifier &)
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.
Index64	copyMaxBytes () const
void	setCopyMaxBytes (Index64)
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 io::ReadOptions &readOptions=io::ReadOptions{}) 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 &, const io::ReadOptions &readOptions=io::ReadOptions{})
	Read an entire grid, including all of its data blocks, using the provided options if given.
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.
GridPtrVecPtr	readGrids (const Name &name, const io::ReadOptions &readOptions=io::ReadOptions{})
	Read all grids whose grid name is exactly name, in file order.
void	write (const GridCPtrVec &, const MetaMap &=MetaMap(), const io::WriteOptions &=io::WriteOptions{}) 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 io::WriteOptions &=io::WriteOptions{}) 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.
void	enableReadDiagnostics ()
	Enable collection of read diagnostics (warnings, etc.) during I/O operations.
void	disableReadDiagnostics ()
	Disable collection of read diagnostics.
const ReadDiagnostics &	readDiagnostics () const
	Return a const reference to the diagnostics collector.
void	clearReadDiagnostics ()
	Clear the diagnostics list while keeping collection active.

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 false (delayed loading has been removed).

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 &, const io::WriteOptions &writeOptions=io::WriteOptions{}) const
	Write the given grids to an output stream.
void	write (std::ostream &, const GridCPtrVec &, bool seekable, const MetaMap &, const io::WriteOptions &writeOptions=io::WriteOptions{}) 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 io::WriteOptions &writeOptions=io::WriteOptions{}) const
void	writeGridInstance (GridDescriptor &, GridBase::ConstPtr, std::ostream &, bool seekable, const io::WriteOptions &writeOptions=io::WriteOptions{}) 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 io::Codec *	findCodec (const std::string &gridType, const io::ReadOptions &options=io::ReadOptions{})
	Find the codec for the given grid type and options.
static GridBase::Ptr	readGrid (const GridDescriptor &, std::istream &, const io::ReadOptions &readOptions, ReadDiagnostics &diagnostics)
	Read in and create the grid represented by the given grid descriptor using the given input stream, using the provided options if given.
static GridBase::Ptr	readGrid (const GridDescriptor &, std::istream &, const io::ReadOptions &readOptions=io::ReadOptions{})

Protected Attributes
ReadDiagnostics	mReadDiagnostics
	Diagnostics collector for read operations (always valid; enabled/disabled via flag)

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 ( )

inlineoverride

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.

clearReadDiagnostics()

void clearReadDiagnostics ( )

inherited

Clear the diagnostics list while keeping collection active.

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.

copyMaxBytes()

Index64 copyMaxBytes ( ) const

inline

Deprecated

"Always returns 0. This method is deprecated and will be removed. Delayed loading is no longer supported."

disableReadDiagnostics()

void disableReadDiagnostics ( )

inherited

Disable collection of read diagnostics.

enableReadDiagnostics()

void enableReadDiagnostics ( )

inherited

Enable collection of read diagnostics (warnings, etc.) during I/O operations.

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.

findCodec()

io::Codec * findCodec ( const std::string & gridType, const io::ReadOptions & options = io::ReadOptions{} )

staticprotectedinherited

Find the codec for the given grid type and options.

getGrids()

GridPtrVecPtr getGrids

(

const io::ReadOptions &

readOptions = io::ReadOptions{}

)

const

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

Instances share trees, except when clipping a file that has grid offsets, where each grid is clipped independently.

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 ( )

inlinestaticinherited

Return false (delayed loading has been removed).

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() [1/3]

bool open

(

)

Open the file, read the file header and the file-level metadata, and populate the grid descriptors, but do not load any grids into memory.

Exceptions

IoError

if the file is not a valid VDB file.

Returns

true if the file's UUID has changed since it was last read.

open() [2/3]

bool open ( bool )

inline

Deprecated

"Use File::open() instead.This method is deprecated and will be removed. Delayed loading is no longer supported."

open() [3/3]

bool open ( bool , const MappedFile::Notifier &  )

inline

Deprecated

"Use File::open() instead. This method is deprecated and will be removed. Delayed loading is no longer supported."

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.

readDiagnostics()

const ReadDiagnostics & readDiagnostics ( ) const

inherited

Return a const reference to the diagnostics collector.

readGrid() [1/4]

GridBase::Ptr readGrid ( const GridDescriptor & , std::istream & , const io::ReadOptions & readOptions, ReadDiagnostics & diagnostics )

staticprotectedinherited

Read in and create the grid represented by the given grid descriptor using the given input stream, using the provided options if given.

readGrid() [2/4]

GridBase::Ptr readGrid ( const GridDescriptor & , std::istream & , const io::ReadOptions & readOptions = io::ReadOptions{} )

staticprotectedinherited

readGrid() [3/4]

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.

readGrid() [4/4]

GridBase::Ptr readGrid	(	const Name &	,
		const io::ReadOptions &	readOptions = io::ReadOptions{} )

Read an entire grid, including all of its data blocks, using the provided options if given.

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.

readGrids()

GridPtrVecPtr readGrids	(	const Name &	name,
		const io::ReadOptions &	readOptions = io::ReadOptions{} )

Read all grids whose grid name is exactly name, in file order.

Grids have a name, such as "density", which may not be unique in a file. When more than one grid share the same name, these names are made unique by adding a [N] suffix. For example, the first "density" grid becomes "density[0]", the second becomes "density[1]", etc. This method ignores the unique name and returns all grids whose grid name exactly matches the given name. Instances share trees as they do with getGrids(), except that a clip on a file with grid offsets does a clip on each grid independently.

Returns

An empty list if no grid has this name.

Exceptions

IoError

if this file is not open for reading.

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.

setCopyMaxBytes()

void setCopyMaxBytes ( Index64 )

inline

Deprecated

"This method is deprecated and will be removed. Delayed loading is no longer 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 & , const io::WriteOptions & writeOptions = io::WriteOptions{} ) const

protectedinherited

write() [2/4]

void write ( std::ostream & , const GridPtrVec & , bool seekable, const MetaMap & , const io::WriteOptions & writeOptions = io::WriteOptions{} ) const

protectedinherited

Write the given grids to an output stream.

write() [3/4]

void write ( const GridCPtrVec & grids, const MetaMap & meta = MetaMap(), const io::WriteOptions & writeOptions = io::WriteOptions{} ) 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 io::WriteOptions & writeOptions = io::WriteOptions{} ) 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 io::WriteOptions & writeOptions = io::WriteOptions{} ) 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
writeOptions	options controlling how grid data is written

writeGridInstance()

void writeGridInstance ( GridDescriptor & , GridBase::ConstPtr , std::ostream & , bool seekable, const io::WriteOptions & writeOptions = io::WriteOptions{} ) 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
writeOptions	options controlling how grid data is written

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

mReadDiagnostics

ReadDiagnostics mReadDiagnostics

mutableprotectedinherited

Diagnostics collector for read operations (always valid; enabled/disabled via flag)