nucleuskit-toolkit 2.2.1__tar.gz → 2.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/PKG-INFO +61 -39
  2. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/README.md +60 -38
  3. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/__init__.py +1 -1
  4. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/__main__.py +6 -1
  5. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/pipeline.py +17 -3
  6. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/position/gps_processor.py +3 -2
  7. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/icons.py +14 -0
  8. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/main_window.py +9 -0
  9. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/offline_page.py +37 -8
  10. nucleuskit_toolkit-2.2.2/nucleuskit_toolkit/ui/pages/playback_helpers.py +153 -0
  11. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/playback_page.py +467 -104
  12. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/PKG-INFO +61 -39
  13. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/SOURCES.txt +3 -0
  14. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/pyproject.toml +1 -1
  15. nucleuskit_toolkit-2.2.2/tests/test_playback_plot.py +265 -0
  16. nucleuskit_toolkit-2.2.2/tests/test_release_pip.py +342 -0
  17. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_ui_pages.py +22 -11
  18. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/LICENSE +0 -0
  19. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/app.py +0 -0
  20. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/camera/__init__.py +0 -0
  21. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/camera/processing.py +0 -0
  22. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/config.py +0 -0
  23. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/__init__.py +0 -0
  24. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/constants.py +0 -0
  25. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/realtime/__init__.py +0 -0
  26. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/realtime/proxy.py +0 -0
  27. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/logging_utils.py +0 -0
  28. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/mqtt/__init__.py +0 -0
  29. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/mqtt/mqtt_controller.py +0 -0
  30. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/position/__init__.py +0 -0
  31. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/session_job.py +0 -0
  32. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/__init__.py +0 -0
  33. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/constants.py +0 -0
  34. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/realtime/__init__.py +0 -0
  35. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/realtime/proxy.py +0 -0
  36. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/__init__.py +0 -0
  37. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/eeg_regression.py +0 -0
  38. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/recording_merger.py +0 -0
  39. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/__init__.py +0 -0
  40. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/offline_job.py +0 -0
  41. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/__init__.py +0 -0
  42. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/about_page.py +0 -0
  43. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/channel_fixer_page.py +0 -0
  44. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/channel_gain_page.py +0 -0
  45. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/eeg_regression_page.py +0 -0
  46. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +0 -0
  47. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +0 -0
  48. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +0 -0
  49. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/recording_merge_page.py +0 -0
  50. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/revert_original_page.py +0 -0
  51. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/settings_page.py +0 -0
  52. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/tools_menu_page.py +0 -0
  53. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/plot_style.py +0 -0
  54. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_eeg_plot.py +0 -0
  55. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +0 -0
  56. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +0 -0
  57. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_shimmer_plot.py +0 -0
  58. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/__init__.py +0 -0
  59. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/branding/__init__.py +0 -0
  60. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
  61. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/session_inspect.py +0 -0
  62. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/theme.py +0 -0
  63. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/widgets.py +0 -0
  64. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/dependency_links.txt +0 -0
  65. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/entry_points.txt +0 -0
  66. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/requires.txt +0 -0
  67. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/top_level.txt +0 -0
  68. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/setup.cfg +0 -0
  69. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_config.py +0 -0
  70. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_hermes_ble_stream.py +0 -0
  71. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_imports.py +0 -0
  72. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_logging_redirect.py +0 -0
  73. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_offline_job.py +0 -0
  74. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_open_core_references.py +0 -0
  75. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_pipeline_cancel.py +0 -0
  76. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_plot_style.py +0 -0
  77. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_realtime_scan.py +0 -0
  78. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_session_inspect.py +0 -0
  79. {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.2.2}/tests/test_session_video_rotation.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: nucleuskit-toolkit
3
- Version: 2.2.1
3
+ Version: 2.2.2
4
4
  Summary: Nucleus-Kit offline processing toolkit (Hermes EEG/EMG, Shimmer PPG/EDA)
5
5
  Author: RE-AK Technologies Inc.
6
6
  License-Expression: GPL-3.0-or-later
@@ -63,11 +63,12 @@ Since version 2.0.0 the processing itself (heart dynamics, arousal, cognition, e
63
63
  - [Top-level folders](#top-level-folders)
64
64
  - [rawData/ — typical inputs](#rawdata--typical-inputs)
65
65
  - [features/ — notable outputs](#features--notable-outputs)
66
- - [results/ — primary toolkit tables](#results--primary-pipeline-tables)
66
+ - [results/ — primary toolkit tables](#results--primary-toolkit-tables)
67
67
  - [Optional POV movie conversion](#optional-pov-movie-conversion)
68
68
  - [Technical documentation](#technical-documentation)
69
69
  - [Trust and bundled models](#trust-and-bundled-models)
70
70
  - [Tests](#tests)
71
+ - [Releasing (maintainers)](#releasing-maintainers)
71
72
  - [License](#license)
72
73
 
73
74
  ## Requirements
@@ -88,22 +89,28 @@ upgraded by another tool installed next to it.
88
89
 
89
90
  ### From PyPI
90
91
 
92
+ The environment is created in the folder where you run these commands, as a `.venv` folder.
93
+
91
94
  **Windows (PowerShell)**
92
95
 
96
+ Open the folder where Nucleus-Kit should be installed. In File Explorer, click the address bar, type `powershell`, and press Enter. PowerShell opens in that folder.
97
+
93
98
  ```powershell
94
- python -m venv "$env:USERPROFILE\nucleuskit"
95
- & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install --upgrade pip
96
- & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install "nucleuskit-toolkit[gui]"
97
- & "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe" --help
99
+ python -m venv .venv
100
+ .\.venv\Scripts\python.exe -m pip install --upgrade pip
101
+ .\.venv\Scripts\python.exe -m pip install "nucleuskit-toolkit[gui]"
102
+ .\.venv\Scripts\nucleuskit-toolkit.exe --help
98
103
  ```
99
104
 
100
105
  **macOS / Linux**
101
106
 
107
+ In a terminal, `cd` to the folder where Nucleus-Kit should be installed, then:
108
+
102
109
  ```bash
103
- python3 -m venv ~/nucleuskit
104
- ~/nucleuskit/bin/python -m pip install --upgrade pip
105
- ~/nucleuskit/bin/python -m pip install "nucleuskit-toolkit[gui]"
106
- ~/nucleuskit/bin/nucleuskit-toolkit --help
110
+ python3 -m venv .venv
111
+ .venv/bin/python -m pip install --upgrade pip
112
+ .venv/bin/python -m pip install "nucleuskit-toolkit[gui]"
113
+ .venv/bin/nucleuskit-toolkit --help
107
114
  ```
108
115
 
109
116
  The `gui` extra installs the desktop interface (PySide6 / Qt 6), Bluetooth and serial streaming and MQTT. Without it
@@ -148,7 +155,7 @@ python3 -m venv .venv
148
155
  .venv/bin/python -m pytest
149
156
  ```
150
157
 
151
- The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0.1,<1.1` requirement, so pip keeps it instead of
158
+ The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0.2,<1.1` requirement, so pip keeps it instead of
152
159
  downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
153
160
  `[dev,gui]` extras (it needs re-ak-core on PyPI).
154
161
 
@@ -243,13 +250,14 @@ The environment variable `HERMES_FFMPEG_DIR` is the same folder and overrides th
243
250
 
244
251
  ### Upgrade and uninstall
245
252
 
246
- ```bash
247
- python -m pip install --upgrade "nucleuskit-toolkit[gui]"
248
- python -m pip uninstall nucleuskit-toolkit re-ak-core
253
+ ```powershell
254
+ .\.venv\Scripts\python.exe -m pip install --upgrade "nucleuskit-toolkit[gui]"
255
+ .\.venv\Scripts\python.exe -m pip uninstall nucleuskit-toolkit re-ak-core
249
256
  ```
250
257
 
251
- Use the environment's `python` (for example `"$env:USERPROFILE\nucleuskit\Scripts\python.exe"`), or delete the
252
- environment folder to remove everything. With pipx: `pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
258
+ Run these from the folder that contains `.venv`. On macOS and Linux, use `.venv/bin/python` in place of
259
+ `.\.venv\Scripts\python.exe`. Deleting the `.venv` folder removes the install. With pipx:
260
+ `pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
253
261
 
254
262
  ## Run
255
263
 
@@ -258,8 +266,10 @@ Run the commands with the environment's executables (as below), or activate the
258
266
 
259
267
  **Graphical mode** (see [Graphical interface](#graphical-interface); needs the `gui` extra):
260
268
 
269
+ From the folder that contains `.venv`:
270
+
261
271
  ```powershell
262
- & "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe"
272
+ .\.venv\Scripts\nucleuskit-toolkit.exe
263
273
  ```
264
274
 
265
275
  The same as `python -m nucleuskit_toolkit`. From a source checkout, `launch_app.bat` runs `python -m nucleuskit_toolkit`
@@ -267,8 +277,10 @@ with the first `python` on the PATH: activate the environment before running it.
267
277
 
268
278
  **Headless mode** (one session, then exit; for automation and CI):
269
279
 
280
+ From the folder that contains `.venv`:
281
+
270
282
  ```powershell
271
- nucleuskit-toolkit --session "D:\path\to\session_folder"
283
+ .\.venv\Scripts\nucleuskit-toolkit.exe --session "D:\path\to\session_folder"
272
284
  ```
273
285
 
274
286
  Options:
@@ -288,29 +300,27 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
288
300
 
289
301
  A desktop shortcut opens Nucleus-Kit like any other program. You do not type a Python command to start it.
290
302
 
291
- The [PyPI install](#from-pypi) saves the program in your user folder. Find it in File Explorer:
303
+ The install creates a `.venv` folder in the folder where you ran the commands. `pythonw.exe` is inside it:
292
304
 
293
- 1. Open **File Explorer**.
294
- 2. Click the address bar (the long box at the top that shows which folder is open).
295
- 3. Type `%USERPROFILE%\nucleuskit\Scripts` and press Enter.
305
+ 1. In File Explorer, open the folder where you ran the install (for example `D:\NucleusKit`).
306
+ 2. Open `.venv`, then `Scripts`.
296
307
 
297
- `%USERPROFILE%` is your personal folder, usually `C:\Users\` plus your Windows name, the same place that holds
298
- Documents and Downloads. The `Scripts` folder should contain a file named `pythonw.exe`.
308
+ That `Scripts` folder contains `pythonw.exe`. A [source install](#from-source-development) uses the same
309
+ `.venv\Scripts` folder inside the cloned repository. After a pipx install the file is in
310
+ `%USERPROFILE%\pipx\venvs\nucleuskit-toolkit\Scripts`.
299
311
 
300
- If File Explorer says that folder does not exist, the install was saved somewhere else. Use the search box in File
301
- Explorer and search for `pythonw.exe`. Pick the copy that is inside a folder named `Scripts`. After a pipx install
302
- that folder is `%USERPROFILE%\pipx\venvs\nucleuskit-toolkit\Scripts`. After a [source install](#from-source-development)
303
- it is the `.venv\Scripts` folder inside the cloned repository.
312
+ If you do not remember the folder, use the search box in File Explorer and search for `pythonw.exe`. Pick the copy
313
+ that is inside a `.venv\Scripts` folder.
304
314
 
305
315
  Create the shortcut from that file:
306
316
 
307
317
  1. In the `Scripts` folder, hold **Shift**, right-click `pythonw.exe`, and choose **Copy as path**. The copied text
308
- already has quotes around it, for example `"C:\Users\Alex\nucleuskit\Scripts\pythonw.exe"`.
318
+ already has quotes around it, for example `"D:\NucleusKit\.venv\Scripts\pythonw.exe"`.
309
319
  2. Right-click the desktop, then **New → Shortcut**.
310
320
  3. In **Type the location of the item**, paste that path, type a space, then type `-m nucleuskit_toolkit`.
311
321
  The full line looks like this, with your own path in place of the example:
312
322
 
313
- `"C:\Users\Alex\nucleuskit\Scripts\pythonw.exe" -m nucleuskit_toolkit`
323
+ `"D:\NucleusKit\.venv\Scripts\pythonw.exe" -m nucleuskit_toolkit`
314
324
 
315
325
  `pythonw.exe` opens the application window and does not leave a black command window on the screen.
316
326
  4. Click **Next**, name the shortcut **Nucleus-Kit**, and click **Finish**.
@@ -336,6 +346,7 @@ leave **Start in** empty.
336
346
  |--------|---------|
337
347
  | **Hermes headset** | EEG and EMG (including features used by the emotion model) |
338
348
  | **Shimmer wristband** | PPG and EDA (GSR processing in code maps to the Shimmer EDA channel) |
349
+ | **GPS** | Latitude and longitude, resampled to the shared 2 Hz timebase (`results/gpsDf.csv`) |
339
350
 
340
351
  ## Graphical interface
341
352
 
@@ -461,18 +472,15 @@ environment variables.
461
472
 
462
473
  ## Technical documentation
463
474
 
464
- The [`doc/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/) folder contains detailed technical descriptions of each processing toolkit for traceability and scientific reference. The heart, arousal, cognition, emotions and events processing now lives in re-ak-core: those pages describe Nucleus-Kit 1.1 and will move to re-ak-core's documentation; re-ak-core's CHANGELOG lists what changed since.
475
+ Heart, arousal, cognition, emotions and events are documented with [re-ak-core](https://github.com/fs-re-ak/re-ak-core/tree/main/doc). This repository documents the desktop orchestration and the steps that stay here. The Nucleus-Kit 1.1 algorithm pages are kept in [`doc/archive/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/archive).
465
476
 
466
- | File | Pipeline |
477
+ | File | What it describes |
467
478
  |------|----------|
468
- | [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) | Pipeline orchestration, step order, session layout, shared 2 Hz timebase |
469
- | [`doc/pipeline_heart.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_heart.md) | Shimmer PPG → Heart Rate Dynamics (SQI + MAD artifact rejection, NeuroKit2, HRV) |
470
- | [`doc/pipeline_arousal.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_arousal.md) | Shimmer EDA → Arousal (cvxEDA tonic/phasic decomposition, SCR detection) |
471
- | [`doc/pipeline_cognition.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_cognition.md) | Hermes EEG → Cognitive Indexes (Welch power bands, epoch-level artefact rejection, Engagement) |
472
- | [`doc/pipeline_emotions.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_emotions.md) | Hermes EMG → Emotion Classification (AVG_RMS artefact gate, two-stage LDA/KNN classifier) |
473
- | [`doc/pipeline_events.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_events.md) | Raw Events → Feature / Web Events + Playback Annotations |
474
- | [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS Positioning |
479
+ | [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) | Current step order: re-ak-core's pipeline plus POV, video rotation and GPS |
480
+ | [re-ak-core `doc/`](https://github.com/fs-re-ak/re-ak-core/tree/main/doc) | Heart, arousal, cognition, emotions, events, invalid samples, 2 Hz timebase |
481
+ | [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS positioning |
475
482
  | [`doc/mqtt_interface.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/mqtt_interface.md) | Vizia Mobile MQTT interface — status, commands, and tags |
483
+ | [`doc/archive/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/archive) | Nucleus-Kit 1.1 algorithm pages (modules removed in 2.0.0) |
476
484
 
477
485
  ## Trust and bundled models
478
486
 
@@ -486,6 +494,20 @@ pytest
486
494
 
487
495
  `tests/test_open_core_references.py` checks that Nucleus-Kit gives exactly re-ak-core's outputs on re-ak-core's synthetic sessions; it needs a `re-ak-core` checkout next to this repository (or `RE_AK_CORE=<path>`) and is skipped otherwise.
488
496
 
497
+ ## Releasing (maintainers)
498
+
499
+ Run this at the repository root, on an up-to-date `main`:
500
+
501
+ ```bat
502
+ .\deploy_pip_package.bat
503
+ ```
504
+
505
+ When the current version is already on PyPI, the script first shows the latest tag and asks for the new version, then opens the release notes in an editor (a draft of the commit subjects since that tag). It runs ruff and pytest, opens the pull request with the version files and the CHANGELOG section, and merges it, only if it changes nothing else. Then it continues with the release, so one run goes from the new version to PyPI.
506
+
507
+ For the release itself, the script checks versions, CHANGELOG and dependencies, pushes the tag that uploads to TestPyPI, tests that package in a throwaway venv, then asks for confirmation before creating the GitHub release that uploads to PyPI. When a run needs an approval on GitHub, it prints the link and waits. Run it again after any failure or Ctrl+C: it continues from what is already done. `.\deploy_pip_package.bat --dry-run` only runs the checks.
508
+
509
+ It needs `git`, an authenticated `gh`, Python 3.11 or newer and the `dev` extra. The upload itself is done by `.github/workflows/publish.yml` with Trusted Publishing, so no token is stored.
510
+
489
511
  ## License
490
512
 
491
513
  Copyright (C) 2026 RE-AK Technologies Inc.
@@ -22,11 +22,12 @@ Since version 2.0.0 the processing itself (heart dynamics, arousal, cognition, e
22
22
  - [Top-level folders](#top-level-folders)
23
23
  - [rawData/ — typical inputs](#rawdata--typical-inputs)
24
24
  - [features/ — notable outputs](#features--notable-outputs)
25
- - [results/ — primary toolkit tables](#results--primary-pipeline-tables)
25
+ - [results/ — primary toolkit tables](#results--primary-toolkit-tables)
26
26
  - [Optional POV movie conversion](#optional-pov-movie-conversion)
27
27
  - [Technical documentation](#technical-documentation)
28
28
  - [Trust and bundled models](#trust-and-bundled-models)
29
29
  - [Tests](#tests)
30
+ - [Releasing (maintainers)](#releasing-maintainers)
30
31
  - [License](#license)
31
32
 
32
33
  ## Requirements
@@ -47,22 +48,28 @@ upgraded by another tool installed next to it.
47
48
 
48
49
  ### From PyPI
49
50
 
51
+ The environment is created in the folder where you run these commands, as a `.venv` folder.
52
+
50
53
  **Windows (PowerShell)**
51
54
 
55
+ Open the folder where Nucleus-Kit should be installed. In File Explorer, click the address bar, type `powershell`, and press Enter. PowerShell opens in that folder.
56
+
52
57
  ```powershell
53
- python -m venv "$env:USERPROFILE\nucleuskit"
54
- & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install --upgrade pip
55
- & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install "nucleuskit-toolkit[gui]"
56
- & "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe" --help
58
+ python -m venv .venv
59
+ .\.venv\Scripts\python.exe -m pip install --upgrade pip
60
+ .\.venv\Scripts\python.exe -m pip install "nucleuskit-toolkit[gui]"
61
+ .\.venv\Scripts\nucleuskit-toolkit.exe --help
57
62
  ```
58
63
 
59
64
  **macOS / Linux**
60
65
 
66
+ In a terminal, `cd` to the folder where Nucleus-Kit should be installed, then:
67
+
61
68
  ```bash
62
- python3 -m venv ~/nucleuskit
63
- ~/nucleuskit/bin/python -m pip install --upgrade pip
64
- ~/nucleuskit/bin/python -m pip install "nucleuskit-toolkit[gui]"
65
- ~/nucleuskit/bin/nucleuskit-toolkit --help
69
+ python3 -m venv .venv
70
+ .venv/bin/python -m pip install --upgrade pip
71
+ .venv/bin/python -m pip install "nucleuskit-toolkit[gui]"
72
+ .venv/bin/nucleuskit-toolkit --help
66
73
  ```
67
74
 
68
75
  The `gui` extra installs the desktop interface (PySide6 / Qt 6), Bluetooth and serial streaming and MQTT. Without it
@@ -107,7 +114,7 @@ python3 -m venv .venv
107
114
  .venv/bin/python -m pytest
108
115
  ```
109
116
 
110
- The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0.1,<1.1` requirement, so pip keeps it instead of
117
+ The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0.2,<1.1` requirement, so pip keeps it instead of
111
118
  downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
112
119
  `[dev,gui]` extras (it needs re-ak-core on PyPI).
113
120
 
@@ -202,13 +209,14 @@ The environment variable `HERMES_FFMPEG_DIR` is the same folder and overrides th
202
209
 
203
210
  ### Upgrade and uninstall
204
211
 
205
- ```bash
206
- python -m pip install --upgrade "nucleuskit-toolkit[gui]"
207
- python -m pip uninstall nucleuskit-toolkit re-ak-core
212
+ ```powershell
213
+ .\.venv\Scripts\python.exe -m pip install --upgrade "nucleuskit-toolkit[gui]"
214
+ .\.venv\Scripts\python.exe -m pip uninstall nucleuskit-toolkit re-ak-core
208
215
  ```
209
216
 
210
- Use the environment's `python` (for example `"$env:USERPROFILE\nucleuskit\Scripts\python.exe"`), or delete the
211
- environment folder to remove everything. With pipx: `pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
217
+ Run these from the folder that contains `.venv`. On macOS and Linux, use `.venv/bin/python` in place of
218
+ `.\.venv\Scripts\python.exe`. Deleting the `.venv` folder removes the install. With pipx:
219
+ `pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
212
220
 
213
221
  ## Run
214
222
 
@@ -217,8 +225,10 @@ Run the commands with the environment's executables (as below), or activate the
217
225
 
218
226
  **Graphical mode** (see [Graphical interface](#graphical-interface); needs the `gui` extra):
219
227
 
228
+ From the folder that contains `.venv`:
229
+
220
230
  ```powershell
221
- & "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe"
231
+ .\.venv\Scripts\nucleuskit-toolkit.exe
222
232
  ```
223
233
 
224
234
  The same as `python -m nucleuskit_toolkit`. From a source checkout, `launch_app.bat` runs `python -m nucleuskit_toolkit`
@@ -226,8 +236,10 @@ with the first `python` on the PATH: activate the environment before running it.
226
236
 
227
237
  **Headless mode** (one session, then exit; for automation and CI):
228
238
 
239
+ From the folder that contains `.venv`:
240
+
229
241
  ```powershell
230
- nucleuskit-toolkit --session "D:\path\to\session_folder"
242
+ .\.venv\Scripts\nucleuskit-toolkit.exe --session "D:\path\to\session_folder"
231
243
  ```
232
244
 
233
245
  Options:
@@ -247,29 +259,27 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
247
259
 
248
260
  A desktop shortcut opens Nucleus-Kit like any other program. You do not type a Python command to start it.
249
261
 
250
- The [PyPI install](#from-pypi) saves the program in your user folder. Find it in File Explorer:
262
+ The install creates a `.venv` folder in the folder where you ran the commands. `pythonw.exe` is inside it:
251
263
 
252
- 1. Open **File Explorer**.
253
- 2. Click the address bar (the long box at the top that shows which folder is open).
254
- 3. Type `%USERPROFILE%\nucleuskit\Scripts` and press Enter.
264
+ 1. In File Explorer, open the folder where you ran the install (for example `D:\NucleusKit`).
265
+ 2. Open `.venv`, then `Scripts`.
255
266
 
256
- `%USERPROFILE%` is your personal folder, usually `C:\Users\` plus your Windows name, the same place that holds
257
- Documents and Downloads. The `Scripts` folder should contain a file named `pythonw.exe`.
267
+ That `Scripts` folder contains `pythonw.exe`. A [source install](#from-source-development) uses the same
268
+ `.venv\Scripts` folder inside the cloned repository. After a pipx install the file is in
269
+ `%USERPROFILE%\pipx\venvs\nucleuskit-toolkit\Scripts`.
258
270
 
259
- If File Explorer says that folder does not exist, the install was saved somewhere else. Use the search box in File
260
- Explorer and search for `pythonw.exe`. Pick the copy that is inside a folder named `Scripts`. After a pipx install
261
- that folder is `%USERPROFILE%\pipx\venvs\nucleuskit-toolkit\Scripts`. After a [source install](#from-source-development)
262
- it is the `.venv\Scripts` folder inside the cloned repository.
271
+ If you do not remember the folder, use the search box in File Explorer and search for `pythonw.exe`. Pick the copy
272
+ that is inside a `.venv\Scripts` folder.
263
273
 
264
274
  Create the shortcut from that file:
265
275
 
266
276
  1. In the `Scripts` folder, hold **Shift**, right-click `pythonw.exe`, and choose **Copy as path**. The copied text
267
- already has quotes around it, for example `"C:\Users\Alex\nucleuskit\Scripts\pythonw.exe"`.
277
+ already has quotes around it, for example `"D:\NucleusKit\.venv\Scripts\pythonw.exe"`.
268
278
  2. Right-click the desktop, then **New → Shortcut**.
269
279
  3. In **Type the location of the item**, paste that path, type a space, then type `-m nucleuskit_toolkit`.
270
280
  The full line looks like this, with your own path in place of the example:
271
281
 
272
- `"C:\Users\Alex\nucleuskit\Scripts\pythonw.exe" -m nucleuskit_toolkit`
282
+ `"D:\NucleusKit\.venv\Scripts\pythonw.exe" -m nucleuskit_toolkit`
273
283
 
274
284
  `pythonw.exe` opens the application window and does not leave a black command window on the screen.
275
285
  4. Click **Next**, name the shortcut **Nucleus-Kit**, and click **Finish**.
@@ -295,6 +305,7 @@ leave **Start in** empty.
295
305
  |--------|---------|
296
306
  | **Hermes headset** | EEG and EMG (including features used by the emotion model) |
297
307
  | **Shimmer wristband** | PPG and EDA (GSR processing in code maps to the Shimmer EDA channel) |
308
+ | **GPS** | Latitude and longitude, resampled to the shared 2 Hz timebase (`results/gpsDf.csv`) |
298
309
 
299
310
  ## Graphical interface
300
311
 
@@ -420,18 +431,15 @@ environment variables.
420
431
 
421
432
  ## Technical documentation
422
433
 
423
- The [`doc/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/) folder contains detailed technical descriptions of each processing toolkit for traceability and scientific reference. The heart, arousal, cognition, emotions and events processing now lives in re-ak-core: those pages describe Nucleus-Kit 1.1 and will move to re-ak-core's documentation; re-ak-core's CHANGELOG lists what changed since.
434
+ Heart, arousal, cognition, emotions and events are documented with [re-ak-core](https://github.com/fs-re-ak/re-ak-core/tree/main/doc). This repository documents the desktop orchestration and the steps that stay here. The Nucleus-Kit 1.1 algorithm pages are kept in [`doc/archive/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/archive).
424
435
 
425
- | File | Pipeline |
436
+ | File | What it describes |
426
437
  |------|----------|
427
- | [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) | Pipeline orchestration, step order, session layout, shared 2 Hz timebase |
428
- | [`doc/pipeline_heart.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_heart.md) | Shimmer PPG → Heart Rate Dynamics (SQI + MAD artifact rejection, NeuroKit2, HRV) |
429
- | [`doc/pipeline_arousal.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_arousal.md) | Shimmer EDA → Arousal (cvxEDA tonic/phasic decomposition, SCR detection) |
430
- | [`doc/pipeline_cognition.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_cognition.md) | Hermes EEG → Cognitive Indexes (Welch power bands, epoch-level artefact rejection, Engagement) |
431
- | [`doc/pipeline_emotions.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_emotions.md) | Hermes EMG → Emotion Classification (AVG_RMS artefact gate, two-stage LDA/KNN classifier) |
432
- | [`doc/pipeline_events.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_events.md) | Raw Events → Feature / Web Events + Playback Annotations |
433
- | [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS Positioning |
438
+ | [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) | Current step order: re-ak-core's pipeline plus POV, video rotation and GPS |
439
+ | [re-ak-core `doc/`](https://github.com/fs-re-ak/re-ak-core/tree/main/doc) | Heart, arousal, cognition, emotions, events, invalid samples, 2 Hz timebase |
440
+ | [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS positioning |
434
441
  | [`doc/mqtt_interface.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/mqtt_interface.md) | Vizia Mobile MQTT interface — status, commands, and tags |
442
+ | [`doc/archive/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/archive) | Nucleus-Kit 1.1 algorithm pages (modules removed in 2.0.0) |
435
443
 
436
444
  ## Trust and bundled models
437
445
 
@@ -445,6 +453,20 @@ pytest
445
453
 
446
454
  `tests/test_open_core_references.py` checks that Nucleus-Kit gives exactly re-ak-core's outputs on re-ak-core's synthetic sessions; it needs a `re-ak-core` checkout next to this repository (or `RE_AK_CORE=<path>`) and is skipped otherwise.
447
455
 
456
+ ## Releasing (maintainers)
457
+
458
+ Run this at the repository root, on an up-to-date `main`:
459
+
460
+ ```bat
461
+ .\deploy_pip_package.bat
462
+ ```
463
+
464
+ When the current version is already on PyPI, the script first shows the latest tag and asks for the new version, then opens the release notes in an editor (a draft of the commit subjects since that tag). It runs ruff and pytest, opens the pull request with the version files and the CHANGELOG section, and merges it, only if it changes nothing else. Then it continues with the release, so one run goes from the new version to PyPI.
465
+
466
+ For the release itself, the script checks versions, CHANGELOG and dependencies, pushes the tag that uploads to TestPyPI, tests that package in a throwaway venv, then asks for confirmation before creating the GitHub release that uploads to PyPI. When a run needs an approval on GitHub, it prints the link and waits. Run it again after any failure or Ctrl+C: it continues from what is already done. `.\deploy_pip_package.bat --dry-run` only runs the checks.
467
+
468
+ It needs `git`, an authenticated `gh`, Python 3.11 or newer and the `dev` extra. The upload itself is done by `.github/workflows/publish.yml` with Trusted Publishing, so no token is stored.
469
+
448
470
  ## License
449
471
 
450
472
  Copyright (C) 2026 RE-AK Technologies Inc.
@@ -1,3 +1,3 @@
1
1
  """Nucleus-Kit offline processing toolkit (``python -m nucleuskit_toolkit``)."""
2
2
 
3
- __version__ = "2.2.1"
3
+ __version__ = "2.2.2"
@@ -39,6 +39,11 @@ def main(argv: list[str] | None = None) -> int:
39
39
  f"(default: {DEFAULT_MODEL}). Available: {', '.join(available_models())}."
40
40
  ),
41
41
  )
42
+ parser.add_argument(
43
+ "--force",
44
+ action="store_true",
45
+ help="Recompute and replace existing features and results (other files in those folders are kept).",
46
+ )
42
47
  ns = parser.parse_args(argv)
43
48
 
44
49
  if ns.session:
@@ -46,7 +51,7 @@ def main(argv: list[str] | None = None) -> int:
46
51
  from nucleuskit_toolkit.session_job import session_job_from_folder
47
52
 
48
53
  job = session_job_from_folder(ns.session, pov_config_json=ns.config)
49
- pipe = NucleusKitProcessingToolkit(None, emotion_model=ns.emotion_model)
54
+ pipe = NucleusKitProcessingToolkit(None, emotion_model=ns.emotion_model, force=ns.force)
50
55
  pipe.processSession(job)
51
56
  return 0
52
57
 
@@ -17,7 +17,6 @@ from reak_core.pipeline import FunctionStep, Pipeline, RunContext, StepResult
17
17
  from nucleuskit_toolkit.camera import convertPOVMovieClip, ensure_session_video_rotated_180
18
18
  from nucleuskit_toolkit.config import resolve_pov_settings
19
19
  from nucleuskit_toolkit.logging_utils import printError, printInfo, printWarning
20
- from nucleuskit_toolkit.position import processGPS
21
20
 
22
21
 
23
22
  class BasePipeline(ABC):
@@ -65,6 +64,17 @@ def _local_step(name: str, fn) -> FunctionStep:
65
64
  return FunctionStep(name, run)
66
65
 
67
66
 
67
+ def _gps_step() -> FunctionStep:
68
+ """GPS step: passes ``force`` from the run context so cached results are replaced when requested."""
69
+
70
+ def run(session: Session, context: RunContext) -> dict:
71
+ from nucleuskit_toolkit.position import processGPS
72
+ processGPS(session.root, force=context.force)
73
+ return {}
74
+
75
+ return FunctionStep("gps", run)
76
+
77
+
68
78
  class _LoggedStep:
69
79
  """Prints the Nucleus-Kit progress line before running the wrapped step.
70
80
 
@@ -102,13 +112,14 @@ def build_pipeline(
102
112
  skip_video_rotation: bool = False,
103
113
  apply_nlms: bool = True,
104
114
  emotion_model: str | None = None,
115
+ force: bool = False,
105
116
  cancel: threading.Event | None = None,
106
117
  ) -> Pipeline:
107
118
  """re-ak-core's default pipeline with the Nucleus-Kit local steps, in Nucleus-Kit's order."""
108
- pipeline = Pipeline.default(emotion_model=emotion_model, apply_nlms=apply_nlms)
119
+ pipeline = Pipeline.default(emotion_model=emotion_model, apply_nlms=apply_nlms, force=force)
109
120
  if not skip_video_rotation:
110
121
  pipeline.with_step(_local_step("video_rotation", ensure_session_video_rotated_180), after="prepare")
111
- pipeline.with_step(_local_step("gps", processGPS))
122
+ pipeline.with_step(_gps_step())
112
123
  pipeline.steps = [_LoggedStep(step, cancel) for step in pipeline.steps]
113
124
  if cancel is not None:
114
125
  pipeline.exporters = [_CancellableExporter(exporter, cancel) for exporter in pipeline.exporters]
@@ -127,6 +138,7 @@ class NucleusKitProcessingToolkit(BasePipeline):
127
138
  skip_video_rotation: bool = False,
128
139
  apply_nlms: bool = True,
129
140
  emotion_model: str | None = None,
141
+ force: bool = False,
130
142
  cancel: threading.Event | None = None,
131
143
  ):
132
144
  super().__init__(configuration)
@@ -135,6 +147,7 @@ class NucleusKitProcessingToolkit(BasePipeline):
135
147
  self._skip_video_rotation = skip_video_rotation
136
148
  self._apply_nlms = apply_nlms
137
149
  self._emotion_model = emotion_model
150
+ self._force = force
138
151
  self._cancel = cancel
139
152
 
140
153
  if configuration is None:
@@ -190,5 +203,6 @@ class NucleusKitProcessingToolkit(BasePipeline):
190
203
  skip_video_rotation=self._skip_video_rotation,
191
204
  apply_nlms=self._apply_nlms,
192
205
  emotion_model=self._emotion_model,
206
+ force=self._force,
193
207
  cancel=self._cancel,
194
208
  )
@@ -22,7 +22,7 @@ _GPS_FILENAMES = ["gps.csv", "gps.tmp"]
22
22
  _GRID_STEP_S = 0.5 # shared 2 Hz / 0.5 s pipeline timebase
23
23
 
24
24
 
25
- def processGPS(recpath):
25
+ def processGPS(recpath, *, force: bool = False):
26
26
  """
27
27
  Process GPS tracking data.
28
28
 
@@ -32,11 +32,12 @@ def processGPS(recpath):
32
32
 
33
33
  Args:
34
34
  recpath: Path to the recording directory
35
+ force: Recompute even when results/gpsDf.csv already exists.
35
36
  """
36
37
  printInfo(f"{GPS_HDR}Processing GPS data")
37
38
 
38
39
  out_path = os.path.join(recpath, "results", "gpsDf.csv")
39
- if os.path.exists(out_path):
40
+ if not force and os.path.exists(out_path):
40
41
  printInfo(f"{GPS_HDR}GPS already processed, using cached results")
41
42
  return
42
43
 
@@ -18,6 +18,7 @@ from PySide6.QtWidgets import QSizePolicy, QWidget
18
18
  _PATHS: dict[str, str] = {
19
19
  "activity": '<polyline points="22 12 18 12 15 21 9 3 6 12 2 12"/>',
20
20
  "play": '<polygon points="7 4 20 12 7 20 7 4"/>',
21
+ "pause": '<path d="M8 5v14M16 5v14"/>',
21
22
  "square": '<rect x="6" y="6" width="12" height="12" rx="1.5"/>',
22
23
  "settings": (
23
24
  '<circle cx="12" cy="12" r="3"/>'
@@ -47,6 +48,19 @@ _PATHS: dict[str, str] = {
47
48
  '<path d="M3 6h18M8 6V4a1 1 0 0 1 1-1h6a1 1 0 0 1 1 1v2"/>'
48
49
  '<path d="M5.5 6l1 14a2 2 0 0 0 2 2h7a2 2 0 0 0 2-2l1-14M10 11v6M14 11v6"/>'
49
50
  ),
51
+ "grip": (
52
+ '<circle cx="9" cy="6" r="1.2" fill="currentColor"/>'
53
+ '<circle cx="9" cy="12" r="1.2" fill="currentColor"/>'
54
+ '<circle cx="9" cy="18" r="1.2" fill="currentColor"/>'
55
+ '<circle cx="15" cy="6" r="1.2" fill="currentColor"/>'
56
+ '<circle cx="15" cy="12" r="1.2" fill="currentColor"/>'
57
+ '<circle cx="15" cy="18" r="1.2" fill="currentColor"/>'
58
+ ),
59
+ "save": (
60
+ '<path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/>'
61
+ '<path d="M17 21v-8H7v8M7 3v5h8"/>'
62
+ ),
63
+ "panel": '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M15 4v16"/>',
50
64
  "radio": (
51
65
  '<circle cx="12" cy="12" r="2"/><path d="M16.2 7.8a6 6 0 0 1 0 8.4M7.8 16.2a6 6 0 0 1 0-8.4"/>'
52
66
  '<path d="M19.1 4.9a10 10 0 0 1 0 14.2M4.9 19.1a10 10 0 0 1 0-14.2"/>'
@@ -350,6 +350,7 @@ class MainWindow(QMainWindow):
350
350
  def show_page(self, key: str) -> None:
351
351
  if key == self._current and key in self._pages:
352
352
  self._sidebar.set_current(PAGES[key].nav or key)
353
+ self._claim_page_focus(key)
353
354
  return
354
355
  current = self._pages.get(self._current)
355
356
  can_leave = getattr(current, "can_leave", None)
@@ -364,6 +365,7 @@ class MainWindow(QMainWindow):
364
365
  self._current = key
365
366
  if key in self._pages:
366
367
  self._stack.setCurrentWidget(self._pages[key])
368
+ self._claim_page_focus(key)
367
369
  return
368
370
  self._pending = key
369
371
  self._loading.show_for(spec.title)
@@ -386,6 +388,13 @@ class MainWindow(QMainWindow):
386
388
  if self._pending == key:
387
389
  self._loading.spinner.stop()
388
390
  self._stack.setCurrentWidget(page)
391
+ self._claim_page_focus(key)
392
+
393
+ def _claim_page_focus(self, key: str) -> None:
394
+ page = self._pages.get(key)
395
+ claim = getattr(page, "claim_keyboard_focus", None)
396
+ if callable(claim):
397
+ claim()
389
398
 
390
399
  def _connect_page(self, key: str, page: QWidget) -> None:
391
400
  if key == "tools":