EDGEAI API

Macros | Enumerations | Functions | Variables
feature_extract.h File Reference

## Detailed Description

PRELIMINARY Feature Extraction for EdgeAI

WARNING These set of functions are PRELIMINARY, and subject to change in the next few months.

To use the Feature Extraction library, include this header file in the application as follows:

#include <ti/ai/edge_ai/fe/feature_extract.h>

# Overview

This library will serve as a pre-processing stage where raw signal inputs will be fed to the feature extraction library and the resulting output will be fed into the pre-compiled NN model. The function that have been implemented so far are the following:

- FE_applyWindow(): extracts windows of data based on a window size, stride size and an input stream.
- FE_fftPool(): calculates the Real FFT magnitude for each window and average pool the resulting bins. The window undergoes a symmetrical modification first, doubling its size.
- FE_kurtosis(): calculates the fisher or excess Kurtorsis for each segment of a given window, without bias (look for exact equation in the previous graph). Kurtosis describes the "peakedness" of a probability distribution.
- FE_zeroCrossingRate(): calculates the zero crossing rate for each window. ZCR measures of how often a signal crosses the zero axis, indicating the frequency or noisiness of a signal.
- FE_slopeChanges(): counts the sign changes of signal differences.
- FE_topFrequencies(): calculates the top N dominant frequencies of a FFT result per window. The window doubles its size first, padded with zeros to the right.
- FE_spectralEntropy(): calculates the Shannon spectral entropy of a FFT result per window. The window doubles its size first, padded with zeros to the right. The Spectral Entropy acts as an indicator of how spread out the power is across different frequencies.
- FE_concatenateFeatures(): Concatenate many feature arrays into a big feature vector. The offsets are determined by NUM_FEAT_X and NUM_WINDOWS macros.

# Usage

To use the Feature Extraction Library call the previous APIs accordingly.

`#include <stddef.h>`
`#include <stdint.h>`
Include dependency graph for feature_extract.h:

Go to the source code of this file.

## Macros
#define | ADCSAMPLESIZE 125
#define | SAMPLING_FREQ 25
#define | PADDING_SIZE_LEFT 4
#define | PADDING_SIZE_RIGHT 3
#define | PADDED_INPUT_SIZE (ADCSAMPLESIZE + PADDING_SIZE_LEFT + PADDING_SIZE_RIGHT)
#define | WINDOW_SIZE 32
#define | WINDOW_STRIDE_SIZE 4
#define | NUM_WINDOWS 25
#define | FFT_SIZE 64
#define | NUM_BINS (FFT_SIZE / 2)
#define | POOLED_BINS (NUM_BINS / 2)
#define | TOP_N_FREQ 2
#define | KURTOSIS_CHUNK_SIZE 8
#define | KURTOSIS_STRIDE_SIZE 8
#define | NUM_FEAT_FFT 16
#define | NUM_FEAT_TOPFREQ TOP_N_FREQ
#define | NUM_FEAT_KURTOSIS 4
#define | NUM_FEAT_ZCR 1
#define | NUM_FEAT_SLOPE 1
#define | NUM_FEAT_PW_SPEC 1
#define | NUM_TOTAL_FEATURES 25

## Enumerations
enum | fe_status_t { FE_OK = 0x00, FE_ERR_NULLPTR = 0x01, FE_ERR_BAD_PARAM = 0x02, FE_ERR_DSP = 0x03 }
| Specifies the FE status codes. More...

## Functions
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. More...
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 signal. More...
fe_status_t | FE_slopeChanges (const uint8_t *input_window, float *slope_changes)
| Counts the sign changes of signal differences. More...
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. More...
fe_status_t | FE_topFrequencies (const uint8_t *input_window, float *top_freqs)
| Extract the index of the dominant frequencies (Hz) per window. More...
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 the power is. More...
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. Kurtosis describes the "peakedness" of a probability distribution. More...
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 and NUM_WINDOWS macros. More...

## Variables
uint32_t | samplingfreq

## Macro Definition Documentation

## § ADCSAMPLESIZE

#define ADCSAMPLESIZE 125

## § SAMPLING_FREQ

#define SAMPLING_FREQ 25

## § PADDING_SIZE_LEFT

#define PADDING_SIZE_LEFT 4

## § PADDING_SIZE_RIGHT

#define PADDING_SIZE_RIGHT 3

## § PADDED_INPUT_SIZE

#define PADDED_INPUT_SIZE (ADCSAMPLESIZE + PADDING_SIZE_LEFT + PADDING_SIZE_RIGHT)

## § WINDOW_SIZE

#define WINDOW_SIZE 32

## § WINDOW_STRIDE_SIZE

#define WINDOW_STRIDE_SIZE 4

## § NUM_WINDOWS

#define NUM_WINDOWS 25

## § FFT_SIZE

#define FFT_SIZE 64

## § NUM_BINS

#define NUM_BINS (FFT_SIZE / 2)

## § POOLED_BINS

#define POOLED_BINS (NUM_BINS / 2)

## § TOP_N_FREQ

#define TOP_N_FREQ 2

## § KURTOSIS_CHUNK_SIZE

#define KURTOSIS_CHUNK_SIZE 8

## § KURTOSIS_STRIDE_SIZE

#define KURTOSIS_STRIDE_SIZE 8

## § NUM_FEAT_FFT

#define NUM_FEAT_FFT 16

## § NUM_FEAT_TOPFREQ

#define NUM_FEAT_TOPFREQ TOP_N_FREQ

## § NUM_FEAT_KURTOSIS

#define NUM_FEAT_KURTOSIS 4

## § NUM_FEAT_ZCR

#define NUM_FEAT_ZCR 1

## § NUM_FEAT_SLOPE

#define NUM_FEAT_SLOPE 1

## § NUM_FEAT_PW_SPEC

#define NUM_FEAT_PW_SPEC 1

## § NUM_TOTAL_FEATURES

#define NUM_TOTAL_FEATURES 25

## Enumeration Type Documentation

## § fe_status_t

enum fe_status_t

Specifies the FE status codes.

This enum defines the return states of the FE functions.

Enumerator
FE_OK | Process ended successfully. The pointer to one of the function arguments has a NULL value.
FE_ERR_NULLPTR | One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_BAD_PARAM | DSP operation has failed.
FE_ERR_DSP |

## Function Documentation

## § 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.

Parameters

  [in] | data_stream | pointer to input data stream [ADCSAMPLESIZE] for time series.
  [out] | output_windows | preallocated 2D-array [NUM_WINDOWS][WINDOW_SIZE].

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## § 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 signal.

Parameters

  [in] | input_window | input window uint8.
  [out] | zcr_out | pointer to result float32.

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## § FE_slopeChanges()

fe_status_t FE_slopeChanges | ( | const uint8_t * | input_window,
|  | float * | slope_changes
| ) |  |

Counts the sign changes of signal differences.

Parameters

  [in] | input_window | input window uint8.
  [out] | slope_changes | pointer to result float32.

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## § 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.

Parameters

  [in] | input_window | input window uint8.
  [out] | fft_output_pool_mag | preallocated array of NUM_FEAT_FFT float32.

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## § 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.

Parameters

  [in] | input_window | input window uint8.
  [out] | top_freqs | preallocated array of length TOP_N_FREQ.

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## § 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 the power is.

Parameters

  [in] | input_window | input window uint8.
  [out] | entropy_out | pointer to float32 result.

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## § 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. Kurtosis describes the "peakedness" of a probability distribution.

Parameters

  [in] | input_window | input window uint8.
  [out] | kurtosis_output | preallocated array of NUM_FEAT_KURTOSIS float32.

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## § 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 and NUM_WINDOWS macros.

Parameters

  [in] | fft_output_pool_mag | pointer to FFT features (NUM_FEAT_FFT)
  [in] | window_index | which window this belongs to (0 .. NUM_WINDOWS-1)
  [in] | kurtosis_output | pointer to NUM_FEAT_KURTOSIS values
  [in] | zcr | pointer to zcr value (scalar)
  [in] | slope_changes | pointer to slope_changes value (scalar)
  [in] | top_dominant_freq | pointer to TOP_N_FREQ values
  [in] | power_spectrum | pointer to spectral entropy (scalar)
  [out] | concatenated_features | preallocated feature vector of size NUM_TOTAL_FEATURES * NUM_WINDOWS

Return values

  FE_OK | Process ended successfully.
  FE_ERR_NULLPTR | The pointer to one of the function arguments has a NULL value.
  FE_ERR_BAD_PARAM | One of the Feature Extraction configuration parameters is incorrect or not supported.
  FE_ERR_DSP | DSP operation has failed.

## Variable Documentation

## § samplingfreq

uint32_t samplingfreq

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