nucleuskit-toolkit 2.2.0__tar.gz → 2.2.1__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 (76) hide show
  1. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/PKG-INFO +206 -62
  2. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/README.md +204 -60
  3. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/__init__.py +1 -1
  4. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/main_window.py +2 -2
  5. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/PKG-INFO +206 -62
  6. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/requires.txt +1 -1
  7. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/pyproject.toml +2 -2
  8. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/LICENSE +0 -0
  9. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/__main__.py +0 -0
  10. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/app.py +0 -0
  11. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/camera/__init__.py +0 -0
  12. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/camera/processing.py +0 -0
  13. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/config.py +0 -0
  14. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/__init__.py +0 -0
  15. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/constants.py +0 -0
  16. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/realtime/__init__.py +0 -0
  17. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/realtime/proxy.py +0 -0
  18. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/logging_utils.py +0 -0
  19. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/mqtt/__init__.py +0 -0
  20. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/mqtt/mqtt_controller.py +0 -0
  21. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/pipeline.py +0 -0
  22. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/position/__init__.py +0 -0
  23. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/position/gps_processor.py +0 -0
  24. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/session_job.py +0 -0
  25. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/__init__.py +0 -0
  26. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/constants.py +0 -0
  27. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/realtime/__init__.py +0 -0
  28. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/realtime/proxy.py +0 -0
  29. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/tools/__init__.py +0 -0
  30. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/tools/eeg_regression.py +0 -0
  31. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/tools/recording_merger.py +0 -0
  32. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/__init__.py +0 -0
  33. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/icons.py +0 -0
  34. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/offline_job.py +0 -0
  35. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/__init__.py +0 -0
  36. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/about_page.py +0 -0
  37. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/channel_fixer_page.py +0 -0
  38. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/channel_gain_page.py +0 -0
  39. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/eeg_regression_page.py +0 -0
  40. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +0 -0
  41. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/offline_page.py +0 -0
  42. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/playback_page.py +0 -0
  43. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +0 -0
  44. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +0 -0
  45. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/recording_merge_page.py +0 -0
  46. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/revert_original_page.py +0 -0
  47. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/settings_page.py +0 -0
  48. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/tools_menu_page.py +0 -0
  49. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/plot_style.py +0 -0
  50. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_eeg_plot.py +0 -0
  51. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +0 -0
  52. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +0 -0
  53. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_shimmer_plot.py +0 -0
  54. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/resources/__init__.py +0 -0
  55. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/resources/branding/__init__.py +0 -0
  56. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
  57. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/session_inspect.py +0 -0
  58. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/theme.py +0 -0
  59. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/widgets.py +0 -0
  60. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/SOURCES.txt +0 -0
  61. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/dependency_links.txt +0 -0
  62. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/entry_points.txt +0 -0
  63. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/top_level.txt +0 -0
  64. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/setup.cfg +0 -0
  65. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_config.py +0 -0
  66. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_hermes_ble_stream.py +0 -0
  67. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_imports.py +0 -0
  68. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_logging_redirect.py +0 -0
  69. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_offline_job.py +0 -0
  70. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_open_core_references.py +0 -0
  71. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_pipeline_cancel.py +0 -0
  72. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_plot_style.py +0 -0
  73. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_realtime_scan.py +0 -0
  74. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_session_inspect.py +0 -0
  75. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_session_video_rotation.py +0 -0
  76. {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_ui_pages.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.1
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,36 @@ 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
66
  - [results/ — primary toolkit tables](#results--primary-pipeline-tables)
66
- - [Optional POV / ffmpeg configuration](#optional-pov--ffmpeg-configuration)
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)
70
71
  - [License](#license)
71
72
 
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
73
  ## Requirements
112
74
 
113
75
  - **Python 3.10, 3.11 or 3.12** (3.12 recommended). Check with `python --version` (`py --version` on Windows).
114
76
  On Windows, install it from [python.org](https://www.python.org/downloads/windows/) and tick **Add python.exe to
115
77
  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)).
78
+ - **FFmpeg** (a system program, not a pip package) for session video, the Recording Merger and optional POV
79
+ conversion. Biosignal processing runs without it. Install it with the other setup steps: [FFmpeg](#ffmpeg).
118
80
  - Dependencies are declared in [`pyproject.toml`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/pyproject.toml);
119
81
  [`requirements.txt`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/requirements.txt) pins the
120
82
  exact versions that were tested, GUI extras included.
@@ -190,6 +152,95 @@ The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0.1,<1.1` requiremen
190
152
  downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
191
153
  `[dev,gui]` extras (it needs re-ak-core on PyPI).
192
154
 
155
+ ### FFmpeg
156
+
157
+ FFmpeg is a system program. pip does not install it, and it does not go inside the virtual environment. Install it
158
+ on the machine after the Python steps above.
159
+
160
+ Nucleus-Kit calls it only for video. If a video step cannot find it, that step is skipped and the log says so; heart,
161
+ arousal, cognition, emotion and GPS processing still run. The Recording Merger does not skip: it stops until both
162
+ `ffmpeg` and `ffprobe` are on PATH.
163
+
164
+ | Use | What it does | Where Nucleus-Kit looks |
165
+ |-----|----------------|-------------------------|
166
+ | **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 |
167
+ | **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 |
168
+ | **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. |
169
+ | **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). |
170
+
171
+ Use a normal release build. The rotation and the Recording Merger re-encode with **libx264** (and AAC for merged
172
+ audio). A build compiled without those encoders will fail those steps.
173
+
174
+ After installing, open a **new** terminal and check:
175
+
176
+ ```powershell
177
+ ffmpeg -version
178
+ ffprobe -version
179
+ ```
180
+
181
+ Both commands should print a version line. Restart Nucleus-Kit as well: a copy that was already open still has the
182
+ old PATH.
183
+
184
+ #### Windows
185
+
186
+ **winget** (built into Windows 10 and 11):
187
+
188
+ ```powershell
189
+ winget install --id Gyan.FFmpeg.Essentials -e --source winget
190
+ ```
191
+
192
+ Close PowerShell, open it again, and run the two checks above. This is the [gyan.dev](https://www.gyan.dev/ffmpeg/builds/)
193
+ essentials build (libx264 and AAC). winget registers `ffmpeg` and `ffprobe` for you. If a new terminal still cannot
194
+ find them, add the `bin` folder that contains `ffmpeg.exe` to PATH, as in the manual steps.
195
+
196
+ **Manual install**, if winget is unavailable or did not put the programs on PATH:
197
+
198
+ 1. Download **ffmpeg-release-essentials.zip** from [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) (also linked from
199
+ [ffmpeg.org](https://ffmpeg.org/download.html#build-windows)). That build includes `ffmpeg.exe`, `ffprobe.exe`,
200
+ libx264 and AAC.
201
+ 2. Extract the zip. Inside a versioned folder there is a `bin` folder. That `bin` folder is the one that contains
202
+ `ffmpeg.exe` and `ffprobe.exe`.
203
+ 3. Add that `bin` folder to your user PATH: **Settings → System → About → Advanced system settings →
204
+ Environment Variables**. Under **User variables**, select **Path**, **Edit**, **New**, and paste the `bin` folder.
205
+ Paste the folder that contains `ffmpeg.exe`, not the folder above it and not the path of `ffmpeg.exe` itself.
206
+ 4. Open a new PowerShell and run `ffmpeg -version` and `ffprobe -version`.
207
+
208
+ If you cannot change PATH, session video and playback can still use a configured folder. The Recording Merger
209
+ cannot; it only searches PATH.
210
+
211
+ #### macOS
212
+
213
+ ```bash
214
+ brew install ffmpeg
215
+ ```
216
+
217
+ Homebrew puts `ffmpeg` and `ffprobe` on PATH, with libx264.
218
+
219
+ #### Linux
220
+
221
+ Install the `ffmpeg` package from your distribution so `ffmpeg` and `ffprobe` are on PATH. On Debian and Ubuntu:
222
+
223
+ ```bash
224
+ sudo apt update
225
+ sudo apt install ffmpeg
226
+ ```
227
+
228
+ #### Using a folder when FFmpeg is not on PATH
229
+
230
+ Session video rotation and playback also accept a directory. `ffmpeg_dir` is the folder that **contains** the
231
+ program (`ffmpeg.exe` on Windows, `ffmpeg` on macOS and Linux). It is not the path of the program file.
232
+
233
+ Put this in `nucleuskit_toolkit_config.json` in the directory you start Nucleus-Kit from. For a desktop shortcut,
234
+ that is the **Start in** folder (see [Desktop shortcut (Windows)](#desktop-shortcut-windows)):
235
+
236
+ ```json
237
+ {
238
+ "ffmpeg_dir": "C:/ffmpeg/bin"
239
+ }
240
+ ```
241
+
242
+ The environment variable `HERMES_FFMPEG_DIR` is the same folder and overrides the JSON file.
243
+
193
244
  ### Upgrade and uninstall
194
245
 
195
246
  ```bash
@@ -225,7 +276,7 @@ Options:
225
276
  | Option | Effect |
226
277
  |---|---|
227
278
  | `--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 |
279
+ | `--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
280
  | `--emotion-model NAME` | Emotion model release (default `classical-emotion-2.6.0`; `nucleuskit-toolkit --help` lists them) |
230
281
 
231
282
  Outputs are written inside the session folder (see [Session layout](#session-layout)). Existing outputs are reused:
@@ -235,11 +286,38 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
235
286
 
236
287
  ### Desktop shortcut (Windows)
237
288
 
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.
289
+ A desktop shortcut opens Nucleus-Kit like any other program. You do not type a Python command to start it.
290
+
291
+ The [PyPI install](#from-pypi) saves the program in your user folder. Find it in File Explorer:
292
+
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.
296
+
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`.
299
+
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.
304
+
305
+ Create the shortcut from that file:
306
+
307
+ 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"`.
309
+ 2. Right-click the desktop, then **New → Shortcut**.
310
+ 3. In **Type the location of the item**, paste that path, type a space, then type `-m nucleuskit_toolkit`.
311
+ The full line looks like this, with your own path in place of the example:
312
+
313
+ `"C:\Users\Alex\nucleuskit\Scripts\pythonw.exe" -m nucleuskit_toolkit`
314
+
315
+ `pythonw.exe` opens the application window and does not leave a black command window on the screen.
316
+ 4. Click **Next**, name the shortcut **Nucleus-Kit**, and click **Finish**.
317
+
318
+ **Start in** is only for a `nucleuskit_toolkit_config.json` file (an FFmpeg folder or POV settings). Right-click the
319
+ shortcut, open **Properties**, and set **Start in** to the folder that contains that file. With no config file,
320
+ leave **Start in** empty.
243
321
 
244
322
  ### Troubleshooting
245
323
 
@@ -250,6 +328,50 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
250
328
  | pip reports a conflict on `scikit-learn` | Another package needs a newer scikit-learn: install Nucleus-Kit in its own environment |
251
329
  | `ModuleNotFoundError: No module named 'PySide6'` | Install the `gui` extra: `pip install "nucleuskit-toolkit[gui]"` |
252
330
  | `python` is not recognized (Windows) | Use `py -3.12` instead of `python`, or reinstall Python with **Add python.exe to PATH** |
331
+ | 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)) |
332
+
333
+ ## Hardware mapping
334
+
335
+ | Device | Signals |
336
+ |--------|---------|
337
+ | **Hermes headset** | EEG and EMG (including features used by the emotion model) |
338
+ | **Shimmer wristband** | PPG and EDA (GSR processing in code maps to the Shimmer EDA channel) |
339
+
340
+ ## Graphical interface
341
+
342
+ After `python -m nucleuskit_toolkit` (or `nucleuskit-toolkit`), the window shows a sidebar on the left and the selected
343
+ page on the right. Every page has a title, a one-line description and a **Help** link to this documentation. A page
344
+ opened for the first time shows a loading screen while its libraries load (a few seconds on the first launch); they
345
+ are also loaded in the background right after start-up.
346
+
347
+ | Sidebar item | Purpose |
348
+ |------|---------|
349
+ | **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. |
350
+ | **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. |
351
+ | **Playback** | Review a processed session: optional `rawData/video.mp4` plus time-aligned plots from `results/*.csv`, with editable event annotations when available. |
352
+ | **Tools** | Experimental only. Utilities for processed sessions (see below). |
353
+ | **MQTT Controller** | Connect to a broker (e.g. Vizia Mobile), discover devices from status traffic, and send recording-related MQTT commands. |
354
+ | **Settings** | Theme (light, dark, or system), persisted under **REAK / NucleusKitToolkit** via `QSettings`. |
355
+ | **Documentation** | Opens the technical documentation in the browser. |
356
+ | **About** | Nucleus-Kit and re-ak-core versions, available emotion models, license and links. |
357
+
358
+ Leaving a page is refused while it is busy (a run in progress, a device connected or connecting, unsaved playback
359
+ annotations are offered for saving first).
360
+
361
+ <a id="tools-submenu"></a>
362
+
363
+ ### Tools submenu (experimental)
364
+
365
+ Experimental only. These utilities sit outside the supported processing path.
366
+
367
+ | Item | Purpose |
368
+ |------|---------|
369
+ | **Channel Fixer** | Repair a single bad RMS channel in an already-processed session using the bundled channel-fix model. |
370
+ | **Channel gain adjustment** | Adjust per-channel RMS gain and zero offset against a reference distribution; updates working emotion RMS features. |
371
+ | **Revert to original** | Restore working RMS features from the frozen baseline under `features/emotions/original/`. |
372
+ | **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). |
373
+ | **EEG Regression Denoising** | Remove shared muscle noise from the EEG by regression on the EMG reference channels, then recompute the cognition outputs. |
374
+ | **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
375
 
254
376
  ## Session layout
255
377
 
@@ -301,19 +423,41 @@ Written by the default offline pipeline (when the corresponding raw inputs exist
301
423
 
302
424
  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
425
 
304
- ## Optional POV / ffmpeg configuration
426
+ ## Optional POV movie conversion
427
+
428
+ This step is only for a POV camera file that has a UUID name and **no extension**. Nucleus-Kit renames it to
429
+ `.mkv`, re-muxes it to `.mp4` with `ffmpeg -c copy`, and puts the result back under the original name. It runs
430
+ only when all three settings below are set. If any one is missing, the step is skipped.
431
+
432
+ | Setting | JSON key | Environment variable | Meaning |
433
+ |---------|----------|----------------------|---------|
434
+ | Data folder | `pov_data_root` | `HERMES_POV_DATA_ROOT` | Folder that contains the UUID-named file |
435
+ | File name | `screen_id` | `HERMES_POV_SCREEN_ID` | That file's name, without an extension |
436
+ | FFmpeg folder | `ffmpeg_dir` | `HERMES_FFMPEG_DIR` | Folder that contains the FFmpeg program (see [FFmpeg](#ffmpeg)) |
305
437
 
306
- POV movie conversion uses optional settings from, in order:
438
+ The source path is `<pov_data_root>/<screen_id>`.
439
+
440
+ Example `nucleuskit_toolkit_config.json`:
441
+
442
+ ```json
443
+ {
444
+ "pov_data_root": "D:/recordings/pov",
445
+ "screen_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
446
+ "ffmpeg_dir": "C:/ffmpeg/bin"
447
+ }
448
+ ```
307
449
 
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`
450
+ Settings are merged in this order. A later source replaces the same key from an earlier one:
313
451
 
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.
452
+ 1. `hermes_standalone_config.json` in the current working directory (legacy name, still read)
453
+ 2. `nucleuskit_pipeline_config.json` in the current working directory (legacy name, still read)
454
+ 3. `nucleuskit_toolkit_config.json` in the current working directory
455
+ 4. The file passed with `--config` (command line only)
456
+ 5. The environment variables in the table above
315
457
 
316
- JSON keys: `pov_data_root`, `ffmpeg_dir`, `screen_id`.
458
+ The **Process** page does not ask for a config path. It reads the JSON files in its working directory and the
459
+ environment variables. From the command line, `--config` adds one more file between those JSON files and the
460
+ environment variables.
317
461
 
318
462
  ## Technical documentation
319
463