MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Extractor.hpp
Go to the documentation of this file.
1#pragma once
2
5
6/**
7 * @file Extractor.hpp
8 * @brief Modern, digital-first extractor framework for Maya Flux
9 *
10 * The Extractor system provides a clean, extensible foundation for data extraction
11 * in the Maya Flux ecosystem. Unlike traditional feature extractors, this focuses on
12 * digital-first paradigms: data-driven workflows, composability, and type safety.
13 *
14 * ## Core Philosophy
15 * An extractor **gives the user a specified ComputeData** through two main pathways:
16 * 1. **Direct extraction:** Using convert_data/extract from DataUtils
17 * 2. **Copy extraction:** Copy data via extract in DataUtils
18 *
19 * Concrete extractors can optionally integrate with analyzers when they need to extract
20 * regions/features identified by analysis.
21 *
22 * ## Key Features
23 * - **Flexible input/output:** Template-based I/O types defined at instantiation
24 * - **Type-safe extraction:** C++20 concepts and compile-time guarantees
25 * - **Extraction strategies:** Direct, region-based, feature-guided, recursive
26 * - **Composable operations:** Integrates with ComputeMatrix execution modes
27 * - **Digital-first design:** Embraces computational possibilities beyond analog metaphors
28 *
29 * ## Usage Examples
30 * ```cpp
31 * // Extract specific data type from DataVariant
32 * auto extractor = std::make_shared<MyExtractor<Kakshya::DataVariant, std::vector<double>>>();
33 *
34 * // Extract matrix from container
35 * auto matrix_extractor = std::make_shared<MyExtractor<
36 * std::shared_ptr<Kakshya::SignalSourceContainer>,
37 * Eigen::MatrixXd>>();
38 * ```
39 */
40
41namespace MayaFlux::Yantra {
42
43/**
44 * @enum ExtractionType
45 * @brief Categories of extraction operations for discovery and organization
46 */
47enum class ExtractionType : uint8_t {
48 DIRECT, ///< Direct data type conversion/extraction
49 REGION_BASED, ///< Extract from spatial/temporal regions
50 FEATURE_GUIDED, ///< Extract based on feature analysis
51 PATTERN_BASED, ///< Extract based on pattern recognition
52 TRANSFORM, ///< Mathematical transformation during extraction
53 RECURSIVE, ///< Recursive/nested extraction
54 CUSTOM ///< User-defined extraction types
55};
56
57/**
58 * @enum ExtractionScope
59 * @brief Scope control for extraction operations
60 */
61enum class ExtractionScope : uint8_t {
62 FULL_DATA, ///< Extract all available data
63 TARGETED_REGIONS, ///< Extract only specific regions
64 FILTERED_CONTENT, ///< Extract content meeting criteria
65 SAMPLED_DATA ///< Extract sampled/downsampled data
66};
67
68/**
69 * @struct ExtractorConfig
70 * @brief Settings every extractor family accepts.
71 *
72 * Each family's config struct inherits these fields and adds its own method field,
73 * typed by its own enum.
74 */
76 /** Portion of the input to extract from. */
78};
79
80MF_DESCRIBE(ExtractorConfig)
81
82/**
83 * @class Extractor
84 * @brief Template-flexible extractor base with instance-defined I/O types
85 *
86 * The Extractor provides a clean, concept-based foundation for all extraction
87 * operations. I/O types are defined at instantiation time, providing maximum flexibility
88 * while maintaining type safety through C++20 concepts.
89 *
90 * Key Features:
91 * - Instance-defined I/O types via template parameters
92 * - Concept-constrained data types for compile-time safety
93 * - Extraction type categorization for discovery
94 * - Scope control for targeted extraction
95 * - Integration with ComputeMatrix execution modes
96 */
97template <ComputeData InputType = std::vector<Kakshya::DataVariant>, ComputeData OutputType = InputType>
98class Extractor : public ComputeOperation<InputType, OutputType> {
99public:
103
104 virtual ~Extractor() = default;
105
106 /**
107 * @brief Gets the extraction type category for this extractor
108 * @return ExtractionType enum value
109 */
110 [[nodiscard]] virtual ExtractionType get_extraction_type() const = 0;
111
112 /**
113 * @brief Gets human-readable name for this extractor
114 * @return String identifier for the extractor
115 */
116 [[nodiscard]] std::string get_name() const override
117 {
118 return get_extractor_name();
119 }
120
121 [[nodiscard]] OperationType get_operation_type() const override
122 {
124 }
125
126 [[nodiscard]] ConfigRefs configs() const override
127 {
129 }
130
131 /**
132 * @brief Type-safe extraction method
133 * @param data Input data
134 * @return Extracted data directly (no Datum wrapper)
135 */
136 OutputType extract_data(const input_type& data)
137 {
138 auto result = operation_function(data);
139 return result.data;
140 }
141
142 OutputType extract_data(const InputType& data)
143 {
144 return this->extract_data(input_type { data });
145 }
146
147 /**
148 * @brief Extract with specific scope, without changing the stored settings
149 * @param data Input data
150 * @param scope Extraction scope to use
151 * @return Extracted output data
152 */
153 OutputType extract_with_scope(const input_type& data, ExtractionScope scope)
154 {
155 auto raw_result = extract_implementation(data);
156 return apply_scope_filtering(raw_result, scope).data;
157 }
158
159 OutputType extract_with_scope(const InputType& data, ExtractionScope scope)
160 {
161 return this->extract_with_scope(input_type { data }, scope);
162 }
163
164 /**
165 * @brief Batch extraction for multiple inputs
166 * @param inputs Vector of input data
167 * @return Vector of extracted results
168 */
169 std::vector<OutputType> extract_batch(const std::vector<input_type>& inputs)
170 {
171 std::vector<OutputType> results;
172 results.reserve(inputs.size());
173
174 for (const auto& input : inputs) {
175 results.push_back(extract_data(input));
176 }
177
178 return results;
179 }
180
181 std::vector<OutputType> extract_batch(const std::vector<InputType>& inputs)
182 {
183 return this->extract_batch(as_io_batch(inputs));
184 }
185
186protected:
187 /**
188 * @brief Core operation implementation - called by ComputeOperation interface
189 * @param input Input data with metadata
190 * @return Output data with metadata
191 */
193 {
194 auto raw_result = extract_implementation(input);
195 return apply_scope_filtering(raw_result, extraction_scope());
196 }
197
198 /**
199 * @brief Pure virtual extraction implementation - derived classes implement this
200 * @param input Input data with metadata
201 * @return Raw extraction output before scope processing
202 */
204
205 /**
206 * @brief Get extractor-specific name (derived classes override this)
207 * @return Extractor name string
208 */
209 [[nodiscard]] virtual std::string get_extractor_name() const { return "Extractor"; }
210
211 /**
212 * @brief The scope the stored config selects; FULL_DATA unless a family overrides it.
213 */
214 [[nodiscard]] virtual ExtractionScope extraction_scope() const { return ExtractionScope::FULL_DATA; }
215
216 /**
217 * @brief Input validation (override for custom validation logic)
218 */
219 virtual bool validate_extraction_input(const input_type& /*input*/) const
220 {
221 // Default: accept any input that satisfies ComputeData concept
222 return true;
223 }
224
225 /**
226 * @brief Apply scope filtering to results
227 * @param raw_output Raw extraction results
228 * @param scope Scope to apply
229 * @return Filtered output based on scope
230 */
232 {
233 switch (scope) {
235 return raw_output;
236
238 return filter_to_target_regions(raw_output);
239
241 return apply_content_filtering(raw_output);
242
244 return apply_data_sampling(raw_output);
245
246 default:
247 return raw_output;
248 }
249 }
250
251 /**
252 * @brief Filter results to target regions (override for custom filtering)
253 * @param raw_output Raw extraction output
254 * @return Filtered output
255 */
257 {
258 return raw_output;
259 }
260
261 /**
262 * @brief Apply content-based filtering (override for custom filtering)
263 * @param raw_output Raw extraction output
264 * @return Content-filtered output
265 */
267 {
268 return raw_output;
269 }
270
271 /**
272 * @brief Apply data sampling (override for custom sampling)
273 * @param raw_output Raw extraction output
274 * @return Sampled output
275 */
276 virtual output_type apply_data_sampling(const output_type& raw_output)
277 {
278 return raw_output;
279 }
280};
281
282/// Extractor that takes DataVariant and produces any ComputeData type
283template <ComputeData OutputType = Kakshya::DataVariant>
285
286/// Extractor for signal container processing
287template <ComputeData OutputType = std::shared_ptr<Kakshya::SignalSourceContainer>>
289
290/// Extractor for region-based extraction
291template <ComputeData OutputType = Kakshya::Region>
293
294/// Extractor for region group processing
295template <ComputeData OutputType = Kakshya::RegionGroup>
297
298/// Extractor for segment processing
299template <ComputeData OutputType = std::vector<Kakshya::RegionSegment>>
301
302/// Extractor that produces Eigen matrices
303template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
305
306/// Extractor that produces Eigen vectors
307template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
309
310/// Extractor that produces numeric vectors
311template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
313
314} // namespace MayaFlux::Yantra
315#include "Extractor.describe.hpp"
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
ConfigRefs stored_configs(Supports< Configs... >) const
The stored configs among those listed, in listed order.
ComputeOperation()
Constructor with data type validation warnings.
virtual output_type extract_implementation(const input_type &input)=0
Pure virtual extraction implementation - derived classes implement this.
OutputType extract_data(const input_type &data)
Type-safe extraction method.
std::string get_name() const override
Gets human-readable name for this extractor.
virtual ~Extractor()=default
virtual output_type filter_to_target_regions(const output_type &raw_output)
Filter results to target regions (override for custom filtering).
OutputType extract_with_scope(const InputType &data, ExtractionScope scope)
virtual bool validate_extraction_input(const input_type &) const
Input validation (override for custom validation logic).
virtual output_type apply_scope_filtering(const output_type &raw_output, ExtractionScope scope)
Apply scope filtering to results.
virtual output_type apply_content_filtering(const output_type &raw_output)
Apply content-based filtering (override for custom filtering).
virtual ExtractionType get_extraction_type() const =0
Gets the extraction type category for this extractor.
virtual output_type apply_data_sampling(const output_type &raw_output)
Apply data sampling (override for custom sampling).
std::vector< OutputType > extract_batch(const std::vector< InputType > &inputs)
Datum< OutputType > output_type
std::vector< OutputType > extract_batch(const std::vector< input_type > &inputs)
Batch extraction for multiple inputs.
output_type operation_function(const input_type &input) override
Core operation implementation - called by ComputeOperation interface.
ConfigRefs configs() const override
The base view of the config structs this operation holds.
Datum< InputType > input_type
virtual std::string get_extractor_name() const
Get extractor-specific name (derived classes override this).
virtual ExtractionScope extraction_scope() const
The scope the stored config selects; FULL_DATA unless a family overrides it.
OperationType get_operation_type() const override
Returns the category of this operation for grammar and registry discovery.
OutputType extract_data(const InputType &data)
OutputType extract_with_scope(const input_type &data, ExtractionScope scope)
Extract with specific scope, without changing the stored settings.
ComputeOperation< InputType, OutputType > base_type
Template-flexible extractor base with instance-defined I/O types.
Definition Extractor.hpp:98
Extractor< std::shared_ptr< Kakshya::SignalSourceContainer >, OutputType > ContainerExtractor
Extractor for signal container processing.
@ CUSTOM
User-defined analysis types.
Definition Analyzer.hpp:41
@ TRANSFORM
Mathematical transformations.
Definition Analyzer.hpp:40
ExtractionType
Categories of extraction operations for discovery and organization.
Definition Extractor.hpp:47
@ RECURSIVE
Recursive/nested extraction.
Definition Extractor.hpp:53
@ DIRECT
Direct data type conversion/extraction.
Definition Extractor.hpp:48
@ FEATURE_GUIDED
Extract based on feature analysis.
Definition Extractor.hpp:50
@ PATTERN_BASED
Extract based on pattern recognition.
Definition Extractor.hpp:51
@ REGION_BASED
Extract from spatial/temporal regions.
Definition Extractor.hpp:49
Extractor< Kakshya::RegionGroup, OutputType > RegionGroupExtractor
Extractor for region group processing.
Extractor< std::vector< Kakshya::DataVariant >, OutputType > DataExtractor
Extractor that takes DataVariant and produces any ComputeData type.
Extractor< Kakshya::Region, OutputType > RegionExtractor
Extractor for region-based extraction.
OperationType
Operation categories for organization and discovery.
Extractor< InputType, std::vector< double > > NumericExtractor
Extractor that produces numeric vectors.
Extractor< InputType, Eigen::MatrixXd > MatrixExtractor
Extractor that produces Eigen matrices.
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
Extractor< std::vector< Kakshya::RegionSegment >, OutputType > SegmentExtractor
Extractor for segment processing.
ExtractionScope
Scope control for extraction operations.
Definition Extractor.hpp:61
@ SAMPLED_DATA
Extract sampled/downsampled data.
Definition Extractor.hpp:65
@ FULL_DATA
Extract all available data.
Definition Extractor.hpp:62
@ FILTERED_CONTENT
Extract content meeting criteria.
Definition Extractor.hpp:64
@ TARGETED_REGIONS
Extract only specific regions.
Definition Extractor.hpp:63
Extractor< InputType, Eigen::VectorXd > VectorExtractor
Extractor that produces Eigen vectors.
T data
The actual computation data.
Definition DataIO.hpp:64
Input/Output container for computation pipeline data flow with structure preservation.
Definition DataIO.hpp:63
ExtractionScope scope
Portion of the input to extract from.
Definition Extractor.hpp:77
Settings every extractor family accepts.
Definition Extractor.hpp:75
The config structs an operation class accepts, declared as using supports.