dspx 0.1.1-alpha.0

package/src/native/core/IirFilter.h

@@ -0,0 +1,210 @@
+/**
+ * IIR (Infinite Impulse Response) Filter
+ *
+ * A recursive filter defined by:
+ *   y[n] = (b[0]*x[n] + b[1]*x[n-1] + ... + b[M]*x[n-M])
+ *        - (a[1]*y[n-1] + a[2]*y[n-2] + ... + a[N]*y[n-N])
+ *
+ * Standard form: a[0] = 1 (normalized)
+ *
+ * Features:
+ * - Feedback structure (can be unstable if poles outside unit circle)
+ * - Efficient (fewer coefficients than FIR for same frequency response)
+ * - Stateful (maintains input/output history) and stateless modes
+ * - Common filter designs: Butterworth, Chebyshev, Bessel
+ * - Biquad cascade structure for numerical stability
+ */
+
+#ifndef DSP_CORE_IIR_FILTER_H
+#define DSP_CORE_IIR_FILTER_H
+
+#include <vector>
+#include <cstddef>
+#include <memory>
+
+namespace dsp
+{
+    namespace core
+    {
+
+        template <typename T = float>
+        class IirFilter
+        {
+        public:
+            /**
+             * Constructor
+             * @param b_coeffs Feedforward coefficients (b[0], b[1], ..., b[M])
+             * @param a_coeffs Feedback coefficients (a[1], a[2], ..., a[N])
+             *                 Note: a[0] is assumed to be 1 (normalized form)
+             * @param stateful If true, maintains state between process calls
+             */
+            IirFilter(const std::vector<T> &b_coeffs, const std::vector<T> &a_coeffs, bool stateful = true);
+
+            /**
+             * Process single sample (stateful mode only)
+             * @param input Input sample
+             * @return Filtered output sample
+             */
+            T processSample(T input);
+
+            /**
+             * Process batch of samples
+             * @param input Input samples
+             * @param output Output buffer (must be same size as input)
+             * @param length Number of samples
+             * @param stateless If true, ignores internal state (batch processing)
+             */
+            void process(const T *input, T *output, size_t length, bool stateless = false);
+
+            /**
+             * Reset filter state (clear history)
+             */
+            void reset();
+
+            /**
+             * Get feedforward order (M)
+             */
+            size_t getFeedforwardOrder() const { return m_b_coeffs.size() - 1; }
+
+            /**
+             * Get feedback order (N)
+             */
+            size_t getFeedbackOrder() const { return m_a_coeffs.size(); }
+
+            /**
+             * Get feedforward coefficients
+             */
+            const std::vector<T> &getBCoefficients() const { return m_b_coeffs; }
+
+            /**
+             * Get feedback coefficients
+             */
+            const std::vector<T> &getACoefficients() const { return m_a_coeffs; }
+
+            /**
+             * Update coefficients (resets state)
+             */
+            void setCoefficients(const std::vector<T> &b_coeffs, const std::vector<T> &a_coeffs);
+
+            /**
+             * Check if filter is stateful
+             */
+            bool isStateful() const { return m_stateful; }
+
+            /**
+             * Check filter stability (all poles inside unit circle)
+             * Note: This is a basic check; full stability analysis requires pole computation
+             */
+            bool isStable() const;
+
+            // ========== Common IIR Filter Designs ==========
+
+            /**
+             * Create Butterworth low-pass filter (maximally flat passband)
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             * @param order Filter order (1-8 recommended)
+             * @return IIR filter
+             */
+            static IirFilter<T> createButterworthLowPass(T cutoffFreq, int order);
+
+            /**
+             * Create Butterworth high-pass filter
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             * @param order Filter order (1-8 recommended)
+             */
+            static IirFilter<T> createButterworthHighPass(T cutoffFreq, int order);
+
+            /**
+             * Create Butterworth band-pass filter
+             * @param lowCutoff Low cutoff frequency (normalized)
+             * @param highCutoff High cutoff frequency (normalized)
+             * @param order Filter order (per band, total = 2*order)
+             */
+            static IirFilter<T> createButterworthBandPass(T lowCutoff, T highCutoff, int order);
+
+            /**
+             * Create first-order low-pass filter (simple RC filter)
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             */
+            static IirFilter<T> createFirstOrderLowPass(T cutoffFreq);
+
+            /**
+             * Create first-order high-pass filter
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             */
+            static IirFilter<T> createFirstOrderHighPass(T cutoffFreq);
+
+            /**
+             * Create biquad filter from biquad coefficients
+             * y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2] - a1*y[n-1] - a2*y[n-2]
+             */
+            static IirFilter<T> createBiquad(T b0, T b1, T b2, T a1, T a2);
+
+            /**
+             * Create Chebyshev Type I low-pass filter (passband ripple)
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             * @param order Filter order (1-8 recommended)
+             * @param rippleDb Passband ripple in dB (0.1 to 3.0, typical: 0.5)
+             * @return IIR filter
+             */
+            static IirFilter<T> createChebyshevLowPass(T cutoffFreq, int order, T rippleDb = T(0.5));
+
+            /**
+             * Create Chebyshev Type I high-pass filter (passband ripple)
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             * @param order Filter order (1-8 recommended)
+             * @param rippleDb Passband ripple in dB (0.1 to 3.0, typical: 0.5)
+             */
+            static IirFilter<T> createChebyshevHighPass(T cutoffFreq, int order, T rippleDb = T(0.5));
+
+            /**
+             * Create Chebyshev Type I band-pass filter (passband ripple)
+             * @param lowCutoff Low cutoff frequency (normalized)
+             * @param highCutoff High cutoff frequency (normalized)
+             * @param order Filter order (per band, total = 2*order)
+             * @param rippleDb Passband ripple in dB (0.1 to 3.0, typical: 0.5)
+             */
+            static IirFilter<T> createChebyshevBandPass(T lowCutoff, T highCutoff, int order, T rippleDb = T(0.5));
+
+            /**
+             * Create peaking EQ biquad filter
+             * @param centerFreq Center frequency (normalized: 0 to 0.5)
+             * @param Q Quality factor (bandwidth = centerFreq/Q, typical: 0.5-10)
+             * @param gainDb Gain in dB (negative for cut, positive for boost)
+             */
+            static IirFilter<T> createPeakingEQ(T centerFreq, T Q, T gainDb);
+
+            /**
+             * Create low-shelf biquad filter
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             * @param gainDb Gain in dB for low frequencies
+             * @param Q Shelf slope (typical: 0.7)
+             */
+            static IirFilter<T> createLowShelf(T cutoffFreq, T gainDb, T Q = T(0.707));
+
+            /**
+             * Create high-shelf biquad filter
+             * @param cutoffFreq Cutoff frequency (normalized: 0 to 0.5)
+             * @param gainDb Gain in dB for high frequencies
+             * @param Q Shelf slope (typical: 0.7)
+             */
+            static IirFilter<T> createHighShelf(T cutoffFreq, T gainDb, T Q = T(0.707));
+
+        private:
+            std::vector<T> m_b_coeffs; // Feedforward coefficients (b[0], b[1], ..., b[M])
+            std::vector<T> m_a_coeffs; // Feedback coefficients (a[1], a[2], ..., a[N])
+            std::vector<T> m_x_state;  // Input history (x[n-1], x[n-2], ...)
+            std::vector<T> m_y_state;  // Output history (y[n-1], y[n-2], ...)
+            bool m_stateful;           // Whether to maintain state between calls
+
+            /**
+             * Bilinear transform: convert analog to digital filter
+             * s -> 2/T * (1 - z^-1) / (1 + z^-1)
+             */
+            static void bilinearTransform(T wc, int order, std::vector<T> &b, std::vector<T> &a);
+        };
+
+    } // namespace core
+} // namespace dsp
+
+#endif // DSP_CORE_IIR_FILTER_H

package/src/native/core/MovingAbsoluteValueFilter.cc

@@ -0,0 +1,17 @@
+/**
+ * @file MovingAbsoluteValueFilter.cc
+ * @brief Implementation file for MovingAbsoluteValueFilter (now header-only with policy-based design)
+ *
+ * This file now only contains explicit template instantiations.
+ * The actual implementation is in the header file MovingAbsoluteValueFilter.h,
+ * which delegates to SlidingWindowFilter<T, MeanAbsoluteValuePolicy<T>>.
+ */
+
+#include "MovingAbsoluteValueFilter.h"
+
+// Explicit template instantiation for common types
+namespace dsp::core
+{
+    template class MovingAbsoluteValueFilter<float>;
+    template class MovingAbsoluteValueFilter<double>;
+}

package/src/native/core/MovingAbsoluteValueFilter.h

@@ -0,0 +1,135 @@
+#pragma once
+#include "../utils/SlidingWindowFilter.h"
+#include "Policies.h"
+#include <utility>
+#include <vector>
+#include <stdexcept>
+
+namespace dsp::core
+{
+    using dsp::utils::SlidingWindowFilter;
+    /**
+     * @brief Implements an efficient Mean Absolute Value (MAV) filter.
+     *
+     * This class is now a thin wrapper around SlidingWindowFilter
+     * using the MeanAbsoluteValuePolicy for statistical computation.
+     *
+     * The policy automatically handles the absolute value calculation,
+     * demonstrating the power of policy-based design for complex transformations.
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double, int).
+     */
+    template <typename T>
+    class MovingAbsoluteValueFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new MAV Filter.
+         * @param window_size The number of samples to average over (N).
+         */
+        explicit MovingAbsoluteValueFilter(size_t window_size)
+            : m_filter(window_size, MeanAbsoluteValuePolicy<T>{})
+        {
+            if (window_size == 0)
+            {
+                throw std::invalid_argument("Window size must be greater than 0");
+            }
+        }
+
+        /**
+         * @brief Constructs a new time-aware MAV Filter.
+         * @param window_size The buffer capacity in samples.
+         * @param window_duration_ms The time window duration in milliseconds.
+         */
+        explicit MovingAbsoluteValueFilter(size_t window_size, double window_duration_ms)
+            : m_filter(window_size, window_duration_ms, MeanAbsoluteValuePolicy<T>{})
+        {
+            if (window_size == 0)
+            {
+                throw std::invalid_argument("Window size must be greater than 0");
+            }
+            if (window_duration_ms <= 0.0)
+            {
+                throw std::invalid_argument("Window duration must be greater than 0");
+            }
+        }
+
+        // Delete copy constructor and copy assignment
+        MovingAbsoluteValueFilter(const MovingAbsoluteValueFilter &) = delete;
+        MovingAbsoluteValueFilter &operator=(const MovingAbsoluteValueFilter &) = delete;
+
+        // Enable move semantics
+        MovingAbsoluteValueFilter(MovingAbsoluteValueFilter &&) noexcept = default;
+        MovingAbsoluteValueFilter &operator=(MovingAbsoluteValueFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample to the filter.
+         * @param newValue The new sample value to add (can be negative).
+         * @return T The new mean absolute value.
+         */
+        T addSample(T newValue) { return m_filter.addSample(newValue); }
+
+        /**
+         * @brief Adds a new sample with timestamp (time-aware mode).
+         * @param newValue The new sample value to add (can be negative).
+         * @param timestamp The timestamp in milliseconds.
+         * @return T The new mean absolute value.
+         */
+        T addSampleWithTimestamp(T newValue, double timestamp)
+        {
+            return m_filter.addSampleWithTimestamp(newValue, timestamp);
+        }
+
+        /**
+         * @brief Gets the current mean absolute value.
+         * @return T The MAV of the samples currently in the buffer.
+         */
+        T getMav() const { return m_filter.getPolicy().getResult(m_filter.getCount()); }
+
+        /**
+         * @brief Clears all samples from the filter and resets the sum.
+         */
+        void clear() { m_filter.clear(); }
+
+        /**
+         * @brief Checks if the filter's buffer is full (i.e., has N samples).
+         * @return true if the buffer is full, false otherwise.
+         */
+        bool isFull() const noexcept { return m_filter.isFull(); }
+
+        /**
+         * @brief Checks if the filter is in time-aware mode.
+         * @return true if time-aware, false otherwise.
+         */
+        bool isTimeAware() const noexcept { return m_filter.isTimeAware(); }
+
+        /**
+         * @brief Exports the filter's internal state.
+         *
+         * Delegates to SlidingWindowFilter's generic state management.
+         *
+         * @return A pair containing the buffer contents (original values)
+         * and the running sum of absolute values.
+         */
+        std::pair<std::vector<T>, T> getState() const
+        {
+            return m_filter.getState();
+        }
+
+        /**
+         * @brief Restores the filter's internal state.
+         *
+         * Delegates to SlidingWindowFilter's generic state management.
+         *
+         * @param bufferData The buffer contents (original values) to restore.
+         * @param sumOfAbs The running sum of absolute values to restore.
+         */
+        void setState(const std::vector<T> &bufferData, T sumOfAbs)
+        {
+            m_filter.setState(bufferData, sumOfAbs);
+        }
+
+    private:
+        SlidingWindowFilter<T, MeanAbsoluteValuePolicy<T>> m_filter;
+    };
+} // namespace dsp::core

package/src/native/core/MovingAverageFilter.cc

@@ -0,0 +1,18 @@
+/**
+ * @file MovingAverageFilter.cc
+ * @brief Implementation file for MovingAverageFilter (now header-only with policy-based design)
+ *
+ * This file now only contains explicit template instantiations.
+ * The actual implementation is in the header file MovingAverageFilter.h,
+ * which delegates to SlidingWindowFilter<T, MeanPolicy<T>>.
+ */
+
+#include "MovingAverageFilter.h"
+
+// Explicit template instantiation for common types
+namespace dsp::core
+{
+    template class MovingAverageFilter<int>;
+    template class MovingAverageFilter<float>;
+    template class MovingAverageFilter<double>;
+}

package/src/native/core/MovingAverageFilter.h

@@ -0,0 +1,135 @@
+#pragma once
+#include "../utils/SlidingWindowFilter.h"
+#include "Policies.h"
+#include <utility>
+#include <vector>
+
+namespace dsp::core
+{
+    using dsp::utils::SlidingWindowFilter;
+    /**
+     * @brief Implements an efficient Simple Moving Average (SMA) filter.
+     *
+     * This class is now a thin wrapper around SlidingWindowFilter
+     * using the MeanPolicy for statistical computation.
+     *
+     * The policy-based design provides:
+     * - Zero-cost abstraction (inlined policy methods)
+     * - Consistent interface across all sliding window filters
+     * - Easy extensibility for new statistical measures
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double, int).
+     */
+    template <typename T>
+    class MovingAverageFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new Moving Average Filter.
+         * @param window_size The number of samples to average over (N).
+         */
+        explicit MovingAverageFilter(size_t window_size)
+            : m_filter(window_size, MeanPolicy<T>{})
+        {
+            if (window_size == 0)
+            {
+                throw std::invalid_argument("Window size must be greater than 0");
+            }
+        }
+
+        /**
+         * @brief Constructs a new time-aware Moving Average Filter.
+         * @param window_size The number of samples to average over (N).
+         * @param window_duration_ms The maximum age of samples in milliseconds.
+         */
+        explicit MovingAverageFilter(size_t window_size, double window_duration_ms)
+            : m_filter(window_size, window_duration_ms, MeanPolicy<T>{})
+        {
+            if (window_size == 0)
+            {
+                throw std::invalid_argument("Window size must be greater than 0");
+            }
+            if (window_duration_ms <= 0.0)
+            {
+                throw std::invalid_argument("Window duration must be positive");
+            }
+        }
+
+        // Delete copy constructor and copy assignment
+        MovingAverageFilter(const MovingAverageFilter &) = delete;
+        MovingAverageFilter &operator=(const MovingAverageFilter &) = delete;
+
+        // Enable move semantics
+        MovingAverageFilter(MovingAverageFilter &&) noexcept = default;
+        MovingAverageFilter &operator=(MovingAverageFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample to the filter.
+         * @param newValue The new sample value to add.
+         * @return T The new moving average.
+         */
+        T addSample(T newValue) { return m_filter.addSample(newValue); }
+
+        /**
+         * @brief Adds a new sample with timestamp (time-aware mode only).
+         * @param newValue The new sample value to add.
+         * @param timestamp The timestamp in milliseconds.
+         * @return T The new moving average.
+         */
+        T addSampleWithTimestamp(T newValue, double timestamp)
+        {
+            return m_filter.addSampleWithTimestamp(newValue, timestamp);
+        }
+
+        /**
+         * @brief Checks if this is a time-aware filter.
+         * @return bool True if window duration is set.
+         */
+        bool isTimeAware() const noexcept { return m_filter.isTimeAware(); }
+
+        /**
+         * @brief Gets the current moving average.
+         * @return T The average of the samples currently in the buffer.
+         */
+        T getAverage() const { return m_filter.getPolicy().getResult(m_filter.getCount()); }
+
+        /**
+         * @brief Clears all samples from the filter and resets the sum.
+         */
+        void clear() { m_filter.clear(); }
+
+        /**
+         * @brief Checks if the filter's buffer is full (i.e., has N samples).
+         * @return true if the buffer is full, false otherwise.
+         */
+        bool isFull() const noexcept { return m_filter.isFull(); }
+
+        /**
+         * @brief Exports the filter's internal state.
+         *
+         * Delegates to SlidingWindowFilter's generic state management.
+         *
+         * @return A pair containing the buffer contents and running sum.
+         */
+        std::pair<std::vector<T>, T> getState() const
+        {
+            return m_filter.getState();
+        }
+
+        /**
+         * @brief Restores the filter's internal state.
+         *
+         * Delegates to SlidingWindowFilter's generic state management.
+         *
+         * @param bufferData The buffer contents to restore.
+         * @param sum The running sum to restore.
+         */
+        void setState(const std::vector<T> &bufferData, T sum)
+        {
+            m_filter.setState(bufferData, sum);
+        }
+
+    private:
+        SlidingWindowFilter<T, MeanPolicy<T>> m_filter;
+    };
+} // namespace dsp::core