dspx 1.2.4 → 1.3.1

package/src/native/adapters/SscStage.h

@@ -3,6 +3,7 @@
 #include "../IDspStage.h"
 #include "../core/SscFilter.h"
 #include "../utils/NapiUtils.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <string>
 #include <stdexcept>
@@ -112,6 +113,70 @@ namespace dsp::adapters
             }
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeInt32(static_cast<int32_t>(m_window_size));
+            s.writeFloat(m_threshold);
+            s.writeInt32(static_cast<int32_t>(m_filters.size()));
+
+            for (const auto &filter : m_filters)
+            {
+                auto [internalState, filterState] = filter.getState();
+                auto [bufferData, runningCount] = internalState;
+
+                // Serialize bool vector as byte array
+                s.writeInt32(static_cast<int32_t>(bufferData.size()));
+                for (bool b : bufferData)
+                {
+                    s.writeBool(b);
+                }
+                s.writeInt32(static_cast<int32_t>(runningCount));
+                s.writeFloat(filterState.sample_minus_1);
+                s.writeFloat(filterState.sample_minus_2);
+                s.writeInt32(filterState.init_count);
+            }
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            size_t windowSize = static_cast<size_t>(d.readInt32());
+            float threshold = d.readFloat();
+            if (windowSize != m_window_size || threshold != m_threshold)
+            {
+                throw std::runtime_error("SSC TOON: parameter mismatch");
+            }
+
+            int32_t numChannels = d.readInt32();
+            m_filters.clear();
+            for (int32_t i = 0; i < numChannels; ++i)
+            {
+                m_filters.emplace_back(m_window_size, m_threshold);
+            }
+
+            for (auto &filter : m_filters)
+            {
+                int32_t bufSize = d.readInt32();
+                std::vector<bool> bufferData(bufSize);
+                for (int32_t j = 0; j < bufSize; ++j)
+                {
+                    bufferData[j] = d.readBool();
+                }
+                size_t runningCount = static_cast<size_t>(d.readInt32());
+
+                dsp::core::SscFilter<float>::SscFilterState filterState;
+                filterState.sample_minus_1 = d.readFloat();
+                filterState.sample_minus_2 = d.readFloat();
+                filterState.init_count = d.readInt32();
+
+                if (!dsp::core::CounterPolicy::validateState(runningCount, bufferData))
+                {
+                    throw std::runtime_error("SSC TOON: validation failed");
+                }
+
+                filter.setState(bufferData, runningCount, filterState);
+            }
+        }
+
     private:
         size_t m_window_size;
         float m_threshold;

package/src/native/adapters/StftStage.h

@@ -38,6 +38,7 @@
 #include "../core/FftEngine.h"
 #include "../utils/CircularBufferArray.h"
 #include "../utils/SimdOps.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <complex>
 #include <memory>
@@ -276,6 +277,67 @@ namespace dsp::adapters
             std::fill(m_samples_since_output.begin(), m_samples_since_output.end(), 0);
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeInt32(static_cast<int32_t>(m_window_size));
+            s.writeInt32(static_cast<int32_t>(m_hop_size));
+            s.writeString(m_method);
+            s.writeString(m_type);
+            s.writeBool(m_forward);
+            s.writeString(m_output);
+            s.writeString(m_window_type);
+            s.writeInt32(static_cast<int32_t>(m_channel_buffers.size()));
+
+            // Serialize each channel's buffer and counter
+            for (size_t i = 0; i < m_channel_buffers.size(); ++i)
+            {
+                std::vector<float> buffer_data = m_channel_buffers[i].toVector();
+                s.writeFloatArray(buffer_data);
+                s.writeInt32(static_cast<int32_t>(m_samples_since_output[i]));
+            }
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            size_t windowSize = static_cast<size_t>(d.readInt32());
+            size_t hopSize = static_cast<size_t>(d.readInt32());
+            std::string method = d.readString();
+            std::string type = d.readString();
+            bool forward = d.readBool();
+            std::string output = d.readString();
+            std::string windowType = d.readString();
+
+            if (windowSize != m_window_size || hopSize != m_hop_size)
+            {
+                throw std::runtime_error("STFT TOON: window/hop size mismatch");
+            }
+
+            uint32_t numChannels = d.readInt32();
+
+            // Recreate channel buffers
+            m_channel_buffers.clear();
+            m_samples_since_output.clear();
+
+            for (uint32_t i = 0; i < numChannels; ++i)
+            {
+                m_channel_buffers.emplace_back(m_window_size);
+                m_samples_since_output.push_back(0);
+            }
+
+            // Restore each channel's state
+            for (uint32_t i = 0; i < numChannels; ++i)
+            {
+                std::vector<float> buffer_data = d.readFloatArray();
+
+                for (float value : buffer_data)
+                {
+                    m_channel_buffers[i].push(value);
+                }
+
+                m_samples_since_output[i] = static_cast<size_t>(d.readInt32());
+            }
+        }
+
     private:
         /**
          * Generate window function coefficients

package/src/native/adapters/VarianceStage.h

@@ -2,6 +2,7 @@
 
 #include "../IDspStage.h"
 #include "../core/MovingVarianceFilter.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <string>
 #include <stdexcept>
@@ -190,6 +191,64 @@ namespace dsp::adapters
             }
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeString(m_mode == VarianceMode::Moving ? "moving" : "batch");
+
+            if (m_mode == VarianceMode::Moving)
+            {
+                s.writeInt32(static_cast<int32_t>(m_window_size));
+                s.writeDouble(m_window_duration_ms);
+                s.writeBool(m_is_initialized);
+
+                s.writeInt32(static_cast<int32_t>(m_filters.size()));
+                for (const auto &filter : m_filters)
+                {
+                    auto [bufferData, sums] = filter.getState();
+                    auto [runningSum, runningSumOfSquares] = sums;
+                    s.writeFloatArray(bufferData);
+                    s.writeFloat(runningSum);
+                    s.writeFloat(runningSumOfSquares);
+                }
+            }
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            std::string modeStr = d.readString();
+            VarianceMode newMode = (modeStr == "moving") ? VarianceMode::Moving : VarianceMode::Batch;
+
+            if (newMode != m_mode)
+            {
+                throw std::runtime_error("Variance TOON load: mode mismatch");
+            }
+
+            if (m_mode == VarianceMode::Moving)
+            {
+                int32_t windowSize = d.readInt32();
+                if (windowSize != static_cast<int32_t>(m_window_size))
+                {
+                    throw std::runtime_error("Variance TOON load: window size mismatch");
+                }
+
+                d.readDouble(); // window_duration_ms
+                d.readBool();   // is_initialized
+
+                int32_t numChannels = d.readInt32();
+                m_filters.clear();
+                for (int32_t i = 0; i < numChannels; ++i)
+                {
+                    m_filters.emplace_back(m_window_size);
+
+                    std::vector<float> bufferData = d.readFloatArray();
+                    float runningSum = d.readFloat();
+                    float runningSumOfSquares = d.readFloat();
+
+                    m_filters[i].setState(bufferData, runningSum, runningSumOfSquares);
+                }
+            }
+        }
+
     private:
         /**
          * @brief Statelessly calculates the variance for each channel

package/src/native/adapters/WampStage.h

@@ -3,6 +3,7 @@
 #include "../IDspStage.h"
 #include "../core/WampFilter.h"
 #include "../utils/NapiUtils.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <string>
 #include <stdexcept>
@@ -105,6 +106,64 @@ namespace dsp::adapters
             }
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeInt32(static_cast<int32_t>(m_window_size));
+            s.writeFloat(m_threshold);
+            s.writeInt32(static_cast<int32_t>(m_filters.size()));
+
+            for (const auto &filter : m_filters)
+            {
+                auto [internalState, prevSample] = filter.getState();
+                auto [bufferData, runningCount] = internalState;
+
+                // Serialize bool vector as byte array
+                s.writeInt32(static_cast<int32_t>(bufferData.size()));
+                for (bool b : bufferData)
+                {
+                    s.writeBool(b);
+                }
+                s.writeInt32(static_cast<int32_t>(runningCount));
+                s.writeFloat(prevSample);
+            }
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            size_t windowSize = static_cast<size_t>(d.readInt32());
+            float threshold = d.readFloat();
+            if (windowSize != m_window_size || threshold != m_threshold)
+            {
+                throw std::runtime_error("WAMP TOON: parameter mismatch");
+            }
+
+            int32_t numChannels = d.readInt32();
+            m_filters.clear();
+            for (int32_t i = 0; i < numChannels; ++i)
+            {
+                m_filters.emplace_back(m_window_size, m_threshold);
+            }
+
+            for (auto &filter : m_filters)
+            {
+                int32_t bufSize = d.readInt32();
+                std::vector<bool> bufferData(bufSize);
+                for (int32_t j = 0; j < bufSize; ++j)
+                {
+                    bufferData[j] = d.readBool();
+                }
+                size_t runningCount = static_cast<size_t>(d.readInt32());
+                float prevSample = d.readFloat();
+
+                if (!dsp::core::CounterPolicy::validateState(runningCount, bufferData))
+                {
+                    throw std::runtime_error("WAMP TOON: validation failed");
+                }
+
+                filter.setState(bufferData, runningCount, prevSample);
+            }
+        }
+
     private:
         size_t m_window_size;
         float m_threshold;

package/src/native/adapters/WaveformLengthStage.h

@@ -3,6 +3,7 @@
 #include "../IDspStage.h"
 #include "../core/WaveformLengthFilter.h"
 #include "../utils/NapiUtils.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <string>
 #include <stdexcept>
@@ -107,6 +108,56 @@ namespace dsp::adapters
             }
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeInt32(static_cast<int32_t>(m_window_size));
+            s.writeInt32(static_cast<int32_t>(m_filters.size()));
+
+            for (const auto &filter : m_filters)
+            {
+                auto state = filter.getState();
+                const auto &internalState = state.first;
+                float prevSample = state.second;
+
+                const std::vector<float> &bufferData = internalState.first;
+                double runningSum = internalState.second;
+
+                s.writeFloatArray(bufferData);
+                s.writeDouble(runningSum);
+                s.writeFloat(prevSample);
+            }
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            size_t windowSize = static_cast<size_t>(d.readInt32());
+            if (windowSize != m_window_size)
+            {
+                throw std::runtime_error("WaveformLength TOON: window size mismatch");
+            }
+
+            int32_t numChannels = d.readInt32();
+            m_filters.clear();
+            for (int32_t i = 0; i < numChannels; ++i)
+            {
+                m_filters.emplace_back(m_window_size);
+            }
+
+            for (auto &filter : m_filters)
+            {
+                std::vector<float> bufferData = d.readFloatArray();
+                double runningSum = d.readDouble();
+                float prevSample = d.readFloat();
+
+                if (!dsp::core::SumPolicy<float>::validateState(runningSum, bufferData))
+                {
+                    throw std::runtime_error("WaveformLength TOON: validation failed");
+                }
+
+                filter.setState(bufferData, runningSum, prevSample);
+            }
+        }
+
     private:
         size_t m_window_size;
         std::vector<dsp::core::WaveformLengthFilter<float>> m_filters;

package/src/native/adapters/ZScoreNormalizeStage.h

@@ -2,6 +2,7 @@
 
 #include "../IDspStage.h"
 #include "../core/MovingZScoreFilter.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <string>
 #include <stdexcept>
@@ -195,6 +196,69 @@ namespace dsp::adapters
             }
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeString(m_mode == ZScoreNormalizeMode::Moving ? "moving" : "batch");
+
+            if (m_mode == ZScoreNormalizeMode::Moving)
+            {
+                s.writeInt32(static_cast<int32_t>(m_window_size));
+                s.writeDouble(m_window_duration_ms);
+                s.writeBool(m_is_initialized);
+                s.writeFloat(m_epsilon);
+
+                s.writeInt32(static_cast<int32_t>(m_filters.size()));
+                for (const auto &filter : m_filters)
+                {
+                    auto [bufferData, sums] = filter.getState();
+                    auto [runningSum, runningSumOfSquares] = sums;
+                    s.writeFloatArray(bufferData);
+                    s.writeFloat(runningSum);
+                    s.writeFloat(runningSumOfSquares);
+                    s.writeFloat(m_epsilon); // Store epsilon explicitly
+                }
+            }
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            std::string modeStr = d.readString();
+            ZScoreNormalizeMode newMode = (modeStr == "moving") ? ZScoreNormalizeMode::Moving : ZScoreNormalizeMode::Batch;
+
+            if (newMode != m_mode)
+            {
+                throw std::runtime_error("ZScore TOON load: mode mismatch");
+            }
+
+            if (m_mode == ZScoreNormalizeMode::Moving)
+            {
+                int32_t windowSize = d.readInt32();
+                if (windowSize != static_cast<int32_t>(m_window_size))
+                {
+                    throw std::runtime_error("ZScore TOON load: window size mismatch");
+                }
+
+                m_window_duration_ms = d.readDouble(); // restore duration
+                m_is_initialized = d.readBool();       // restore init flag
+                m_epsilon = d.readFloat();             // restore epsilon
+
+                int32_t numChannels = d.readInt32();
+                m_filters.clear();
+                for (int32_t i = 0; i < numChannels; ++i)
+                {
+                    m_filters.emplace_back(m_window_size, m_epsilon);
+
+                    std::vector<float> bufferData = d.readFloatArray();
+                    float runningSum = d.readFloat();
+                    float runningSumOfSquares = d.readFloat();
+                    d.readFloat(); // epsilon (already restored)
+
+                    // setState takes (buffer, sum, sumOfSquares) - 3 separate params
+                    m_filters[i].setState(bufferData, runningSum, runningSumOfSquares);
+                }
+            }
+        }
+
     private:
         /**
          * @brief Statelessly calculates the Z-Score for each sample

package/src/native/core/CumulativeMovingAverageFilter.h

@@ -0,0 +1,123 @@
+#pragma once
+#include "Policies.h"
+#include <vector>
+#include <stdexcept>
+
+namespace dsp::core
+{
+    /**
+     * @brief Implements a Cumulative Moving Average (CMA) filter.
+     *
+     * CMA is the average of all samples seen since initialization.
+     * Formula: CMA(n) = (CMA(n-1) * (n-1) + value(n)) / n
+     *          or: CMA(n) = sum(values[1..n]) / n
+     *
+     * Unlike simple moving average (SMA), CMA considers ALL historical data:
+     * - SMA: Uses fixed window of recent N samples
+     * - CMA: Uses all samples from start to current
+     *
+     * Properties:
+     * - Memory-efficient: Only stores running sum and count
+     * - Stable convergence: Influence of new samples decreases over time
+     * - No window size needed: Adapts to any data length
+     *
+     * Use cases:
+     * - Long-term averages where all history matters
+     * - Baseline estimation from calibration data
+     * - Online mean estimation for statistics
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double).
+     */
+    template <typename T>
+    class CumulativeMovingAverageFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new CMA Filter.
+         */
+        CumulativeMovingAverageFilter()
+            : m_policy()
+        {
+        }
+
+        // Delete copy constructor and copy assignment
+        CumulativeMovingAverageFilter(const CumulativeMovingAverageFilter &) = delete;
+        CumulativeMovingAverageFilter &operator=(const CumulativeMovingAverageFilter &) = delete;
+
+        // Enable move semantics
+        CumulativeMovingAverageFilter(CumulativeMovingAverageFilter &&) noexcept = default;
+        CumulativeMovingAverageFilter &operator=(CumulativeMovingAverageFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample and updates the CMA.
+         * @param newValue The new sample value.
+         * @return T The updated CMA value.
+         */
+        T addSample(T newValue)
+        {
+            m_policy.onAdd(newValue);
+            return m_policy.getResult(0); // Window count parameter unused for CMA
+        }
+
+        /**
+         * @brief Process array of samples in batch (optimized for throughput).
+         *
+         * @param input Input array of samples
+         * @param output Output array (same size as input)
+         * @param length Number of samples to process
+         */
+        void processArray(const T *input, T *output, size_t length)
+        {
+            for (size_t i = 0; i < length; ++i)
+            {
+                output[i] = addSample(input[i]);
+            }
+        }
+
+        /**
+         * @brief Gets the current CMA value.
+         * @return T The cumulative moving average.
+         */
+        T getCma() const { return m_policy.getResult(0); }
+
+        /**
+         * @brief Gets the number of samples processed.
+         * @return size_t The total count of samples.
+         */
+        size_t getCount() const { return m_policy.getCount(); }
+
+        /**
+         * @brief Clears the CMA state (resets to zero).
+         */
+        void clear() { m_policy.clear(); }
+
+        /**
+         * @brief Checks if any samples have been processed.
+         * @return true if count > 0, false otherwise.
+         */
+        bool hasData() const { return m_policy.getCount() > 0; }
+
+        /**
+         * @brief Exports the filter's internal state.
+         * @return A pair containing the running sum and sample count.
+         */
+        std::pair<T, size_t> getState() const
+        {
+            return m_policy.getState();
+        }
+
+        /**
+         * @brief Restores the filter's internal state.
+         * @param sum The running sum to restore.
+         * @param count The sample count to restore.
+         */
+        void setState(T sum, size_t count)
+        {
+            m_policy.setState(sum, count);
+        }
+
+    private:
+        CmaPolicy<T> m_policy;
+    };
+
+} // namespace dsp::core

package/src/native/core/ExponentialMovingAverageFilter.h

@@ -0,0 +1,129 @@
+#pragma once
+#include "Policies.h"
+#include <vector>
+#include <stdexcept>
+
+namespace dsp::core
+{
+    /**
+     * @brief Implements an Exponential Moving Average (EMA) filter.
+     *
+     * EMA gives more weight to recent samples and exponentially decaying weight to older samples.
+     * Formula: EMA(t) = α * value(t) + (1 - α) * EMA(t-1)
+     *
+     * where α (alpha) is the smoothing factor:
+     * - α close to 1: Fast response to changes (less smoothing)
+     * - α close to 0: Slow response to changes (more smoothing)
+     *
+     * Common conversions:
+     * - From N-period SMA: α = 2 / (N + 1)
+     * - From time constant: α = 1 - exp(-Δt / τ)
+     *
+     * Unlike simple moving average, EMA does not require a fixed window size,
+     * making it memory-efficient for very long averaging periods.
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double).
+     */
+    template <typename T>
+    class ExponentialMovingAverageFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new EMA Filter with specified alpha.
+         * @param alpha The smoothing factor (0 < α ≤ 1).
+         * @throws std::invalid_argument if alpha is outside valid range.
+         */
+        explicit ExponentialMovingAverageFilter(T alpha)
+            : m_policy(alpha)
+        {
+            if (alpha <= 0 || alpha > 1)
+            {
+                throw std::invalid_argument("EMA alpha must be in range (0, 1]");
+            }
+        }
+
+        // Delete copy constructor and copy assignment
+        ExponentialMovingAverageFilter(const ExponentialMovingAverageFilter &) = delete;
+        ExponentialMovingAverageFilter &operator=(const ExponentialMovingAverageFilter &) = delete;
+
+        // Enable move semantics
+        ExponentialMovingAverageFilter(ExponentialMovingAverageFilter &&) noexcept = default;
+        ExponentialMovingAverageFilter &operator=(ExponentialMovingAverageFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample and updates the EMA.
+         * @param newValue The new sample value.
+         * @return T The updated EMA value.
+         */
+        T addSample(T newValue)
+        {
+            m_policy.onAdd(newValue);
+            return m_policy.getResult(0); // Count parameter unused for EMA
+        }
+
+        /**
+         * @brief Process array of samples in batch (optimized for throughput).
+         *
+         * @param input Input array of samples
+         * @param output Output array (same size as input)
+         * @param length Number of samples to process
+         */
+        void processArray(const T *input, T *output, size_t length)
+        {
+            for (size_t i = 0; i < length; ++i)
+            {
+                output[i] = addSample(input[i]);
+            }
+        }
+
+        /**
+         * @brief Gets the current EMA value.
+         * @return T The current exponential moving average.
+         */
+        T getEma() const { return m_policy.getResult(0); }
+
+        /**
+         * @brief Gets the alpha (smoothing factor).
+         * @return T The alpha value.
+         */
+        T getAlpha() const { return m_policy.getAlpha(); }
+
+        /**
+         * @brief Clears the EMA state.
+         */
+        void clear() { m_policy.clear(); }
+
+        /**
+         * @brief Checks if the filter has been initialized with at least one sample.
+         * @return true if initialized, false otherwise.
+         */
+        bool isInitialized() const
+        {
+            auto [ema, initialized] = m_policy.getState();
+            return initialized;
+        }
+
+        /**
+         * @brief Exports the filter's internal state.
+         * @return A pair containing the current EMA value and initialization flag.
+         */
+        std::pair<T, bool> getState() const
+        {
+            return m_policy.getState();
+        }
+
+        /**
+         * @brief Restores the filter's internal state.
+         * @param ema The EMA value to restore.
+         * @param initialized The initialization flag to restore.
+         */
+        void setState(T ema, bool initialized)
+        {
+            m_policy.setState(ema, initialized);
+        }
+
+    private:
+        EmaPolicy<T> m_policy;
+    };
+
+} // namespace dsp::core