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.
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/PKG-INFO +206 -62
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/README.md +204 -60
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/__init__.py +1 -1
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/main_window.py +2 -2
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/PKG-INFO +206 -62
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/requires.txt +1 -1
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/pyproject.toml +2 -2
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/LICENSE +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/__main__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/app.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/camera/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/camera/processing.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/config.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/constants.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/realtime/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/hermes/realtime/proxy.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/logging_utils.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/mqtt/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/mqtt/mqtt_controller.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/pipeline.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/position/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/position/gps_processor.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/session_job.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/constants.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/realtime/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/shimmer/realtime/proxy.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/tools/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/tools/eeg_regression.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/tools/recording_merger.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/icons.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/offline_job.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/about_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/channel_fixer_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/channel_gain_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/eeg_regression_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/offline_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/playback_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/recording_merge_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/revert_original_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/settings_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/pages/tools_menu_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/plot_style.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_eeg_plot.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/realtime_shimmer_plot.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/resources/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/resources/branding/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/session_inspect.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/theme.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit/ui/widgets.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/SOURCES.txt +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/dependency_links.txt +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/entry_points.txt +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/nucleuskit_toolkit.egg-info/top_level.txt +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/setup.cfg +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_config.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_hermes_ble_stream.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_imports.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_logging_redirect.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_offline_job.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_open_core_references.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_pipeline_cancel.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_plot_style.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_realtime_scan.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_session_inspect.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.1}/tests/test_session_video_rotation.py +0 -0
- {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.
|
|
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.
|
|
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
|
|
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
|
-
- **
|
|
117
|
-
|
|
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` |
|
|
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
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|