Implemented xtract_harmonics

4 files changed, 24 insertions, 9 deletions

diff --git a/xtract/libxtract.h b/xtract/libxtract.h
index 6e76ff3..489cddf 100644
--- a/xtract/libxtract.h
+++ b/xtract/libxtract.h
@@ -53,7 +53,7 @@ extern "C" {
   * @{
   */
 
-#define XTRACT_FEATURES 43
+#define XTRACT_FEATURES 44
     
 #define LOG_LIMIT 10e-10
 #define VERY_BIG_NUMBER 2e10
@@ -104,7 +104,8 @@ enum features_ {
     MAGNITUDE_SPECTRUM,
     AUTOCORRELATION_FFT,
     MFCC,
-    DCT
+    DCT,
+    HARMONICS
 };
 
 /** \brief Enumeration of feature types */
@@ -126,7 +127,8 @@ enum return_codes_ {
     MALLOC_FAILED,
     BAD_ARGV,
     BAD_VECTOR_SIZE,
-    NO_RESULT
+    NO_RESULT,
+    FEATURE_NOT_IMPLEMENTED
 };
 
 /**
@@ -178,12 +180,18 @@ printf("Mean = %.2f\n", mean);
 #ifdef XTRACT
 extern int(*xtract[XTRACT_FEATURES])(float *data, int N, void *argv, float *result);
 
-
 /** \brief An array of pointers to function help strings
  *
  * Defined in libxtract.c. As a minimum this will contain pointers to the names of all of the feature extraction functions in the library. This is intended as a 'quick reference' to be queried as necessary.
  */
 extern char *xtract_help_strings[XTRACT_FEATURES];
+
+/** \brief An array of pointers to strings giving function output units
+ *
+ * Defined in libxtract.c. This contains pointers to strings giving the output units of all of the feature extraction functions in the library. This is intended as a 'quick reference' to be queried as necessary.
+ */
+extern char *xtract_units[XTRACT_FEATURES];
+
 #endif
 
 /** \brief A structure to store a set of n_filters Mel filters */
diff --git a/xtract/xtract_macros.h b/xtract/xtract_macros.h
index 534e1af..3ee97b2 100644
--- a/xtract/xtract_macros.h
+++ b/xtract/xtract_macros.h
@@ -34,7 +34,6 @@ extern "C" {
 #define SQ(a) ((a) * (a))
 #define MIN(a, b) ((a) < (b) ? (a) : (b))
 #define MAX(a, b) ((a) > (b) ? (a) : (b))
-#define NOT_IMPLEMENTED printf("Feature not implemented yet.\n")
 #define NEEDS_FFTW printf("LibXtract must be compiled with fftw support to use this function.\n")
 
 #ifdef __cplusplus
diff --git a/xtract/xtract_scalar.h b/xtract/xtract_scalar.h
index 59c92dc..eae8afc 100644
--- a/xtract/xtract_scalar.h
+++ b/xtract/xtract_scalar.h
@@ -117,7 +117,7 @@ int xtract_irregularity_j(float *data, int N, void *argv, float *result);
 
 /** \brief Calculate the Tristimulus of an input vector using a method described by Pollard and Jansson (1982)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the amplitudes of the harmonic spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the amplitudes of the harmonic spectrum of an audio vector e.g. a pointer to the second half of the array pointed to by *result from xtract_harmonics()
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the tristimulus of N values from the array pointed to by *data
@@ -246,8 +246,8 @@ int xtract_power(float *data, int N, void *argv, float *result);
 /* Odd to even harmonic ratio */
 /** \brief Extract the Odd to even harmonic ratio of an input vector 
  * 
- * \param *data: a pointer to the first element in an array of floats representing the harmonic spectrum of an audio vector
- * \param N: the number of elements to be considered
+ * \param *data: a pointer to the first element in an array of floats representing the frequencies of the harmonic spectrum of an audio vector. It is sufficient to pass in a pointer to the array pointed to by *result from xtract_harmonics.
+ * \param N: the number of elements to be considered. If using the array pointed to by *result from xtract_harmonics, N should equal half the total array size i.e., just the frequencies of the peaks.
  * \param *argv: a pointer to NULL
  * \param *result: the odd/even harmonic ratio of N values from the array pointed to by *data
  */
diff --git a/xtract/xtract_vector.h b/xtract/xtract_vector.h
index d72d051..21cc8a3 100644
--- a/xtract/xtract_vector.h
+++ b/xtract/xtract_vector.h
@@ -109,7 +109,7 @@ int xtract_asdf(float *data, int N, void *argv, float *result);
  */
 int xtract_bark_coefficients(float *data, int N, void *argv, float *result);
 
-/** \brief Extract the frequency and amplitude of spectral peaks from a of a magnitude spectrum
+/** \brief Extract the frequency and amplitude of spectral peaks from a magnitude spectrum
  * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
  * \param N: the number of array elements to be considered
  * \param *argv: a pointer to an array containing peak threshold as percentage below max peak, and sample rate 
@@ -117,6 +117,14 @@ int xtract_bark_coefficients(float *data, int N, void *argv, float *result);
  */
 int xtract_peaks(float *data, int N, void *argv, float *result);
 
+/** \brief Extract the harmonic spectrum of from a of a peak spectrum 
+ * \param *data: a pointer to the first element in an array of floats representing the peak spectrum of an audio vector (e.g. *result from  xtract_peaks). It is expected that the first half of the array pointed to by *data will contain frequencies for each peak considered, and the the second half will contain the respective amplitudes
+ * \param N: the size of the array pointed to by *data
+ * \param *argv: a pointer to an array containing the fundamental (f0) of the spectrum, and a threshold (t) where 0<=t<=1.0, and t determines the distance from the nearest harmonic number within which a partial can be considered harmonic.
+ * \param *result: a pointer to an array of size N containing N/2 freqs and N/2 amplitudes, amplitudes are on a decibel scale with dbFS = 0
+ */
+int xtract_harmonics(float *data, int N, void *argv, float *result);
+
 /** @} */
 
 #ifdef __cplusplus