# 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.