dspx 1.1.5 → 1.2.3

package/src/native/adapters/PeakDetectionStage.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "../IDspStage.h"
+#include "../core/PeakDetection.h"
 #include <cmath>
 #include <stdexcept>
 #include <string>
@@ -11,34 +12,52 @@ namespace dsp::adapters
     /**
      * @brief Peak Detection Stage - Detects local maxima in a signal.
      *
-     * This stage identifies peaks (local maxima) in the input signal using a simple
-     * three-point comparison method. A peak is detected when:
-     * 1. The previous sample is greater than the sample before it
-     * 2. The previous sample is greater than the current sample
-     * 3. The previous sample exceeds the threshold
+     * ... (docs updated) ...
      *
-     * **Use Cases:**
-     * - Heart rate detection (R-peaks in ECG)
-     * - Event detection in sensor data
-     * - Tempo detection in audio
-     * - Spike detection in neural recordings
-     *
-     * **Output:**
-     * - 1.0 at peak locations
-     * - 0.0 elsewhere
-     *
-     * **State:** Maintains 2 previous samples per channel for continuity
+     * **Parameters:**
+     * - threshold: Minimum value for a peak.
+     * - mode: 'moving' (stateful) or 'batch' (stateless).
+     * - domain: 'time' or 'frequency'.
+     * - windowSize: (Batch mode only) Local neighborhood size (odd, >= 3). Default 3.
+     * - minPeakDistance: Minimum samples between peaks. Default 1.
      */
     class PeakDetectionStage : public IDspStage
     {
     public:
-        explicit PeakDetectionStage(float threshold)
-            : m_threshold(threshold), m_num_channels(0)
+        explicit PeakDetectionStage(float threshold, std::string mode = "moving", std::string domain = "time", int windowSize = 3, int minPeakDistance = 1)
+            : m_threshold(threshold),
+              m_mode(std::move(mode)),
+              m_domain(std::move(domain)),
+              m_windowSize(windowSize),
+              m_minPeakDistance(minPeakDistance),
+              m_num_channels(0)
         {
             if (threshold < 0.0f)
             {
                 throw std::invalid_argument("PeakDetection: threshold must be >= 0");
             }
+            if (m_mode != "moving" && m_mode != "batch")
+            {
+                throw std::invalid_argument("PeakDetection: mode must be 'moving' or 'batch'");
+            }
+            if (m_domain != "time" && m_domain != "frequency")
+            {
+                throw std::invalid_argument("PeakDetection: domain must be 'time' or 'frequency'");
+            }
+            if (windowSize < 3 || windowSize % 2 == 0)
+            {
+                throw std::invalid_argument("PeakDetection: windowSize must be an odd number >= 3");
+            }
+            if (minPeakDistance < 1)
+            {
+                throw std::invalid_argument("PeakDetection: minPeakDistance must be >= 1");
+            }
+
+            // In moving mode, we only support the 3-point window
+            if (m_mode == "moving")
+            {
+                m_windowSize = 3;
+            }
         }
 
         const char *getType() const override
@@ -48,77 +67,43 @@ namespace dsp::adapters
 
         void process(float *buffer, size_t numSamples, int numChannels, const float *timestamps = nullptr) override
         {
-            if (m_num_channels != numChannels || m_prev_sample.empty())
+            if (m_mode == "moving")
             {
-                m_num_channels = numChannels;
-                m_prev_sample.resize(numChannels, 0.0f);
-                m_prev_prev_sample.resize(numChannels, 0.0f);
+                // Note: processMoving implicitly uses m_windowSize = 3
+                processMoving(buffer, numSamples, numChannels);
             }
-
-            size_t samplesPerChannel = numSamples / numChannels;
-
-            for (int ch = 0; ch < numChannels; ++ch)
+            else // m_mode == "batch"
             {
-                float prev_prev = m_prev_prev_sample[ch];
-                float prev = m_prev_sample[ch];
-
-                for (size_t i = 0; i < samplesPerChannel; ++i)
-                {
-                    size_t idx = i * numChannels + ch;
-                    float current = buffer[idx];
-
-                    // Check if `prev` (the previous sample) was a peak
-                    // We can now confirm this since we have the current sample
-                    bool prev_is_peak = (prev > prev_prev) && (prev > current) && (prev >= m_threshold);
-
-                    if (i > 0)
-                    {
-                        // Write peak marker BACK to the previous sample's position
-                        buffer[idx - numChannels] = prev_is_peak ? 1.0f : 0.0f;
-                    }
-                    else
-                    {
-                        // For the first sample, we mark it if the prev (from previous process call) was a peak
-                        buffer[idx] = prev_is_peak ? 1.0f : 0.0f;
-                    }
-
-                    // Shift history forward
-                    prev_prev = prev;
-                    prev = current;
-                }
-
-                // The last sample in the buffer can't be confirmed as a peak yet
-                // (we need to see the next sample), so set it to 0
-                // BUT: Don't overwrite if there's only 1 sample and we just wrote the pending result at i==0
-                if (samplesPerChannel > 1)
-                {
-                    buffer[(samplesPerChannel - 1) * numChannels + ch] = 0.0f;
-                }
-
-                // Save state for next process call
-                m_prev_prev_sample[ch] = prev_prev;
-                m_prev_sample[ch] = prev;
+                processBatch(buffer, numSamples, numChannels);
             }
         }
+
         Napi::Object serializeState(Napi::Env env) const override
         {
             Napi::Object state = Napi::Object::New(env);
             state.Set("threshold", m_threshold);
             state.Set("numChannels", m_num_channels);
+            state.Set("mode", m_mode);
+            state.Set("domain", m_domain);
+            state.Set("windowSize", m_windowSize);
+            state.Set("minPeakDistance", m_minPeakDistance);
 
-            if (!m_prev_sample.empty())
+            if (m_mode == "moving" && !m_prev_sample.empty())
             {
                 Napi::Array prevArray = Napi::Array::New(env, m_prev_sample.size());
                 Napi::Array prevPrevArray = Napi::Array::New(env, m_prev_prev_sample.size());
+                Napi::Array cooldownArray = Napi::Array::New(env, m_peakCooldown.size());
 
                 for (size_t i = 0; i < m_prev_sample.size(); ++i)
                 {
                     prevArray.Set(i, m_prev_sample[i]);
                     prevPrevArray.Set(i, m_prev_prev_sample[i]);
+                    cooldownArray.Set(i, m_peakCooldown[i]);
                 }
 
                 state.Set("prevSample", prevArray);
                 state.Set("prevPrevSample", prevPrevArray);
+                state.Set("peakCooldown", cooldownArray);
             }
 
             return state;
@@ -130,19 +115,30 @@ namespace dsp::adapters
                 m_threshold = state.Get("threshold").As<Napi::Number>().FloatValue();
             if (state.Has("numChannels"))
                 m_num_channels = state.Get("numChannels").As<Napi::Number>().Int32Value();
+            if (state.Has("mode"))
+                m_mode = state.Get("mode").As<Napi::String>().Utf8Value();
+            if (state.Has("domain"))
+                m_domain = state.Get("domain").As<Napi::String>().Utf8Value();
+            if (state.Has("windowSize"))
+                m_windowSize = state.Get("windowSize").As<Napi::Number>().Int32Value();
+            if (state.Has("minPeakDistance"))
+                m_minPeakDistance = state.Get("minPeakDistance").As<Napi::Number>().Int32Value();
 
-            if (state.Has("prevSample"))
+            if (m_mode == "moving" && state.Has("prevSample"))
             {
                 Napi::Array prevArray = state.Get("prevSample").As<Napi::Array>();
                 Napi::Array prevPrevArray = state.Get("prevPrevSample").As<Napi::Array>();
+                Napi::Array cooldownArray = state.Get("peakCooldown").As<Napi::Array>();
 
                 m_prev_sample.clear();
                 m_prev_prev_sample.clear();
+                m_peakCooldown.clear();
 
                 for (size_t i = 0; i < prevArray.Length(); ++i)
                 {
                     m_prev_sample.push_back(prevArray.Get(i).As<Napi::Number>().FloatValue());
                     m_prev_prev_sample.push_back(prevPrevArray.Get(i).As<Napi::Number>().FloatValue());
+                    m_peakCooldown.push_back(cooldownArray.Get(i).As<Napi::Number>().Int32Value());
                 }
             }
         }
@@ -151,15 +147,132 @@ namespace dsp::adapters
         {
             std::fill(m_prev_sample.begin(), m_prev_sample.end(), 0.0f);
             std::fill(m_prev_prev_sample.begin(), m_prev_prev_sample.end(), 0.0f);
+            std::fill(m_peakCooldown.begin(), m_peakCooldown.end(), 0);
         }
 
         bool isResizing() const override { return false; }
 
     private:
+        /**
+         * @brief Stateful ("moving") peak detection processing (WindowSize = 3 only).
+         */
+        void processMoving(float *buffer, size_t numSamples, int numChannels)
+        {
+            if (m_num_channels != numChannels || m_prev_sample.empty())
+            {
+                m_num_channels = numChannels;
+                m_prev_sample.resize(numChannels, 0.0f);
+                m_prev_prev_sample.resize(numChannels, 0.0f);
+                m_peakCooldown.resize(numChannels, 0); // Resize cooldown state
+            }
+
+            size_t samplesPerChannel = numSamples / numChannels;
+
+            for (int ch = 0; ch < numChannels; ++ch)
+            {
+                float prev_prev = m_prev_prev_sample[ch];
+                float prev = m_prev_sample[ch];
+                int &cooldown = m_peakCooldown[ch]; // Get reference to cooldown counter
+
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    size_t idx = i * numChannels + ch;
+                    float current = buffer[idx];
+
+                    // Decrement cooldown if active
+                    if (cooldown > 0)
+                    {
+                        cooldown--;
+                    }
+
+                    // Check if `prev` (the previous sample) was a peak
+                    bool prev_is_peak = (cooldown == 0) && // Must not be in cooldown
+                                        (prev > prev_prev) &&
+                                        (prev > current) &&
+                                        (prev >= m_threshold);
+
+                    if (i > 0)
+                    {
+                        buffer[idx - numChannels] = prev_is_peak ? 1.0f : 0.0f;
+                    }
+                    else
+                    {
+                        buffer[idx] = prev_is_peak ? 1.0f : 0.0f;
+                    }
+
+                    // If we found a peak, reset the cooldown
+                    if (prev_is_peak)
+                    {
+                        cooldown = m_minPeakDistance - 1;
+                    }
+
+                    // Shift history forward
+                    prev_prev = prev;
+                    prev = current;
+                }
+
+                if (samplesPerChannel > 1)
+                {
+                    buffer[(samplesPerChannel - 1) * numChannels + ch] = 0.0f;
+                }
+
+                m_prev_prev_sample[ch] = prev_prev;
+                m_prev_sample[ch] = prev;
+            }
+        }
+
+        /**
+         * @brief Stateless ("batch") peak detection processing.
+         */
+        void processBatch(float *buffer, size_t numSamples, int numChannels)
+        {
+            if (m_planar_input.size() < numSamples / numChannels)
+            {
+                m_planar_input.resize(numSamples / numChannels);
+                m_planar_output.resize(numSamples / numChannels);
+            }
+
+            size_t samplesPerChannel = numSamples / numChannels;
+
+            // Select the correct core function
+            void (*peak_func)(const float *, float *, size_t, float, int, int) =
+                (m_domain == "frequency")
+                    ? dsp::core::find_freq_peaks_batch
+                    : dsp::core::find_peaks_batch_delayed;
+
+            for (int ch = 0; ch < numChannels; ++ch)
+            {
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    m_planar_input[i] = buffer[i * numChannels + ch];
+                }
+
+                // Process using the core function, passing all parameters
+                peak_func(m_planar_input.data(), m_planar_output.data(), samplesPerChannel, m_threshold, m_windowSize, m_minPeakDistance);
+
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    buffer[i * numChannels + ch] = m_planar_output[i];
+                }
+            }
+        }
+
+        // --- Member Variables ---
         float m_threshold;
+        std::string m_mode;
+        std::string m_domain;
+        int m_windowSize;
+        int m_minPeakDistance;
         int m_num_channels;
+
+        // State for "moving" mode
         std::vector<float> m_prev_sample;
         std::vector<float> m_prev_prev_sample;
+        std::vector<int> m_peakCooldown; // Cooldown counter per channel
+
+        // Temporary planar buffers for "batch" mode
+        std::vector<float> m_planar_input;
+        std::vector<float> m_planar_output;
     };
 
-} // namespace dsp::adapters
+} // namespace dsp::adapters

package/src/native/core/PeakDetection.h

@@ -0,0 +1,225 @@
+#pragma once
+
+#include <cmath>
+#include <cstddef>
+#include <vector>
+#include <algorithm>
+#include "../utils/SimdOps.h"
+
+namespace dsp::core
+{
+    /**
+     * @brief Post-processing pass to enforce minimum peak distance.
+     * Modifies the output buffer in-place.
+     */
+    inline void apply_min_peak_distance(float *output, size_t size, int minPeakDistance)
+    {
+        if (minPeakDistance <= 1)
+        {
+            return;
+        }
+
+        int cooldown = 0;
+        for (size_t i = 0; i < size; ++i)
+        {
+            if (output[i] == 1.0f)
+            {
+                if (cooldown == 0)
+                {
+                    // This is a valid peak, start cooldown
+                    cooldown = minPeakDistance - 1;
+                }
+                else
+                {
+                    // This peak is suppressed
+                    output[i] = 0.0f;
+                    cooldown--; // Still decrement cooldown
+                }
+            }
+            else if (cooldown > 0)
+            {
+                cooldown--;
+            }
+        }
+    }
+
+    /**
+     * @brief Scalar (flexible) delayed peak detection.
+     * This is the fallback for windowSize != 3.
+     */
+    inline void find_peaks_batch_scalar_delayed(const float *input, float *output, size_t size, float threshold, int windowSize)
+    {
+        // We check a peak at [i-k] when we see sample [i].
+        // This maintains the "delayed" logic.
+        const int k = (windowSize - 1) / 2;
+        const int end_idx = windowSize - 1;
+
+        if (size < windowSize)
+        {
+            return; // Not enough samples
+        }
+
+        for (size_t i = end_idx; i < size; ++i)
+        {
+            const size_t peak_idx = i - k; // The candidate peak index
+            const float candidate = input[peak_idx];
+
+            if (candidate < threshold)
+            {
+                output[peak_idx] = 0.0f;
+                continue;
+            }
+
+            bool is_max = true;
+            // Check all neighbors from [i-k-k] to [i-k+k] (which is [i-end_idx] to [i])
+            for (int j = -k; j <= k; ++j)
+            {
+                if (j == 0)
+                    continue; // Don't compare to self
+
+                if (candidate <= input[peak_idx + j])
+                {
+                    is_max = false;
+                    break;
+                }
+            }
+
+            output[peak_idx] = is_max ? 1.0f : 0.0f;
+        }
+    }
+
+    /**
+     * @brief Stateless (batch) peak detection using the 3-point delayed method.
+     *
+     * Finds local maxima in a buffer.
+     *
+     * @param input The input signal buffer.
+     * @param output The output buffer (will be filled with 1.0 at peaks, 0.0 otherwise).
+     * @param size The number of samples in the input/output buffers.
+     * @param threshold The minimum value for a peak to be considered.
+     * @param windowSize The local neighborhood size (must be odd, >= 3).
+     * @param minPeakDistance The minimum samples between peaks.
+     *
+     * @note Output edges (0..k and size-k..size) will be 0.
+     */
+    inline void find_peaks_batch_delayed(const float *input, float *output, size_t size, float threshold, int windowSize, int minPeakDistance)
+    {
+        // Initialize output to 0.0
+        std::fill(output, output + size, 0.0f);
+
+        if (windowSize < 3 || windowSize % 2 == 0)
+        {
+            return; // Invalid window size
+        }
+
+        if (size < windowSize)
+        {
+            return; // Not enough samples
+        }
+
+        if (windowSize == 3)
+        {
+            // --- Optimized SIMD Path for windowSize = 3 ---
+            size_t i = 2;
+
+#if defined(SIMD_AVX2)
+            const size_t simd_width = 8;
+            const size_t simd_limit = (size >= simd_width + 2) ? (size - simd_width) : 0;
+            const __m256 v_thresh = _mm256_set1_ps(threshold);
+            const __m256 v_ones = _mm256_set1_ps(1.0f);
+
+            for (i = 2; i <= simd_limit; i += simd_width)
+            {
+                __m256 v_prev_prev = _mm256_loadu_ps(&input[i - 2]);
+                __m256 v_prev = _mm256_loadu_ps(&input[i - 1]);
+                __m256 v_current = _mm256_loadu_ps(&input[i]);
+
+                __m256 mask1 = _mm256_cmp_ps(v_prev, v_prev_prev, _CMP_GT_OQ);
+                __m256 mask2 = _mm256_cmp_ps(v_prev, v_current, _CMP_GT_OQ);
+                __m256 mask3 = _mm256_cmp_ps(v_prev, v_thresh, _CMP_GE_OQ);
+
+                __m256 mask = _mm256_and_ps(_mm256_and_ps(mask1, mask2), mask3);
+                __m256 v_result = _mm256_and_ps(mask, v_ones);
+                _mm256_storeu_ps(&output[i - 1], v_result);
+            }
+#elif defined(SIMD_SSE2)
+            // ... (Same SSE2 logic as before) ...
+            const size_t simd_width = 4;
+            const size_t simd_limit = (size >= simd_width + 2) ? (size - simd_width) : 0;
+            const __m128 v_thresh = _mm_set1_ps(threshold);
+            const __m128 v_ones = _mm_set1_ps(1.0f);
+
+            for (i = 2; i <= simd_limit; i += simd_width)
+            {
+                __m128 v_prev_prev = _mm_loadu_ps(&input[i - 2]);
+                __m128 v_prev = _mm_loadu_ps(&input[i - 1]);
+                __m128 v_current = _mm_loadu_ps(&input[i]);
+
+                __m128 mask1 = _mm_cmpgt_ps(v_prev, v_prev_prev);
+                __m128 mask2 = _mm_cmpgt_ps(v_prev, v_current);
+                __m128 mask3 = _mm_cmpge_ps(v_prev, v_thresh);
+
+                __m128 mask = _mm_and_ps(_mm_and_ps(mask1, mask2), mask3);
+                __m128 v_result = _mm_and_ps(mask, v_ones);
+                _mm_storeu_ps(&output[i - 1], v_result);
+            }
+#elif defined(SIMD_NEON)
+            // ... (Same NEON logic as before) ...
+            const size_t simd_width = 4;
+            const size_t simd_limit = (size >= simd_width + 2) ? (size - simd_width) : 0;
+            const float32x4_t v_thresh = vdupq_n_f32(threshold);
+            const float32x4_t v_ones = vdupq_n_f32(1.0f);
+            const float32x4_t v_zeros = vdupq_n_f32(0.0f);
+
+            for (i = 2; i <= simd_limit; i += simd_width)
+            {
+                float32x4_t v_prev_prev = vld1q_f32(&input[i - 2]);
+                float32x4_t v_prev = vld1q_f32(&input[i - 1]);
+                float32x4_t v_current = vld1q_f32(&input[i]);
+
+                uint32x4_t mask1 = vcgtq_f32(v_prev, v_prev_prev);
+                uint32x4_t mask2 = vcgtq_f32(v_prev, v_current);
+                uint32x4_t mask3 = vcgeq_f32(v_prev, v_thresh);
+
+                uint32x4_t mask = vandq_u32(vandq_u32(mask1, mask2), mask3);
+                float32x4_t v_result = vbslq_f32(mask, v_ones, v_zeros);
+                vst1q_f32(&output[i - 1], v_result);
+            }
+#endif
+            // Handle remainder for windowSize = 3
+            for (; i < size; ++i)
+            {
+                const float prev_prev = input[i - 2];
+                const float prev = input[i - 1];
+                const float current = input[i];
+
+                bool prev_is_peak = (prev > prev_prev) && (prev > current) && (prev >= threshold);
+                if (prev_is_peak)
+                {
+                    output[i - 1] = 1.0f;
+                }
+            }
+        }
+        else
+        {
+            // --- Scalar Fallback Path for windowSize != 3 ---
+            find_peaks_batch_scalar_delayed(input, output, size, threshold, windowSize);
+        }
+
+        // --- Post-processing for Minimum Peak Distance ---
+        if (minPeakDistance > 1)
+        {
+            apply_min_peak_distance(output, size, minPeakDistance);
+        }
+    }
+
+    /**
+     * @brief Stateless (batch) peak detection for frequency domain.
+     */
+    inline void find_freq_peaks_batch(const float *input, float *output, size_t size, float threshold, int windowSize, int minPeakDistance)
+    {
+        // The algorithm is identical to the time-domain batch version.
+        find_peaks_batch_delayed(input, output, size, threshold, windowSize, minPeakDistance);
+    }
+
+} // namespace dsp::core