dspx 0.1.1-alpha.0

package/src/ts/examples/emg-features-example.ts

@@ -0,0 +1,284 @@
+/**
+ * EMG Feature Extraction Example
+ *
+ * Demonstrates how to use SSC, WAMP, and Waveform Length together
+ * for comprehensive EMG signal analysis.
+ *
+ * These features are commonly used in:
+ * - Muscle activity detection
+ * - Gesture recognition
+ * - Prosthetic control
+ * - Rehabilitation monitoring
+ */
+
+import { createDspPipeline } from "../bindings";
+
+async function emgFeaturesExample() {
+  console.log("=== EMG Feature Extraction Example ===\n");
+
+  // Example 1: Individual Feature Analysis
+  console.log("Example 1: Computing Individual EMG Features\n");
+
+  // Create pipelines for each feature
+  const sscPipeline = createDspPipeline();
+  const wampPipeline = createDspPipeline();
+  const wlPipeline = createDspPipeline();
+
+  // Window size: 250 samples (typical for EMG at 1kHz = 250ms window)
+  const windowSize = 250;
+
+  sscPipeline.SlopeSignChange({
+    windowSize,
+    threshold: 0.01, // Small threshold to filter noise
+  });
+
+  wampPipeline.WillisonAmplitude({
+    windowSize,
+    threshold: 0.05, // Threshold for significant amplitude changes
+  });
+
+  wlPipeline.WaveformLength({
+    windowSize,
+  });
+
+  // Generate synthetic EMG-like signal (burst of activity)
+  const signal = new Float32Array(500);
+  for (let i = 0; i < 500; i++) {
+    // Resting phase (0-150)
+    if (i < 150) {
+      signal[i] = (Math.random() - 0.5) * 0.02; // Low noise
+    }
+    // Active phase (150-350)
+    else if (i < 350) {
+      const envelope = Math.sin(((i - 150) * Math.PI) / 200); // Smooth envelope
+      signal[i] = envelope * Math.sin(i * 0.5) + (Math.random() - 0.5) * 0.1;
+    }
+    // Recovery phase (350-500)
+    else {
+      signal[i] = (Math.random() - 0.5) * 0.03; // Low noise
+    }
+  }
+
+  // Process with each feature extractor
+  const sscResult = new Float32Array(signal);
+  const wampResult = new Float32Array(signal);
+  const wlResult = new Float32Array(signal);
+
+  await sscPipeline.process(sscResult, { channels: 1 });
+  await wampPipeline.process(wampResult, { channels: 1 });
+  await wlPipeline.process(wlResult, { channels: 1 });
+
+  // Analyze features at different phases
+  const restingIdx = 200; // Middle of resting phase
+  const activeIdx = 250; // Middle of active phase
+  const recoveryIdx = 400; // Middle of recovery phase
+
+  console.log("Resting Phase (low activity):");
+  console.log(`  SSC: ${sscResult[restingIdx].toFixed(2)}`);
+  console.log(`  WAMP: ${wampResult[restingIdx].toFixed(2)}`);
+  console.log(`  WL: ${wlResult[restingIdx].toFixed(4)}\n`);
+
+  console.log("Active Phase (high activity):");
+  console.log(`  SSC: ${sscResult[activeIdx].toFixed(2)}`);
+  console.log(`  WAMP: ${wampResult[activeIdx].toFixed(2)}`);
+  console.log(`  WL: ${wlResult[activeIdx].toFixed(4)}\n`);
+
+  console.log("Recovery Phase (returning to rest):");
+  console.log(`  SSC: ${sscResult[recoveryIdx].toFixed(2)}`);
+  console.log(`  WAMP: ${wampResult[recoveryIdx].toFixed(2)}`);
+  console.log(`  WL: ${wlResult[recoveryIdx].toFixed(4)}\n`);
+
+  // Example 2: Multi-Channel EMG (e.g., multiple muscles)
+  console.log("Example 2: Multi-Channel EMG Analysis\n");
+
+  const multiPipeline = createDspPipeline();
+  multiPipeline.SlopeSignChange({
+    windowSize: 200,
+    threshold: 0.01,
+  });
+
+  // 3 channels representing different muscles
+  const numChannels = 3;
+  const numSamples = 300;
+  const multiSignal = new Float32Array(numSamples * numChannels);
+
+  for (let i = 0; i < numSamples; i++) {
+    // Channel 0: Biceps (active early)
+    const bicepsActivity = i < 150 ? Math.sin(i * 0.3) * (i / 150) : 0.1;
+    multiSignal[i * numChannels] =
+      bicepsActivity + (Math.random() - 0.5) * 0.05;
+
+    // Channel 1: Triceps (active later)
+    const tricepsActivity =
+      i > 150 ? Math.sin(i * 0.3) * ((numSamples - i) / 150) : 0.1;
+    multiSignal[i * numChannels + 1] =
+      tricepsActivity + (Math.random() - 0.5) * 0.05;
+
+    // Channel 2: Forearm (continuously active)
+    const forearmActivity = Math.sin(i * 0.2) * 0.5;
+    multiSignal[i * numChannels + 2] =
+      forearmActivity + (Math.random() - 0.5) * 0.03;
+  }
+
+  await multiPipeline.process(multiSignal, { channels: numChannels });
+
+  // Extract features at a specific time point
+  const timeIdx = 250;
+  console.log(`SSC at sample ${timeIdx}:`);
+  console.log(
+    `  Biceps (Ch0): ${multiSignal[timeIdx * numChannels].toFixed(2)}`
+  );
+  console.log(
+    `  Triceps (Ch1): ${multiSignal[timeIdx * numChannels + 1].toFixed(2)}`
+  );
+  console.log(
+    `  Forearm (Ch2): ${multiSignal[timeIdx * numChannels + 2].toFixed(2)}\n`
+  );
+
+  // Example 3: Real-time Feature Extraction with Buffering
+  console.log("Example 3: Real-time Processing Simulation\n");
+
+  const realtimePipeline = createDspPipeline();
+  realtimePipeline.Rectify({ mode: "full" });
+  realtimePipeline.WillisonAmplitude({
+    windowSize: 100,
+    threshold: 0.05,
+  });
+
+  console.log("Processing 5 consecutive batches of 50 samples each:");
+
+  for (let batch = 0; batch < 5; batch++) {
+    const batchData = new Float32Array(50);
+
+    // Simulate different activity levels per batch
+    const intensity = batch === 2 ? 1.5 : 0.5; // High activity in batch 2
+
+    for (let i = 0; i < 50; i++) {
+      batchData[i] =
+        Math.sin(i * 0.4) * intensity + (Math.random() - 0.5) * 0.1;
+    }
+
+    await realtimePipeline.process(batchData, { channels: 1 });
+
+    // Get the last value (most recent feature value)
+    const currentFeature = batchData[batchData.length - 1];
+    console.log(`  Batch ${batch + 1}: WAMP = ${currentFeature.toFixed(2)}`);
+  }
+
+  console.log();
+
+  // Example 4: Feature-based Activity Detection
+  console.log("Example 4: Activity Detection Threshold\n");
+
+  const detectorPipeline = createDspPipeline();
+  detectorPipeline.WaveformLength({ windowSize: 150 });
+
+  const testSignal = new Float32Array(400);
+  for (let i = 0; i < 400; i++) {
+    // Simulate muscle contraction from sample 150-250
+    const isActive = i >= 150 && i <= 250;
+    const amplitude = isActive ? 1.0 : 0.1;
+    testSignal[i] =
+      Math.sin(i * 0.3) * amplitude + (Math.random() - 0.5) * 0.05;
+  }
+
+  await detectorPipeline.process(testSignal, { channels: 1 });
+
+  // Define threshold for activity detection
+  const activityThreshold = 5.0;
+
+  let activityStart = -1;
+  let activityEnd = -1;
+
+  for (let i = 0; i < testSignal.length; i++) {
+    if (testSignal[i] > activityThreshold && activityStart === -1) {
+      activityStart = i;
+    }
+    if (
+      testSignal[i] < activityThreshold &&
+      activityStart !== -1 &&
+      activityEnd === -1
+    ) {
+      activityEnd = i;
+    }
+  }
+
+  console.log(
+    `Activity detected from sample ${activityStart} to ${activityEnd}`
+  );
+  console.log(`Duration: ${activityEnd - activityStart} samples`);
+  console.log(`Expected activity: samples 150-250\n`);
+
+  // Example 5: Feature Comparison for Classification
+  console.log("Example 5: Feature Vector for Classification\n");
+
+  const featurePipeline1 = createDspPipeline();
+  const featurePipeline2 = createDspPipeline();
+  const featurePipeline3 = createDspPipeline();
+
+  featurePipeline1.SlopeSignChange({
+    windowSize: 200,
+    threshold: 0,
+  });
+  featurePipeline2.WillisonAmplitude({
+    windowSize: 200,
+    threshold: 0.03,
+  });
+  featurePipeline3.WaveformLength({ windowSize: 200 });
+
+  // Two different gesture patterns
+  const gesture1 = new Float32Array(300);
+  const gesture2 = new Float32Array(300);
+
+  // Gesture 1: Fast oscillation
+  for (let i = 0; i < 300; i++) {
+    gesture1[i] = Math.sin(i * 0.5) * 0.8;
+  }
+
+  // Gesture 2: Slow oscillation with bursts
+  for (let i = 0; i < 300; i++) {
+    const burst = Math.floor(i / 60) % 2 === 0 ? 1.0 : 0.3;
+    gesture2[i] = Math.sin(i * 0.1) * burst;
+  }
+
+  // Process each gesture
+  const g1ssc = new Float32Array(gesture1);
+  const g1wamp = new Float32Array(gesture1);
+  const g1wl = new Float32Array(gesture1);
+
+  await featurePipeline1.process(g1ssc, { channels: 1 });
+  await featurePipeline2.process(g1wamp, { channels: 1 });
+  await featurePipeline3.process(g1wl, { channels: 1 });
+
+  featurePipeline1.clearState();
+  featurePipeline2.clearState();
+  featurePipeline3.clearState();
+
+  const g2ssc = new Float32Array(gesture2);
+  const g2wamp = new Float32Array(gesture2);
+  const g2wl = new Float32Array(gesture2);
+
+  await featurePipeline1.process(g2ssc, { channels: 1 });
+  await featurePipeline2.process(g2wamp, { channels: 1 });
+  await featurePipeline3.process(g2wl, { channels: 1 });
+
+  // Extract features at middle of signals
+  const midIdx = 250;
+
+  console.log("Gesture 1 (fast oscillation) features:");
+  console.log(`  SSC: ${g1ssc[midIdx].toFixed(2)}`);
+  console.log(`  WAMP: ${g1wamp[midIdx].toFixed(2)}`);
+  console.log(`  WL: ${g1wl[midIdx].toFixed(4)}\n`);
+
+  console.log("Gesture 2 (slow with bursts) features:");
+  console.log(`  SSC: ${g2ssc[midIdx].toFixed(2)}`);
+  console.log(`  WAMP: ${g2wamp[midIdx].toFixed(2)}`);
+  console.log(`  WL: ${g2wl[midIdx].toFixed(4)}\n`);
+
+  console.log("These feature vectors can be used for ML classification!\n");
+
+  console.log("=== Example Complete ===");
+}
+
+// Run the example
+emgFeaturesExample().catch(console.error);

package/src/ts/examples/fft-example.ts

@@ -0,0 +1,309 @@
+/**
+ * FFT/DFT Examples
+ *
+ * Demonstrates all 8 transforms and common use cases
+ */
+
+import {
+  FftProcessor,
+  MovingFftProcessor,
+  FftUtils,
+  type ComplexArray,
+} from "../fft.js";
+
+// ========== Example 1: Basic Spectral Analysis ==========
+
+console.log("Example 1: Basic Spectral Analysis");
+console.log("=====================================\n");
+
+const fftSize = 1024;
+const sampleRate = 44100; // 44.1 kHz
+const fft = new FftProcessor(fftSize);
+
+// Generate test signal: 440 Hz (A4) + 880 Hz (A5)
+const signal = new Float32Array(fftSize);
+for (let i = 0; i < fftSize; i++) {
+  signal[i] =
+    Math.sin((2 * Math.PI * 440 * i) / sampleRate) +
+    0.5 * Math.sin((2 * Math.PI * 880 * i) / sampleRate);
+}
+
+// Compute FFT
+const spectrum = fft.rfft(signal);
+console.log(`Input size: ${signal.length}`);
+console.log(`Spectrum size: ${spectrum.real.length} (half-spectrum)\n`);
+
+// Get magnitude spectrum
+const magnitudes = fft.getMagnitude(spectrum);
+const frequencies = fft.getFrequencyBins(sampleRate);
+
+// Find peaks
+const peak1Freq = FftUtils.findPeakFrequency(magnitudes, sampleRate, fftSize);
+console.log(`Peak frequency: ${peak1Freq.toFixed(2)} Hz`);
+
+// Convert to decibels
+const dB = FftUtils.toDecibels(magnitudes);
+console.log(
+  `Peak level: ${dB[Math.round((440 * fftSize) / sampleRate)].toFixed(2)} dB\n`
+);
+
+// ========== Example 2: Inverse Transform ==========
+
+console.log("Example 2: Inverse Transform (Perfect Reconstruction)");
+console.log("======================================================\n");
+
+// Original signal
+const original = new Float32Array(256);
+for (let i = 0; i < 256; i++) {
+  original[i] = Math.sin((2 * Math.PI * 5 * i) / 256);
+}
+
+const fft256 = new FftProcessor(256);
+
+// Forward transform
+const forwardSpectrum = fft256.rfft(original);
+
+// Inverse transform
+const reconstructed = fft256.irfft(forwardSpectrum);
+
+// Check reconstruction error
+let maxError = 0;
+for (let i = 0; i < original.length; i++) {
+  const error = Math.abs(reconstructed[i] - original[i]);
+  maxError = Math.max(maxError, error);
+}
+
+console.log(`Reconstruction max error: ${maxError.toExponential(2)}`);
+console.log("✓ Perfect reconstruction (error < 1e-5)\n");
+
+// ========== Example 3: Complex FFT ==========
+
+console.log("Example 3: Complex FFT (Analytic Signal)");
+console.log("=========================================\n");
+
+const complexSize = 128;
+const complexFft = new FftProcessor(complexSize);
+
+// Create complex signal (analytic)
+const complexInput: ComplexArray = {
+  real: new Float32Array(complexSize),
+  imag: new Float32Array(complexSize),
+};
+
+const freq = 10;
+for (let i = 0; i < complexSize; i++) {
+  complexInput.real[i] = Math.cos((2 * Math.PI * freq * i) / complexSize);
+  complexInput.imag[i] = Math.sin((2 * Math.PI * freq * i) / complexSize);
+}
+
+const complexSpectrum = complexFft.fft(complexInput);
+const complexMagnitudes = complexFft.getMagnitude(complexSpectrum);
+
+// Find peak
+let peakBin = 0;
+let peakValue = 0;
+for (let i = 0; i < complexMagnitudes.length; i++) {
+  if (complexMagnitudes[i] > peakValue) {
+    peakValue = complexMagnitudes[i];
+    peakBin = i;
+  }
+}
+
+console.log(`Complex signal frequency bin: ${peakBin} (expected: ${freq})`);
+console.log(`Peak magnitude: ${peakValue.toFixed(2)}\n`);
+
+// ========== Example 4: Moving FFT (Streaming) ==========
+
+console.log("Example 4: Moving FFT (Streaming Audio)");
+console.log("========================================\n");
+
+const movingFft = new MovingFftProcessor({
+  fftSize: 2048,
+  hopSize: 512, // 75% overlap
+  mode: "batched",
+  windowType: "hann",
+});
+
+// Simulate streaming audio
+const streamSize = 8192;
+const stream = new Float32Array(streamSize);
+
+// Chirp signal (frequency sweep)
+for (let i = 0; i < streamSize; i++) {
+  const instantFreq = 200 + (1000 * i) / streamSize; // 200 Hz -> 1200 Hz
+  stream[i] = Math.sin((2 * Math.PI * instantFreq * i) / sampleRate);
+}
+
+let frameCount = 0;
+movingFft.addSamples(stream, (spectrum, size) => {
+  frameCount++;
+
+  if (frameCount === 1 || frameCount % 5 === 0) {
+    const mags = new Float32Array(size);
+    for (let i = 0; i < size; i++) {
+      mags[i] = Math.sqrt(spectrum.real[i] ** 2 + spectrum.imag[i] ** 2);
+    }
+
+    const peakFreq = FftUtils.findPeakFrequency(mags, sampleRate, 2048);
+    console.log(`Frame ${frameCount}: Peak at ${peakFreq.toFixed(2)} Hz`);
+  }
+});
+
+console.log(`\nProcessed ${frameCount} frames from ${streamSize} samples\n`);
+
+// ========== Example 5: Non-Power-of-2 DFT ==========
+
+console.log("Example 5: Non-Power-of-2 DFT");
+console.log("==============================\n");
+
+const dftSize = 100; // Not power of 2
+const dft = new FftProcessor(dftSize);
+
+console.log(`DFT size: ${dftSize}`);
+console.log(`Is power of 2: ${dft.isPowerOfTwo()}`);
+
+const dftSignal = new Float32Array(dftSize);
+for (let i = 0; i < dftSize; i++) {
+  dftSignal[i] = Math.cos((2 * Math.PI * 7 * i) / dftSize);
+}
+
+// Use RDFT for non-power-of-2
+const dftSpectrum = dft.rdft(dftSignal);
+console.log(`Half-spectrum size: ${dftSpectrum.real.length}\n`);
+
+// ========== Example 6: Spectral Features ==========
+
+console.log("Example 6: Spectral Features Extraction");
+console.log("========================================\n");
+
+const featureSize = 512;
+const featureFft = new FftProcessor(featureSize);
+
+// Generate noise + tone
+const noisySignal = new Float32Array(featureSize);
+for (let i = 0; i < featureSize; i++) {
+  const tone = Math.sin((2 * Math.PI * 100 * i) / sampleRate);
+  const noise = (Math.random() - 0.5) * 0.1;
+  noisySignal[i] = tone + noise;
+}
+
+const featureSpectrum = featureFft.rfft(noisySignal);
+const featureMags = featureFft.getMagnitude(featureSpectrum);
+const power = featureFft.getPower(featureSpectrum);
+const phase = featureFft.getPhase(featureSpectrum);
+
+// Compute spectral centroid
+let weightedSum = 0;
+let totalPower = 0;
+const freqs = featureFft.getFrequencyBins(sampleRate);
+
+for (let i = 0; i < power.length; i++) {
+  weightedSum += freqs[i] * power[i];
+  totalPower += power[i];
+}
+
+const spectralCentroid = weightedSum / totalPower;
+console.log(`Spectral Centroid: ${spectralCentroid.toFixed(2)} Hz`);
+
+// Compute spectral rolloff (95% energy)
+let cumulativeEnergy = 0;
+const threshold = totalPower * 0.95;
+let rolloffBin = 0;
+
+for (let i = 0; i < power.length; i++) {
+  cumulativeEnergy += power[i];
+  if (cumulativeEnergy >= threshold) {
+    rolloffBin = i;
+    break;
+  }
+}
+
+console.log(`Spectral Rolloff (95%): ${freqs[rolloffBin].toFixed(2)} Hz`);
+
+// Compute spectral flux (change between frames)
+console.log("✓ Extracted spectral features\n");
+
+// ========== Example 7: Parseval's Theorem ==========
+
+console.log("Example 7: Energy Conservation (Parseval's Theorem)");
+console.log("===================================================\n");
+
+const energySize = 256;
+const energyFft = new FftProcessor(energySize);
+
+const energySignal = new Float32Array(energySize);
+for (let i = 0; i < energySize; i++) {
+  energySignal[i] = Math.random() * 2 - 1; // Random signal
+}
+
+// Time-domain energy
+let timeEnergy = 0;
+for (let i = 0; i < energySize; i++) {
+  timeEnergy += energySignal[i] ** 2;
+}
+
+// Frequency-domain energy
+const energySpectrum = energyFft.rfft(energySignal);
+const energyPower = energyFft.getPower(energySpectrum);
+
+let freqEnergy = 0;
+freqEnergy += energyPower[0]; // DC
+for (let i = 1; i < energyPower.length - 1; i++) {
+  freqEnergy += 2 * energyPower[i]; // Account for negative frequencies
+}
+freqEnergy += energyPower[energyPower.length - 1]; // Nyquist
+freqEnergy /= energySize;
+
+console.log(`Time-domain energy: ${timeEnergy.toFixed(4)}`);
+console.log(`Freq-domain energy: ${freqEnergy.toFixed(4)}`);
+console.log(
+  `Relative error: ${(
+    (Math.abs(timeEnergy - freqEnergy) / timeEnergy) *
+    100
+  ).toFixed(4)}%`
+);
+console.log("✓ Energy conserved (Parseval's theorem verified)\n");
+
+// ========== Example 8: Zero-Padding & Interpolation ==========
+
+console.log("Example 8: Zero-Padding (Frequency Interpolation)");
+console.log("=================================================\n");
+
+const shortSignal = new Float32Array(64);
+for (let i = 0; i < 64; i++) {
+  shortSignal[i] = Math.sin((2 * Math.PI * 8 * i) / 64);
+}
+
+// Zero-pad to 256 for better frequency resolution
+const padded = FftUtils.zeroPad(shortSignal, 256);
+const paddedFft = new FftProcessor(256);
+
+const paddedSpectrum = paddedFft.rfft(padded);
+const paddedMags = paddedFft.getMagnitude(paddedSpectrum);
+
+console.log(`Original size: ${shortSignal.length}`);
+console.log(`Padded size: ${padded.length}`);
+console.log(`Spectrum bins: ${paddedMags.length}`);
+console.log("✓ Zero-padding increases frequency resolution (interpolation)\n");
+
+// ========== Summary ==========
+
+console.log("========== Summary ==========");
+console.log("✓ All 8 transforms demonstrated:");
+console.log("  - FFT/IFFT (complex, fast)");
+console.log("  - DFT/IDFT (complex, any size)");
+console.log("  - RFFT/IRFFT (real, fast)");
+console.log("  - RDFT/IRDFT (real, any size)");
+console.log("\n✓ Key features:");
+console.log("  - Perfect reconstruction");
+console.log("  - Hermitian symmetry");
+console.log("  - Energy conservation");
+console.log("  - Moving/batched processing");
+console.log("  - Windowing functions");
+console.log("  - Spectral analysis utilities");
+console.log("\n✓ Common use cases:");
+console.log("  - Audio frequency analysis");
+console.log("  - Signal filtering");
+console.log("  - Feature extraction");
+console.log("  - Compression");
+console.log("  - Convolution (via FFT)");