nucleuskit-toolkit 2.2.0__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.0 → nucleuskit_toolkit-2.2.2}/PKG-INFO +254 -88
  2. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/README.md +252 -86
  3. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/__init__.py +1 -1
  4. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/__main__.py +6 -1
  5. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/pipeline.py +17 -3
  6. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/position/gps_processor.py +3 -2
  7. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/icons.py +14 -0
  8. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/main_window.py +11 -2
  9. {nucleuskit_toolkit-2.2.0 → 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.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/playback_page.py +467 -104
  12. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/PKG-INFO +254 -88
  13. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/SOURCES.txt +3 -0
  14. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/requires.txt +1 -1
  15. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/pyproject.toml +2 -2
  16. nucleuskit_toolkit-2.2.2/tests/test_playback_plot.py +265 -0
  17. nucleuskit_toolkit-2.2.2/tests/test_release_pip.py +342 -0
  18. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_ui_pages.py +22 -11
  19. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/LICENSE +0 -0
  20. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/app.py +0 -0
  21. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/camera/__init__.py +0 -0
  22. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/camera/processing.py +0 -0
  23. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/config.py +0 -0
  24. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/__init__.py +0 -0
  25. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/constants.py +0 -0
  26. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/realtime/__init__.py +0 -0
  27. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/realtime/proxy.py +0 -0
  28. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/logging_utils.py +0 -0
  29. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/mqtt/__init__.py +0 -0
  30. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/mqtt/mqtt_controller.py +0 -0
  31. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/position/__init__.py +0 -0
  32. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/session_job.py +0 -0
  33. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/__init__.py +0 -0
  34. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/constants.py +0 -0
  35. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/realtime/__init__.py +0 -0
  36. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/realtime/proxy.py +0 -0
  37. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/__init__.py +0 -0
  38. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/eeg_regression.py +0 -0
  39. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/recording_merger.py +0 -0
  40. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/__init__.py +0 -0
  41. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/offline_job.py +0 -0
  42. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/__init__.py +0 -0
  43. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/about_page.py +0 -0
  44. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/channel_fixer_page.py +0 -0
  45. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/channel_gain_page.py +0 -0
  46. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/eeg_regression_page.py +0 -0
  47. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +0 -0
  48. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +0 -0
  49. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +0 -0
  50. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/recording_merge_page.py +0 -0
  51. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/revert_original_page.py +0 -0
  52. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/settings_page.py +0 -0
  53. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/tools_menu_page.py +0 -0
  54. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/plot_style.py +0 -0
  55. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_eeg_plot.py +0 -0
  56. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +0 -0
  57. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +0 -0
  58. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_shimmer_plot.py +0 -0
  59. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/__init__.py +0 -0
  60. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/branding/__init__.py +0 -0
  61. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
  62. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/session_inspect.py +0 -0
  63. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/theme.py +0 -0
  64. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/widgets.py +0 -0
  65. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/dependency_links.txt +0 -0
  66. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/entry_points.txt +0 -0
  67. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/top_level.txt +0 -0
  68. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/setup.cfg +0 -0
  69. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_config.py +0 -0
  70. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_hermes_ble_stream.py +0 -0
  71. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_imports.py +0 -0
  72. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_logging_redirect.py +0 -0
  73. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_offline_job.py +0 -0
  74. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_open_core_references.py +0 -0
  75. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_pipeline_cancel.py +0 -0
  76. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_plot_style.py +0 -0
  77. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_realtime_scan.py +0 -0
  78. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_session_inspect.py +0 -0
  79. {nucleuskit_toolkit-2.2.0 → 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.0
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
@@ -21,7 +21,7 @@ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
21
21
  Requires-Python: >=3.10
22
22
  Description-Content-Type: text/markdown
23
23
  License-File: LICENSE
24
- Requires-Dist: re-ak-core<1.1,>=1.0.1
24
+ Requires-Dist: re-ak-core<1.1,>=1.0.2
25
25
  Requires-Dist: numpy>=2.5
26
26
  Requires-Dist: pandas>=2.3
27
27
  Requires-Dist: scipy<1.18,>=1.17
@@ -47,74 +47,37 @@ Since version 2.0.0 the processing itself (heart dynamics, arousal, cognition, e
47
47
 
48
48
  ## Table of contents
49
49
 
50
- - [Hardware mapping](#hardware-mapping)
51
- - [Graphical interface](#graphical-interface)
52
- - [Tools submenu](#tools-submenu)
53
50
  - [Requirements](#requirements)
54
51
  - [Install](#install)
55
52
  - [From PyPI](#from-pypi)
56
53
  - [From source (development)](#from-source-development)
54
+ - [FFmpeg](#ffmpeg)
57
55
  - [Upgrade and uninstall](#upgrade-and-uninstall)
58
56
  - [Run](#run)
59
57
  - [Desktop shortcut (Windows)](#desktop-shortcut-windows)
60
58
  - [Troubleshooting](#troubleshooting)
59
+ - [Hardware mapping](#hardware-mapping)
60
+ - [Graphical interface](#graphical-interface)
61
+ - [Tools submenu (experimental)](#tools-submenu)
61
62
  - [Session layout](#session-layout)
62
63
  - [Top-level folders](#top-level-folders)
63
64
  - [rawData/ — typical inputs](#rawdata--typical-inputs)
64
65
  - [features/ — notable outputs](#features--notable-outputs)
65
- - [results/ — primary toolkit tables](#results--primary-pipeline-tables)
66
- - [Optional POV / ffmpeg configuration](#optional-pov--ffmpeg-configuration)
66
+ - [results/ — primary toolkit tables](#results--primary-toolkit-tables)
67
+ - [Optional POV movie conversion](#optional-pov-movie-conversion)
67
68
  - [Technical documentation](#technical-documentation)
68
69
  - [Trust and bundled models](#trust-and-bundled-models)
69
70
  - [Tests](#tests)
71
+ - [Releasing (maintainers)](#releasing-maintainers)
70
72
  - [License](#license)
71
73
 
72
- ## Hardware mapping
73
-
74
- | Device | Signals |
75
- |--------|---------|
76
- | **Hermes headset** | EEG and EMG (including features used by the emotion model) |
77
- | **Shimmer wristband** | PPG and EDA (GSR processing in code maps to the Shimmer EDA channel) |
78
-
79
- ## Graphical interface
80
-
81
- After `python -m nucleuskit_toolkit` (or `nucleuskit-toolkit`), the window shows a sidebar on the left and the selected
82
- page on the right. Every page has a title, a one-line description and a **Help** link to this documentation. A page
83
- opened for the first time shows a loading screen while its libraries load (a few seconds on the first launch); they
84
- are also loaded in the background right after start-up.
85
-
86
- | Sidebar item | Purpose |
87
- |------|---------|
88
- | **Process** | Run the pipeline on one session folder or on every session of a dataset folder. The selected folder is checked as you type (read only): session name, duration and recorded signals, or for a dataset the number of sessions and how many are incomplete. Run is enabled once the folder is valid; while running it becomes **Cancel**, which finishes the step in progress and skips the rest. In a dataset, a failing session does not stop the others. |
89
- | **Real-time viewer** | Connect to a Hermes headset over BLE (devices appear in the list as soon as the scan sees them) and an optional Shimmer over serial: stream, plot EEG / motion / Shimmer signals, and record into a session-style folder. |
90
- | **Playback** | Review a processed session: optional `rawData/video.mp4` plus time-aligned plots from `results/*.csv`, with editable event annotations when available. |
91
- | **Tools** | Maintenance utilities for processed sessions (see below). |
92
- | **MQTT Controller** | Connect to a broker (e.g. Vizia Mobile), discover devices from status traffic, and send recording-related MQTT commands. |
93
- | **Settings** | Theme (light, dark, or system), persisted under **REAK / NucleusKitToolkit** via `QSettings`. |
94
- | **Documentation** | Opens the technical documentation in the browser. |
95
- | **About** | Nucleus-Kit and re-ak-core versions, available emotion models, license and links. |
96
-
97
- Leaving a page is refused while it is busy (a run in progress, a device connected or connecting, unsaved playback
98
- annotations are offered for saving first).
99
-
100
- ### Tools submenu
101
-
102
- | Item | Purpose |
103
- |------|---------|
104
- | **Channel Fixer** | Repair a single bad RMS channel in an already-processed session using the bundled channel-fix model. |
105
- | **Channel gain adjustment** | Adjust per-channel RMS gain and zero offset against a reference distribution; updates working emotion RMS features. |
106
- | **Revert to original** | Restore working RMS features from the frozen baseline under `features/emotions/original/`. |
107
- | **PPG Fixer** | Re-run PPG artifact rejection and HRV computation on an already-processed session (useful when tuning rejection thresholds without reprocessing the full pipeline). |
108
- | **EEG Regression Denoising** | Remove shared muscle noise from the EEG by regression on the EMG reference channels, then recompute the cognition outputs. |
109
- | **Recording Merger** | Join up to 5 recordings into one session, with empty CSV rows and black video for the gaps. |
110
-
111
74
  ## Requirements
112
75
 
113
76
  - **Python 3.10, 3.11 or 3.12** (3.12 recommended). Check with `python --version` (`py --version` on Windows).
114
77
  On Windows, install it from [python.org](https://www.python.org/downloads/windows/) and tick **Add python.exe to
115
78
  PATH** in the installer.
116
- - **ffmpeg** (optional): only for POV movie conversion and session video rotation. Point Nucleus-Kit to it with
117
- `ffmpeg_dir` (see [Optional POV / ffmpeg configuration](#optional-pov--ffmpeg-configuration)).
79
+ - **FFmpeg** (a system program, not a pip package) for session video, the Recording Merger and optional POV
80
+ conversion. Biosignal processing runs without it. Install it with the other setup steps: [FFmpeg](#ffmpeg).
118
81
  - Dependencies are declared in [`pyproject.toml`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/pyproject.toml);
119
82
  [`requirements.txt`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/requirements.txt) pins the
120
83
  exact versions that were tested, GUI extras included.
@@ -126,22 +89,28 @@ upgraded by another tool installed next to it.
126
89
 
127
90
  ### From PyPI
128
91
 
92
+ The environment is created in the folder where you run these commands, as a `.venv` folder.
93
+
129
94
  **Windows (PowerShell)**
130
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
+
131
98
  ```powershell
132
- python -m venv "$env:USERPROFILE\nucleuskit"
133
- & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install --upgrade pip
134
- & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install "nucleuskit-toolkit[gui]"
135
- & "$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
136
103
  ```
137
104
 
138
105
  **macOS / Linux**
139
106
 
107
+ In a terminal, `cd` to the folder where Nucleus-Kit should be installed, then:
108
+
140
109
  ```bash
141
- python3 -m venv ~/nucleuskit
142
- ~/nucleuskit/bin/python -m pip install --upgrade pip
143
- ~/nucleuskit/bin/python -m pip install "nucleuskit-toolkit[gui]"
144
- ~/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
145
114
  ```
146
115
 
147
116
  The `gui` extra installs the desktop interface (PySide6 / Qt 6), Bluetooth and serial streaming and MQTT. Without it
@@ -186,19 +155,109 @@ python3 -m venv .venv
186
155
  .venv/bin/python -m pytest
187
156
  ```
188
157
 
189
- 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
190
159
  downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
191
160
  `[dev,gui]` extras (it needs re-ak-core on PyPI).
192
161
 
193
- ### Upgrade and uninstall
162
+ ### FFmpeg
163
+
164
+ FFmpeg is a system program. pip does not install it, and it does not go inside the virtual environment. Install it
165
+ on the machine after the Python steps above.
166
+
167
+ Nucleus-Kit calls it only for video. If a video step cannot find it, that step is skipped and the log says so; heart,
168
+ arousal, cognition, emotion and GPS processing still run. The Recording Merger does not skip: it stops until both
169
+ `ffmpeg` and `ffprobe` are on PATH.
170
+
171
+ | Use | What it does | Where Nucleus-Kit looks |
172
+ |-----|----------------|-------------------------|
173
+ | **Session video** | While processing, rotates `rawData/video.mp4` 180° once (`hflip,vflip`, re-encoded with libx264). | `ffmpeg_dir` if you set it, otherwise `ffmpeg` on PATH |
174
+ | **Playback** | When you open a session, remuxes `rawData/video.mp4` so the file header is at the start and seeking works on long recordings. | Same as session video |
175
+ | **Recording Merger** | Joins up to five videos and inserts black-screen gaps (libx264 and AAC). | PATH only. `ffmpeg_dir` is not read. Both `ffmpeg` and `ffprobe` must be on PATH. |
176
+ | **POV conversion** | Optional. Re-muxes one camera file from MKV to MP4 without re-encoding. | `ffmpeg_dir` is required. PATH alone is not enough. See [Optional POV movie conversion](#optional-pov-movie-conversion). |
177
+
178
+ Use a normal release build. The rotation and the Recording Merger re-encode with **libx264** (and AAC for merged
179
+ audio). A build compiled without those encoders will fail those steps.
180
+
181
+ After installing, open a **new** terminal and check:
182
+
183
+ ```powershell
184
+ ffmpeg -version
185
+ ffprobe -version
186
+ ```
187
+
188
+ Both commands should print a version line. Restart Nucleus-Kit as well: a copy that was already open still has the
189
+ old PATH.
190
+
191
+ #### Windows
192
+
193
+ **winget** (built into Windows 10 and 11):
194
+
195
+ ```powershell
196
+ winget install --id Gyan.FFmpeg.Essentials -e --source winget
197
+ ```
198
+
199
+ Close PowerShell, open it again, and run the two checks above. This is the [gyan.dev](https://www.gyan.dev/ffmpeg/builds/)
200
+ essentials build (libx264 and AAC). winget registers `ffmpeg` and `ffprobe` for you. If a new terminal still cannot
201
+ find them, add the `bin` folder that contains `ffmpeg.exe` to PATH, as in the manual steps.
202
+
203
+ **Manual install**, if winget is unavailable or did not put the programs on PATH:
204
+
205
+ 1. Download **ffmpeg-release-essentials.zip** from [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) (also linked from
206
+ [ffmpeg.org](https://ffmpeg.org/download.html#build-windows)). That build includes `ffmpeg.exe`, `ffprobe.exe`,
207
+ libx264 and AAC.
208
+ 2. Extract the zip. Inside a versioned folder there is a `bin` folder. That `bin` folder is the one that contains
209
+ `ffmpeg.exe` and `ffprobe.exe`.
210
+ 3. Add that `bin` folder to your user PATH: **Settings → System → About → Advanced system settings →
211
+ Environment Variables**. Under **User variables**, select **Path**, **Edit**, **New**, and paste the `bin` folder.
212
+ Paste the folder that contains `ffmpeg.exe`, not the folder above it and not the path of `ffmpeg.exe` itself.
213
+ 4. Open a new PowerShell and run `ffmpeg -version` and `ffprobe -version`.
214
+
215
+ If you cannot change PATH, session video and playback can still use a configured folder. The Recording Merger
216
+ cannot; it only searches PATH.
217
+
218
+ #### macOS
219
+
220
+ ```bash
221
+ brew install ffmpeg
222
+ ```
223
+
224
+ Homebrew puts `ffmpeg` and `ffprobe` on PATH, with libx264.
225
+
226
+ #### Linux
227
+
228
+ Install the `ffmpeg` package from your distribution so `ffmpeg` and `ffprobe` are on PATH. On Debian and Ubuntu:
194
229
 
195
230
  ```bash
196
- python -m pip install --upgrade "nucleuskit-toolkit[gui]"
197
- python -m pip uninstall nucleuskit-toolkit re-ak-core
231
+ sudo apt update
232
+ sudo apt install ffmpeg
198
233
  ```
199
234
 
200
- Use the environment's `python` (for example `"$env:USERPROFILE\nucleuskit\Scripts\python.exe"`), or delete the
201
- environment folder to remove everything. With pipx: `pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
235
+ #### Using a folder when FFmpeg is not on PATH
236
+
237
+ Session video rotation and playback also accept a directory. `ffmpeg_dir` is the folder that **contains** the
238
+ program (`ffmpeg.exe` on Windows, `ffmpeg` on macOS and Linux). It is not the path of the program file.
239
+
240
+ Put this in `nucleuskit_toolkit_config.json` in the directory you start Nucleus-Kit from. For a desktop shortcut,
241
+ that is the **Start in** folder (see [Desktop shortcut (Windows)](#desktop-shortcut-windows)):
242
+
243
+ ```json
244
+ {
245
+ "ffmpeg_dir": "C:/ffmpeg/bin"
246
+ }
247
+ ```
248
+
249
+ The environment variable `HERMES_FFMPEG_DIR` is the same folder and overrides the JSON file.
250
+
251
+ ### Upgrade and uninstall
252
+
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
256
+ ```
257
+
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`.
202
261
 
203
262
  ## Run
204
263
 
@@ -207,8 +266,10 @@ Run the commands with the environment's executables (as below), or activate the
207
266
 
208
267
  **Graphical mode** (see [Graphical interface](#graphical-interface); needs the `gui` extra):
209
268
 
269
+ From the folder that contains `.venv`:
270
+
210
271
  ```powershell
211
- & "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe"
272
+ .\.venv\Scripts\nucleuskit-toolkit.exe
212
273
  ```
213
274
 
214
275
  The same as `python -m nucleuskit_toolkit`. From a source checkout, `launch_app.bat` runs `python -m nucleuskit_toolkit`
@@ -216,8 +277,10 @@ with the first `python` on the PATH: activate the environment before running it.
216
277
 
217
278
  **Headless mode** (one session, then exit; for automation and CI):
218
279
 
280
+ From the folder that contains `.venv`:
281
+
219
282
  ```powershell
220
- nucleuskit-toolkit --session "D:\path\to\session_folder"
283
+ .\.venv\Scripts\nucleuskit-toolkit.exe --session "D:\path\to\session_folder"
221
284
  ```
222
285
 
223
286
  Options:
@@ -225,7 +288,7 @@ Options:
225
288
  | Option | Effect |
226
289
  |---|---|
227
290
  | `--session DIR` | Process this session folder and exit (no GUI) |
228
- | `--config JSON` | Optional POV / ffmpeg settings, merged after the config files of the current directory |
291
+ | `--config JSON` | Extra POV / FFmpeg settings. Applied after JSON files in the current directory and before environment variables ([Optional POV movie conversion](#optional-pov-movie-conversion)) |
229
292
  | `--emotion-model NAME` | Emotion model release (default `classical-emotion-2.6.0`; `nucleuskit-toolkit --help` lists them) |
230
293
 
231
294
  Outputs are written inside the session folder (see [Session layout](#session-layout)). Existing outputs are reused:
@@ -235,11 +298,36 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
235
298
 
236
299
  ### Desktop shortcut (Windows)
237
300
 
238
- 1. Right-click the desktop, **New → Shortcut**.
239
- 2. Location: the environment's `pythonw.exe` followed by `-m nucleuskit_toolkit`, for example
240
- `C:\Users\<you>\nucleuskit\Scripts\pythonw.exe -m nucleuskit_toolkit` (`pythonw` opens no console window).
241
- 3. Name it **Nucleus-Kit**, then in **Properties → Start in**, choose the folder that holds your
242
- `nucleuskit_toolkit_config.json`, if you use one.
301
+ A desktop shortcut opens Nucleus-Kit like any other program. You do not type a Python command to start it.
302
+
303
+ The install creates a `.venv` folder in the folder where you ran the commands. `pythonw.exe` is inside it:
304
+
305
+ 1. In File Explorer, open the folder where you ran the install (for example `D:\NucleusKit`).
306
+ 2. Open `.venv`, then `Scripts`.
307
+
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`.
311
+
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.
314
+
315
+ Create the shortcut from that file:
316
+
317
+ 1. In the `Scripts` folder, hold **Shift**, right-click `pythonw.exe`, and choose **Copy as path**. The copied text
318
+ already has quotes around it, for example `"D:\NucleusKit\.venv\Scripts\pythonw.exe"`.
319
+ 2. Right-click the desktop, then **New → Shortcut**.
320
+ 3. In **Type the location of the item**, paste that path, type a space, then type `-m nucleuskit_toolkit`.
321
+ The full line looks like this, with your own path in place of the example:
322
+
323
+ `"D:\NucleusKit\.venv\Scripts\pythonw.exe" -m nucleuskit_toolkit`
324
+
325
+ `pythonw.exe` opens the application window and does not leave a black command window on the screen.
326
+ 4. Click **Next**, name the shortcut **Nucleus-Kit**, and click **Finish**.
327
+
328
+ **Start in** is only for a `nucleuskit_toolkit_config.json` file (an FFmpeg folder or POV settings). Right-click the
329
+ shortcut, open **Properties**, and set **Start in** to the folder that contains that file. With no config file,
330
+ leave **Start in** empty.
243
331
 
244
332
  ### Troubleshooting
245
333
 
@@ -250,6 +338,51 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
250
338
  | pip reports a conflict on `scikit-learn` | Another package needs a newer scikit-learn: install Nucleus-Kit in its own environment |
251
339
  | `ModuleNotFoundError: No module named 'PySide6'` | Install the `gui` extra: `pip install "nucleuskit-toolkit[gui]"` |
252
340
  | `python` is not recognized (Windows) | Use `py -3.12` instead of `python`, or reinstall Python with **Add python.exe to PATH** |
341
+ | Log says ffmpeg was not found, or the Recording Merger asks for `ffmpeg` / `ffprobe` | Install FFmpeg, then restart the terminal and Nucleus-Kit ([FFmpeg](#ffmpeg)) |
342
+
343
+ ## Hardware mapping
344
+
345
+ | Device | Signals |
346
+ |--------|---------|
347
+ | **Hermes headset** | EEG and EMG (including features used by the emotion model) |
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`) |
350
+
351
+ ## Graphical interface
352
+
353
+ After `python -m nucleuskit_toolkit` (or `nucleuskit-toolkit`), the window shows a sidebar on the left and the selected
354
+ page on the right. Every page has a title, a one-line description and a **Help** link to this documentation. A page
355
+ opened for the first time shows a loading screen while its libraries load (a few seconds on the first launch); they
356
+ are also loaded in the background right after start-up.
357
+
358
+ | Sidebar item | Purpose |
359
+ |------|---------|
360
+ | **Process** | Run the pipeline on one session folder or on every session of a dataset folder. The selected folder is checked as you type (read only): session name, duration and recorded signals, or for a dataset the number of sessions and how many are incomplete. Run is enabled once the folder is valid; while running it becomes **Cancel**, which finishes the step in progress and skips the rest. In a dataset, a failing session does not stop the others. |
361
+ | **Real-time viewer** | Connect to a Hermes headset over BLE (devices appear in the list as soon as the scan sees them) and an optional Shimmer over serial: stream, plot EEG / motion / Shimmer signals, and record into a session-style folder. |
362
+ | **Playback** | Review a processed session: optional `rawData/video.mp4` plus time-aligned plots from `results/*.csv`, with editable event annotations when available. |
363
+ | **Tools** | Experimental only. Utilities for processed sessions (see below). |
364
+ | **MQTT Controller** | Connect to a broker (e.g. Vizia Mobile), discover devices from status traffic, and send recording-related MQTT commands. |
365
+ | **Settings** | Theme (light, dark, or system), persisted under **REAK / NucleusKitToolkit** via `QSettings`. |
366
+ | **Documentation** | Opens the technical documentation in the browser. |
367
+ | **About** | Nucleus-Kit and re-ak-core versions, available emotion models, license and links. |
368
+
369
+ Leaving a page is refused while it is busy (a run in progress, a device connected or connecting, unsaved playback
370
+ annotations are offered for saving first).
371
+
372
+ <a id="tools-submenu"></a>
373
+
374
+ ### Tools submenu (experimental)
375
+
376
+ Experimental only. These utilities sit outside the supported processing path.
377
+
378
+ | Item | Purpose |
379
+ |------|---------|
380
+ | **Channel Fixer** | Repair a single bad RMS channel in an already-processed session using the bundled channel-fix model. |
381
+ | **Channel gain adjustment** | Adjust per-channel RMS gain and zero offset against a reference distribution; updates working emotion RMS features. |
382
+ | **Revert to original** | Restore working RMS features from the frozen baseline under `features/emotions/original/`. |
383
+ | **PPG Fixer** | Re-run PPG artifact rejection and HRV computation on an already-processed session (useful when tuning rejection thresholds without reprocessing the full pipeline). |
384
+ | **EEG Regression Denoising** | Remove shared muscle noise from the EEG by regression on the EMG reference channels, then recompute the cognition outputs. |
385
+ | **Recording Merger** | Join up to 5 recordings into one session, with empty CSV rows and black video for the gaps. Needs `ffmpeg` and `ffprobe` on PATH ([FFmpeg](#ffmpeg)). |
253
386
 
254
387
  ## Session layout
255
388
 
@@ -301,34 +434,53 @@ Written by the default offline pipeline (when the corresponding raw inputs exist
301
434
 
302
435
  Playback mode looks for metric CSVs here and, for synchronized video, uses **`rawData/video.mp4`**. Event annotations are **loaded** from **`features/events/playback_annotations.json`**. When you edit annotations in Playback and save, the app writes that file and **mirrors** the same JSON to **`results/playback_annotations.json`** for convenience.
303
436
 
304
- ## Optional POV / ffmpeg configuration
437
+ ## Optional POV movie conversion
438
+
439
+ This step is only for a POV camera file that has a UUID name and **no extension**. Nucleus-Kit renames it to
440
+ `.mkv`, re-muxes it to `.mp4` with `ffmpeg -c copy`, and puts the result back under the original name. It runs
441
+ only when all three settings below are set. If any one is missing, the step is skipped.
442
+
443
+ | Setting | JSON key | Environment variable | Meaning |
444
+ |---------|----------|----------------------|---------|
445
+ | Data folder | `pov_data_root` | `HERMES_POV_DATA_ROOT` | Folder that contains the UUID-named file |
446
+ | File name | `screen_id` | `HERMES_POV_SCREEN_ID` | That file's name, without an extension |
447
+ | FFmpeg folder | `ffmpeg_dir` | `HERMES_FFMPEG_DIR` | Folder that contains the FFmpeg program (see [FFmpeg](#ffmpeg)) |
448
+
449
+ The source path is `<pov_data_root>/<screen_id>`.
305
450
 
306
- POV movie conversion uses optional settings from, in order:
451
+ Example `nucleuskit_toolkit_config.json`:
307
452
 
308
- 1. `hermes_standalone_config.json` in the **current working directory** (legacy name, still supported)
309
- 2. `nucleuskit_pipeline_config.json` in the **current working directory** (legacy name, still supported)
310
- 3. `nucleuskit_toolkit_config.json` in the **current working directory** (overrides legacy keys if both exist)
311
- 4. An extra JSON path passed with `--config` (CLI only)
312
- 5. Environment variables: `HERMES_POV_DATA_ROOT`, `HERMES_FFMPEG_DIR`, `HERMES_POV_SCREEN_ID`
453
+ ```json
454
+ {
455
+ "pov_data_root": "D:/recordings/pov",
456
+ "screen_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
457
+ "ffmpeg_dir": "C:/ffmpeg/bin"
458
+ }
459
+ ```
460
+
461
+ Settings are merged in this order. A later source replaces the same key from an earlier one:
313
462
 
314
- A run from the **Process** page uses the same merge rules from the **process working directory** and environment; it does not prompt for a config file path.
463
+ 1. `hermes_standalone_config.json` in the current working directory (legacy name, still read)
464
+ 2. `nucleuskit_pipeline_config.json` in the current working directory (legacy name, still read)
465
+ 3. `nucleuskit_toolkit_config.json` in the current working directory
466
+ 4. The file passed with `--config` (command line only)
467
+ 5. The environment variables in the table above
315
468
 
316
- JSON keys: `pov_data_root`, `ffmpeg_dir`, `screen_id`.
469
+ The **Process** page does not ask for a config path. It reads the JSON files in its working directory and the
470
+ environment variables. From the command line, `--config` adds one more file between those JSON files and the
471
+ environment variables.
317
472
 
318
473
  ## Technical documentation
319
474
 
320
- 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).
321
476
 
322
- | File | Pipeline |
477
+ | File | What it describes |
323
478
  |------|----------|
324
- | [`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 |
325
- | [`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) |
326
- | [`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) |
327
- | [`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) |
328
- | [`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) |
329
- | [`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 |
330
- | [`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 |
331
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) |
332
484
 
333
485
  ## Trust and bundled models
334
486
 
@@ -342,6 +494,20 @@ pytest
342
494
 
343
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.
344
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
+
345
511
  ## License
346
512
 
347
513
  Copyright (C) 2026 RE-AK Technologies Inc.