Metadata-Version: 2.4
Name: pywboard
Version: 0.2.0
Summary: Network Annotation Whiteboard — annotate topology diagrams with pen, arrows, shapes, text, and drag-and-drop network icons
Author: Scott Peterman
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/scottpeterman/pywboard
Project-URL: Repository, https://github.com/scottpeterman/pywboard
Project-URL: Issues, https://github.com/scottpeterman/pywboard/issues
Keywords: network,annotation,whiteboard,topology,diagram,PyQt6
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Topic :: System :: Networking
Classifier: Topic :: Multimedia :: Graphics :: Editors
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Environment :: X11 Applications :: Qt
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6>=6.5
Requires-Dist: PyQt6-WebEngine>=6.5
Dynamic: license-file

# pywboard

**Network Annotation Whiteboard** — a lightweight desktop tool for annotating network topology diagrams and screenshots with pen, lines, arrows, shapes, text labels, and drag-and-drop network icons.

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

![pywboard screenshot](https://raw.githubusercontent.com/scottpeterman/pywboard/main/screenshots/sample2.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 |
| Rectangle | `R` | Rectangles and boxes |
| Ellipse | `O` | Ellipses and circles |
| Text | `T` | Click to place text labels |
| Icon | `I` | Place network device icons |
| Eraser | `E` | Remove annotations |
| Pan | `H` | Move the background image |

### Network Icons

Place standard network device icons directly onto the canvas. Select an icon type from the palette, then click to place it. Icons can be selected, dragged, resized, copied, and deleted.

**Icon Sets** — switch between icon sets using the dropdown in the icon palette:

- **Basic** — simple geometric icons (router, switch, firewall, cloud, server, LB)
- **Cisco** — classic Cisco-style topology icons (router, L2 switch, L3 switch, firewall, cloud, server, LB)

Icon manipulation:

- **Click** on an existing icon to select it
- **Drag** a selected icon to reposition
- **Corner handle** to resize (visible grab handle on the bottom-right corner)
- **`Ctrl+C` / `Ctrl+V`** to copy and paste icons (pastes with a diagonal offset for rapid duplication)
- **`Delete`** to remove the selected icon

### Animation

Select an icon and click **ANIM** to assign an animation effect. Animations are embedded in SVG exports.

| Animation | Effect |
|-----------|--------|
| Pulse | Smooth scale breathing |
| Rotate | Continuous 360° rotation |
| Blink | Opacity fade in/out |
| Traffic Flow | Horizontal slide loop |

### Export

- **Export PNG** — full-resolution rasterized output with all annotations composited onto the background
- **Export SVG** — vector output with embedded CSS animations, suitable for embedding in documentation or web pages

### 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+C` | Copy selected annotation |
| `Ctrl+V` | Paste annotation / paste image from clipboard |
| `Ctrl+Z` | Undo last annotation |
| `Ctrl+N` | New canvas (reset all) |
| `Ctrl+O` | Open image (native dialog) |
| `Ctrl+Shift+S` | Export PNG (native save dialog) |
| `Ctrl+Q` | Quit |
| `Ctrl+0` | Fit to window |
| `Ctrl+1` | Actual size (1:1) |
| `Delete` | Remove selected icon |
| `F` | Toggle FIT / 1:1 |

### Other Features

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

## Extending Icon Sets

Icon sets are self-contained JavaScript files that register with `window.registerIconSet()`. Each icon is a function returning an SVG string:

```javascript
window.registerIconSet("myvendor", "My Vendor", {
  router: {
    label: "Router",
    svg: function(color, size) {
      return '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">...</svg>';
    }
  }
});
```

Place icon set `.js` files in `pywboard/assets/icons/` and they are loaded automatically. Internal SVG `id` attributes should be namespaced per icon to prevent DOM collisions when multiple icons are rendered on the same page.

## 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
        └── icons/
            ├── basic.js     # Basic geometric icon set
            └── cisco.js     # Cisco-style topology icons
```

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

GPLv3
