Application Layer

Business logic and processing components.

Keymap Generator

Main orchestration module for keymap image generation.

This module provides the primary entry point for generating Svalboard keymap visualization images. It coordinates the loading of configuration and keymap files, transformation of keycodes to display labels, rendering of SVG drawings, and export to image files.

The generation pipeline follows these steps: 1. Load configuration (with gradient generation for layer colors) 2. Load keymap from file or stdin 3. Transform keycodes to renderable target keys 4. Draw SVG images for requested layers 5. Export drawings to output directory

Example

>>> from pathlib import Path
>>> from skim.data.cli import InputFiles, OutputFiles, KeymapGeneratorTargets
>>> from skim.application.keymap_generator import generate_keymap
>>> inputs = InputFiles(keymap=Path("keymap.kbi"))
>>> outputs = OutputFiles(output_dir=Path("./images"), output_format="png")
>>> targets = KeymapGeneratorTargets(all_layers=True, overview=True)
>>> generate_keymap(inputs, outputs, targets)

skim.application.keymap_generator.logger = <Logger skim.application.keymap_generator (INFO)>

Module-level logger for keymap generation operations.

skim.application.keymap_generator.generate_keymap(inputs, outputs, targets)

Generate keymap visualization images.

Main entry point for the keymap generation pipeline. Loads configuration and keymap data, transforms keycodes to display labels, renders SVG drawings, and exports them to the specified output directory.

Parameters:

• inputs (InputFiles) – Configuration for input files (keymap path, config path, stdin flag).

• outputs (OutputFiles) – Configuration for output (directory, format, overwrite flag).

• targets (KeymapGeneratorTargets) – Specification of which layers and views to generate.

Raises:

SystemExit – If the output directory path exists but is not a directory.

Return type:

None

Note

The output directory is created if it doesn’t exist. Existing files may be overwritten depending on the outputs.force_overwrite setting.

Config Generator

Configuration generator for creating skim config YAML files.

Provides ConfigGenerator which can produce default configuration templates or extract metadata from Keybard (.kbi) files to generate pre-populated configuration files.

Example

Generate default config:

generator = ConfigGenerator()
print(generator.generate_default())

Generate from Keybard file:

generator = ConfigGenerator()
yaml_config = generator.generate_from_keybard(
    Path("layout.kbi").read_text(),
    adjust_lightness=0.31,
)
Path("skim-config.yaml").write_text(yaml_config)

class skim.application.config_generator.ConfigGenerator

Bases: object

Generates skim configuration YAML from defaults or source files.

generate_default()

Generate YAML from SkimConfig defaults.

Return type:

str

Returns:

YAML string containing the default skim configuration.

generate_from_keybard(keybard_content, qmk_header_content=None, adjust_lightness=None, adjust_saturation=None)

Generate config YAML by extracting metadata from a Keybard file.

Parses the .kbi JSON to extract layer colors, layer names, and custom keycode definitions. Optionally applies color adjustments and merges QMK named colors from a color.h header.

Parameters:

• keybard_content (str) – JSON string from a .kbi file.

• qmk_header_content (Optional[str]) – Optional C header content with color defines.

• adjust_lightness (Optional[float]) – Target lightness (0.0-1.0) for extracted colors.

• adjust_saturation (Optional[float]) – Max saturation (0.0-1.0) for extracted colors.

Return type:

str

Returns:

YAML string containing the generated skim configuration.

Raises:

ValueError – If keybard_content is not valid JSON.

generate_from_keymap(content)

Generate config YAML from a Vial or c2json keymap file.

Detects the keymap format, counts layers to create default layer entries with auto-generated colors, and scans for non-standard keycodes to populate overrides.

For Keybard files, delegates to generate_from_keybard() which extracts richer metadata (layer names, colors, custom keycodes).

Parameters:

content (str) – JSON string from a keymap file (.vil or .json).

Return type:

str

Returns:

YAML string containing the generated skim configuration.

Raises:

ValueError – If content is not valid JSON or format is unknown.

Loaders

Data loading modules for keymaps, configuration, and assets.

This package provides loaders for: - Keymap files (C2JSON, Vial, Keybard) - Skim configuration (YAML) - Keycode mappings - Nerd Font glyphs

skim.application.loaders.load_keycode_mappings(keycodes_config)

Load and merge keycode mappings.

Loads the bundled keycode-mappings.yaml file and applies any user-provided pre-processing and override mappings from the skim configuration.

Parameters:

keycodes_config (Keycodes) – The keycode overrides from the skim configuration (SkimConfig.keycodes).

Returns:

• keycodes: Keycode to label mappings

• pre_processing: Keycode normalization rules

• macro_functions: Macro template definitions

• modifier_union: Modifier constant mappings

Return type:

Dictionary containing merged keycode mappings with keys

skim.application.loaders.load_keymap(file_path, layer_indices=None)

Load a complete keymap from file or stdin.

Main entry point for loading keymaps. Loads from the specified file or from stdin if no file is provided.

Parameters:

• file_path (Path | None) – Path to the keymap file, or None to read from stdin.

• layer_indices (Optional[list[int]]) – Optional list of QMK layer indices to map each positional layer to. If None, sequential indices (0, 1, 2, …) are used.

Return type:

SvalboardKeymap[str]

Returns:

A SvalboardKeymap containing raw keycode strings for all layers.

Raises:

ValueError – If the file doesn’t exist or content is invalid.

skim.application.loaders.load_nerdfont_glyphs()

Load Nerd Font glyph mappings from the bundled JSON file.

Reads the nerd_glyphnames.json file from the assets directory and transforms it into a dictionary mapping prefixed glyph names to their corresponding Unicode characters.

The function uses lru_cache to cache the loaded mappings, ensuring the JSON file is only read once per process lifetime.

Return type:

dict[str, str]

Returns:

Dictionary mapping glyph names (prefixed with “nf-”) to their corresponding Unicode characters. For example: {"nf-md-home": "", "nf-fa-star": "", ...}

Raises:

FileNotFoundError – If the nerd_glyphnames.json file is not found in the assets/data directory.

Example

>>> glyphs = load_nerdfont_glyphs()
>>> char = glyphs.get("nf-md-home")
>>> # char contains the Unicode home icon character

skim.application.loaders.load_skim_config(config_path=None)

Load skim configuration from a YAML file.

Loads and validates configuration from the specified YAML file. If no path is provided or the path doesn’t point to an existing file, returns a default SkimConfig with all default values.

Parameters:

config_path (Optional[Path]) – Optional path to a YAML configuration file. If None or if the file doesn’t exist, returns default configuration.

Return type:

SkimConfig

Returns:

A validated SkimConfig instance, either loaded from the file or with default values.

Raises:

• pydantic.ValidationError – If the YAML content doesn’t match the expected configuration schema.

• yaml.YAMLError – If the file content is not valid YAML.

Example

>>> # Load from file
>>> config = load_skim_config(Path("custom-config.yaml"))

>>> # Get default config
>>> config = load_skim_config()
>>> config.output.layout.width
800

Render

Rendering module for generating keymap visualizations.

This package contains the core rendering logic for transforming keymap data into SVG drawings. It handles: - Layout calculation (Finger/Thumb clusters) - Component rendering (Keys, Clusters) - Styling and coloring - Text and font management - Geometry and shape generation

skim.application.render.draw_keymap(config, keymap, targets)

Return type:

dict[str, Drawing]

Parameters:

• config (SkimConfig)

• keymap (SvalboardKeymap[SvalboardTargetKey])

• targets (KeymapGeneratorTargets)

skim.application.render.make_gradient(base_color, base_index=2)

Generate a 6-color gradient with base color at specified index.

Creates a gradient that interpolates from dark to light colors, with the base color appearing at the specified index position.

Parameters:

• base_color (str) – The base color in hexadecimal format.

• base_index (int) – Position (0-5) where base color should appear. Colors before this index will be darker, colors after will be lighter. Default: 2

Return type:

tuple[str, str, str, str, str, str]

Returns:

List of 6 hexadecimal color strings forming a gradient.

Examples

>>> grad = make_gradient("#347156", base_index=2)
>>> len(grad)
6
>>> gradient[2]  # Base color at index 2
'#347156'

Exporter

Image exporter with support for Playwright and Cairo backends.

skim.application.exporter.is_playwright_available()

Return type:

bool

skim.application.exporter.is_cairo_available()

Return type:

bool

skim.application.exporter.get_available_export_formats()

Return type:

list[str]

skim.application.exporter.get_available_render_engines()

Return type:

list[RenderEngine]

skim.application.exporter.save_drawings(outputs, drawings, render_engine=None)

Parameters:

• outputs (OutputFiles)

• drawings (dict[str, Drawing])

• render_engine (RenderEngine | None)