pywboard 0.2.0

Network Annotation Whiteboard — annotate topology diagrams with pen, arrows, shapes, text, and drag-and-drop network icons

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.

Install

pip install pywboard

Or from source:

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

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

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