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.
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/PKG-INFO +254 -88
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/README.md +252 -86
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/__init__.py +1 -1
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/__main__.py +6 -1
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/pipeline.py +17 -3
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/position/gps_processor.py +3 -2
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/icons.py +14 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/main_window.py +11 -2
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/offline_page.py +37 -8
- nucleuskit_toolkit-2.2.2/nucleuskit_toolkit/ui/pages/playback_helpers.py +153 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/playback_page.py +467 -104
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/PKG-INFO +254 -88
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/SOURCES.txt +3 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/requires.txt +1 -1
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/pyproject.toml +2 -2
- nucleuskit_toolkit-2.2.2/tests/test_playback_plot.py +265 -0
- nucleuskit_toolkit-2.2.2/tests/test_release_pip.py +342 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_ui_pages.py +22 -11
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/LICENSE +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/app.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/camera/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/camera/processing.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/config.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/constants.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/realtime/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/hermes/realtime/proxy.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/logging_utils.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/mqtt/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/mqtt/mqtt_controller.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/position/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/session_job.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/constants.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/realtime/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/shimmer/realtime/proxy.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/eeg_regression.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/tools/recording_merger.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/offline_job.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/about_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/channel_fixer_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/channel_gain_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/eeg_regression_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/recording_merge_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/revert_original_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/settings_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/pages/tools_menu_page.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/plot_style.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_eeg_plot.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/realtime_shimmer_plot.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/branding/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/session_inspect.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/theme.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit/ui/widgets.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/dependency_links.txt +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/entry_points.txt +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/nucleuskit_toolkit.egg-info/top_level.txt +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/setup.cfg +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_config.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_hermes_ble_stream.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_imports.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_logging_redirect.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_offline_job.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_open_core_references.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_pipeline_cancel.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_plot_style.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_realtime_scan.py +0 -0
- {nucleuskit_toolkit-2.2.0 → nucleuskit_toolkit-2.2.2}/tests/test_session_inspect.py +0 -0
- {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.
|
|
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.
|
|
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-
|
|
66
|
-
- [Optional POV
|
|
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
|
-
- **
|
|
117
|
-
|
|
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
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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.
|
|
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
|
-
###
|
|
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
|
-
|
|
197
|
-
|
|
231
|
+
sudo apt update
|
|
232
|
+
sudo apt install ffmpeg
|
|
198
233
|
```
|
|
199
234
|
|
|
200
|
-
|
|
201
|
-
|
|
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
|
-
|
|
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` |
|
|
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
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
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
|
|
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
|
-
|
|
451
|
+
Example `nucleuskit_toolkit_config.json`:
|
|
307
452
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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 |
|
|
477
|
+
| File | What it describes |
|
|
323
478
|
|------|----------|
|
|
324
|
-
| [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) |
|
|
325
|
-
| [`doc
|
|
326
|
-
| [`doc/
|
|
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.
|