MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TensorContainer.hpp
Go to the documentation of this file.
1#pragma once
2
6
7namespace MayaFlux::Kakshya {
8
9/**
10 * @brief Key for a cached TensorData held by a RegionSegment.
11 */
13{
14 static const Facet<TensorData> key;
15 return key;
16}
17
18/**
19 * @class TensorContainer
20 * @brief Owns one tensor and serves N-dimensional regions of it.
21 *
22 * A Region is an inclusive box in the tensor's index space. Trailing axes the
23 * region does not name span their full extent. view() borrows the box as a
24 * strided TensorAccess without copying; the get_*_data calls copy boxes into
25 * independent dense tensors; set_region_data writes a tensor of the box's
26 * shape back in place.
27 *
28 * Specializes NDDataContainer<TensorData> directly, not SignalSourceContainer,
29 * so it carries no ProcessingState and no DataProcessor lifecycle. Frames are
30 * slices along the leading axis.
31 *
32 * Usage:
33 * @code
34 * auto weights = TensorData::from_values<float>(values, { 64, 3, 7, 7 }, "conv1");
35 * TensorContainer container(std::move(*weights));
36 * auto filter = container.view(Region({ 5 }, { 5 }));
37 * auto rows = container.get_region_data(Region({ 0, 0 }, { 9, 1 }));
38 * @endcode
39 *
40 * @note Views borrow the container's storage. Replacing the tensor through
41 * insert() or clear() invalidates them.
42 */
43class MAYAFLUX_API TensorContainer : public NDDataContainer<TensorData> {
44public:
45 ~TensorContainer() override;
46
47 /**
48 * @brief Take ownership of a tensor.
49 * @throws std::invalid_argument If the tensor holds no valid spec.
50 */
51 explicit TensorContainer(TensorData data);
52
53 /**
54 * @brief Allocate a zero-filled tensor for a spec.
55 * @throws std::invalid_argument If the spec is inconsistent or not host memory.
56 */
57 explicit TensorContainer(TensorSpec spec);
58
59 /** @brief Borrow the tensor. */
60 [[nodiscard]] const TensorData& get_data() const noexcept { return m_data; }
61
62 /** @brief Create an insertion adapter for the tensor. */
63 [[nodiscard]] TensorInsertion insert() noexcept { return TensorInsertion(m_data); }
64
65 /**
66 * @brief Borrow the whole tensor.
67 * @return Access view, or std::nullopt when the container holds nothing valid.
68 */
69 [[nodiscard]] std::optional<TensorAccess> view() const { return m_data.access(); }
70
71 /**
72 * @brief Borrow the box a Region selects, without copying.
73 * @param region Inclusive bounds; trailing axes not named span fully.
74 * @return Strided view, or std::nullopt when the region is empty, has more
75 * axes than the tensor, leaves the shape, or cannot be addressed.
76 */
77 [[nodiscard]] std::optional<TensorAccess> view(const Region& region) const;
78
79 /** @brief Describe the tensor's axes with their sizes and stride magnitudes. */
80 [[nodiscard]] std::vector<DataDimension> get_dimensions() const override;
81
82 /** @brief Number of elements in the tensor. */
83 [[nodiscard]] uint64_t get_total_elements() const override;
84
85 /** @brief Column-major when the strides are exactly Fortran order, otherwise row-major. */
86 [[nodiscard]] MemoryLayout get_memory_layout() const override;
87
88 /** @brief The layout is described by the tensor's strides and is not changed here. */
90
91 /** @brief Elements in one slice along the leading axis. */
92 [[nodiscard]] uint64_t get_frame_size() const override;
93
94 /** @brief Extent of the leading axis. */
95 [[nodiscard]] uint64_t get_num_frames() const override;
96
97 /**
98 * @brief Copy the box a Region selects into an owning dense tensor.
99 * @return One tensor, or empty when the region is invalid.
100 */
101 [[nodiscard]] std::vector<TensorData> get_region_data(const Region& region) const override;
102
103 /**
104 * @brief Copy the boxes of a group into separate tensors.
105 * @return One tensor per valid region; shorter than group.regions when a
106 * region is invalid.
107 */
108 [[nodiscard]] std::vector<TensorData> get_region_group_data(const RegionGroup& group) const override;
109
110 /**
111 * @brief Copy segments into separate tensors.
112 *
113 * A segment is the box that starts at offset_in_region inside its source
114 * region and spans segment_size per axis. A cached segment returns its
115 * cached tensor, stored under tensor_cache().
116 * @return One tensor per valid segment; malformed or out-of-bounds segments are skipped.
117 */
118 [[nodiscard]] std::vector<TensorData> get_segments_data(const std::vector<RegionSegment>& segments) const override;
119
120 /**
121 * @brief Overwrite the box a Region selects.
122 * @param region Destination box.
123 * @param data Exactly one tensor with the box's shape and the container's dtype.
124 * @note Anything else leaves the tensor unchanged.
125 */
126 void set_region_data(const Region& region, const std::vector<TensorData>& data) override;
127
128 /** @brief Store or replace a named region group. */
129 void add_region_group(const RegionGroup& group) override;
130
131 /** @brief Return a named region group, or an empty group if absent. */
132 [[nodiscard]] RegionGroup get_region_group(const std::string& name) const override;
133
134 /** @brief Copy all named region groups. */
135 [[nodiscard]] std::unordered_map<std::string, RegionGroup> get_all_region_groups() const override
136 {
137 return m_region_groups;
138 }
139
140 /** @brief Remove a named region group if present. */
141 void remove_region_group(const std::string& name) override;
142
143 /** @brief Whether the region selects a valid box. */
144 [[nodiscard]] bool is_region_loaded(const Region& region) const override;
145
146 /** @brief The tensor is resident. */
147 void load_region(const Region&) override { }
148
149 /** @brief The tensor stays resident until clear() is called. */
150 void unload_region(const Region&) override { }
151
152 /**
153 * @brief Row-major logical index of a coordinate, independent of strides.
154 * @return The index, or 0 when the coordinate has the wrong rank or leaves the shape.
155 */
156 [[nodiscard]] uint64_t coordinates_to_linear_index(const std::vector<uint64_t>& coordinates) const override;
157
158 /**
159 * @brief Coordinate of a row-major logical index.
160 * @return The coordinate, or empty when the index is past the last element.
161 */
162 [[nodiscard]] std::vector<uint64_t> linear_index_to_coordinates(uint64_t linear_index) const override;
163
164 /** @brief Become an empty tensor of the same dtype and name, and drop all region groups. */
165 void clear() override;
166
167 /** @brief Borrow element zero, or nullptr when empty. */
168 [[nodiscard]] const void* get_raw_data() const override;
169
170 /** @brief Whether the tensor contains any elements. */
171 [[nodiscard]] bool has_data() const override { return get_total_elements() > 0; }
172
173 /** @brief Mutable structure metadata. */
174 [[nodiscard]] ContainerDataStructure& get_structure() override { return m_structure; }
175
176 /** @brief Structure metadata. */
177 [[nodiscard]] const ContainerDataStructure& get_structure() const override { return m_structure; }
178
179 /** @brief Replace structure metadata. */
180 void set_structure(ContainerDataStructure structure) override { m_structure = std::move(structure); }
181
182private:
185 std::unordered_map<std::string, RegionGroup> m_region_groups;
186};
187
188}
Typed key for an arbitrary attribute stored in a Facets bag.
Definition Facets.hpp:26
Abstract interface for N-dimensional data containers.
void set_structure(ContainerDataStructure structure) override
Replace structure metadata.
const ContainerDataStructure & get_structure() const override
Structure metadata.
ContainerDataStructure & get_structure() override
Mutable structure metadata.
void set_memory_layout(MemoryLayout) override
The layout is described by the tensor's strides and is not changed here.
std::unordered_map< std::string, RegionGroup > m_region_groups
void unload_region(const Region &) override
The tensor stays resident until clear() is called.
std::unordered_map< std::string, RegionGroup > get_all_region_groups() const override
Copy all named region groups.
uint64_t get_total_elements() const override
Number of elements in the tensor.
TensorContainer(TensorData data)
Take ownership of a tensor.
TensorInsertion insert() noexcept
Create an insertion adapter for the tensor.
std::optional< TensorAccess > view() const
Borrow the whole tensor.
void load_region(const Region &) override
The tensor is resident.
bool has_data() const override
Whether the tensor contains any elements.
const TensorData & get_data() const noexcept
Borrow the tensor.
Owning host tensor: a TensorSpec and the bytes it describes.
Definition Tensor.hpp:42
Mutable adapter for writing into a TensorData.
const Facet< TensorData > & tensor_cache()
Key for a cached TensorData held by a RegionSegment.
void remove_region_group(std::unordered_map< std::string, RegionGroup > &groups, const std::string &name)
Remove a RegionGroup by name from a group map.
std::optional< RegionGroup > get_region_group(const std::unordered_map< std::string, RegionGroup > &groups, const std::string &name)
Get a RegionGroup by name from a group map.
@ TENSOR_ND
N-dimensional tensor.
Definition NDData.hpp:143
MemoryLayout
Memory layout for multi-dimensional data.
Definition NDData.hpp:33
@ INTERLEAVED
Single DataVariant with interleaved data (LRLRLR for stereo).
Definition NDData.hpp:44
void add_region_group(std::unordered_map< std::string, RegionGroup > &groups, const RegionGroup &group)
Add a RegionGroup to a group map.
Container structure for consistent dimension ordering.
Organizes related signal regions into a categorized collection.
Represents a point or span in N-dimensional space.
Definition Region.hpp:74
Complete description of a tensor: type, shape, layout, meaning.