MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
VolumeReader.hpp
Go to the documentation of this file.
1#pragma once
2
6
7namespace MayaFlux::IO::Detail {
8class VDBArchive;
9}
10
11namespace MayaFlux::IO {
12
13/**
14 * @struct VolumeInfo
15 * @brief Grid count of an OpenVDB archive.
16 *
17 * Stored on FileMetadata by VolumeReader.
18 */
19struct VolumeInfo {
20 uint64_t grid_count = 0; ///< Number of grids in the archive
21};
22
24
25/**
26 * @struct VolumeReadOptions
27 * @brief Configuration for volume reading.
28 */
30 /**
31 * @brief Grids to load, matched by name. Empty loads every grid in the
32 * file, in file order.
33 *
34 * A name with no matching grid is logged and skipped; the rest of the
35 * selection proceeds.
36 */
37 std::vector<std::string> field_names;
38};
39
40/**
41 * @class VolumeReader
42 * @brief tinyvdb-backed loader for volumetric grid files.
43 *
44 * Parallels ModelReader: a FileReader subclass whose primary API is
45 * open()+extract() or the one-shot load(), producing Kakshya::VolumeData —
46 * one lattice and every selected grid as a named VolumeField over it.
47 * create_container() and load_into_container() are no-ops, as for
48 * ModelReader; volume data does not go through the SignalSourceContainer
49 * streaming path.
50 *
51 * Supported formats: .vdb, via Detail::VDBArchive's read path.
52 *
53 * ## Lattice reconstruction
54 *
55 * A .vdb carries a transform and, per grid, an active-voxel bounding box —
56 * not a resolution and world bounds the way Lattice3D wants. VolumeData
57 * needs one lattice shared by every field, so this reader offers two ways
58 * to get one:
59 *
60 * - extract()/load() with no lattice: the output lattice is the union of
61 * every selected grid's active bbox, in voxel-index space, with voxel
62 * size and translation taken from the first selected grid's transform.
63 * This is what a DCC user expects — the file's own content decides the
64 * size — and is exact when every grid in the file shares one transform,
65 * which every file MayaFlux writes does and most single-purpose exports
66 * from another DCC do too.
67 * - extract()/load() with a caller-supplied Lattice3D: region_min is
68 * derived from the lattice's world bounds through the *first selected
69 * grid's* transform, snapped to the nearest voxel index — no
70 * interpolation. This is the only path that round-trips exactly: pass
71 * the same Lattice3D a VDBWriter call was given and the cell values come
72 * back unpermuted and unresampled, which is what verify_volume_export's
73 * round-trip check exercises.
74 *
75 * Both paths assume every selected grid shares the first grid's voxel size
76 * and translation. A file with per-grid transforms that actually differ is
77 * not resampled into agreement — each grid's raw voxel indices are read
78 * directly against the shared region, which misplaces that grid's content
79 * relative to the others. materialize() logs an MF_WARN naming the
80 * mismatched grid so this is a loud failure rather than a silent one, but
81 * it does not correct it — actual per-grid resampling would need to
82 * materialize the mismatched grid separately in its own index space and
83 * interpolate into the shared lattice, which is not implemented. This is a
84 * real limitation for a file assembled by hand from mismatched sources; it
85 * is not a limitation for output produced by a single simulation or DCC
86 * export, which is what this reader exists to consume.
87 *
88 * ## Inactive cells
89 *
90 * VolumeData is dense: every cell in the output lattice that is not covered
91 * by an active leaf takes the grid's own background value (root.background
92 * in exchange), narrowed the same way an active cell's value is if the
93 * grid's own type needs it — see below. This means a sparse simulation
94 * export expands to full density in host memory: six fields at 256 cubed
95 * is roughly 400 MB, before whatever the caller does with it next. A tile
96 * whose inactive fill differs from the plain background — a level set's
97 * sign-flood-filled interior/exterior tiles are the standard example — is
98 * not reconstructed; every non-leaf cell reads as the one background value
99 * regardless of which side of the surface it is on. A foreign narrow-band
100 * level set is therefore the case most likely to come back wrong; a fog
101 * volume or a carried scalar, where every non-leaf cell genuinely is the
102 * background, round-trips correctly.
103 *
104 * ## Type narrowing
105 *
106 * VolumeData's variant holds float and glm::vec3 only. A grid whose leaf
107 * value type is double, int32, int64, bool or half is narrowed to float; a
108 * vec3d or vec3i grid is narrowed to glm::vec3, via MayaFlux::try_convert
109 * per element (per component, for vectors). This is logged once per grid
110 * at MF_WARN, distinguishing a narrowing that round-tripped every element
111 * exactly from one where at least one element actually lost precision —
112 * the common case for a double or int64 grid whose range exceeds float,
113 * uncommon for a value meant to feed a float GPU field in the first place,
114 * which is the purpose this reader is built for. Accepted as the cost of a
115 * single representable type rather than widening VolumeData to carry every
116 * tinyvdb value type.
117 */
118class MAYAFLUX_API VolumeReader : public FileReader {
119public:
120 VolumeReader();
121 ~VolumeReader() override;
122
123 // -------------------------------------------------------------------------
124 // Primary API — use these
125 // -------------------------------------------------------------------------
126
127 /**
128 * @brief Load every selected grid from a file in one call.
129 *
130 * Opens, reads, extracts and closes in a single synchronous operation.
131 * The output lattice is the union of active bboxes; see the class docs.
132 *
133 * @param filepath Path to the .vdb file.
134 * @param options Grid selection.
135 * @return Populated VolumeData, or nullopt on failure; check
136 * get_last_error().
137 */
138 [[nodiscard]] std::optional<Kakshya::VolumeData> load(
139 const std::string& filepath, const VolumeReadOptions& options = {});
140
141 /**
142 * @brief Load every selected grid onto a caller-supplied lattice.
143 *
144 * As load(), but the output lattice is @p lattice rather than derived
145 * from the file. The only path that round-trips a write exactly; see
146 * the class docs.
147 *
148 * @param filepath Path to the .vdb file.
149 * @param lattice Output lattice. Its resolution and bounds are used
150 * as given; nothing about it is validated against the
151 * file's own transform.
152 * @param options Grid selection.
153 * @return Populated VolumeData, or nullopt on failure; check
154 * get_last_error().
155 */
156 [[nodiscard]] std::optional<Kakshya::VolumeData> load(
157 const std::string& filepath,
158 const Kinesis::Lattice3D& lattice,
159 const VolumeReadOptions& options = {});
160
161 /**
162 * @brief Extract every selected grid after open() has already been called.
163 *
164 * As load(), but reads the currently open file rather than opening one.
165 * Does not call close().
166 *
167 * @param options Grid selection.
168 * @return Populated VolumeData, or nullopt if no file is open or on
169 * failure; check get_last_error().
170 */
171 [[nodiscard]] std::optional<Kakshya::VolumeData> extract(
172 const VolumeReadOptions& options = {}) const;
173
174 /**
175 * @brief Extract every selected grid onto a caller-supplied lattice.
176 * @param lattice Output lattice, as in the load() overload.
177 * @param options Grid selection.
178 * @return Populated VolumeData, or nullopt if no file is open or on
179 * failure; check get_last_error().
180 */
181 [[nodiscard]] std::optional<Kakshya::VolumeData> extract(
182 const Kinesis::Lattice3D& lattice,
183 const VolumeReadOptions& options = {}) const;
184
185 // -------------------------------------------------------------------------
186 // FileReader interface
187 // -------------------------------------------------------------------------
188
189 [[nodiscard]] bool can_read(const std::string& filepath) const override;
190
191 bool open(const std::string& filepath,
192 FileReadOptions options = FileReadOptions::ALL) override;
193
194 void close() override;
195
196 [[nodiscard]] bool is_open() const override { return m_is_open; }
197
198 [[nodiscard]] std::optional<FileMetadata> get_metadata() const override;
199
200 [[nodiscard]] std::vector<FileRegion> get_regions() const override { return {}; }
201 std::vector<Kakshya::DataVariant> read_all() override { return {}; }
202 std::vector<Kakshya::DataVariant> read_region(const FileRegion& /*region*/) override { return {}; }
203
204 /**
205 * @brief No-op. Volume data does not use SignalSourceContainer.
206 * @return nullptr always.
207 */
208 std::shared_ptr<Kakshya::SignalSourceContainer> create_container() override;
209
210 /**
211 * @brief No-op. Volume data does not use SignalSourceContainer.
212 * @return false always.
213 */
214 bool load_into_container(
215 std::shared_ptr<Kakshya::SignalSourceContainer> container) override;
216
217 [[nodiscard]] std::vector<uint64_t> get_read_position() const override { return { 0 }; }
218 bool seek(const std::vector<uint64_t>& /*position*/) override { return true; }
219 [[nodiscard]] std::vector<std::string> get_supported_extensions() const override { return { ".vdb" }; }
220
221 [[nodiscard]] std::type_index get_data_type() const override
222 {
223 return typeid(std::vector<uint8_t>);
224 }
225
226 [[nodiscard]] std::type_index get_container_type() const override
227 {
228 return typeid(void);
229 }
230
231 [[nodiscard]] std::string get_last_error() const override { return m_last_error; }
232
233 [[nodiscard]] bool supports_streaming() const override { return false; }
234 [[nodiscard]] uint64_t get_preferred_chunk_size() const override { return 0; }
235 [[nodiscard]] size_t get_num_dimensions() const override { return 0; }
236 [[nodiscard]] std::vector<uint64_t> get_dimension_sizes() const override { return {}; }
237
238private:
239 std::unique_ptr<Detail::VDBArchive> m_archive;
240
241 bool m_is_open { false };
242 std::string m_filepath;
243 mutable std::string m_last_error;
244
245 /**
246 * @brief Build VolumeData from selected grids over an explicit region.
247 * @param indices Grid indices, in the order fields should appear.
248 * @param region_min Voxel-index origin, in the first grid's index space.
249 * @param lattice Output lattice. Its resolution drives every
250 * read_dense_scalar/read_dense_vector call.
251 * @return Populated VolumeData, or nullopt on failure.
252 */
253 [[nodiscard]] std::optional<Kakshya::VolumeData> materialize(
254 const std::vector<size_t>& indices,
255 const glm::ivec3& region_min,
256 const Kinesis::Lattice3D& lattice) const;
257
258 void set_error(std::string msg) const { m_last_error = std::move(msg); }
259};
260
261} // namespace MayaFlux::IO
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
RAII boundary around tinyvdb's C read and write paths.
Abstract interface for reading various file formats into containers.
bool is_open() const override
Check if a file is currently open.
std::vector< FileRegion > get_regions() const override
Get semantic regions from the file.
void set_error(std::string msg) const
std::vector< std::string > get_supported_extensions() const override
Get supported file extensions for this reader.
bool seek(const std::vector< uint64_t > &) override
Seek to a specific position in the file.
std::optional< Kakshya::VolumeData > materialize(const std::vector< size_t > &indices, const glm::ivec3 &region_min, const Kinesis::Lattice3D &lattice) const
Build VolumeData from selected grids over an explicit region.
std::unique_ptr< Detail::VDBArchive > m_archive
bool can_read(const std::string &filepath) const override
Check if a file can be read by this reader.
bool open(const std::string &filepath, FileReadOptions options=FileReadOptions::ALL) override
Open a file for reading.
bool supports_streaming() const override
Check if streaming is supported for the current file.
std::vector< Kakshya::DataVariant > read_region(const FileRegion &) override
Read a specific region of data.
size_t get_num_dimensions() const override
Get the dimensionality of the file data.
std::type_index get_data_type() const override
Get the data type this reader produces.
std::vector< uint64_t > get_read_position() const override
Get current read position in primary dimension.
uint64_t get_preferred_chunk_size() const override
Get the preferred chunk size for streaming.
std::string get_last_error() const override
Get the last error message.
std::type_index get_container_type() const override
Get the container type this reader creates.
std::vector< uint64_t > get_dimension_sizes() const override
Get size of each dimension in the file data.
std::optional< Kakshya::VolumeData > load(const std::string &filepath, const VolumeReadOptions &options={})
Load every selected grid from a file in one call.
void close() override
Close the currently open file.
std::optional< Kakshya::VolumeData > extract(const VolumeReadOptions &options={}) const
Extract every selected grid after open() has already been called.
std::vector< Kakshya::DataVariant > read_all() override
Read all data from the file into memory.
FileReadOptions
Generic options for file reading behavior.
@ ALL
All options enabled.
auto create_container(Args &&... args) -> std::shared_ptr< ContainerType >
creates a new container of the specified type
Definition Depot.hpp:67
Generic region descriptor for any file type.
uint64_t grid_count
Number of grids in the archive.
Grid count of an OpenVDB archive.
std::vector< std::string > field_names
Grids to load, matched by name.
Configuration for volume reading.
A regular subdivision of an AABB3D into a cell count per axis.
Definition Lattice.hpp:25