Glove80 Keymap Visualizer

Generate beautiful PDF visualizations of your Glove80 keyboard layers from ZMK keymap files.

What It Does

This tool takes your ZMK .keymap file (exported from the MoErgo Glove80 Layout Editor) and generates a PDF document with a visual diagram for each layer—similar to sunaku's layer diagrams.

Example Output

Default output — Shows shifted characters above keys (! above 1, @ above 2, etc.):

With --color flag — Semantic coloring by key category with legend:

Layer with held key indicator — Fingerprint icon shows which key activates this layer:

With --no-shifted flag — Hide shifted characters for a cleaner look:

Getting Started

Step 1: Install System Dependencies

macOS:

brew install cairo

Ubuntu/Debian:

sudo apt-get install libcairo2-dev

Windows: See CairoSVG installation docs for Windows instructions.

Step 2: Install the Tool

Option A: Install from PyPI (recommended)

pip install glove80-keymap-visualizer

Option B: Install from source

git clone https://github.com/dsifry/glove80-keymap-visualizer.git
cd glove80-keymap-visualizer
pip install .

Step 2.5: Install Browser for KLE Output (Optional)

For KLE PNG/PDF output (using keyboard-layout-editor.com styling), install Chromium:

playwright install chromium

This is only needed if you want to use --format kle-png or --format kle-pdf.

Step 3: Export Your Keymap

1. Go to my.glove80.com
2. Load your layout
3. Click Export → Download ZMK Keymap
4. Save the .keymap file

Step 4: Generate Your PDF

# Basic usage - generates a PDF with all layers
glove80-viz your-keymap.keymap -o my-layers.pdf

# With color coding (recommended!)
glove80-viz your-keymap.keymap -o my-layers.pdf --color

That's it! Open my-layers.pdf to see your keyboard layout.

Common Options

# Color-coded keys by category (modifiers, navigation, etc.)
glove80-viz keymap.keymap -o output.pdf --color

# Color-coded without the legend
glove80-viz keymap.keymap -o output.pdf --color --no-legend

# Windows modifier symbols (Win, Ctrl, Alt, Shift) instead of Mac symbols
glove80-viz keymap.keymap -o output.pdf --windows

# Show what keys do on transparent layers (instead of "trans")
glove80-viz keymap.keymap -o output.pdf --resolve-trans

# Generate only specific layers
glove80-viz keymap.keymap -o output.pdf --layers Base,Symbol,Cursor

# Control layers per page (1, 2, or 3 - default is 3)
glove80-viz keymap.keymap -o output.pdf --layers-per-page 1  # Full page per layer
glove80-viz keymap.keymap -o output.pdf --layers-per-page 2  # Two layers per page

# Custom DPI for higher/lower resolution output
glove80-viz keymap.keymap -o output.pdf --dpi 150  # Lower res, smaller file
glove80-viz keymap.keymap -o output.pdf --dpi 600  # Higher res, larger file

# Page orientation (portrait is default)
glove80-viz keymap.keymap -o output.pdf --portrait   # Portrait orientation (default)
glove80-viz keymap.keymap -o output.pdf --landscape  # Landscape orientation

# Generate SVG files instead of PDF
glove80-viz keymap.keymap -o ./svg-folder --format svg

# Generate KLE JSON (for keyboard-layout-editor.com)
glove80-viz keymap.keymap -o ./kle-folder --format kle

# Generate KLE-style PNG via headless browser (requires Chromium)
glove80-viz keymap.keymap -o ./png-folder --format kle-png

# Generate KLE-style combined PDF via headless browser
glove80-viz keymap.keymap -o output.pdf --format kle-pdf

# List all available layers in your keymap
glove80-viz keymap.keymap --list-layers

Features

• Shifted character display — Shows shifted characters above keys (! above 1, " above ') like a physical keyboard
• Custom mod-morph support — Automatically detects custom shift mappings (e.g., ( → <) from your keymap
• Refined typography — Balanced key label positioning inspired by physical keycaps, with clear visual hierarchy
• OS-specific modifier symbols — Mac (⌘⌥⌃⇧), Windows (Win+Ctrl+Alt+Shift), or Linux (Super+Ctrl+Alt+Shift)
• Semantic coloring — Color-code keys by category: modifiers, navigation, numbers, symbols, media, layers, system
• Color legend — Shows what each color means (can be hidden with --no-legend)
• Held key indicators — Fingerprint icon shows which key you hold to activate each layer
• MEH/HYPER expansion — MEH(K) displays as ⌃⌥⇧K on Mac
• Transparent key resolution — Optionally show inherited keys instead of "trans" markers
• Layers per page — Control PDF density with 1, 2, or 3 layers per page (default: 3)
• Configurable DPI — Adjust PDF resolution for quality vs. file size tradeoff
• Table of contents — PDF includes clickable TOC for easy navigation
• Layer filtering — Generate only the layers you want
• KLE output — Export to keyboard-layout-editor.com JSON or render via headless browser to PNG/PDF

All CLI Options

Option	Description
-o, --output	Output file (PDF) or directory (SVG/KLE)
--format	Output format: pdf (default), svg, kle, kle-png, kle-pdf
--layers	Comma-separated list of layers to include
--exclude-layers	Comma-separated list of layers to exclude
--list-layers	List available layers and exit
--config	Path to YAML configuration file
--mac	Use Mac modifier symbols (⌘⌥⌃⇧) — default
--windows	Use Windows modifier symbols
--linux	Use Linux modifier symbols
--color	Apply semantic colors to keys
--no-legend	Hide color legend (use with --color)
--no-shifted	Hide shifted characters on keys (shown by default)
--resolve-trans	Show inherited keys instead of "trans"
--base-layer	Base layer for --resolve-trans (default: first layer)
--no-toc	Disable table of contents in PDF
--layers-per-page	Number of layers per PDF page: 1, 2, or 3 (default: 3)
--dpi	Output resolution for PDF rendering (default: 300)
--portrait	Use portrait page orientation (default)
--landscape	Use landscape page orientation
--continue-on-error	Continue if a layer fails to render
-v, --verbose	Show detailed output
-q, --quiet	Suppress all output except errors

Color Scheme

When using --color, keys are colored by category using an Everforest-inspired palette:

Category	Color	Example Keys
Modifiers	Teal	⌘, ⌥, ⌃, ⇧, Shift, Ctrl, Alt
Navigation	Green	←, →, ↑, ↓, Home, End, PgUp, PgDn
Numbers	Yellow	0-9, F1-F12
Symbols	Orange	!@#$%^&*() etc.
Media	Light Green	⏯, ⏭, 🔊, 🔇, brightness
Layer	Purple	Layer activators (held keys)
System	Red	Reset, Boot, Bluetooth keys
Mouse	Teal	Mouse movement and clicks
Transparent	Gray	Transparent/pass-through keys

Configuration File

For persistent settings, create a YAML config file:

# my-config.yaml
os_style: mac          # "mac", "windows", or "linux"
show_colors: true
show_legend: true
show_shifted: true     # show shifted chars (default: true)
resolve_trans: false
include_toc: true
page_size: letter      # or "a4"
orientation: portrait  # "portrait" (default) or "landscape"
layers_per_page: 3     # 1, 2, or 3 layers per PDF page
dpi: 300               # output resolution (72-600 typical)

Then use it:

glove80-viz keymap.keymap -o output.pdf --config my-config.yaml

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Install browsers for KLE rendering tests
playwright install chromium

# Run tests
pytest

# Run tests with coverage
pytest --cov

# Run fast tests only (skip slow browser tests)
pytest -m "not slow"

# Format code
ruff format .

# Lint
ruff check .

How It Works

1. Parse — Uses keymap-drawer to parse ZMK keymap files
2. Extract — Extracts layer info, key bindings, hold behaviors, and layer activators
3. Generate SVG — Creates SVG diagrams with keymap-drawer's layout engine
4. Convert to PDF — Combines SVGs into a PDF with TOC using CairoSVG and pikepdf

Developer Resources

Developer FAQ

For questions about development setup, testing, CI/CD, and common troubleshooting, see DEVELOPER-FAQ.md.

Topics covered:

• Setting up your development environment
• Running tests and achieving coverage
• Understanding the codebase architecture
• Common issues and solutions

Superpowers (AI-Assisted Development)

This project uses Claude Code with custom skills for AI-assisted development. See SUPERPOWERS.md for details on:

• Using Claude Code effectively with this codebase
• Available AI skills and workflows
• TDD and debugging patterns
• Code review and PR processes

Credits

• keymap-drawer — ZMK keymap parsing and SVG generation
• sunaku's Glove80 keymaps — Inspiration for visualization format
• MoErgo Glove80 — The keyboard this tool is built for
• Everforest — Color palette inspiration

License

MIT License — see LICENSE file for details.