File.h

Go to the documentation of this file.

// Copyright Contributors to the OpenVDB Project
// SPDX-License-Identifier: Apache-2.0
//
/// @file File.h
 
#ifndef OPENVDB_IO_FILE_HAS_BEEN_INCLUDED
#define OPENVDB_IO_FILE_HAS_BEEN_INCLUDED
 
#include <openvdb/version.h>
#include "io.h" // for MappedFile::Notifier
#include "Archive.h"
#include "GridDescriptor.h"
#include <algorithm> // for std::copy()
#include <iosfwd>
#include <iterator> // for std::back_inserter()
#include <map>
#include <memory>
#include <string>
 
 
class TestFile;
class TestStream;
 
namespace openvdb {
OPENVDB_USE_VERSION_NAMESPACE
namespace OPENVDB_VERSION_NAME {
namespace io {
 
/// Grid archive associated with a file on disk
class OPENVDB_API File: public Archive
{
public:
    using NameMap = std::multimap<Name, GridDescriptor>;
    using NameMapCIter = NameMap::const_iterator;
 
    explicit File(const std::string& filename);
    ~File() override { }
 
    /// @brief Copy constructor
    /// @details The copy will be closed and will not reference the same
    /// file descriptor as the original.
    File(const File& other);
    /// @brief Assignment
    /// @details After assignment, this File will be closed and will not
    /// reference the same file descriptor as the source File.
    File& operator=(const File& other);
 
    /// @brief Return a copy of this archive.
    /// @details The copy will be closed and will not reference the same
    /// file descriptor as the original.
    SharedPtr<Archive> copy() const override;
 
    /// @brief Return the name of the file with which this archive is associated.
    /// @details The file does not necessarily exist on disk yet.
    const std::string& filename() const;
 
    /// @brief 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.
    /// @throw IoError if the file is not a valid VDB file.
    /// @return @c true if the file's UUID has changed since it was last read.
    bool open();
 
    OPENVDB_DEPRECATED_MESSAGE("Use File::open() instead.This method is deprecated and will be removed. Delayed loading is no longer supported.")
    bool open(bool /*delayLoad*/) { return open(); }
    OPENVDB_DEPRECATED_MESSAGE("Use File::open() instead. This method is deprecated and will be removed. Delayed loading is no longer supported.")
    bool open(bool /*delayLoad*/, const MappedFile::Notifier& /*notifier*/) { return open(); }
 
    /// Return @c true if the file has been opened for reading.
    bool isOpen() const;
 
    /// Close the file once we are done reading from it.
    void close();
 
    /// @brief Return this file's current size on disk in bytes.
    /// @throw IoError if the file size cannot be determined.
    Index64 getSize() const;
 
    OPENVDB_DEPRECATED_MESSAGE("Always returns 0. This method is deprecated and will be removed. Delayed loading is no longer supported.")
    Index64 copyMaxBytes() const { return 0; }
    OPENVDB_DEPRECATED_MESSAGE("This method is deprecated and will be removed. Delayed loading is no longer supported.")
    void setCopyMaxBytes(Index64 /*bytes*/) { }
 
    /// Return @c true if a grid of the given name exists in this file.
    bool hasGrid(const Name&) const;
 
    /// Return (in a newly created MetaMap) the file-level metadata.
    MetaMap::Ptr getMetadata() const;
 
    /// @brief Read the entire contents of the file and return a list of grid pointers.
    /// @details Instances share trees, except when clipping a file that has grid offsets,
    /// where each grid is clipped independently.
    GridPtrVecPtr getGrids(const io::ReadOptions& readOptions = io::ReadOptions{}) const;
 
    /// @brief 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.
    /// @throw IoError if this file is not open for reading.
    GridPtrVecPtr readAllGridMetadata();
 
    /// @brief Read a grid's metadata and transform only.
    /// @return A pointer to a grid that is empty except for its metadata and transform.
    /// @throw IoError if this file is not open for reading.
    /// @throw KeyError if no grid with the given name exists in this file.
    GridBase::Ptr readGridMetadata(const Name&);
 
    /// Read an entire grid, including all of its data blocks, using the provided options if given.
    GridBase::Ptr readGrid(const Name&, const io::ReadOptions& readOptions = io::ReadOptions{});
    /// @brief Read a grid, including its data blocks, but only where it
    /// intersects the given world-space bounding box.
    GridBase::Ptr readGrid(const Name&, const BBoxd&);
 
    /// @brief Read all grids whose grid name is exactly @a name, in file order.
    /// @details 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.
    /// @return An empty list if no grid has this name.
    /// @throw IoError if this file is not open for reading.
    GridPtrVecPtr readGrids(const Name& name, const io::ReadOptions& readOptions = io::ReadOptions{});
 
    /// @brief Write the grids in the given container to the file whose name
    /// was given in the constructor.
    void write(const GridCPtrVec&, const MetaMap& = MetaMap(),
        const io::WriteOptions& = io::WriteOptions{}) const override;
 
    /// @brief 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;
 
    /// A const iterator that iterates over all names in the file. This is only
    /// valid once the file has been opened.
    class OPENVDB_API NameIterator
    {
    public:
        NameIterator(const NameMapCIter& iter): mIter(iter) {}
        NameIterator(const NameIterator&) = default;
        ~NameIterator() {}
 
        NameIterator& operator++() { mIter++; return *this; }
 
        bool operator==(const NameIterator& iter) const { return mIter == iter.mIter; }
        bool operator!=(const NameIterator& iter) const { return mIter != iter.mIter; }
 
        Name operator*() const { return this->gridName(); }
 
        Name gridName() const { return GridDescriptor::nameAsString(mIter->second.uniqueName()); }
 
    private:
        NameMapCIter mIter;
    };
 
    /// @return a NameIterator to iterate over all grid names in the file.
    NameIterator beginName() const;
 
    /// @return the ending iterator for all grid names in the file.
    NameIterator endName() const;
 
private:
    /// @brief Return an iterator to the descriptor for the grid with the given name.
    /// @details If "density" is searched and there is more than one "density" grid,
    /// returns an iterator to the first matching grid. If "density[1]" is searched,
    /// it is tested against the unique name, so it matches the second "density" grid.
    NameMapCIter findDescriptor(const Name&) const;
 
    /// @brief Return an iterator to the descriptor whose unique name is exactly the given name,
    /// or the end iterator if there is none.
    /// @details Only the unique name is searched. "density" does not match a grid that was
    /// made unique as "density[1]", "density[1]" must be used instead.
    NameMapCIter findDescriptorByUniqueName(const Name&) const;
 
    /// @brief Read the grid for the given descriptor, including its instance parent's tree.
    /// @note This method should not be called for files that don't contain grid offsets.
    /// @throw KeyError if the grid is an instance and its parent is missing.
    GridBase::Ptr readGridFromDescriptor(const GridDescriptor&, const io::ReadOptions&) const;
 
    /// @brief Retrieve a grid from @c mNamedGrids.  Return a null pointer
    /// if @c mNamedGrids was not populated (because this file is random-access).
    /// @throw KeyError if no grid with the given name exists in this file.
    GridBase::Ptr retrieveCachedGrid(const Name&) const;
 
    /// @brief Return the grid that @a readOptions asks for, given the already
    /// cached @a cachedGrid. Doesn't mutate @a cachedGrid, and returns it
    /// unchanged when no option applies.
    GridBase::Ptr resolveCachedGrid(const GridBase::Ptr& cachedGrid,
        const io::ReadOptions& readOptions, ReadDiagnostics& diagnostics) const;
 
    /// @brief Resolve each of @a cachedGrids as resolveCachedGrid() does. Grids that
    /// share a source tree share the resolved tree when instancing is enabled.
    GridPtrVecPtr resolveCachedGrids(const GridPtrVec& cachedGrids,
        const io::ReadOptions& readOptions) const;
 
    void writeGrids(const GridCPtrVec&, const MetaMap&, const io::WriteOptions&) const;
 
    MetaMap::Ptr fileMetadata();
    MetaMap::ConstPtr fileMetadata() const;
 
    const NameMap& gridDescriptors() const;
    NameMap& gridDescriptors();
 
    std::istream& inputStream() const;
 
    friend class ::TestFile;
    friend class ::TestStream;
 
    std::string mFilename;
    // The file-level metadata
    MetaMap::Ptr mMeta;
    // The file stream that is open for reading
    std::unique_ptr<std::istream> mInStream;
    // File-level stream metadata (file format, compression, etc.)
    StreamMetadata::Ptr mStreamMetadata;
    // Flag indicating if we have read in the global information (header,
    // metadata, and grid descriptors) for this VDB file
    bool mIsOpen = false;
    // Grid descriptors for all grids stored in the file, indexed by grid name
    NameMap mGridDescriptors;
    // All grids, indexed by unique name (used only when mHasGridOffsets is false)
    Archive::NamedGridMap mNamedGrids;
    // All grids stored in the file (used only when mHasGridOffsets is false)
    GridPtrVecPtr mGrids;
};
 
 
////////////////////////////////////////
 
 
inline void
File::write(const GridCPtrVec& grids, const MetaMap& meta,
    const io::WriteOptions& writeOptions) const
{
    this->writeGrids(grids, meta, writeOptions);
}
 
 
template<typename GridPtrContainerT>
inline void
File::write(const GridPtrContainerT& container, const MetaMap& meta,
    const io::WriteOptions& writeOptions) const
{
    GridCPtrVec grids;
    std::copy(container.begin(), container.end(), std::back_inserter(grids));
    this->writeGrids(grids, meta, writeOptions);
}
 
} // namespace io
} // namespace OPENVDB_VERSION_NAME
} // namespace openvdb
 
#endif // OPENVDB_IO_FILE_HAS_BEEN_INCLUDED