Waveform Analyzer

A Python application for visualizing and analyzing multiple waveforms in real-time with envelope analysis capabilities.

Installation

1. Activate the virtual environment:

   # Windows
   env\Scripts\activate

2. Install dependencies (if not already done):

   pip install -r requirements.txt

Running the Application

python main.py

Or with the virtual environment:

env\Scripts\python.exe main.py

Quick Start Guide

Basic Usage

1. Launch the application - The app starts with one default waveform using values from default.cfg

2. Adjust waveform parameters:

   • Use the Frequency input to change the wave frequency (0.1-100 Hz)
   • Use the Amplitude input to adjust the wave amplitude (0-10)
   • Use the Offset input to adjust the Y-axis offset (0-10)
   • For Square waves, use the Duty Cycle input (1-100%)

3. Change waveform type:

   • Use the Type dropdown to select: Sine, Square, Sawtooth, or Triangle

4. Add more waveforms:

   • Click + Add Waveform button (max 5 waveforms)
   • Each waveform gets a unique color automatically

5. Manage waveforms:

   • Click on a waveform in the list to select and edit it
   • Click the ON/OFF button to show/hide a waveform
   • Click the X button to remove a waveform (minimum 1 required)
   • Right-click a waveform button to rename it or change its color (custom names appear in the plot legend and CSV export)

Envelope Analysis

When you have 2 or more enabled waveforms:

• Show Max Envelope - Displays the maximum amplitude at each time point (green glowing line)
• Show Min Envelope - Displays the minimum amplitude at each time point (red glowing line)
• Show RMS Envelope - Displays the root-mean-square across all enabled waveforms (orange glowing line)
• Peak-to-Peak Fill - When both Max and Min envelopes are enabled, a cyan shaded region fills the area between them

All envelopes can be enabled simultaneously. Source waveforms are automatically hidden when envelopes are shown.

Measurement Cursors

Measurement cursors are always active — no toggle needed:

1. Move the mouse over the plot — a live cursor line tracks the mouse position
2. Hover near a waveform or envelope line — the cursor color matches the nearest line and a highlight dot appears at the intersection
3. Left-click on the plot to pin a reference cursor (dashed gray line) for comparison

Waveform Parameters

Each waveform has the following adjustable parameters:

• Type - Waveform type (Sine, Square, Sawtooth, Triangle)
• Wave Duration - Adjusts the time window for visualization (0.5-120 seconds)
• Frequency - Wave frequency in Hz (0.1-100 Hz)
• Amplitude - Wave amplitude (0-10)
• Offset - Y-axis offset (0-10)
• Duty Cycle - For Square waves only (1-100%)

Configuration

Default settings are stored in default.cfg (INI format) alongside the application. You can edit this file directly or use the built-in Configure dialog:

1. Open File → Configure...
2. Adjust settings in three sections:
   • Global — Wave duration default
   • Waveform — Type, frequency, amplitude, offset, duty cycle (applied on next launch)
   • Display — Y-axis title, Y-axis min/max (applied immediately)
3. Click Save to persist changes to default.cfg

Note: Display settings (Y-axis title and range) take effect immediately. Waveform settings apply the next time the application is launched.

Theme Toggle

Switch between dark and light mode via File → Toggle Theme. The theme choice persists across sessions in default.cfg.

Detachable Plot Window

Move the plot to a separate window for multi-monitor setups or flexible workspace layouts:

1. Detach: Click File → Detach Plot to move the plot to a separate 800×600 resizable window
2. Use: The detached window includes pan/zoom navigation and responds immediately to parameter changes in the main window
3. Re-attach: Close the detached window, click the "Re-attach Plot" button in the main window placeholder, or use File → Attach Plot

All interactive features (cursors, envelopes, pan/zoom) work identically in both attached and detached modes.

Exporting Data

1. Click Export to CSV (button exports to any supported format)
2. A native file dialog will open — choose format from the file type dropdown:
   • CSV (.csv) — time + amplitude columns with metadata comments
   • MATLAB (.mat) — named variables per waveform/envelope
   • JSON (.json) — structured document with parameters and data arrays
3. Exported data includes:
   • All enabled waveforms
   • Active envelopes (if enabled)
   • Metadata (waveform type, frequency, amplitude, etc.)

Features

• 4 Waveform Types: Sine, Square, Sawtooth, Triangle
• Up to 5 simultaneous waveforms
• Custom waveform naming and colors via right-click context menu
• Real-time visualization with responsive performance
• Envelope analysis with glowing Max/Min/RMS envelope lines and Peak-to-Peak fill
• Live measurement cursors with real-time tracking, proximity highlight, and pinned reference
• Auto-hide source waveforms when envelopes are enabled
• Detachable plot window for multi-monitor setups (File → Detach Plot)
• Multi-format export (CSV, MATLAB .mat, JSON) with native OS file dialog
• Independent waveform control
• Configurable defaults via File → Configure... dialog and default.cfg
• Help menu with About dialog (version, author info)
• Modern Windows 11 UI with CustomTkinter
• Dark/Light theme toggle via File → Toggle Theme (persists across sessions)

File Structure

waveform_analyzer/
├── main.py                       # Application entry point
├── app_state.py                  # State management
├── waveform_generator.py         # Waveform generation functions
├── ui_components.py              # UI and callbacks
├── data_export.py                # CSV export functionality
├── config.py                     # Configuration loader/saver
├── winui_theme.json              # WinUI/Windows 11 color theme for CustomTkinter
├── test_waveform_analyzer.py     # Automated pre-commit tests (106 tests)
├── default.cfg                   # User-editable default settings (INI format)
├── icon.ico                      # Application icon
├── requirements.txt              # Python dependencies
├── README.md                     # This file
└── docs/                         # Sphinx documentation source
    ├── conf.py                   # Sphinx configuration
    ├── index.rst                 # Documentation landing page
    ├── make.bat                  # Windows build script
    ├── Makefile                  # Linux/macOS build script
    └── *.rst                     # Per-module API reference pages

System Requirements

• Python 3.11 or higher
• Windows/Linux/macOS
• Minimum resolution: 1000x800 (recommended: 1200x900)

Dependencies

• CustomTkinter >= 5.2.0 - Modern GUI framework
• CTkMenuBar >= 0.9 - Dark-themed menu bar for CustomTkinter
• matplotlib >= 3.8.0 - Plotting library
• NumPy >= 1.24.0 - Numerical computing
• SciPy >= 1.11.0 - Signal processing

Performance

• Target frame rate: >30 FPS
• Plot update latency: <100ms
• Memory usage: <200MB
• Startup time: <2 seconds

Testing

Run the automated test suite (requires pytest):

pip install pytest
python -m pytest test_waveform_analyzer.py -v

The 106 tests cover all pre-commit checklist items: wave types, edge cases, duty cycle, durations, envelope calculations, enabled/disabled state, CSV export, waveform limits, error handling, and performance SLAs.

Documentation

API documentation is auto-generated from source code docstrings using Sphinx.

Building the Docs

pip install sphinx sphinx-rtd-theme
cd docs
make.bat html

The generated HTML will be in build/sphinx/html/. Open build/sphinx/html/index.html to browse.

Keyboard Shortcuts

• Use +/- buttons for fine control of parameters
• Click and drag on the plot to pan
• Scroll to zoom in/out on the plot

Troubleshooting

Application won't start:

• Ensure Python 3.11+ is installed: python --version
• Verify dependencies are installed: pip list
• Activate virtual environment first

Performance issues:

• Reduce the number of visible waveforms
• Decrease the wave duration
• Disable envelopes if not needed

Export fails:

• Check file path permissions
• Ensure filename doesn't contain invalid characters
• The app will auto-correct the filename and add .csv if needed

Version

Current version: 2.0.0

What's New in v2.0.0

• ✨ Detachable Plot Window - Move the plot to a separate window for multi-monitor workflows
• 🎯 All existing features from v1.x (envelopes, cursors, themes, export formats, custom colors)