Swipe-o-Scope

Swipe-o-Scope is a visualiser for looking at gesture-typing data produced by Heliboard.

A screenshot of Swipe-o-Scope rendering a visualisation for the word "millionth"

What can I do with Swipe-o-Scope?

There are two main uses for Swipe-o-Scope:

1. Inspecting gestures out of curiousity about what Heliboard is exporting. You may also want to use Swipe-o-Scope to filter out private data from your gestures before you submit them to the Heliboard gesture data gathering project, if you prefer to do so on your computer instead of on your phone via Heliboard.

2. Sorting gestures into categorizations for testing. For instance, I use it to sort gestures into the "rejected" bin if a test failed on it... and it looks like the gesture is genuinely unusable. I also will sort a gesture into the "accepted" bin if a test failed on it and the gesture looks reasonably correct, and like a better algorithm should have gotten it right. I would otherwise leave a gesture as "unsorted", with the implication that it is "accepted" but unverified.

installation

Whether you want to use Swipe-o-Scope for your own reasons or you want to set up a dev environment, the process of getting setup is the same, currently. On a linux system that has QT 6.8-6.11 frameworks and python3 installed you need only follow these commands. If you don't have QT 6.8-6.11 installed, these steps should work anyway as pip should install a version locally just for use with this project.

cd folder/where/you/want/to/download/swipe-o-scope/ 
# this is not a literal file path, you should pick where to put it!
git clone https://codeberg.org/eclexic/swipe-o-scope.git
cd swipe-o-scope
python -m venv .venv
source .venv/bin/activate
pip install --editable .
python -m swipe_o_scope

To run swipe-o-scope again in the future you only need...

cd folder/you/where/you/cloned/swipe-o-scope/ 
# running "ls" in this folder should list this file you are reading now ("README.md"). 
# You should also see the "pyproject.toml" file, and the "src" directory.
source .venv/bin/activate
python -m swipe_o_scope

to update swipe-o-scope, you can...

cd folder/you/where/you/cloned/swipe-o-scope/ 
# same one you run swipe-o-scope from, as detailed above
git pull

If you would like to help package Swipe-o-Scope. I would love your assistance, as I don't have much time for it currently! I was hoping to package it for Windows, Mac, flatpak, and maybe the aur.

How do I get started?

Swipe-o-Scope wasn't made with the utmost usability in mind, it was made to get it written quickly for my own use. So, you may need some help getting started.

First to make a new project, find a folder to put it in, and then give a name to the project, which will be placed in a subfolder of that name.

After that, you can import a valid .gestures.json file(s); Heliboard produces valid .gestures.json files. There is also an example file "examples.gestures.json" in the root of this project.

After importing a file, you will be placed in a subproject for that imported file. This is to avoid overwhelming some of the QT components used in the interface... if say 50,000 gestures or more were loaded into the left hand table view at once... To reduce the likelihood of that, each imported file is relegated to its own subproject.

Swipe-o-Scope automatically saves every time a subproject is unloaded from the UI, when the window is closed, or 2 minutes after the last project edit. If you close it and come back, it should dump you back into the same project and subproject, with all the sorting you did preserved. There is no need to wait for an auto-save. Just close the window whenever, and wait for Swipe-o-Scope to shutdown gracefully.

No work was done to handle recovery from unexpected power loss, or other improper termination of swipe-o-scope. If the worst happens while files are writing, you are going to have a bad time. It is not super likely to happen, but backups are always encouraged.

I tried to do something and nothing happened

All errors are simply printed to console currently, in an effort to save me time while working on it. I expect you will be able to find some, as it has currently only been tested with English. If something silently fails, check the console.

Feel free to submit patches for more user centric error reporting, such as error popups for when opening invalid files, or when a word fails to properly render because a key in the word cannot be found on the keyboard. These are two known most important places exceptions would occur. The program won't crash, it just won't load the file or won't render the word path properly.

hidden features

Typing a # at the beginning of a gesture search will search the uuids instead of the display words.

Acknowledgements

The work taken to write the initial version of swipe-o-scope was paid for via funding provided by this nlnet's grant. The nlnet foundation logo