MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Transformer.hpp
Go to the documentation of this file.
1#pragma once
2
6
8
9/**
10 * @file Transformer.hpp
11 * @brief Base for transformers. Settings are held in a config struct per family.
12 *
13 * Each family's config extends TransformerConfig and is described with
14 * MF_DESCRIBE, which includes the inherited settings. The config is set through
15 * set_config and read through config().
16 */
17
18namespace MayaFlux::Yantra {
19
20/**
21 * @enum TransformationType
22 * @brief Categories of transformation for discovery and organization
23 */
24enum class TransformationType : uint8_t {
25 TEMPORAL, ///< Time-based transformations (time-stretch, reverse, delay)
26 SPECTRAL, ///< Frequency domain transformations (pitch-shift, spectral filtering)
27 MATHEMATICAL, ///< Mathematical transformations (polynomial mapping, matrix operations)
28 CROSS_MODAL, ///< Cross-modality transformations (audio-to-visual, pattern translation)
29 GENERATIVE, ///< AI/ML-driven or algorithmic generation-based transformations
30 SPATIAL, ///< Multi-dimensional spatial transformations
31 PATTERN_BASED, ///< Pattern recognition and transformation
32 RECURSIVE, ///< Recursive/fractal transformations
33 GRANULAR, ///< Granular synthesis and micro-temporal transformations
34 CONVOLUTION, ///< Convolution-based transformations (impulse response, filters)
35 CUSTOM ///< User-defined transformation types
36};
37
38/**
39 * @enum TransformationStrategy
40 * @brief How a transformer handles its input
41 */
42enum class TransformationStrategy : uint8_t {
43 IN_PLACE, ///< Transform data in-place (modifies input)
44 BUFFERED, ///< Create transformed copy (preserves input)
45 STREAMING, ///< Stream-based transformation for large data
46 INCREMENTAL, ///< Progressive transformation with intermediate results
47 LAZY, ///< Lazy evaluation transformation (future: coroutines)
48 CHUNKED, ///< Transform in chunks for efficient processing
49 PARALLEL, ///< Parallel/concurrent transformation
50 RECURSIVE ///< Recursive transformation with feedback
51};
52
53/**
54 * @enum TransformationQuality
55 * @brief Quality level requested from a transformer
56 */
57enum class TransformationQuality : uint8_t {
58 DRAFT, ///< Fast, low-quality transformation for previews
59 STANDARD, ///< Balanced quality/performance for real-time use
60 HIGH_QUALITY, ///< High-quality transformation, may be slower
61 REFERENCE, ///< Maximum quality, computational cost is secondary
62 ADAPTIVE ///< Quality adapts based on available computational resources
63};
64
65/**
66 * @enum TransformationScope
67 * @brief Portion of the data a transformer processes
68 */
69enum class TransformationScope : uint8_t {
70 FULL_DATA, ///< Transform entire data set
71 TARGETED_REGIONS, ///< Transform only specific regions
72 SELECTIVE_BANDS, ///< Transform specific frequency/spatial bands
73 CONDITIONAL ///< Transform based on dynamic conditions
74};
75
76/**
77 * @struct TransformerConfig
78 * @brief Settings every transformer family accepts.
79 *
80 * Family configs extend this struct and add their own fields.
81 */
83 /** How the input is handled. */
85 /** Requested quality level. */
87 /** Portion of the data processed. */
89 /** Amount of transformation, 0.0 to 2.0. */
90 double intensity { 1.0 };
91};
92
93MF_DESCRIBE(TransformerConfig)
94
95/**
96 * @class Transformer
97 * @brief Base of every transformer family.
98 *
99 * Holds no settings of its own. Derived classes read their family config through config().
100 */
101template <ComputeData InputType = Kakshya::DataVariant, ComputeData OutputType = InputType>
102class Transformer : public ComputeOperation<InputType, OutputType> {
103public:
107
108 virtual ~Transformer() = default;
109
110 /**
111 * @brief Gets the transformation type category for this transformer
112 * @return TransformationType enum value
113 */
114 [[nodiscard]] virtual TransformationType get_transformation_type() const = 0;
115
116 [[nodiscard]] std::string get_name() const override
117 {
118 return get_transformer_name();
119 }
120
121 [[nodiscard]] OperationType get_operation_type() const override
122 {
124 }
125
126 /**
127 * @brief The stored transformer settings, empty when none were set.
128 */
129 [[nodiscard]] ConfigRefs configs() const override
130 {
132 }
133
134 [[nodiscard]] bool is_in_place() const
135 {
136 const auto stored = configs();
137 return !stored.empty()
138 && static_cast<const TransformerConfig&>(stored.front().get()).strategy == TransformationStrategy::IN_PLACE;
139 }
140
141protected:
143 {
144 if (!validate_input(input)) {
145 MF_WARN(
148 "{}: input failed validation, passing it through unchanged",
150 return create_safe_output(input);
151 }
152 auto raw_result = transform_implementation(const_cast<input_type&>(input));
153 return apply_scope_and_quality_processing(raw_result);
154 }
155
157
158 [[nodiscard]] virtual std::string get_transformer_name() const { return "Transformer"; }
159
161 {
162 return result;
163 }
164
165 bool validate_input(const input_type& input) const override
166 {
167 if constexpr (RequiresContainer<InputType>) {
168 const auto source = input.get_container();
169 if (!source) {
170 return false;
171 }
172 auto numeric_data = OperationHelper::extract_numeric_data(input.data, source);
173 return validate_multi_channel_data(numeric_data);
174 } else {
175 auto numeric_data = OperationHelper::extract_numeric_data(input.data);
176 return validate_multi_channel_data(numeric_data);
177 }
178 }
179
180private:
182 {
183 output_type result;
184 result.dimensions = input.dimensions;
185 result.modality = input.modality;
186 result.metadata = input.metadata;
187 result.facets = input.facets;
188
189 if constexpr (std::is_same_v<InputType, OutputType>) {
190 result.data = input.data;
191 } else {
192 result.data = {};
193 }
194 return result;
195 }
196
197 [[nodiscard]] bool validate_multi_channel_data(const std::vector<std::span<double>>& channels) const
198 {
199 if (channels.empty()) {
200 return false;
201 }
202 for (const auto& channel : channels) {
203 if (channel.empty()) {
204 continue;
205 }
206 for (double sample : channel) {
207 if (std::isnan(sample)) {
208 return false;
209 }
210 if (std::isinf(sample)) {
211 return false;
212 }
213 }
214 }
215 return true;
216 }
217};
218
219}
#define MF_WARN(comp, ctx,...)
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
static NumericChannels extract_numeric_data(const T &compute_data)
extract numeric data from single-variant types
ComputeOperation< InputType, OutputType > base_type
virtual output_type apply_scope_and_quality_processing(const output_type &result)
bool validate_multi_channel_data(const std::vector< std::span< double > > &channels) const
virtual ~Transformer()=default
virtual std::string get_transformer_name() const
OperationType get_operation_type() const override
Returns the category of this operation for grammar and registry discovery.
std::string get_name() const override
Get operation name for debugging/introspection.
Datum< OutputType > output_type
virtual TransformationType get_transformation_type() const =0
Gets the transformation type category for this transformer.
virtual output_type transform_implementation(input_type &input)=0
ConfigRefs configs() const override
The stored transformer settings, empty when none were set.
bool validate_input(const input_type &input) const override
Validates if the input data meets the operation's requirements.
output_type operation_function(const input_type &input) override
Executes the computational transformation on the input data.
Datum< InputType > input_type
output_type create_safe_output(const input_type &input) const
Base of every transformer family.
Types that need an associated SignalSourceContainer to extract data.
Definition DataSpec.hpp:118
@ BufferProcessing
Buffer processing (Buffers::BufferManager, processing chains).
@ Yantra
DSP algorithms, computational units, matrix operations, Grammar.
@ TEMPORAL
Time-based patterns, onset detection.
Definition Analyzer.hpp:36
@ CUSTOM
User-defined analysis types.
Definition Analyzer.hpp:41
@ SPATIAL
Multi-dimensional geometric analysis.
Definition Analyzer.hpp:37
@ SPECTRAL
Spectral energy (FFT-based).
@ RECURSIVE
Recursive/nested extraction.
Definition Extractor.hpp:53
@ PATTERN_BASED
Extract based on pattern recognition.
Definition Extractor.hpp:51
TransformationScope
Portion of the data a transformer processes.
@ SELECTIVE_BANDS
Transform specific frequency/spatial bands.
@ CONDITIONAL
Transform based on dynamic conditions.
@ FULL_DATA
Transform entire data set.
TransformationQuality
Quality level requested from a transformer.
@ HIGH_QUALITY
High-quality transformation, may be slower.
@ DRAFT
Fast, low-quality transformation for previews.
@ ADAPTIVE
Quality adapts based on available computational resources.
@ STANDARD
Balanced quality/performance for real-time use.
@ REFERENCE
Maximum quality, computational cost is secondary.
OperationType
Operation categories for organization and discovery.
@ IN_PLACE
Sort data in-place (modifies input).
Definition Sorter.hpp:72
@ CROSS_MODAL
Sort one modality by features of another.
Definition Sorter.hpp:62
@ STANDARD
Traditional comparison-based sorting.
Definition Sorter.hpp:56
@ PARALLEL
Parallel with other operations.
std::vector< std::reference_wrapper< const OperationConfig > > ConfigRefs
Borrowed views of the configs an operation holds.
TransformationType
Categories of transformation for discovery and organization.
@ GENERATIVE
AI/ML-driven or algorithmic generation-based transformations.
@ GRANULAR
Granular synthesis and micro-temporal transformations.
@ MATHEMATICAL
Mathematical transformations (polynomial mapping, matrix operations).
@ CONVOLUTION
Convolution-based transformations (impulse response, filters).
TransformationStrategy
How a transformer handles its input.
@ BUFFERED
Create transformed copy (preserves input).
@ LAZY
Lazy evaluation transformation (future: coroutines).
@ CHUNKED
Transform in chunks for efficient processing.
@ INCREMENTAL
Progressive transformation with intermediate results.
@ IN_PLACE
Transform data in-place (modifies input).
@ STREAMING
Stream-based transformation for large data.
@ FULL_DATA
Extract all available data.
Definition Extractor.hpp:62
@ TARGETED_REGIONS
Extract only specific regions.
Definition Extractor.hpp:63
std::shared_ptr< container_family_t< C > > get_container() const
The associated container of one family.
Definition DataIO.hpp:223
T data
The actual computation data.
Definition DataIO.hpp:64
std::vector< Kakshya::DataDimension > dimensions
Data dimensional structure.
Definition DataIO.hpp:65
Kakshya::DataModality modality
Data modality (audio, image, spectral, etc.).
Definition DataIO.hpp:66
Facets facets
Typed results that travel with the data, read by type.
Definition DataIO.hpp:68
std::unordered_map< std::string, std::any > metadata
Associated metadata.
Definition DataIO.hpp:67
Input/Output container for computation pipeline data flow with structure preservation.
Definition DataIO.hpp:63
The config structs an operation class accepts, declared as using supports.
TransformationScope scope
Portion of the data processed.
TransformationQuality quality
Requested quality level.
TransformationStrategy strategy
How the input is handled.
double intensity
Amount of transformation, 0.0 to 2.0.
Settings every transformer family accepts.