keyscore/README.md
Linus Björnstam 1da78595bd GUI: edit layouts, copy a layout, and start with saved files present
- The Layout tab edits the chosen layout: its three rows as text, or
  two keys swapped by clicking them on the board. Copy adds a copy to
  edit; built-in layouts cannot be edited.
- An edit that puts a character on two keys, or leaves a character of
  the texts on no key, is rejected and reported.
- The initial model is a function called from main. As a module-level
  value it read saved-layouts.txt, params.txt and presets/ where no
  scope is open, and the GUI did not start when one of them existed.
- The test covers the editor and runs with saved layouts present. It
  writes saved-layouts.txt back as it was.
- New screenshots, and a README section on editing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 12:03:16 +01:00

130 lines
4.8 KiB
Markdown

# keyscore
keyscore scores and optimizes keyboard layouts for an ISO Swedish keyboard
typed with the angle mod. It scores on Swedish and English text, and it has
a GUI for tuning the scoring.
It is written in [Bjolang](https://github.com/bjoli/bjolang). The GUI uses
bjogui.
![The Layout tab: the chosen layout on the board, and the parts of its score](docs/layout.png)
## The model
The scoring starts from Michael Capewell's rules and adds more rules. Lower
is better. A score is a cost per key press.
- **Key costs:** each key has a cost. A press costs the key's cost times the
key weight.
- **Vowels on the top row:** each press of a vowel on the top row costs
more.
- **Pairs:** a rule gives a cost or a bonus to each pair of presses on one
hand. The rules are stretch keys, same finger, jumps between the top and
bottom rows, easy jumps, close keys and adjacent keys. A pair with a space
between costs a share of the full cost.
- **Row motion:** a pair on one hand that changes rows costs by direction.
If the outer finger is up, the hand keeps its shape. If the inner finger
or a pinky is up, the hand twists. Pairs with the bottom row cost more,
except pairs with the index keys.
- **Triples:** hand runs, same-finger skips and two-finger runs.
- **Pinky load:** each pinky can type a share of all presses at no cost.
Each press past that share costs extra.
- **Finger distance:** how far the fingers travel, in key widths per press.
By default it is shown but not scored.
`src/score.bjo` describes each rule. `src/board.bjo` describes the board
and the key costs.
The texts are in `corpus/`:
- `sv.txt` and `en.txt` are extracts of featured Wikipedia articles.
`corpus/fetch.py` fetches them again. They have the same weight.
- `bjolang.txt` is Bjolang source code. Its weight is 0: it is shown but not
in the mean.
## Running
You need Bjolang. Put bjogui next to this folder, as `../bjogui`. Run the
programs from this folder.
| Command | What it does |
| --- | --- |
| `bjo run .` | Prints the report: each layout's score on each text, the parts of the scores, and the pairs that cost each layout most. |
| `bjo run src/gui.bjo` | Opens the GUI. |
| `bjo run src/optimize.bjo [runs] [steps] [layout] [t-start] [vowels-left] [fixed=CHARS]` | Searches for a better layout by simulated annealing. |
| `bjo run src/swaps.bjo [char] [layout]` | Tries to swap one character with each other key. |
| `bjo run src/word.bjo word [layout]` | Shows what a word costs a layout, pair by pair. |
| `bjo run tests/gui-shots.bjo [folder]` | Tests the GUI without a screen, and saves the screenshots in this file. |
All the programs score with the numbers in `params.txt` if that file exists.
If not, they use the defaults. The GUI writes `params.txt`.
## The GUI
The left side shows each layout's score, best first. A change to a number
rescores all the layouts at once. Click a layout to choose it for the
Layout and Search tabs.
Each number and option has a blue "i" mark. Point at the mark to see what
the setting does and its default value.
### Rules
All the numbers of the model, by group. You can save the numbers as a named
preset. Presets are kept in `presets/`. **Save** at the top writes the
numbers to `params.txt` for the other programs. **Defaults** puts back the
built-in numbers.
![The Rules tab](docs/rules.png)
### Key costs
The cost of each key, shown on the board.
![The Key costs tab](docs/key-costs.png)
### Layout
The chosen layout and each part of its score, for each text and as the mean.
You can save a layout under a name, or remove a layout that is not built in.
Saved layouts are kept in `saved-layouts.txt` and are listed at start.
To make a layout of your own, choose one and click **Copy**. Then change the
copy:
- Type in the three row fields. They use the same format as
`src/layouts.bjo`.
- Click two keys on the board to swap them.
The scores change at once. A built-in layout cannot be changed, and the
original of a copy does not change. An edit is rejected if a character is on
two keys, or if a character of the texts is on no key. A changed layout is
saved to the file only when you click **Save layout**.
![A copy of ZYK,Å with Y and Z swapped](docs/editing.png)
### Search
Runs the optimizer from the chosen layout with the current numbers. For each
result:
- **Keep** adds it to the list.
- **Save** saves it under the name in "Save as".
- **Copy** puts it on the clipboard as a `make-layout` form for
`src/layouts.bjo`.
![The Search tab, after a short search](docs/searched.png)
## Layouts
The built-in layouts are in `src/layouts.bjo`. A layout is three rows of
characters. The top row starts at Q, the home row at A and the bottom row at
<. Spaces are skipped. With the default numbers the optimized layouts score
about 4.3 to 4.5, Svdvorak scores 7.38 and QWERTY 15.38. An example is
ZYK,Å:
```
ZYK,Å XCHPW
IEDAÄ VTRNS
ÖUFO. Q GMLBJ
```