Just found an amazing keymap drawer tool

[newsve]

But it draws only from QMK and ZMK configs, so I created an issue: caksoylar/keymap-drawer#95 but are there any similar tools that might take Kanata configs?

[caksoylar]

Feedback is welcome on how to support different physical layouts. To summarize my current thinking:

• I am guessing most people would be using it on a laptop and would be fine with displaying it on a row staggered layout.
  • We can do a smart selection by checking which src keys are used, and use a generic 60%, 65%, TKL, 104/105 key layout accordingly
• If you are using a custom keyboard (split, ortho, col stagger etc.) and still doing some remapping with Kanata (rather than on keyboard firmware) let me know
   - Adding support for these will be difficult, because in addition to the physical layout (i.e. positioning of switches) we also need to know the logical layout (i.e. keymap, what keycodes are on what positions) to understand which positions are remapped
   - Maybe we could constrain to a few other form factors, like generic 4x12, 5x12 orthos? But even then there isn't a definite "default" keymap people use, so it's hard.
   - We could allow for parsing a QMK/ZMK keymap together with a Kanata keymap, but that sounds overkill?

[CosmoDm]

Please consider using the standard JSON file for VIA to support different physical layouts.
For example - K11 Pro Keymap JSON File.

[caksoylar]

Currently keymap-drawer supports QMK info.json-style physical layout definitions along with some parametrized generators. Supporting VIA keyboard definitions is orthogonal to above issue, since (like other physical layouts already supported) it doesn't seem to contain keycode assignments. OTOH I believe VIA backup files do, and if they have a QMK keyboard field the physical layout can be automatically fetched from it (when converted via qmk via2json).

[CosmoDm]

What I meant was to use the standard set as a generic 60%, 65%, TKL, Alice, 104/105 key layout and VIA keyboard definitions for the rest of the physical layouts. And take the logical layouts from the Kanata config. That is, allow parsing VIA keymap together with a Kanata keymap. And this is not an overkill, but very convenient.

I apologize if QMK/ZMK keymap is basically the same as VIA keymap. I'm not really familiar with the intricacies of those formats.

[caksoylar]

I see, thanks for your input. From your comment I understand that at least some amount of people would be using Kanata together with a programmable keyboard (e.g. using VIA). Then perhaps the last option of combining QMK/ZMK/VIA parsing with a Kanata keymap isn't overkill.

I would still like to support parsing without any firmware keymap input (since I imagine that'd still be the dominant use case), in which case it could default to assuming a standard keymap layout (e.g. US QWERTY 65%).

[jtroo]

Thanks for the discussion caksoylar 🙂.

Fwiw I use a split-ortho ZMK board and exclusively use Kanata for special keyboard behaviours, with the primary reason being faster experimentation loop.

Defaulting to a standard layout, with an optional info.json file to customize, sounds great to me!

[newsve]

warning, wall of text ahead but with a tl;dr at the end haha

also fyi, some important parts are edited...

in which case it could default to assuming a standard keymap layout (e.g. US QWERTY 65%).

Defaulting to some kind of 60% sounds like a great idea! Still there are some important details to be aware of, so it really does work for everyone, please correct me if I miss something:

• The default layout should work for the majority of users; following bullets should aim for being a common base for anyone
• Using the typical notebook keyboard as a baseline is great
• But I would leave out the function row for two reasons: While most notebooks have kind of similar function rows, they are just similar with subtle differences, to catch them all seems non-trivial; then and because the function row is so far way one rather maps f-keys on some layers closer to the home row than the way around, I have nothing mapped to the f-row
• I would treat the cursor keys similarity for the same reasons: Subtle differences across all boards and again, I map cursor keys closer to the home row and nothing mapped on the actual cursor keys, also that notebooks use two half keys but on one row make stuff even more complicated
• I am not a big fan of ISO and most of my keyboards are ANSI but since I am living in a ISO country, notebooks on discount come exclusively as ISO which isn't a problem, my keymaps work on both ANSI and ISO; what does it means for us: I would make ANSI plus the key IntlBackslash the default, see below; having two defaults for ANSI and ISO could work too but ISO has this strange altgr at the bottom, so that's another option
• Important: I mean ISO with an US keymapping, not a local mapping; while kanata can do this, it would be a huge fragmentation and user can easily use an US mapping on ISO to map the local keys as well
• So, we are somehow at some standard 60% ANSI and ISO layout; what about 65%? There are many 65% users out there, I wouldn't mind to put that extra cursor block on my maps but then you have those other keys next to Backspace, Backslash and Enter which vary a lot, everybody has there own layout; also when people start to remap they rather map stuff to the center than using these keys so far away; still nice, even when we ignore the 65% layout, people with a 65% can still use the default map
• What about the gravel and esc at the top-left (many keyboards map just an esc on the gravel assuming nobody is using gravel and backtick): we can just add both keys, so we catch all of them

After all the theory, here my defsrc catching all my gazillion keyboards from any notebook and any external (non-ergo) keyboard you can buy:

(defsrc
  esc
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]   \
  caps a    s    d    f    g    h    j    k    l    ;    '    ret
  lsft IntlBackslash  z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc              ralt rmet rctl
)

With this layout we catch all, in particular:

• Standard 60% ANSI, e.g. Wooting60, all notebooks sold in the US and in China
• Standard 60% ISO, notebooks from all other countries
• Every kind of 65%, both ANSI and ISO without the option to remap cursor keys
• Every other bigger keyboard, e.g. TKL, 100%, again without the option to remap further keys but again, also why should one?

When looking at Amazon, AliExpress and kbdfans, we should catch all mainstream layouts.

Again, if I missed something, pls correct me, my goal is to find the default working for anyone who want to remap their mainstream keyboard in order to be more efficient, have less finger movement, etc.

tl;dr: I'd suggest to have ANSI plus one key from ISO (IntBackslash) the default to catch all or two 60% defaults for ANSI and ISO

[caksoylar]

Hi, I have an initial implementation for a Kanata config parser at https://github.com/caksoylar/keymap-drawer/tree/kanata. You can test it by installing the branch with

pipx install git+https://github.com/caksoylar/keymap-drawer.git@kanata

(also see the general instructions in the readme.)

Then you can test it by using the kanata switch in keymap parse. You can pipe it directly to keymap draw to generate the SVG, or check the parser's output first:

keymap parse -k ~/kanata/cfg_samples/kanata.kbd | keymap draw - >kanata.svg

Currently it only shows keys from the basic 60% layout, and only understands the defsrc aliases used in e.g. the simple.kbd example. It can parse and show layer switches and toggles, tap-holds, one-shots, forks (as mod-morphs), combos (using defchordsv2-experimental only), multis (not very smartly), aliases and includes (not well tested) -- I am sure there are some bugs as well, let me know.

My plans are, in order of priority:

• Implement showing keys for layouts larger than 60% (staged approach similar to @newsve's suggestions above)
• Add support for using different aliases for defsrc keys (it'd be nice to have a definitive source besides the source code, but I'll extract from there otherwise)
• Think more about customization of the parsing behavior (currently raw_bindings_map can be used to override parse output, both before or after aliases are expanded)
• Look into deflocalkeys
• Handle defvar
• Platform-specific config?
• Look into advanced/weird features?
• Combine with ZMK/QMK parsing -- this is going to be difficult because there needs to be a mapping from the output of QMK/ZMK keycode to defsrc keys as well

Feedback welcome!

[jtroo]

Looks nice for the simple.kbd file!

---

For the multi action, perhaps display only the first 2 with an ellipsis for the rest? e.g. the @alp alias would be displayed as lsft +a ...

---

For the kanata.kbd file, the thing that stands out most is the output coming from defchordsv2, e.g. macro h e l l o. Perhaps (macro ...) could be displayed as macro? Or display only max 3 characters and ... for the rest, e.g. macro h e l ...?

Also is there a way to turn off drawing features? E.g. some might want to turn off chord drawing entirely, I know a few users who have generated 100s-1000s of chordsv2 chords and such use cases might not be desirable to be part of the SVG at all, for file size / loading / processing reasons. I looked through the config guide and didn't find a way; I did see separate_combo_diagrams though.

---

Add support for using different aliases for defsrc keys (it'd be nice to have a definitive source besides the source code, but I'll extract from there otherwise).

The code would be the definitive source, that being both str_to_oscode and add_default_str_osc_mappings. I could look to make this easier. A new program or a CLI flag could get all mappings, including those from deflocalkeys, and output to some useful format for keymap-drawer.

[caksoylar]

Thanks for having a look!

The defaults for bindings can definitely be improved, especially multi and macros. Both your suggestions for those make sense, we really shouldn't have 5+ lines for a key legend in any case, so truncation is needed. I also opted to leave aliases unexpanded for the unparsed cases (like macros, currently), but if an alias wasn't used you'd still want to truncate.

Also is there a way to turn off drawing features? E.g. some might want to turn off chord drawing entirely, I know a few users who have generated 100s-1000s of chordsv2 chords and such use cases might not be desirable to be part of the SVG at all, for file size / loading / processing reasons. I looked through the config guide and didn't find a way; I did see separate_combo_diagrams though.

There are a few controls for these:

• CLI args --keys-only and --combos-only for keymap draw can disable showing combos, or show only combos
• You can add a draw_separate field to the combo (in the parse output YAML) to draw that combo with a separate mini diagram
• If you set draw_config.separate_combo_diagrams in the config file you pass via keymap -c config.yaml draw ... it sets the default behavior for all combos for above setting (which you found)
  (For quick testing, you can use KEYMAP_separate_combo_diagrams=true keymap draw ...)

I could look to make this easier. A new program or a CLI flag could get all mappings, including those from deflocalkeys, and output to some useful format for keymap-drawer.

That would be useful! I usually like having a definitive data file for this kind of thing and having the code read from it, then external tools can use the same source of truth (by e.g. vendoring in that file). But having a way to export such a data file from the code would be useful as well, and I assume it'd be a less disruptive change on kanata side.

[jtroo]

That would be useful! I usually like having a definitive data file for this kind of thing

What data format would be useful? I'm not familiar with what keymap-drawer might use. E.g. in deflocalkeys users configure a mapping of name : number. Surely the number itself is not useful, but the number might end up coinciding with other defsrc keys due to locale differences. Should the data format allow knowing which defsrc names have a common output, and also contain the canonical name for that output? What would the source of canonical names be?

[caksoylar]

At the end of the day, what I need to do is assign the defsrc element to a key position in a, say, full size keyboard. Currently this happens (very simplistically and hardcoded) here. One example that'd let me do that would be the HID keycode for that defsrc alias, where I could hardcode the HID keycodes for a full size keyboard and do a lookup using that + the kanata mapping file. Instead of HID keycodes, it could be one of the defsrc aliases selected as canonical as well. But I will have a look at what Kanata is doing in the source code, I might have a more informed idea 😄

[caksoylar]

To clarify the HID keycode point, I meant e.g. the page ID+usage ID in https://usb.org/sites/default/files/hut1_2.pdf#page=83, like ZMK uses. (While I can't say I understand the code,) I see that Kanata has its own enums where e.g. 1-9 comes before QWERTY etc., which can be OK as the common output too. I think it would be enough that it is a fixed mapping that doesn't depend on Kanata implementation changes (like the USB HID IDs).