MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TensorFormat.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "TensorReader.hpp"
4#include "TensorWriter.hpp"
5
6namespace MayaFlux::IO {
7
8/**
9 * @struct TensorFormat
10 * @brief Everything the registry needs to know about one tensor file format.
11 *
12 * probe inspects the leading bytes and the file size to recognise a format by
13 * content. Leave it empty when the format has no reliable signature (a zip
14 * container, a headerless dump) so it is chosen by extension or by name only.
15 */
17 std::string name;
18 std::vector<std::string> extensions;
19 std::function<bool(std::span<const std::byte> head, uint64_t file_size)> probe;
20 std::function<std::unique_ptr<TensorReader>()> make_reader;
21 std::function<std::unique_ptr<TensorWriter>()> make_writer;
22};
23
24/**
25 * @class TensorFormatRegistry
26 * @brief Registry that picks a tensor reader or writer by name, content or extension.
27 *
28 * Reading tries an explicit format name first, then content probes in
29 * registration order, then the file extension. Writing, where no file exists
30 * yet, tries the name and then the extension. A format is added by calling
31 * register_format(); nothing else needs to change.
32 *
33 * Usage:
34 * @code
35 * auto& registry = TensorFormatRegistry::instance();
36 * auto reader = registry.create_reader("weights.safetensors");
37 * auto writer = registry.create_writer("out.npz");
38 * @endcode
39 */
40class MAYAFLUX_API TensorFormatRegistry {
41public:
42 /** @brief The process-wide registry. */
44
45 /** @brief Add a format, replacing any earlier one with the same name. */
46 void register_format(TensorFormat format);
47
48 /** @brief Format with this name, or nullptr. */
49 [[nodiscard]] const TensorFormat* find(std::string_view name) const;
50
51 /** @brief Format recognised by content, then by extension, or nullptr. */
52 [[nodiscard]] const TensorFormat* detect(const std::string& filepath) const;
53
54 /**
55 * @brief New reader for a file.
56 * @param filepath Path to read.
57 * @param format Optional format name that overrides detection.
58 * @return Unopened reader, or nullptr when no format applies.
59 */
60 [[nodiscard]] std::unique_ptr<TensorReader> create_reader(
61 const std::string& filepath, std::string_view format = {}) const;
62
63 /**
64 * @brief New writer for a destination path.
65 * @param filepath Path to write.
66 * @param format Optional format name that overrides the extension.
67 * @return Writer, or nullptr when no writing format applies.
68 */
69 [[nodiscard]] std::unique_ptr<TensorWriter> create_writer(
70 const std::string& filepath, std::string_view format = {}) const;
71
72 /** @brief Names of all registered formats, in registration order. */
73 [[nodiscard]] std::vector<std::string> format_names() const;
74
75private:
76 [[nodiscard]] const TensorFormat* by_extension(const std::string& filepath, bool need_writer) const;
77
78 std::vector<TensorFormat> m_formats;
79};
80
81}
const TensorFormat * detect(const std::string &filepath) const
Format recognised by content, then by extension, or nullptr.
std::unique_ptr< TensorWriter > create_writer(const std::string &filepath, std::string_view format={}) const
New writer for a destination path.
static TensorFormatRegistry & instance()
The process-wide registry.
const TensorFormat * find(std::string_view name) const
Format with this name, or nullptr.
std::unique_ptr< TensorReader > create_reader(const std::string &filepath, std::string_view format={}) const
New reader for a file.
std::vector< TensorFormat > m_formats
const TensorFormat * by_extension(const std::string &filepath, bool need_writer) const
std::vector< std::string > format_names() const
Names of all registered formats, in registration order.
void register_format(TensorFormat format)
Add a format, replacing any earlier one with the same name.
Registry that picks a tensor reader or writer by name, content or extension.
std::vector< std::string > extensions
std::function< std::unique_ptr< TensorReader >()> make_reader
std::function< std::unique_ptr< TensorWriter >()> make_writer
std::function< bool(std::span< const std::byte > head, uint64_t file_size)> probe
Everything the registry needs to know about one tensor file format.