GUI

INSTALL_VISUALIZATION.md

@@ -0,0 +1,117 @@
+# Signal Visualization Setup Guide
+
+## Installing Required Dependencies
+
+### For macOS (with Homebrew)
+
+The issue you're experiencing is that tkinter (the GUI library) isn't properly installed with your Python. Here are several solutions:
+
+#### Option 1: Install Python with tkinter support
+```bash
+# If using Homebrew, reinstall Python with tkinter
+brew uninstall python@3.13
+brew install python-tk@3.13
+
+# Or install tkinter specifically
+brew install tcl-tk
+```
+
+#### Option 2: Use conda instead of pip
+```bash
+# Install conda/miniconda first, then:
+conda create -n streamlens python=3.11
+conda activate streamlens
+conda install matplotlib numpy scapy tk
+```
+
+#### Option 3: Use PyQt backend (alternative to tkinter)
+```bash
+pip install PyQt5
+# or
+pip install PyQt6
+```
+
+#### Option 4: Use X11 forwarding (if running over SSH)
+```bash
+# Install XQuartz first: https://www.xquartz.org/
+ssh -X your_server
+# Then run StreamLens
+```
+
+### For Ubuntu/Debian
+```bash
+sudo apt-get install python3-tk
+pip install matplotlib numpy scapy
+```
+
+### For CentOS/RHEL
+```bash
+sudo yum install tkinter
+# or
+sudo dnf install python3-tkinter
+pip install matplotlib numpy scapy
+```
+
+## Testing Your Installation
+
+Run this test to verify everything works:
+
+```bash
+python -c "
+import matplotlib
+matplotlib.use('TkAgg')  # or 'Qt5Agg' if using PyQt
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Create a test plot
+x = np.linspace(0, 10, 100)
+y = np.sin(x)
+plt.plot(x, y)
+plt.title('Test Plot')
+plt.show()
+print('Visualization test successful!')
+"
+```
+
+## Fallback Mode
+
+If you can't get interactive visualization working, StreamLens will automatically:
+1. Use the 'Agg' backend (non-interactive)
+2. Save plots as PNG files instead of showing windows
+3. Print the filename where each plot is saved
+
+This means you can still visualize Chapter 10 signals - they'll just be saved as image files that you can open separately.
+
+## Troubleshooting
+
+### Issue: "No module named '_tkinter'"
+- **Solution**: Install tkinter using your system package manager (not pip)
+- **macOS**: `brew install python-tk@3.13`
+- **Ubuntu**: `sudo apt-get install python3-tk`
+
+### Issue: "Matplotlib backend failed"
+- **Solution**: Try different backends in this order:
+  1. Qt5Agg: `pip install PyQt5`
+  2. Qt6Agg: `pip install PyQt6` 
+  3. TkAgg: Install tkinter (see above)
+  4. Agg: Files will be saved instead of displayed
+
+### Issue: Running over SSH
+- **Solution**: Use X11 forwarding: `ssh -X hostname`
+- **Alternative**: Use the file output mode (automatic fallback)
+
+## Recommended Setup
+
+For the best experience, we recommend:
+
+```bash
+# Install system dependencies first
+brew install python-tk@3.13  # macOS
+# or
+sudo apt-get install python3-tk  # Ubuntu
+
+# Then install Python packages
+pip install matplotlib numpy scapy PyQt5
+```
+
+This gives you multiple backend options and the best compatibility.