feature_extract.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025-2026, Texas Instruments Incorporated
 * 
 *  All rights reserved not granted herein.
 *  Limited License.
 * 
 *  Texas Instruments Incorporated grants a world-wide, royalty-free,
 *  non-exclusive license under copyrights and patents it now or hereafter
 *  owns or controls to make, have made, use, import, offer to sell and sell
 *  ("Utilize") this software subject to the terms herein. With respect to the
 *  foregoing patent license, such license is granted solely to the extent that
 *  any such patent is necessary to Utilize the software alone. The patent
 *  license shall not apply to any combinations which include this software,
 *  other than combinations with devices manufactured by or for TI ("TI
 *  Devices"). No hardware patent is licensed hereunder.
 * 
 *  Redistributions must preserve existing copyright notices and reproduce
 *  this license (including the above copyright notice and the disclaimer and
 *  (if applicable) source code license limitations below) in the documentation
 *  and/or other materials provided with the distribution.
 * 
 *  Redistribution and use in binary form, without modification, are permitted
 *  provided that the following conditions are met:
 * 
 *    * No reverse engineering, decompilation, or disassembly of this software
 *      is permitted with respect to any software provided in binary form.
 *    * Any redistribution and use are licensed by TI for use only with TI Devices.
 *    * Nothing shall obligate TI to provide you with source code for the software
 *      licensed and provided to you in object code.
 * 
 *  If software source code is provided to you, modification and redistribution
 *  of the source code are permitted provided that the following conditions are
 *  met:
 * 
 *    * Any redistribution and use of the source code, including any resulting
 *      derivative works, are licensed by TI for use only with TI Devices.
 *    * Any redistribution and use of any object code compiled from the source
 *      code and any resulting derivative works, are licensed by TI for use
 *      only with TI Devices.
 * 
 *  Neither the name of Texas Instruments Incorporated nor the names of its
 *  suppliers may be used to endorse or promote products derived from this
 *  software without specific prior written permission.
 * 
 *  DISCLAIMER.
 * 
 *  THIS SOFTWARE IS PROVIDED BY TI AND TI'S LICENSORS "AS IS" AND ANY EXPRESS
 *  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 *  IN NO EVENT SHALL TI AND TI'S LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 *  OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
*  @file       feature_extract.h
*  @brief      <b>PRELIMINARY</b> Feature Extraction for EdgeAI
*
*  <b>WARNING</b> These set of functions are <b>PRELIMINARY</b>, and subject to
*  change in the next few months.
*
*  To use the Feature Extraction library, include this header file in the
*  application as follows:

*  @code
*  #include <ti/ai/edge_ai/fe/feature_extract.h>
*  @endcode
*
*  @anchor ti_edgeai_feature_extract_Overview
*  # 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.
*
*  <hr>
*  # Usage
*  To use the Feature Extraction Library call the previous APIs accordingly.
*
******************************************************************************
*/

#ifndef ti_edgeai_feature_extract__include
#define ti_edgeai_feature_extract__include

#ifdef __cplusplus
extern "C" {
#endif

#include <stddef.h>
#include <stdint.h>

#ifndef FE_PARAMETERS_IS_DEFINE

    /* Sampling */
    #define ADCSAMPLESIZE 125
    #define SAMPLING_FREQ 25

    /* Windowing */
    #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

    /* FFT */
    #define FFT_SIZE    64
    #define NUM_BINS    (FFT_SIZE / 2)
    #define POOLED_BINS (NUM_BINS / 2)

    /* Top Dominant Frequencies */
    #define TOP_N_FREQ 2

    /* Kurtosis */
    #define KURTOSIS_CHUNK_SIZE  8
    #define KURTOSIS_STRIDE_SIZE 8

    /* Total Features */
    #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

#endif

extern uint32_t samplingfreq;

typedef enum
{
    FE_OK            = 0x00,
    FE_ERR_NULLPTR   = 0x01,
    FE_ERR_BAD_PARAM = 0x02,
    FE_ERR_DSP       = 0x03,
} fe_status_t;

fe_status_t FE_applyWindow(const uint8_t *data_stream, uint8_t output_windows[NUM_WINDOWS][WINDOW_SIZE]);

fe_status_t FE_zeroCrossingRate(const uint8_t *input_window, float *zcr_out);

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

fe_status_t FE_fftPool(const uint8_t *input_window, float *fft_output_pool_mag);

fe_status_t FE_topFrequencies(const uint8_t *input_window, float *top_freqs);

fe_status_t FE_spectralEntropy(const uint8_t *input_window, float *entropy_out);

fe_status_t FE_kurtosis(const uint8_t *input_window, float *kurtosis_output);

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);

#endif /* fe_feature_extract_Module__include */

#ifdef __cplusplus
}
#endif