MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Analyzer.hpp
Go to the documentation of this file.
1#pragma once
2
5
6/**
7 * @file Analyzer.hpp
8 * @brief Modern, digital-first analyzer framework for Maya Flux
9 *
10 * This header defines the core analyzer abstractions for the Maya Flux ecosystem,
11 * enabling robust, type-safe, and extensible analysis pipelines for multi-dimensional
12 * data. The design is inspired by digital-first, data-driven conventions, avoiding
13 * analog metaphors and focusing on composability, introspection, and future-proof
14 * extensibility.
15 *
16 * Key Features:
17 * - **Unified input/output variants:** Supports raw data, containers, regions, and segments.
18 * - **Type-safe, concept-based analyzers:** Uses C++20 concepts and std::variant for strict type safety.
19 * - **Granularity control:** Flexible output granularity for raw values, attributed segments, or organized groups.
20 * - **Composable operations:** Integrates with ComputeMatrix and processing chains for scalable workflows.
21 * - **Parameterization and introspection:** Dynamic configuration and runtime method discovery.
22 *
23 * This abstraction is foundational for building advanced, maintainable, and scalable
24 * analysis architectures in digital-first, data-centric applications.
25 */
26
27namespace MayaFlux::Yantra {
28
29/**
30 * @enum AnalysisType
31 * @brief Categories of analysis operations for discovery and organization
32 */
33enum class AnalysisType : uint8_t {
34 STATISTICAL, ///< Mean, variance, distribution analysis
35 SPECTRAL, ///< FFT, frequency domain analysis
36 TEMPORAL, ///< Time-based patterns, onset detection
37 SPATIAL, ///< Multi-dimensional geometric analysis
38 FEATURE, ///< Feature extraction and characterization
39 PATTERN, ///< Pattern recognition and matching
40 TRANSFORM, ///< Mathematical transformations
41 CUSTOM ///< User-defined analysis types
42};
43
44/**
45 * @enum AnalysisGranularity
46 * @brief Output granularity control for analysis results
47 */
48enum class AnalysisGranularity : uint8_t {
49 RAW_VALUES, ///< Direct analysis results
50 ATTRIBUTED_SEGMENTS, ///< Results with attribution
51 ORGANIZED_GROUPS, ///< Hierarchically organized results
52 SUMMARY_STATISTICS ///< Condensed statistical summaries
53};
54
55/**
56 * @struct AnalyzerConfig
57 * @brief Settings every analyzer family accepts.
58 *
59 * Stored whole, keyed by type, in the operation's facets. Each family's
60 * config struct inherits these fields and adds its own method field, typed by its own enum.
61 */
63 /** Analysis window length in samples. */
64 uint32_t window_size { 256 };
65 /** Distance between successive windows in samples. */
66 uint32_t hop_size { 128 };
67 /** Level at which the analyzer processes input. */
69 /** Whether to classify energy or value levels. */
70 bool classification_enabled { false };
71};
72
73MF_DESCRIBE(AnalyzerConfig)
74
75/**
76 * @class Analyzer
77 * @brief Template-flexible analyzer base with instance-defined I/O types
78 *
79 * The Analyzer provides a clean, concept-based foundation for all analysis
80 * operations. Unlike the old approach, the I/O types are defined at instantiation
81 * time rather than at the class definition level, providing maximum flexibility.
82 *
83 * Key Features:
84 * - Instance-defined I/O types via template parameters
85 * - Concept-constrained data types for compile-time safety
86 * - Analysis type categorization for discovery
87 * - Granularity control for output formatting
88 * - Parameter management with type safety
89 * - Integration with ComputeMatrix execution modes
90 *
91 * Usage:
92 * ```cpp
93 * // Create analyzer for DataVariant -> Eigen::VectorXd
94 * auto analyzer = std::make_shared<MyAnalyzer<std::vector<Kakshya::DataVariant>, Eigen::VectorXd>>();
95 *
96 * // Or for Region -> RegionGroup
97 * auto region_analyzer = std::make_shared<MyAnalyzer<Kakshya::Region, Kakshya::RegionGroup>>();
98 * ```
99 */
100template <ComputeData InputType = std::vector<Kakshya::DataVariant>, ComputeData OutputType = InputType>
101class Analyzer : public ComputeOperation<InputType, OutputType> {
102public:
106
107 virtual ~Analyzer() = default;
108
109 /**
110 * @brief Gets the analysis type category for this analyzer
111 * @return AnalysisType enum value
112 */
113 [[nodiscard]] virtual AnalysisType get_analysis_type() const = 0;
114
115 [[nodiscard]] OperationType get_operation_type() const override
116 {
118 }
119
120 [[nodiscard]] ConfigRefs configs() const override
121 {
123 }
124
125 /**
126 * @brief Validates input data meets analyzer requirements
127 */
128 bool validate_input(const input_type& input) const override
129 {
130 return validate_analysis_input(input);
131 }
132
133 /**
134 * @brief User-facing analysis method - returns analysis results directly
135 * @param data Raw input data
136 * @return Analysis results as std::any
137 */
138 std::any analyze_data(const input_type& data)
139 {
140 m_current_output = this->apply_operation(data);
141 return m_current_analysis;
142 }
143
144 std::any analyze_data(const InputType& data)
145 {
146 return this->analyze_data(input_type { data });
147 }
148
149 /**
150 * @brief Batch analysis for multiple inputs
151 * @param inputs Vector of input data
152 * @return Vector of analysis results as std::any
153 */
154 std::vector<std::any> analyze_batch(const std::vector<input_type>& inputs)
155 {
156 std::vector<std::any> analyses;
157 analyses.reserve(inputs.size());
158
159 for (const auto& input : inputs) {
160 analyses.push_back(analyze_data(input));
161 }
162
163 return analyses;
164 }
165
166 std::vector<std::any> analyze_batch(const std::vector<InputType>& inputs)
167 {
168 return this->analyze_batch(as_io_batch(inputs));
169 }
170
171 /**
172 * @brief Access cached analysis from last operation
173 * @return Current analysis result as std::any
174 */
175 std::any get_current_analysis() const
176 {
177 return m_current_analysis;
178 }
179
180 /**
181 * @brief Check if analysis has been performed
182 * @return True if analysis result is available
183 */
185 {
186 return m_current_analysis.has_value();
187 }
188
189protected:
190 /**
191 * @brief Core analysis implementation - must be overridden by derived classes
192 * @param input Input data wrapped in Datum container
193 * @return Analysis results wrapped in Datum container
194 *
195 * This is where the actual analysis logic goes. The method receives data
196 * in an Datum wrapper which may contain metadata, and should return results
197 * in the same wrapper format.
198 */
200 {
201 auto raw_result = analyze_implementation(input);
202 return apply_granularity_formatting(raw_result);
203 }
204
205 /**
206 * @brief Pure virtual analysis implementation - derived classes implement this
207 * @param input Input data with metadata
208 * @return Raw analysis output before granularity formatting
209 */
211
212 /**
213 * @brief Input validation (override for custom validation logic)
214 */
215 virtual bool validate_analysis_input(const input_type& /*input*/) const
216 {
217 // Default: accept any input that satisfies ComputeData concept
218 return true;
219 }
220
221 /**
222 * @brief Output formatting by granularity (override for custom formatting)
223 * @param raw_output Raw analysis results
224 * @return The output unchanged by default
225 */
227 {
228 return raw_output;
229 }
230
231 mutable std::any m_current_analysis;
232
233 template <typename AnalysisResultType>
234 void store_current_analysis(AnalysisResultType&& result) const
235 {
236 m_current_analysis = std::forward<AnalysisResultType>(result);
237 }
238
239 std::optional<output_type> m_current_output;
240};
241
242/// Analyzer that takes DataVariant and produces DataVariant
243template <ComputeData OutputType = std::vector<Kakshya::DataVariant>>
245
246/// Analyzer for signal container processing
247template <ComputeData OutputType = std::shared_ptr<Kakshya::SignalSourceContainer>>
249
250/// Analyzer for region-based analysis
251template <ComputeData OutputType = Kakshya::Region>
253
254/// Analyzer for region group processing
255template <ComputeData OutputType = Kakshya::RegionGroup>
257
258/// Analyzer for segment processing
259template <ComputeData OutputType = std::vector<Kakshya::RegionSegment>>
261
262/// Analyzer that produces Eigen matrices
263template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
265
266/// Analyzer that produces Eigen vectors
267template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
269
270} // namespace MayaFlux::Yantra
271#include "Analyzer.describe.hpp"
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
void store_current_analysis(AnalysisResultType &&result) const
Definition Analyzer.hpp:234
output_type operation_function(const input_type &input) override
Core analysis implementation - must be overridden by derived classes.
Definition Analyzer.hpp:199
std::vector< std::any > analyze_batch(const std::vector< input_type > &inputs)
Batch analysis for multiple inputs.
Definition Analyzer.hpp:154
std::any get_current_analysis() const
Access cached analysis from last operation.
Definition Analyzer.hpp:175
virtual bool validate_analysis_input(const input_type &) const
Input validation (override for custom validation logic).
Definition Analyzer.hpp:215
virtual output_type analyze_implementation(const input_type &input)=0
Pure virtual analysis implementation - derived classes implement this.
ComputeOperation< InputType, OutputType > base_type
Definition Analyzer.hpp:105
std::any analyze_data(const input_type &data)
User-facing analysis method - returns analysis results directly.
Definition Analyzer.hpp:138
std::any analyze_data(const InputType &data)
Definition Analyzer.hpp:144
virtual output_type apply_granularity_formatting(const output_type &raw_output)
Output formatting by granularity (override for custom formatting).
Definition Analyzer.hpp:226
bool validate_input(const input_type &input) const override
Validates input data meets analyzer requirements.
Definition Analyzer.hpp:128
bool has_current_analysis() const
Check if analysis has been performed.
Definition Analyzer.hpp:184
Datum< OutputType > output_type
Definition Analyzer.hpp:104
virtual AnalysisType get_analysis_type() const =0
Gets the analysis type category for this analyzer.
ConfigRefs configs() const override
The base view of the config structs this operation holds.
Definition Analyzer.hpp:120
Datum< InputType > input_type
Definition Analyzer.hpp:103
virtual ~Analyzer()=default
std::vector< std::any > analyze_batch(const std::vector< InputType > &inputs)
Definition Analyzer.hpp:166
OperationType get_operation_type() const override
Returns the category of this operation for grammar and registry discovery.
Definition Analyzer.hpp:115
Template-flexible analyzer base with instance-defined I/O types.
Definition Analyzer.hpp:101
output_type apply_operation(const input_type &input)
Public synchronous execution interface.
ConfigRefs stored_configs(Supports< Configs... >) const
The stored configs among those listed, in listed order.
ComputeOperation()
Constructor with data type validation warnings.
AnalysisType
Categories of analysis operations for discovery and organization.
Definition Analyzer.hpp:33
@ PATTERN
Pattern recognition and matching.
Definition Analyzer.hpp:39
@ 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
@ FEATURE
Feature extraction and characterization.
Definition Analyzer.hpp:38
@ TRANSFORM
Mathematical transformations.
Definition Analyzer.hpp:40
@ STATISTICAL
Mean, variance, distribution analysis.
Definition Analyzer.hpp:34
@ SPECTRAL
Spectral energy (FFT-based).
Analyzer< InputType, Eigen::MatrixXd > MatrixAnalyzer
Analyzer that produces Eigen matrices.
Definition Analyzer.hpp:264
Analyzer< Kakshya::Region, OutputType > RegionAnalyzer
Analyzer for region-based analysis.
Definition Analyzer.hpp:252
OperationType
Operation categories for organization and discovery.
Analyzer< Kakshya::RegionGroup, OutputType > RegionGroupAnalyzer
Analyzer for region group processing.
Definition Analyzer.hpp:256
Analyzer< std::vector< Kakshya::RegionSegment >, OutputType > SegmentAnalyzer
Analyzer for segment processing.
Definition Analyzer.hpp:260
AnalysisGranularity
Output granularity control for analysis results.
Definition Analyzer.hpp:48
@ SUMMARY_STATISTICS
Condensed statistical summaries.
Definition Analyzer.hpp:52
@ ATTRIBUTED_SEGMENTS
Results with attribution.
Definition Analyzer.hpp:50
@ ORGANIZED_GROUPS
Hierarchically organized results.
Definition Analyzer.hpp:51
@ RAW_VALUES
Direct analysis results.
Definition Analyzer.hpp:49
Analyzer< InputType, Eigen::VectorXd > VectorAnalyzer
Analyzer that produces Eigen vectors.
Definition Analyzer.hpp:268
Analyzer< std::vector< Kakshya::DataVariant >, OutputType > DataAnalyzer
Analyzer that takes DataVariant and produces DataVariant.
Definition Analyzer.hpp:244
Analyzer< std::shared_ptr< Kakshya::SignalSourceContainer >, OutputType > ContainerAnalyzer
Analyzer for signal container processing.
Definition Analyzer.hpp:248
std::vector< std::reference_wrapper< const OperationConfig > > ConfigRefs
Borrowed views of the configs an operation holds.
std::vector< Datum< T > > as_io_batch(const std::vector< T > &inputs)
Convert a vector of raw values into a vector of Datum wrappers.
Definition DataIO.hpp:430
AnalysisGranularity granularity
Level at which the analyzer processes input.
Definition Analyzer.hpp:68
bool classification_enabled
Whether to classify energy or value levels.
Definition Analyzer.hpp:70
uint32_t window_size
Analysis window length in samples.
Definition Analyzer.hpp:64
uint32_t hop_size
Distance between successive windows in samples.
Definition Analyzer.hpp:66
Settings every analyzer family accepts.
Definition Analyzer.hpp:62
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.