EDGEAI API

feature_extract.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2025, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /*!****************************************************************************
33 * @file feature_extract.h
34 * @brief <b>PRELIMINARY</b> Feature Extraction for EdgeAI
35 *
36 * <b>WARNING</b> These set of functions are <b>PRELIMINARY</b>, and subject to
37 * change in the next few months.
38 *
39 * To use the Feature Extraction library, include this header file in the
40 * application as follows:
41
42 * @code
43 * #include <ti/ai/edge_ai/fe/feature_extract.h>
44 * @endcode
45 *
46 * @anchor ti_edgeai_feature_extract_Overview
47 * # Overview #
48 * This library will serve as a pre-processing stage where raw signal inputs
49 * will be fed to the feature extraction library and the resulting output will
50 * be fed into the pre-compiled NN model. The function that have been implemented
51 * so far are the following:
52 *
53 * - FE_applyWindow(): extracts windows of data based on a window size, stride size
54 * and an input stream.
55 *
56 * - FE_fftPool(): calculates the Real FFT magnitude for each window and average
57 * pool the resulting bins. The window undergoes a symmetrical modification first,
58 * doubling its size.
59 *
60 * - FE_kurtosis(): calculates the fisher or excess Kurtorsis for each segment of
61 * a given window, without bias (look for exact equation in the previous graph).
62 * Kurtosis describes the "peakedness" of a probability distribution.
63 *
64 * - FE_zeroCrossingRate(): calculates the zero crossing rate for each window. ZCR measures
65 * of how often a signal crosses the zero axis, indicating the frequency or noisiness
66 * of a signal.
67 *
68 * - FE_slopeChanges(): counts the sign changes of signal differences.
69 *
70 * - FE_topFrequencies(): calculates the top N dominant frequencies of a FFT result per window.
71 * The window doubles its size first, padded with zeros to the right.
72 *
73 * - FE_spectralEntropy(): calculates the Shannon spectral entropy of a FFT result per
74 * window. The window doubles its size first, padded with zeros to the right. The
75 * Spectral Entropy acts as an indicator of how spread out the power is across different
76 * frequencies.
77 *
78 * - FE_concatenateFeatures(): Concatenate many feature arrays into a big feature vector.
79 * The offsets are determined by NUM_FEAT_X and NUM_WINDOWS macros.
80 *
81 * <hr>
82 * # Usage
83 * To use the Feature Extraction Library call the previous APIs accordingly.
84 *
85 ******************************************************************************
86 */
87
88 #ifndef ti_edgeai_feature_extract__include
89 #define ti_edgeai_feature_extract__include
90
91 #ifdef __cplusplus
92 extern "C" {
93 #endif
94
95 #include <stddef.h>
96 #include <stdint.h>
97
98 #ifndef FE_PARAMETERS_IS_DEFINE
99
100 /* Sampling */
101 #define ADCSAMPLESIZE 125
102 #define SAMPLING_FREQ 25
103
104 /* Windowing */
105 #define PADDING_SIZE_LEFT 4
106 #define PADDING_SIZE_RIGHT 3
107 #define PADDED_INPUT_SIZE (ADCSAMPLESIZE + PADDING_SIZE_LEFT + PADDING_SIZE_RIGHT)
108 #define WINDOW_SIZE 32
109 #define WINDOW_STRIDE_SIZE 4
110 #define NUM_WINDOWS 25
111
112 /* FFT */
113 #define FFT_SIZE 64
114 #define NUM_BINS (FFT_SIZE / 2)
115 #define POOLED_BINS (NUM_BINS / 2)
116
117 /* Top Dominant Frequencies */
118 #define TOP_N_FREQ 2
119
120 /* Kurtosis */
121 #define KURTOSIS_CHUNK_SIZE 8
122 #define KURTOSIS_STRIDE_SIZE 8
123
124 /* Total Features */
125 #define NUM_FEAT_FFT 16
126 #define NUM_FEAT_TOPFREQ TOP_N_FREQ
127 #define NUM_FEAT_KURTOSIS 4
128 #define NUM_FEAT_ZCR 1
129 #define NUM_FEAT_SLOPE 1
130 #define NUM_FEAT_PW_SPEC 1
131 #define NUM_TOTAL_FEATURES 25
132
133 #endif
134
135 extern uint32_t samplingfreq;
136
143 typedef enum
144 {
146 FE_OK = 0x00,
148 FE_ERR_NULLPTR = 0x01,
150 FE_ERR_BAD_PARAM = 0x02,
152 FE_ERR_DSP = 0x03,
153 } fe_status_t;
154
169 fe_status_t FE_applyWindow(const uint8_t *data_stream, uint8_t output_windows[NUM_WINDOWS][WINDOW_SIZE]);
170
186 fe_status_t FE_zeroCrossingRate(const uint8_t *input_window, float *zcr_out);
187
200 fe_status_t FE_slopeChanges(const uint8_t *input_window, float *slope_changes);
201
216 fe_status_t FE_fftPool(const uint8_t *input_window, float *fft_output_pool_mag);
217
231 fe_status_t FE_topFrequencies(const uint8_t *input_window, float *top_freqs);
232
247 fe_status_t FE_spectralEntropy(const uint8_t *input_window, float *entropy_out);
248
263 fe_status_t FE_kurtosis(const uint8_t *input_window, float *kurtosis_output);
264
286 fe_status_t FE_concatenateFeatures(const float *fft_output_pool_mag,
287 uint32_t window_index,
288 const float *kurtosis_output,
289 const float *zcr,
290 const float *slope_changes,
291 const float *top_dominant_freq,
292 const float *power_spectrum,
293 float *concatenated_features);
294
295 #endif /* fe_feature_extract_Module__include */
296
297 #ifdef __cplusplus
298 }
299 #endif
NUM_WINDOWS
#define NUM_WINDOWS
Definition: feature_extract.h:110
FE_slopeChanges
fe_status_t FE_slopeChanges(const uint8_t *input_window, float *slope_changes)
Counts the sign changes of signal differences.
FE_topFrequencies
fe_status_t FE_topFrequencies(const uint8_t *input_window, float *top_freqs)
Extract the index of the dominant frequencies (Hz) per window.
FE_ERR_BAD_PARAM
Definition: feature_extract.h:150
FE_spectralEntropy
fe_status_t FE_spectralEntropy(const uint8_t *input_window, float *entropy_out)
Calculates the Shannon spectral entropy. The Spectral Entropy acts as an indicator of how spread out ...
FE_applyWindow
fe_status_t FE_applyWindow(const uint8_t *data_stream, uint8_t output_windows[25][32])
Builds padded/sliding windows from an input stream considering a stride size.
fe_status_t
fe_status_t
Specifies the FE status codes.
Definition: feature_extract.h:143
FE_ERR_NULLPTR
Definition: feature_extract.h:148
FE_kurtosis
fe_status_t FE_kurtosis(const uint8_t *input_window, float *kurtosis_output)
Calculates the fisher or excess kurtosis without bias for each segment of a given series...
FE_zeroCrossingRate
fe_status_t FE_zeroCrossingRate(const uint8_t *input_window, float *zcr_out)
Measures of how often a signal crosses the zero axis, indicating the frequency or noisiness of a sign...
samplingfreq
uint32_t samplingfreq
FE_concatenateFeatures
fe_status_t FE_concatenateFeatures(const float *fft_output_pool_mag, uint32_t window_index, const float *kurtosis_output, const float *zcr, const float *slope_changes, const float *top_dominant_freq, const float *power_spectrum, float *concatenated_features)
Concatenate many feature arrays into a big feature vector. The offsets are determined by NUM_FEAT_X a...
FE_OK
Definition: feature_extract.h:146
WINDOW_SIZE
#define WINDOW_SIZE
Definition: feature_extract.h:108
FE_ERR_DSP
Definition: feature_extract.h:152
FE_fftPool
fe_status_t FE_fftPool(const uint8_t *input_window, float *fft_output_pool_mag)
calculate FFT magnitudes and pooling (averaging) to produce NUM_FEAT_FFT features.

© Copyright 1995-2025, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale