nucleuskit-toolkit 2.2.0__py3-none-any.whl

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 (59) hide show
  1. nucleuskit_toolkit/__init__.py +3 -0
  2. nucleuskit_toolkit/__main__.py +60 -0
  3. nucleuskit_toolkit/app.py +34 -0
  4. nucleuskit_toolkit/camera/__init__.py +9 -0
  5. nucleuskit_toolkit/camera/processing.py +374 -0
  6. nucleuskit_toolkit/config.py +86 -0
  7. nucleuskit_toolkit/hermes/__init__.py +0 -0
  8. nucleuskit_toolkit/hermes/constants.py +77 -0
  9. nucleuskit_toolkit/hermes/realtime/__init__.py +8 -0
  10. nucleuskit_toolkit/hermes/realtime/proxy.py +652 -0
  11. nucleuskit_toolkit/logging_utils.py +68 -0
  12. nucleuskit_toolkit/mqtt/__init__.py +5 -0
  13. nucleuskit_toolkit/mqtt/mqtt_controller.py +256 -0
  14. nucleuskit_toolkit/pipeline.py +194 -0
  15. nucleuskit_toolkit/position/__init__.py +5 -0
  16. nucleuskit_toolkit/position/gps_processor.py +91 -0
  17. nucleuskit_toolkit/session_job.py +28 -0
  18. nucleuskit_toolkit/shimmer/__init__.py +5 -0
  19. nucleuskit_toolkit/shimmer/constants.py +32 -0
  20. nucleuskit_toolkit/shimmer/realtime/__init__.py +5 -0
  21. nucleuskit_toolkit/shimmer/realtime/proxy.py +279 -0
  22. nucleuskit_toolkit/tools/__init__.py +1 -0
  23. nucleuskit_toolkit/tools/eeg_regression.py +91 -0
  24. nucleuskit_toolkit/tools/recording_merger.py +437 -0
  25. nucleuskit_toolkit/ui/__init__.py +1 -0
  26. nucleuskit_toolkit/ui/icons.py +165 -0
  27. nucleuskit_toolkit/ui/main_window.py +465 -0
  28. nucleuskit_toolkit/ui/offline_job.py +144 -0
  29. nucleuskit_toolkit/ui/pages/__init__.py +1 -0
  30. nucleuskit_toolkit/ui/pages/about_page.py +88 -0
  31. nucleuskit_toolkit/ui/pages/channel_fixer_page.py +205 -0
  32. nucleuskit_toolkit/ui/pages/channel_gain_page.py +362 -0
  33. nucleuskit_toolkit/ui/pages/eeg_regression_page.py +385 -0
  34. nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +394 -0
  35. nucleuskit_toolkit/ui/pages/offline_page.py +754 -0
  36. nucleuskit_toolkit/ui/pages/playback_page.py +1524 -0
  37. nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +199 -0
  38. nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +954 -0
  39. nucleuskit_toolkit/ui/pages/recording_merge_page.py +395 -0
  40. nucleuskit_toolkit/ui/pages/revert_original_page.py +128 -0
  41. nucleuskit_toolkit/ui/pages/settings_page.py +69 -0
  42. nucleuskit_toolkit/ui/pages/tools_menu_page.py +42 -0
  43. nucleuskit_toolkit/ui/plot_style.py +155 -0
  44. nucleuskit_toolkit/ui/realtime_eeg_plot.py +244 -0
  45. nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +162 -0
  46. nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +101 -0
  47. nucleuskit_toolkit/ui/realtime_shimmer_plot.py +135 -0
  48. nucleuskit_toolkit/ui/resources/__init__.py +1 -0
  49. nucleuskit_toolkit/ui/resources/branding/__init__.py +1 -0
  50. nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
  51. nucleuskit_toolkit/ui/session_inspect.py +226 -0
  52. nucleuskit_toolkit/ui/theme.py +330 -0
  53. nucleuskit_toolkit/ui/widgets.py +190 -0
  54. nucleuskit_toolkit-2.2.0.dist-info/METADATA +351 -0
  55. nucleuskit_toolkit-2.2.0.dist-info/RECORD +59 -0
  56. nucleuskit_toolkit-2.2.0.dist-info/WHEEL +5 -0
  57. nucleuskit_toolkit-2.2.0.dist-info/entry_points.txt +2 -0
  58. nucleuskit_toolkit-2.2.0.dist-info/licenses/LICENSE +675 -0
  59. nucleuskit_toolkit-2.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,351 @@
1
+ Metadata-Version: 2.4
2
+ Name: nucleuskit-toolkit
3
+ Version: 2.2.0
4
+ Summary: Nucleus-Kit offline processing toolkit (Hermes EEG/EMG, Shimmer PPG/EDA)
5
+ Author: RE-AK Technologies Inc.
6
+ License-Expression: GPL-3.0-or-later
7
+ Project-URL: Homepage, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline
8
+ Project-URL: Source, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline
9
+ Project-URL: Issues, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/issues
10
+ Project-URL: Changelog, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/CHANGELOG.md
11
+ Keywords: EEG,EMG,EDA,PPG,Nucleus-Kit,Hermes,Shimmer,biosignals
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: re-ak-core<1.1,>=1.0.1
25
+ Requires-Dist: numpy>=2.5
26
+ Requires-Dist: pandas>=2.3
27
+ Requires-Dist: scipy<1.18,>=1.17
28
+ Requires-Dist: matplotlib>=3.11
29
+ Requires-Dist: opencv-python>=5.0
30
+ Requires-Dist: scikit-learn==1.6.*
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=9; extra == "dev"
33
+ Requires-Dist: ruff>=0.17; extra == "dev"
34
+ Provides-Extra: gui
35
+ Requires-Dist: PySide6>=6.12; extra == "gui"
36
+ Requires-Dist: bleak>=3.0; extra == "gui"
37
+ Requires-Dist: pyqtgraph>=0.14; extra == "gui"
38
+ Requires-Dist: pyserial>=3.5; extra == "gui"
39
+ Requires-Dist: paho-mqtt>=1.6; extra == "gui"
40
+ Dynamic: license-file
41
+
42
+ # Nucleus-Kit Processing Toolkit
43
+
44
+ Desktop application for **Nucleus-Kit** sessions: **offline** analytics (ingest session folders on disk, run the bundled processing steps, write outputs under each session's `features/` and `results/`), plus real-time streaming, playback review, and MQTT device control. The **offline** pipeline can be run from the GUI or from the command line.
45
+
46
+ Since version 2.0.0 the processing itself (heart dynamics, arousal, cognition, emotions, events, emotion models and the RMS / PPG repair tools) is [re-ak-core](https://github.com/fs-re-ak/re-ak-core), RE-AK's open processing core, shared with the re-akcas cloud processor. Nucleus-Kit adds the desktop application and its local steps: POV movie conversion, session video rotation and GPS. Every change in the results compared with Nucleus-Kit 1.1 is listed in re-ak-core's [CHANGELOG](https://github.com/fs-re-ak/re-ak-core/blob/main/CHANGELOG.md).
47
+
48
+ ## Table of contents
49
+
50
+ - [Hardware mapping](#hardware-mapping)
51
+ - [Graphical interface](#graphical-interface)
52
+ - [Tools submenu](#tools-submenu)
53
+ - [Requirements](#requirements)
54
+ - [Install](#install)
55
+ - [From PyPI](#from-pypi)
56
+ - [From source (development)](#from-source-development)
57
+ - [Upgrade and uninstall](#upgrade-and-uninstall)
58
+ - [Run](#run)
59
+ - [Desktop shortcut (Windows)](#desktop-shortcut-windows)
60
+ - [Troubleshooting](#troubleshooting)
61
+ - [Session layout](#session-layout)
62
+ - [Top-level folders](#top-level-folders)
63
+ - [rawData/ — typical inputs](#rawdata--typical-inputs)
64
+ - [features/ — notable outputs](#features--notable-outputs)
65
+ - [results/ — primary toolkit tables](#results--primary-pipeline-tables)
66
+ - [Optional POV / ffmpeg configuration](#optional-pov--ffmpeg-configuration)
67
+ - [Technical documentation](#technical-documentation)
68
+ - [Trust and bundled models](#trust-and-bundled-models)
69
+ - [Tests](#tests)
70
+ - [License](#license)
71
+
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
+ ## Requirements
112
+
113
+ - **Python 3.10, 3.11 or 3.12** (3.12 recommended). Check with `python --version` (`py --version` on Windows).
114
+ On Windows, install it from [python.org](https://www.python.org/downloads/windows/) and tick **Add python.exe to
115
+ 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)).
118
+ - Dependencies are declared in [`pyproject.toml`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/pyproject.toml);
119
+ [`requirements.txt`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/requirements.txt) pins the
120
+ exact versions that were tested, GUI extras included.
121
+
122
+ Install Nucleus-Kit in its **own virtual environment**: its emotion models need scikit-learn 1.6, which must not be
123
+ upgraded by another tool installed next to it.
124
+
125
+ ## Install
126
+
127
+ ### From PyPI
128
+
129
+ **Windows (PowerShell)**
130
+
131
+ ```powershell
132
+ python -m venv "$env:USERPROFILE\nucleuskit"
133
+ & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install --upgrade pip
134
+ & "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install "nucleuskit-toolkit[gui]"
135
+ & "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe" --help
136
+ ```
137
+
138
+ **macOS / Linux**
139
+
140
+ ```bash
141
+ python3 -m venv ~/nucleuskit
142
+ ~/nucleuskit/bin/python -m pip install --upgrade pip
143
+ ~/nucleuskit/bin/python -m pip install "nucleuskit-toolkit[gui]"
144
+ ~/nucleuskit/bin/nucleuskit-toolkit --help
145
+ ```
146
+
147
+ The `gui` extra installs the desktop interface (PySide6 / Qt 6), Bluetooth and serial streaming and MQTT. Without it
148
+ only headless processing (`--session`) is available. [re-ak-core](https://github.com/fs-re-ak/re-ak-core), the
149
+ processing core, is installed automatically.
150
+
151
+ With [pipx](https://pipx.pypa.io), which creates the environment for you and puts the commands on your PATH:
152
+
153
+ ```bash
154
+ pipx install "nucleuskit-toolkit[gui]"
155
+ ```
156
+
157
+ ### From source (development)
158
+
159
+ Clone this repository and [re-ak-core](https://github.com/fs-re-ak/re-ak-core) side by side, then install both in
160
+ editable mode (changes in either clone apply without reinstalling). This is also the way to install before a version is
161
+ published on PyPI.
162
+
163
+ **Windows (PowerShell)**
164
+
165
+ ```powershell
166
+ git clone https://github.com/fs-re-ak/re-ak-core.git
167
+ git clone https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline.git
168
+ cd NucleusKit-ProcessingPipeline
169
+ python -m venv .venv
170
+ .\.venv\Scripts\python.exe -m pip install --upgrade pip
171
+ .\.venv\Scripts\python.exe -m pip install -e ..\re-ak-core
172
+ .\.venv\Scripts\python.exe -m pip install -e ".[dev,gui]"
173
+ .\.venv\Scripts\python.exe -m pytest
174
+ ```
175
+
176
+ **macOS / Linux**
177
+
178
+ ```bash
179
+ git clone https://github.com/fs-re-ak/re-ak-core.git
180
+ git clone https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline.git
181
+ cd NucleusKit-ProcessingPipeline
182
+ python3 -m venv .venv
183
+ .venv/bin/python -m pip install --upgrade pip
184
+ .venv/bin/python -m pip install -e ../re-ak-core
185
+ .venv/bin/python -m pip install -e ".[dev,gui]"
186
+ .venv/bin/python -m pytest
187
+ ```
188
+
189
+ The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0.1,<1.1` requirement, so pip keeps it instead of
190
+ downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
191
+ `[dev,gui]` extras (it needs re-ak-core on PyPI).
192
+
193
+ ### Upgrade and uninstall
194
+
195
+ ```bash
196
+ python -m pip install --upgrade "nucleuskit-toolkit[gui]"
197
+ python -m pip uninstall nucleuskit-toolkit re-ak-core
198
+ ```
199
+
200
+ Use the environment's `python` (for example `"$env:USERPROFILE\nucleuskit\Scripts\python.exe"`), or delete the
201
+ environment folder to remove everything. With pipx: `pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
202
+
203
+ ## Run
204
+
205
+ Run the commands with the environment's executables (as below), or activate the environment first
206
+ (`.\.venv\Scripts\Activate.ps1` in PowerShell, `source .venv/bin/activate` on macOS / Linux) and drop the path.
207
+
208
+ **Graphical mode** (see [Graphical interface](#graphical-interface); needs the `gui` extra):
209
+
210
+ ```powershell
211
+ & "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe"
212
+ ```
213
+
214
+ The same as `python -m nucleuskit_toolkit`. From a source checkout, `launch_app.bat` runs `python -m nucleuskit_toolkit`
215
+ with the first `python` on the PATH: activate the environment before running it.
216
+
217
+ **Headless mode** (one session, then exit; for automation and CI):
218
+
219
+ ```powershell
220
+ nucleuskit-toolkit --session "D:\path\to\session_folder"
221
+ ```
222
+
223
+ Options:
224
+
225
+ | Option | Effect |
226
+ |---|---|
227
+ | `--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 |
229
+ | `--emotion-model NAME` | Emotion model release (default `classical-emotion-2.6.0`; `nucleuskit-toolkit --help` lists them) |
230
+
231
+ Outputs are written inside the session folder (see [Session layout](#session-layout)). Existing outputs are reused:
232
+ delete a file under `results/` to recompute that step.
233
+
234
+ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/resources/branding/logo.png`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/nucleuskit_toolkit/ui/resources/branding/logo.png) (same path in an installed package).
235
+
236
+ ### Desktop shortcut (Windows)
237
+
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.
243
+
244
+ ### Troubleshooting
245
+
246
+ | Problem | Fix |
247
+ |---|---|
248
+ | `Activate.ps1 cannot be loaded because running scripts is disabled` | Call the environment's `python.exe` / `nucleuskit-toolkit.exe` by its path, as above, instead of activating |
249
+ | `No matching distribution found for re-ak-core` | That version is not on PyPI yet: install [from source](#from-source-development) |
250
+ | pip reports a conflict on `scikit-learn` | Another package needs a newer scikit-learn: install Nucleus-Kit in its own environment |
251
+ | `ModuleNotFoundError: No module named 'PySide6'` | Install the `gui` extra: `pip install "nucleuskit-toolkit[gui]"` |
252
+ | `python` is not recognized (Windows) | Use `py -3.12` instead of `python`, or reinstall Python with **Add python.exe to PATH** |
253
+
254
+ ## Session layout
255
+
256
+ The pipeline treats the **session root** as a single directory (the folder you select on the Process page or pass to `--session`).
257
+
258
+ ### Top-level folders
259
+
260
+ | Folder | Role |
261
+ |--------|------|
262
+ | **`rawData/`** | Canonical location for recordings and acquisition-side files. The GUI expects this folder to exist and be non-empty after any automatic layout fix (see below). |
263
+ | **`features/`** | Intermediate and traceability outputs: meta summary, per-processor feature exports, processed events, optional playback annotation seed. |
264
+ | **`results/`** | Primary analytics tables, logs, and optional playback-side annotation copies. |
265
+ | **`meta/`** | Reserved for session-level assets such as preview images (created when needed). |
266
+ | **`experimentConfigs/`** | Reserved for experiment or run configuration artifacts. |
267
+
268
+ On startup, if **`rawData/` is missing**, the pipeline may **create it and move** every other top-level entry into it, except the reserved names above (`rawData`, `features`, `results`, `meta`, `experimentConfigs`). That normalizes older layouts where files lived at the session root.
269
+
270
+ ### `rawData/` — typical inputs
271
+
272
+ Exact filenames vary by firmware and recording path; common patterns include:
273
+
274
+ - **Hermes EEG / EMG:** `rawEEG_0.csv` or `eeg.tmp`
275
+ - **Shimmer:** `shimmer.csv`, or legacy `rawShimmer_0.csv` / `gsr.tmp`
276
+ - **Video:** `video.mp4` (used for playback and optional one-time 180° rotation during processing)
277
+ - **Events:** `rawEvents.csv` (processed into `features/events/processedFeatureEvents.csv` and related); `event.csv` (used to seed `features/events/playback_annotations.json` when that file does not yet exist)
278
+ - **Position:** GPS CSV as expected by the GPS processor (under `rawData/`)
279
+
280
+ ### `features/` — notable outputs
281
+
282
+ - **`features/metainfo.json`** — session duration and stream presence flags from meta extraction
283
+ - **`features/ppg/`** — PPG intermediate files: `ppg_resampled.csv` (artifact-cleaned signal), `ppg_normalized.csv` (rolling z-score used for peak detection), `ppg_resample_report.txt`, and diagnostic figures `ppg_rejected.png`, `ppg_overview.png`, `ppg_spectrogram.png`
284
+ - **`features/eda/`** — EDA intermediate files: `eda_resampled.csv` (resistance in kΩ), `eda_resample_report.txt`, `eda_overview.png`, and `SCR_events.csv` (discrete skin conductance response events)
285
+ - **`features/cognition/`** — EEG band powers (`powerBands.csv`), bilateral temporal averages (`temporalBandPowers.csv`), epoch-level artefact rejection summary (`artefactStats.csv`), per-epoch signal metrics (`epochMetrics.csv`), and artefact waveform plot (`eegArtefactPlot.png`)
286
+ - **`features/emotions/`** — e.g. `rmsSignals.csv`, `emotionClassifierInputs.csv`, plus `original/` when using RMS editing tools
287
+ - **`features/events/playback_annotations.json`** — point/zone annotations for playback (seeded from `rawData/event.csv` once, then user-editable in the app)
288
+ - **`features/events/processedFeatureEvents.csv`** / **`features/events/processedWebFeatureEvents.csv`** — derived from `rawData/rawEvents.csv` when present
289
+
290
+ Other steps may still write auxiliary artifacts directly under `features/`.
291
+
292
+ ### `results/` — primary toolkit tables
293
+
294
+ Written by the default offline pipeline (when the corresponding raw inputs exist). Existing outputs are reused: delete them to recompute a step.
295
+
296
+ - **`processingLog.txt`** — append-only run log
297
+ - **`Emotions.csv`**, **`Cognition.csv`**, **`Arousal.csv`**, **`HeartDynamics.csv`**
298
+ - **`emotion_model.json`** — emotion model and post-processing used for `Emotions.csv`
299
+ - **`processing.json`** — re-ak-core version, model, status of each step and a signal-quality summary
300
+ - **`gpsDf.csv`** (GPS)
301
+
302
+ 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
+
304
+ ## Optional POV / ffmpeg configuration
305
+
306
+ POV movie conversion uses optional settings from, in order:
307
+
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`
313
+
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.
315
+
316
+ JSON keys: `pov_data_root`, `ffmpeg_dir`, `screen_id`.
317
+
318
+ ## Technical documentation
319
+
320
+ The [`doc/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/) folder contains detailed technical descriptions of each processing toolkit for traceability and scientific reference. The heart, arousal, cognition, emotions and events processing now lives in re-ak-core: those pages describe Nucleus-Kit 1.1 and will move to re-ak-core's documentation; re-ak-core's CHANGELOG lists what changed since.
321
+
322
+ | File | Pipeline |
323
+ |------|----------|
324
+ | [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) | Pipeline orchestration, step order, session layout, shared 2 Hz timebase |
325
+ | [`doc/pipeline_heart.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_heart.md) | Shimmer PPG → Heart Rate Dynamics (SQI + MAD artifact rejection, NeuroKit2, HRV) |
326
+ | [`doc/pipeline_arousal.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_arousal.md) | Shimmer EDA → Arousal (cvxEDA tonic/phasic decomposition, SCR detection) |
327
+ | [`doc/pipeline_cognition.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_cognition.md) | Hermes EEG → Cognitive Indexes (Welch power bands, epoch-level artefact rejection, Engagement) |
328
+ | [`doc/pipeline_emotions.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_emotions.md) | Hermes EMG → Emotion Classification (AVG_RMS artefact gate, two-stage LDA/KNN classifier) |
329
+ | [`doc/pipeline_events.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_events.md) | Raw Events → Feature / Web Events + Playback Annotations |
330
+ | [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS Positioning |
331
+ | [`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 |
332
+
333
+ ## Trust and bundled models
334
+
335
+ The emotion models are shipped by re-ak-core as **joblib/pickle** artifacts, checked against the checksums of their release manifest before loading. Treat them like executable data: only use models shipped with re-ak-core or that you trust.
336
+
337
+ ## Tests
338
+
339
+ ```bash
340
+ pytest
341
+ ```
342
+
343
+ `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
+
345
+ ## License
346
+
347
+ Copyright (C) 2026 RE-AK Technologies Inc.
348
+
349
+ This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See [LICENSE](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/LICENSE) for the full text.
350
+
351
+ SPDX-License-Identifier: `GPL-3.0-or-later`. Versions up to 1.1 were released under the MIT License.
@@ -0,0 +1,59 @@
1
+ nucleuskit_toolkit/__init__.py,sha256=lQbBSaR_om_B88pRtZIn5IvGfg8Uj5kQBIe6jaIiFnM,107
2
+ nucleuskit_toolkit/__main__.py,sha256=6-PlcuaQkVyhUQDGk4NR7I0RuhkPqzwfmQhhqAGmbWk,1631
3
+ nucleuskit_toolkit/app.py,sha256=n3IIhVL-gU3-RcYNRhpCxqOX8HVOM6tAZlf5ogdloW4,1056
4
+ nucleuskit_toolkit/config.py,sha256=i0CnmZRpzdPJUXGyqloIQxrFGQgDHDMGpma8KRAQ13U,3101
5
+ nucleuskit_toolkit/logging_utils.py,sha256=3ao5QdM9kHI8STtHNzDl9H80LRqv_RtZykuFAwx4N_g,2055
6
+ nucleuskit_toolkit/pipeline.py,sha256=dpzWKuE-imJeSaX6StIfAhePawxJyUNFQTNIxjdfOek,7177
7
+ nucleuskit_toolkit/session_job.py,sha256=fmoOEF3agFx8ut2jBZaDTakp3anW267BmC-FmEHdpf4,868
8
+ nucleuskit_toolkit/camera/__init__.py,sha256=yzT_Xqp5ICs6axZ8mczmEIHTl6hK7-mzujJ8trxxkPA,335
9
+ nucleuskit_toolkit/camera/processing.py,sha256=3l4x4ulFjiz_qv9PkCJSd2qVIX8piBQ_BXoera0riU8,14109
10
+ nucleuskit_toolkit/hermes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
11
+ nucleuskit_toolkit/hermes/constants.py,sha256=0N6nTOzwfeSn78PJ613Ghg7Bglt2wr-X9nFkh2ID_mI,2317
12
+ nucleuskit_toolkit/hermes/realtime/__init__.py,sha256=E32tV89YVNfW94VoVyRtGM3I-okSgBu0q8L93ViSJm4,211
13
+ nucleuskit_toolkit/hermes/realtime/proxy.py,sha256=HhQGG_jDhwXJJiUaul6rzUWd9zKEvCqYq5ZQ2970O2Q,27047
14
+ nucleuskit_toolkit/mqtt/__init__.py,sha256=C7exc0mpFfQsDGolSNwjwkzHRCPMKUaMtYgMTEu_rzM,149
15
+ nucleuskit_toolkit/mqtt/mqtt_controller.py,sha256=h0vLWbM4gngcuYIt-JskztlObfGPz3BNxdVfrnKttzs,10330
16
+ nucleuskit_toolkit/position/__init__.py,sha256=qAfuAovtIkh8YM9p3AAZoymePcpAGKrnW5WdM0CHsx0,136
17
+ nucleuskit_toolkit/position/gps_processor.py,sha256=yImUcf35HPMQw6UfBP4m-TmR4lQhbN7egPHq4PA3c88,2641
18
+ nucleuskit_toolkit/shimmer/__init__.py,sha256=Jhf96tOi1vAr5zkboljbOIR5C8r_bKNg-gno2y2rYmg,172
19
+ nucleuskit_toolkit/shimmer/constants.py,sha256=HTyBRNu4I0LSlpJ34KXRLwCnxJmOvnfU-pxnXqLwcFY,698
20
+ nucleuskit_toolkit/shimmer/realtime/__init__.py,sha256=7ng6tne_xj8KwsgSAjx8T5rowMjGtkTwXGDua3JZFS8,185
21
+ nucleuskit_toolkit/shimmer/realtime/proxy.py,sha256=QlmSkVvWRyceqd3-u8V6e5vgnjq4atVE7C927YYDIXU,9855
22
+ nucleuskit_toolkit/tools/__init__.py,sha256=tWkn2nsEl1pWgQWzG3R5gxCINgZClipsN4kGOb3YFo8,60
23
+ nucleuskit_toolkit/tools/eeg_regression.py,sha256=yxCpHYytN97ObzvTafU6cFtSGbAAfOaqB0PAYq21xSU,3686
24
+ nucleuskit_toolkit/tools/recording_merger.py,sha256=UbAfGZyOpG_usbbpPQi2YpmrxP3jkGyyOJO_nZGmLeo,15792
25
+ nucleuskit_toolkit/ui/__init__.py,sha256=IkZOifdUuJbHt-2U5aThFS9Ox5Pl_AmgSsKVMQgzR3A,50
26
+ nucleuskit_toolkit/ui/icons.py,sha256=0oE0hlIpeavEC3b_VoJ3hGvGT5zIKNWOpHoajGWeqiI,6919
27
+ nucleuskit_toolkit/ui/main_window.py,sha256=7DsGHWjLhDdruxyt7tabMyufqBtGiYjkaYuPrGH7wYU,18016
28
+ nucleuskit_toolkit/ui/offline_job.py,sha256=Ncwjh0QWC0fEe3g_Zg9bgA2eNVY0yASR1Sr-KN4MXh8,5203
29
+ nucleuskit_toolkit/ui/plot_style.py,sha256=w3PrK-PZmOG6v3KZoYATYEmp7iLIAy-G5q6OyY073qg,5357
30
+ nucleuskit_toolkit/ui/realtime_eeg_plot.py,sha256=piFFhT7aFHGzNyadYvjOCtkQ-0YNF3t1_f0c5QAJDvw,10236
31
+ nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py,sha256=cp7bUaWImBmy5rTK-tzqx1qf5zUf1Y2mhrsmnSHzN9M,5574
32
+ nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py,sha256=59T2ohXEuTXSp3A88objYFRMA51hw8JEpwVbtisr128,3545
33
+ nucleuskit_toolkit/ui/realtime_shimmer_plot.py,sha256=f_MXjA05cFjkdZ3agmgyfXw30AAdcd2SKTtR3kaqR5U,4951
34
+ nucleuskit_toolkit/ui/session_inspect.py,sha256=0Lv0DbxcSLlOJ9An2noraAWzrQg5EGvt3IIZ05fV83o,8027
35
+ nucleuskit_toolkit/ui/theme.py,sha256=aAJNZ0qwqcwRYG6bFmj9HSrwVCE70qAgdFin37vuWVQ,15801
36
+ nucleuskit_toolkit/ui/widgets.py,sha256=3Et4Qk1oXxgz-MEZTK_cZD3opNcQLuJRMWksLQfSZKo,6645
37
+ nucleuskit_toolkit/ui/pages/__init__.py,sha256=68B1QjTMVac4hGegvLDwJv63IFVMwt9OTqpR0u4YIE8,24
38
+ nucleuskit_toolkit/ui/pages/about_page.py,sha256=MIphIhAGczwrYK87vszU-8n-GyTIglNW_ivBDCaGCaU,3396
39
+ nucleuskit_toolkit/ui/pages/channel_fixer_page.py,sha256=DBR3NaQ83fYhy_BwkPdorcVpit-SFRWKt1KNNvlgW7k,6514
40
+ nucleuskit_toolkit/ui/pages/channel_gain_page.py,sha256=iwU7UfYzUyKR1Jw2FKr2EBGoO4d74fLnohY95FxbOLk,12618
41
+ nucleuskit_toolkit/ui/pages/eeg_regression_page.py,sha256=Q1NKOY28dkWAvTrzpyzwq_PMXcwCTk-ZaUOezwW4Nc0,16252
42
+ nucleuskit_toolkit/ui/pages/mqtt_controller_page.py,sha256=UDekm1kRLXSxNgBaWGGnaIPrXEosORopW-eVs-0FwDw,14985
43
+ nucleuskit_toolkit/ui/pages/offline_page.py,sha256=kr4sYOJ0_09QIfE5adPI7OQpLErGUKGUbc9-nNhVxbo,31375
44
+ nucleuskit_toolkit/ui/pages/playback_page.py,sha256=V0wylrEprN4R8s-B5DjAGO45QvLwCS721EMOnQo97O4,56851
45
+ nucleuskit_toolkit/ui/pages/ppg_fixer_page.py,sha256=WrMBNOcFIQTJbv0eaj01UeCHTBIfDonjnm-YmlxaFlg,7014
46
+ nucleuskit_toolkit/ui/pages/realtime_viewer_page.py,sha256=gRDh-jw0-oFEiOrYp4hIyff2r-sFGXV88e4JU3OIXxU,36917
47
+ nucleuskit_toolkit/ui/pages/recording_merge_page.py,sha256=GPGYmA3USZLHq2hz-DXdNxphMyeqKqLaKRlLKAI-n9I,15551
48
+ nucleuskit_toolkit/ui/pages/revert_original_page.py,sha256=lHZ6hhUI7pv5MvduDnsxkDFUlgZeeHwYViRmE9cpLQM,4051
49
+ nucleuskit_toolkit/ui/pages/settings_page.py,sha256=6ISXcJw7-t0zTIt2vvHKZkjXmyCI7dLZRbhEUlOK144,2351
50
+ nucleuskit_toolkit/ui/pages/tools_menu_page.py,sha256=_RY2ZbgpmAFNtXRza4BgKzzKlGAnK1bbTVit2DgBaBs,1761
51
+ nucleuskit_toolkit/ui/resources/__init__.py,sha256=oacbF_wvH97MJeQ_RhHCiZuBh_BG6qtHgUzVWbmBo_g,42
52
+ nucleuskit_toolkit/ui/resources/branding/__init__.py,sha256=exU_kZEShc6WGAMUd4JOMoROaiBefmmMRB3kDDC2p5k,48
53
+ nucleuskit_toolkit/ui/resources/branding/logo.png,sha256=Ol6Rq3E9JkI3TVMevugFS3PnscchyLWTD-bzT4Rnn_g,122259
54
+ nucleuskit_toolkit-2.2.0.dist-info/licenses/LICENSE,sha256=5X8cMguM-HmKfS_4Om-eBqM6A1hfbgZf6pfx2G24QFI,35150
55
+ nucleuskit_toolkit-2.2.0.dist-info/METADATA,sha256=XsXInBJvKrp7YI_08pnaZM4r7icdhUCzcKdsuHGEFEs,21264
56
+ nucleuskit_toolkit-2.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
57
+ nucleuskit_toolkit-2.2.0.dist-info/entry_points.txt,sha256=-GflPBCvqvZe8BTNt6ijwB2L1teCmjIQ9jwBUQqpC3M,72
58
+ nucleuskit_toolkit-2.2.0.dist-info/top_level.txt,sha256=-ffGtSPqLbvSnQ6TE0ZAKdLObHwlFUHM7ZZ4KeTO9rE,19
59
+ nucleuskit_toolkit-2.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ nucleuskit-toolkit = nucleuskit_toolkit.__main__:main