feat: Add advanced waveform analysis tools

[X9X0]

Summary

Implements comprehensive advanced waveform analysis capabilities for professional-grade signal characterization and testing. This feature elevates LabLink's oscilloscope functionality to match high-end test equipment with 7 major analysis categories.

Features Implemented

🔬 Spectral Analysis

• Spectrogram: Time-frequency analysis using STFT with configurable windows (Hann, Hamming, Blackman)
• Cross-Correlation: Signal similarity and propagation delay measurement between channels
• Transfer Function: H(f) = Y(f)/X(f) with magnitude, phase, and coherence analysis

⏱️ Jitter Analysis (5 Types)

• TIE (Time Interval Error): Cumulative timing error from ideal positions
• Period Jitter: Variation from mean period
• Cycle-to-Cycle Jitter: Consecutive period differences (critical for high-speed serial)
• Half-Period Jitter: Both edge analysis for dual-edge clocks
• N-Period Jitter: Configurable long-term stability assessment
• Complete statistics: mean, RMS, peak-to-peak, histograms

👁️ Eye Diagram Analysis

• Professional eye diagram generation for serial data links
• 13 measurements: eye height/width, crossing %, RMS/pk-pk jitter, RMS noise, Q-factor, SNR, eye opening %
• Persistence visualization with 2D histogram
• Logic level detection and rise/fall time analysis

✅ Mask Testing

• Polygon-based pass/fail testing with violation tracking
• Support for normalized and absolute coordinates
• Margin analysis (min/mean distance to mask boundaries)
• Per-region failure counts and location reporting

🔍 Waveform Search (6 Event Types)

• Edges: Rising/falling edge detection
• Pulses: Positive/negative pulse detection with width filtering
• Runts: Incomplete pulse detection
• Glitches: Narrow spike detection using derivative analysis
• Event statistics and timing analysis

📊 Reference Waveform Comparison

• Golden unit comparison with configurable tolerances
• Voltage error analysis (RMS, max, mean)
• Correlation coefficient and phase shift measurement
• Similarity percentage and failure point reporting

📈 Parameter Trending

• Track 13+ parameters over time (frequency, amplitude, jitter, eye metrics, etc.)
• Drift detection using linear regression
• Trend direction classification (up/down/stable)
• Long-term monitoring for aging and predictive maintenance

Implementation Details

New Files (3,250+ lines)

• server/waveform/advanced_models.py (700+ lines) - Pydantic data models
• server/waveform/advanced_analysis.py (1,287 lines) - Core analysis algorithms
• server/api/waveform_advanced.py (650+ lines) - REST API endpoints
• server/ADVANCED_WAVEFORM_ANALYSIS.md (800+ lines) - User guide

API Endpoints (20+)

Spectral:

• POST /api/waveform/advanced/spectrogram
• POST /api/waveform/advanced/cross-correlation
• POST /api/waveform/advanced/transfer-function

Jitter & Eye:

• POST /api/waveform/advanced/jitter
• POST /api/waveform/advanced/eye-diagram

Mask Testing:

• POST /api/waveform/advanced/mask/define
• GET /api/waveform/advanced/mask/list
• POST /api/waveform/advanced/mask/test

Search & Reference:

• POST /api/waveform/advanced/search
• POST /api/waveform/advanced/reference/add
• POST /api/waveform/advanced/reference/compare

Trending:

• POST /api/waveform/advanced/trend/update
• GET /api/waveform/advanced/trend/get/{equipment_id}/{channel}/{parameter}

Technology Stack

• NumPy/SciPy: Efficient signal processing algorithms
• Pydantic: Request/response validation
• FastAPI: REST API framework
• Proper error handling and type hints throughout

Use Cases

• Serial Data Validation: Eye diagrams, jitter analysis, mask testing for high-speed links
• System Characterization: Transfer functions, spectrograms for filter/amplifier analysis
• Quality Control: Reference comparison, mask testing, parameter trending for production
• Signal Integrity: Comprehensive jitter analysis, eye diagrams, event search for debugging
• Compliance Testing: Mask testing against industry standards (IEEE, JEDEC, etc.)

Documentation

• Comprehensive User Guide (800+ lines) with examples, API reference, and best practices
• Inline API Documentation on all endpoints with use cases and configuration details
• Updated README with full feature list and documentation links

Testing Notes

This implementation provides the algorithmic foundation and API layer. Integration testing will require:

• Initialization in main.py to create AdvancedWaveformAnalyzer instance
• Router registration for /api/waveform/advanced endpoints
• Waveform manager integration for cached waveform access

Breaking Changes

None - purely additive feature.

Closes

• Feature: Advanced waveform analysis tools (from "In Development" section)