# pywboard

**Simple Annotation Whiteboard** — a lightweight desktop tool for annotating network topology diagrams and screenshots with pen, lines, arrows, and text labels.

Built with PyQt6 + QWebEngine. Zero CDN dependencies. Fully offline.

![pywboard screenshot](https://raw.githubusercontent.com/scottpeterman/pywboard/main/screenshots/sample1.png)
## Install

```bash
pip install pywboard
```

Or from source:

```bash
git clone https://github.com/scottpeterman/pywboard.git
cd pywboard
pip install -e .
```

### Requirements

- Python 3.9+
- PyQt6 >= 6.5
- PyQt6-WebEngine >= 6.5

## Usage

```bash
# Launch empty canvas
pywboard

# Open with a topology image
pywboard topology.png

# Module execution
python -m pywboard
python -m pywboard screenshot.png
```

## Features

### Drawing Tools
| Tool | Key | Description |
|------|-----|-------------|
| Pen | `P` | Freehand drawing |
| Line | `L` | Straight lines |
| Arrow | `A` | Directional arrows |
| Text | `T` | Click to place text labels |
| Eraser | `E` | Remove annotations |
| Pan | `H` | Move the background image |

### Canvas Sizes

Preset sizes from the toolbar dropdown:

- **XGA** — 1024 × 768
- **Full HD** — 1920 × 1080
- **QHD** — 2560 × 1440
- **4K UHD** — 3840 × 2160
- **Large Topo** — 2400 × 1600
- **XL Topo** — 3200 × 2400
- **XXL Topo** — 4000 × 3000
- **Custom** — up to 8000 × 8000

### View Modes

- **FIT** — scales canvas to fit the window (default)
- **1:1** — actual pixel size with scroll navigation

Toggle with `F` key, or `Ctrl+0` (fit) / `Ctrl+1` (actual size).

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+O` | Open image (native dialog) |
| `Ctrl+Shift+S` | Export PNG (native save dialog) |
| `Ctrl+Z` | Undo last annotation |
| `Ctrl+Q` | Quit |
| `Ctrl+0` | Fit to window |
| `Ctrl+1` | Actual size (1:1) |
| `F` | Toggle FIT / 1:1 |

### Other Features

- **Drag & drop** images onto the canvas
- **9 colors** with 4 stroke widths
- **Native file dialogs** for open/save (via PyQt6 bridge)
- **Dark theme** throughout — toolbar, menus, scrollbars
- **Export** full-resolution annotated PNG

## Architecture

```
pywboard/
├── pyproject.toml
├── README.md
├── LICENSE
└── pywboard/
    ├── __init__.py
    ├── __main__.py          # python -m pywboard
    ├── app.py               # PyQt6 QWebEngineView wrapper
    └── assets/
        └── annotate.html    # Self-contained HTML/CSS/JS canvas app
```

The HTML annotation engine is entirely self-contained — no external fonts, no CDN JavaScript, no build step. The PyQt6 wrapper adds native file dialogs, menu bar, CLI image loading, and dark window chrome via a `QWebChannel` bridge.

The HTML also works standalone in any browser for quick use without Python.

## License

MIT
