About creating keyboard configuration files

[fohrloop]

Hi, and first of all thanks for the awesome project! I'm in a process of trying the keyboard layout optimizer out, and trying to understand the configuration file options. Here are a few questions I have in mind:

• What is the unit in positions ? It's certainly not millimeters. Is that some arbitrary scale? Where are the numbers used in the optimization / evaluation process? Does it matter if I scale everything by 10, for example?
• How are the numbers for keys in plot_template_short and plot_template defined? Do you get it from the base_layout.keys; "only non-fixed" or "all", in insertion order, or is there some other logic?

[dariogoetz]

Thank you, I appreciate that :)

The positions are only used in the kla_distance metric that is switched off by default. This is a metric that corresponds to the KLA(next) analyzer and uses the same values as there. I am not sure, where these values come from, to be honest. At some point, I had the plan to use the positions to automatically draw the image of the configured keyboard, but never came to actually implementing this.

The numbers in the plot_template templates correspond to the keys defined in the other sections (base_layout.keys and also matrix_positions, positions, hands, fingers, ...) when counting from left to right, row after row (i.e. "flattening" the list of lists).
For the plot_template_short, only the non-fixed keys are accounted for, as you guessed, keeping the order from before the filtering.

[fohrloop]

Thank you for the ansswers @dariogoetz ! I had a pause in my keyboard layout optimization project but I'm back in business. Now I'm trying to understand the following options in the keyboard configuration yaml files.

First one is unbalancing_positions. I read from config/evaluation/default.yml:

  # If the movement involves unbalancing keys (horizontally or vertically), the corresponding
  # unbalancing values are weighted with this factor and multiplied to the result.
  unbalancing_factor: 0.5

but I'm still not understanding completely how should I define the unbalancing_positions. I see that in config/keyboard/chocolad.yml they are:

  unbalancing_positions:
    - [[0, 0.5], [0,   0], [0,  0], [0, 0.5], [1,    1],                  [-1,    1], [0, 0.5], [0, 0], [0,   0], [0, 0.5]]
    - [[0,   0], [0,   0], [0,  0], [0,   0], [1,    0],                  [-1,    0], [0,   0], [0, 0], [0,   0], [0,   0]]
    - [[0,   0], [0,   0], [0,  0], [0,   0], [1,   -1],                  [-1,   -1], [0,   0], [0, 0], [0,   0], [0,   0]]
    - [                             [0,   0], [0,    0],  [0, 0], [0, 0], [0,   0],   [0,   0],                           ]

Now there are few things: The unbalancing position seems to be defining something for the column and the row? Or what are the two numbers? What does [0, 0.5] mean? And what would [0, -0.5] mean? Or [0.5, 1] ? And what does this "result" mean? Is there a single score calculated for the layout?

Another one is symmetries. For example, from config/keyboard/chocolad.yml:

  symmetries:
    - [10, 11, 12, 13, 14,           14, 13, 12, 11, 10]
    - [16, 17, 18, 19, 20,           20, 19, 18, 17, 16]
    - [22, 23, 24, 25, 26,           26, 25, 24, 23, 22]
    - [            27, 28, 29,   29, 28, 27            ]

Are these just arbitrary numbers pairing two keys? What is the benefit of pairing the keys? What would it mean if I give the same number to three keys?

In addition, about the finger_resting_positions:

  finger_resting_positions:
    Left:
      Pinky: [50.5, 115.5]
      Ring: [100.5, 115.5]
      Middle: [150.5, 115.5]
      Index: [200.5, 115.5]
      Thumb: [230.5, 210.5]
    Right:
      Pinky: [650.5, 115.5]
      Ring: [600.5, 115.5]
      Middle: [550.5, 115.5]
      Index: [500.5, 115.5]
      Thumb: [470.5, 210.5]

Are these important? Is the unit same as in positions? If positions is not used, how does the program calculate penalties like

movement pattern - How comfortable is it to type individual bigrams? Which finger follows which? How many rows? Upwards/downwards?

Am I correct assuming that keyboard_layout_optimizer does count penalty for LSB (Lateral Stretch Bigrams) and overall movement?

[dariogoetz]

Thank you for the ansswers @dariogoetz ! I had a pause in my keyboard layout optimization project but I'm back in business. Now I'm trying to understand the following options in the keyboard configuration yaml files.

First one is unbalancing_positions. I read from config/evaluation/default.yml:

  # If the movement involves unbalancing keys (horizontally or vertically), the corresponding
  # unbalancing values are weighted with this factor and multiplied to the result.
  unbalancing_factor: 0.5

but I'm still not understanding completely how should I define the unbalancing_positions. I see that in config/keyboard/chocolad.yml they are:

  unbalancing_positions:
    - [[0, 0.5], [0,   0], [0,  0], [0, 0.5], [1,    1],                  [-1,    1], [0, 0.5], [0, 0], [0,   0], [0, 0.5]]
    - [[0,   0], [0,   0], [0,  0], [0,   0], [1,    0],                  [-1,    0], [0,   0], [0, 0], [0,   0], [0,   0]]
    - [[0,   0], [0,   0], [0,  0], [0,   0], [1,   -1],                  [-1,   -1], [0,   0], [0, 0], [0,   0], [0,   0]]
    - [                             [0,   0], [0,    0],  [0, 0], [0, 0], [0,   0],   [0,   0],                           ]

Now there are few things: The unbalancing position seems to be defining something for the column and the row? Or what are the two numbers? What does [0, 0.5] mean? And what would [0, -0.5] mean? Or [0.5, 1] ? And what does this "result" mean? Is there a single score calculated for the layout?

The unbalancing_positions shall describe, to which extent the hand needs to be moved out of their base position in order to press the key. It is a metric accounting for more "global" movement instead of the more local movement of individual fingers. The two items in these lists are movement horizontally and vertically. So [0, -0.5] means the hand needs to move 0.5 units (whatever that is) in negative vertical direction (so "down"). A [0.5, 1] means the hand moves 0.5 units to the right and one unit up.

Another one is symmetries. For example, from config/keyboard/chocolad.yml:

  symmetries:
    - [10, 11, 12, 13, 14,           14, 13, 12, 11, 10]
    - [16, 17, 18, 19, 20,           20, 19, 18, 17, 16]
    - [22, 23, 24, 25, 26,           26, 25, 24, 23, 22]
    - [            27, 28, 29,   29, 28, 27            ]

Are these just arbitrary numbers pairing two keys? What is the benefit of pairing the keys? What would it mean if I give the same number to three keys?

Yes, they are just any value that means that if the value is identical, the keys are considered "symmetric". If a third key has the same number, it would also be "symmetric" to the other two keys. This table is only used by the symmetric_handswitches metric that gives a negative cost to a bigram if the two corresponding keys are symmetric.

In addition, about the finger_resting_positions:

  finger_resting_positions:
    Left:
      Pinky: [50.5, 115.5]
      Ring: [100.5, 115.5]
      Middle: [150.5, 115.5]
      Index: [200.5, 115.5]
      Thumb: [230.5, 210.5]
    Right:
      Pinky: [650.5, 115.5]
      Ring: [600.5, 115.5]
      Middle: [550.5, 115.5]
      Index: [500.5, 115.5]
      Thumb: [470.5, 210.5]

Are these important? Is the unit same as in positions? If positions is not used, how does the program calculate penalties like

These values are only used by the kla_* metrics (if I recall correctly) in order to determine finger travel distances. These metrics are switched off by default. The values shall be aligned to the positions. They are also in line with the definitions of the KLAnext analyzer and assume 50 units width of a key.

movement pattern - How comfortable is it to type individual bigrams? Which finger follows which? How many rows? Upwards/downwards?

They are mostly depending on matrix_positions, finger_lengths, and `unbalancing_positions", see the code of the metric.

Am I correct assuming that keyboard_layout_optimizer does count penalty for LSB (Lateral Stretch Bigrams) and overall movement?

Yes. They are accounted for both in the metrics finger_repeats (for the SFB-case) and movement_pattern (for the non-SFB-case) with separate penalty factors for lateral stretches.

I suggest having a look at the code of the two metrics. It's not overly complicated and you should be able to understand the gist without excessive programming knowledge.