Add ReadDiagnostics to Codecs

Signed-off-by: Dan Bailey <danbailey@ilm.com>

Author: danrbailey

openvdb/openvdb/codecs/BoolCodec.h

@@ -110,7 +110,7 @@ struct OPENVDB_API BoolCodec : public TopologyCodec<GridT>
 
     static inline std::string name() { return GridT::gridType(); }
 
-    void readBuffers(std::istream& is, io::CodecData& data, const io::ReadOptions& options) final
+    void readBuffers(std::istream& is, io::CodecData& data, const io::ReadOptions& options, io::ReadDiagnostics*) final
     {
         GridT& grid = static_cast<GridT&>(*data.grid);
 

openvdb/openvdb/codecs/TopologyCodec.h

@@ -107,17 +107,22 @@ struct ReadTopologyOp
     using LeafT = typename TreeT::LeafNodeType;
     using StorageValueT = typename StorageTreeT::ValueType;
 
-    ReadTopologyOp(std::istream& _is, bool _saveFloatAsHalf)
+    ReadTopologyOp(std::istream& _is, bool _saveFloatAsHalf, io::ReadDiagnostics* _diagnostics,
+            const std::string& _gridName)
         : is(_is)
-        , saveFloatAsHalf(_saveFloatAsHalf) { }
+        , saveFloatAsHalf(_saveFloatAsHalf)
+        , diagnostics(_diagnostics)
+        , gridName(_gridName) { }
 
     void operator()(RootT& root)
     {
         using ChildT = typename RootT::ChildNodeType;
 
         int32_t bufferCount;
         is.read(reinterpret_cast<char*>(&bufferCount), sizeof(int32_t));
-        if (bufferCount != 1) OPENVDB_LOG_WARN("multi-buffer trees are no longer supported");
+        if (bufferCount != 1) {
+            if (diagnostics) diagnostics->addWarning(gridName, "multi-buffer trees are no longer supported");
+        }
 
         // Delete the existing tree.
         root.clear();
@@ -216,6 +221,8 @@ struct ReadTopologyOp
     std::istream& is;
     bool saveFloatAsHalf;
     ValueT background;
+    io::ReadDiagnostics* diagnostics = nullptr;
+    std::string gridName;
 }; // struct ReadTopologyOp
 
 template <typename TreeT>
@@ -264,14 +271,14 @@ void setTilesToBackground(TreeT& tree)
 
 // Free-standing function for read case (supports type conversion via StorageGridT)
 template<typename GridT, typename StorageGridT = GridT>
-void topologyCodecReadTopology(GridBase& gridBase, std::istream& is, const io::ReadOptions& options)
+void topologyCodecReadTopology(GridBase& gridBase, std::istream& is, const io::ReadOptions& options, io::ReadDiagnostics* diagnostics)
 {
     io::checkFormatVersion(is);
 
     GridT& grid = static_cast<GridT&>(gridBase);
     grid.tree().clearAllAccessors();
 
-    internal::ReadTopologyOp<typename GridT::TreeType, typename StorageGridT::TreeType> readTopologyOp(is, grid.saveFloatAsHalf());
+    internal::ReadTopologyOp<typename GridT::TreeType, typename StorageGridT::TreeType> readTopologyOp(is, grid.saveFloatAsHalf(), diagnostics, grid.getName());
     readTopologyOp(grid.tree().root());
 
     if (options.readMode == io::ReadMode::TopologyOnly) {
@@ -307,9 +314,10 @@ struct OPENVDB_API TopologyCodec : public io::Codec
         return data;
     }
 
-    void readTopology(std::istream& is, io::CodecData& data, const io::ReadOptions& options) final
+    void readTopology(std::istream& is, io::CodecData& data, const io::ReadOptions& options,
+        io::ReadDiagnostics* diagnostics) final
     {
-        internal::topologyCodecReadTopology<GridT, StorageGridT>(*data.grid, is, options);
+        internal::topologyCodecReadTopology<GridT, StorageGridT>(*data.grid, is, options, diagnostics);
     }
 
     void writeTopology(std::ostream& os, const GridBase& gridBase, const io::WriteOptions&) final

openvdb/openvdb/io/Archive.cc

@@ -384,6 +384,27 @@ Archive::copy() const
 }
 
 
+void
+Archive::enableReadDiagnostics()
+{
+    if (!mReadDiagnostics) mReadDiagnostics = std::make_shared<ReadDiagnostics>();
+}
+
+
+void
+Archive::disableReadDiagnostics()
+{
+    mReadDiagnostics.reset();
+}
+
+
+ReadDiagnostics*
+Archive::readDiagnostics() const
+{
+    return mReadDiagnostics.get();
+}
+
+
 ////////////////////////////////////////
 
 
@@ -898,7 +919,7 @@ Archive::connectInstance(const GridDescriptor& gd, const NamedGridMap& grids) co
 
 
 GridBase::Ptr
-Archive::readGrid(const GridDescriptor& gd, std::istream& is, const io::ReadOptions& readOptions)
+Archive::readGrid(const GridDescriptor& gd, std::istream& is, const io::ReadOptions& readOptions, ReadDiagnostics* diagnostics)
 {
     // Read the compression settings for this grid and tag the stream with them
     // so that downstream functions can reference them.
@@ -964,13 +985,13 @@ Archive::readGrid(const GridDescriptor& gd, std::istream& is, const io::ReadOpti
     if (readOptions.readMode != io::ReadMode::TopologyOnly && !gd.isInstance()) {
         // read topology
         if (codec) {
-            codec->readTopology(is, *codecData, readOptions);
+            codec->readTopology(is, *codecData, readOptions, diagnostics);
         } else {
             grid->readTopology(is);
         }
         // read buffers
         if (codec) {
-            codec->readBuffers(is, *codecData, readOptions);
+            codec->readBuffers(is, *codecData, readOptions, diagnostics);
         } else {
             const auto& worldBBox = readOptions.clipBBox;
             const bool clip = worldBBox.isSorted();

openvdb/openvdb/io/Archive.h

@@ -98,6 +98,15 @@ class OPENVDB_API Archive
     /// @brief Return @c false (delayed loading has been removed).
     static bool isDelayedLoadingEnabled() { return false; }
 
+    /// @brief Enable collection of read diagnostics (warnings, etc.) during I/O operations.
+    void enableReadDiagnostics();
+
+    /// @brief Disable collection of read diagnostics.
+    void disableReadDiagnostics();
+
+    /// @brief Return a pointer to the diagnostics collector, or nullptr if disabled.
+    ReadDiagnostics* readDiagnostics() const;
+
 protected:
     /// @brief Return @c true if the input stream contains grid offsets
     /// that allow for random access or partial reading.
@@ -137,7 +146,7 @@ class OPENVDB_API Archive
     /// @brief 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{});
+        const io::ReadOptions& readOptions = io::ReadOptions{}, ReadDiagnostics* = nullptr);
 
     using NamedGridMap = std::map<Name /*uniqueName*/, GridBase::Ptr>;
 
@@ -192,6 +201,8 @@ class OPENVDB_API Archive
     uint32_t mCompression;
     /// Flag indicating whether grid statistics metadata should be written
     bool mEnableGridStats;
+    /// Diagnostics collector for read operations
+    std::shared_ptr<ReadDiagnostics> mReadDiagnostics;
 }; // class Archive
 
 } // namespace io

openvdb/openvdb/io/Codec.h

@@ -8,6 +8,8 @@
 #include <unordered_map>
 #include <memory>
 #include <iostream>
+#include <vector>
+#include <mutex>
 
 #include <openvdb/Types.h>
 
@@ -71,6 +73,30 @@ struct OPENVDB_API WriteOptions
 {
 }; // struct WriteOptions
 
+enum class DiagnosticSeverity { Warning };
+
+struct ReadDiagnostic {
+    DiagnosticSeverity severity;
+    std::string context;
+    std::string message;
+};
+
+struct OPENVDB_API ReadDiagnostics {
+    void addWarning(const std::string& context, const std::string& message) {
+        std::lock_guard<std::mutex> lock(mMutex);
+        mDiagnostics.push_back({DiagnosticSeverity::Warning, context, message});
+    }
+    void clear() {
+        std::lock_guard<std::mutex> lock(mMutex);
+        mDiagnostics.clear();
+    }
+    const std::vector<ReadDiagnostic>& diagnostics() const { return mDiagnostics; }
+    bool empty() const { return mDiagnostics.empty(); }
+private:
+    std::vector<ReadDiagnostic> mDiagnostics;
+    mutable std::mutex mMutex;
+}; // struct ReadDiagnostics
+
 /// Per-codec mutable data created by Codec::createData()
 /// Contains the grid and any codec-specific state
 struct OPENVDB_API CodecData
@@ -93,10 +119,10 @@ struct OPENVDB_API Codec
     virtual CodecData::Ptr createData() = 0;
 
     /// Read the grid topology
-    virtual void readTopology(std::istream&, CodecData&, const ReadOptions&) { }
+    virtual void readTopology(std::istream&, CodecData&, const ReadOptions&, ReadDiagnostics*) { }
 
     /// Read all data buffers for this grid
-    virtual void readBuffers(std::istream&, CodecData&, const ReadOptions&) { }
+    virtual void readBuffers(std::istream&, CodecData&, const ReadOptions&, ReadDiagnostics*) { }
 
     /// Write the grid topology
     virtual void writeTopology(std::ostream&, const GridBase&, const WriteOptions&) { }

openvdb/openvdb/io/File.cc

@@ -319,7 +319,7 @@ File::getGrids(const io::ReadOptions& readOptions) const
             const GridDescriptor& gd = i->second;
             // Seek to the grid in the file.
             gd.seekToGrid(inputStream());
-            GridBase::Ptr grid = Archive::readGrid(gd, inputStream(), readOptions);
+            GridBase::Ptr grid = Archive::readGrid(gd, inputStream(), readOptions, readDiagnostics());
             ret->push_back(grid);
             namedGrids[gd.uniqueName()] = grid;
         }
@@ -477,7 +477,7 @@ File::readGrid(const Name& name, const io::ReadOptions& readOptions)
     OPENVDB_ASSERT(inputHasGridOffsets());
     // Seek to the grid in the file.
     gd.seekToGrid(inputStream());
-    grid = Archive::readGrid(gd, inputStream(), readOptions);
+    grid = Archive::readGrid(gd, inputStream(), readOptions, readDiagnostics());
 
     if (gd.isInstance()) {
         /// @todo Refactor to share code with Archive::connectInstance()?
@@ -493,7 +493,7 @@ File::readGrid(const Name& name, const io::ReadOptions& readOptions)
         GridBase::Ptr parent;
         OPENVDB_ASSERT(inputHasGridOffsets());
         parentIt->second.seekToGrid(inputStream());
-        parent = Archive::readGrid(parentIt->second, inputStream(), readOptions);
+        parent = Archive::readGrid(parentIt->second, inputStream(), readOptions, readDiagnostics());
         if (parent) grid->setTree(parent->baseTreePtr());
     }
     return grid;
@@ -592,6 +592,7 @@ File::endName() const
     return File::NameIterator(mGridDescriptors.end());
 }
 
+
 } // namespace io
 } // namespace OPENVDB_VERSION_NAME
 } // namespace openvdb

openvdb/openvdb/unittest/TestCodec.cc

@@ -213,3 +213,147 @@ TEST_F(TestCodec, testBoolCodecIO)
     std::remove(rawPath.c_str());
     std::remove(codecPath.c_str());
 }
+
+
+TEST_F(TestCodec, testReadDiagnosticsStruct)
+{
+    using namespace openvdb::io;
+
+    // Default-constructed: no diagnostics
+    ReadDiagnostics diags;
+    EXPECT_TRUE(diags.diagnostics().empty());
+
+    // addWarning accumulates entries
+    diags.addWarning("grid_a", "something went wrong");
+    ASSERT_EQ(diags.diagnostics().size(), size_t(1));
+    EXPECT_EQ(diags.diagnostics()[0].severity, DiagnosticSeverity::Warning);
+    EXPECT_EQ(diags.diagnostics()[0].context, std::string("grid_a"));
+    EXPECT_EQ(diags.diagnostics()[0].message, std::string("something went wrong"));
+
+    diags.addWarning("grid_b", "another issue");
+    EXPECT_EQ(diags.diagnostics().size(), size_t(2));
+
+    // clear() empties the vector
+    diags.clear();
+    EXPECT_TRUE(diags.diagnostics().empty());
+}
+
+
+TEST_F(TestCodec, testReadDiagnosticsArchiveAPI)
+{
+    using namespace openvdb;
+    using namespace openvdb::io;
+
+    openvdb::initialize();
+    CodecRegistry::clear();
+    io::internal::initialize();
+
+    BoolGrid::Ptr srcGrid = BoolGrid::create(false);
+    srcGrid->setName("bool_grid");
+    srcGrid->fill(CoordBBox(Coord(-5), Coord(5)), true, true);
+
+    const std::string codecPath = "testReadDiagnosticsArchiveAPI.vdb";
+
+    {
+        io::File f(codecPath);
+        f.write(GridPtrVec{srcGrid});
+    }
+
+    // Without enableReadDiagnostics: readDiagnostics() returns nullptr
+    {
+        io::File f(codecPath);
+        f.open();
+        EXPECT_EQ(f.readDiagnostics(), nullptr);
+        f.readGrid("bool_grid");
+        EXPECT_EQ(f.readDiagnostics(), nullptr);
+        f.close();
+    }
+
+    // With enableReadDiagnostics: readDiagnostics() returns a pointer, normal read has no warnings
+    {
+        io::File f(codecPath);
+        f.open();
+        f.enableReadDiagnostics();
+        EXPECT_NE(f.readDiagnostics(), nullptr);
+        f.readGrid("bool_grid");
+        EXPECT_NE(f.readDiagnostics(), nullptr);
+        EXPECT_TRUE(f.readDiagnostics()->diagnostics().empty());
+        f.close();
+    }
+
+    // clearReadDiagnostics() empties the list but keeps collection active
+    {
+        io::File f(codecPath);
+        f.open();
+        f.enableReadDiagnostics();
+        f.readGrid("bool_grid");
+        f.readDiagnostics()->clear();
+        EXPECT_NE(f.readDiagnostics(), nullptr);
+        EXPECT_TRUE(f.readDiagnostics()->diagnostics().empty());
+        f.close();
+    }
+
+    // enableReadDiagnostics() is idempotent
+    {
+        io::File f(codecPath);
+        f.open();
+        f.enableReadDiagnostics();
+        const io::ReadDiagnostics* ptr = f.readDiagnostics();
+        f.enableReadDiagnostics();
+        EXPECT_EQ(f.readDiagnostics(), ptr);
+        f.close();
+    }
+
+    // Cleanup
+    CodecRegistry::clear();
+    std::remove(codecPath.c_str());
+}
+
+
+TEST_F(TestCodec, testReadDiagnosticsGetGrids)
+{
+    using namespace openvdb;
+    using namespace openvdb::io;
+
+    openvdb::initialize();
+    CodecRegistry::clear();
+    io::internal::initialize();
+
+    BoolGrid::Ptr srcGrid = BoolGrid::create(false);
+    srcGrid->setName("bool_grid");
+    srcGrid->fill(CoordBBox(Coord(-5), Coord(5)), true, true);
+
+    const std::string codecPath = "testReadDiagnosticsGetGrids.vdb";
+
+    {
+        io::File f(codecPath);
+        f.write(GridPtrVec{srcGrid});
+    }
+
+    // getGrids() with diagnostics enabled — normal read produces no warnings
+    {
+        io::File f(codecPath);
+        f.open();
+        f.enableReadDiagnostics();
+        GridPtrVecPtr grids = f.getGrids();
+        ASSERT_TRUE(grids && !grids->empty());
+        EXPECT_NE(f.readDiagnostics(), nullptr);
+        EXPECT_TRUE(f.readDiagnostics()->diagnostics().empty());
+        f.close();
+    }
+
+    // clearReadDiagnostics() between getGrids() calls resets state
+    {
+        io::File f(codecPath);
+        f.open();
+        f.enableReadDiagnostics();
+        f.getGrids();
+        f.readDiagnostics()->clear();
+        EXPECT_TRUE(f.readDiagnostics()->diagnostics().empty());
+        f.close();
+    }
+
+    // Cleanup
+    CodecRegistry::clear();
+    std::remove(codecPath.c_str());
+}