nucleuskit-toolkit 2.2.1__tar.gz → 2.3.0__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.1 → nucleuskit_toolkit-2.3.0}/PKG-INFO +62 -40
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/README.md +60 -38
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/__init__.py +1 -1
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/__main__.py +6 -1
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/mqtt/mqtt_controller.py +133 -25
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/pipeline.py +17 -3
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/position/gps_processor.py +3 -2
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/icons.py +14 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/main_window.py +9 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +58 -16
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/offline_page.py +37 -8
- nucleuskit_toolkit-2.3.0/nucleuskit_toolkit/ui/pages/playback_helpers.py +153 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/playback_page.py +467 -104
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit.egg-info/PKG-INFO +62 -40
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit.egg-info/SOURCES.txt +4 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit.egg-info/requires.txt +1 -1
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/pyproject.toml +2 -2
- nucleuskit_toolkit-2.3.0/tests/test_mqtt_controller.py +63 -0
- nucleuskit_toolkit-2.3.0/tests/test_playback_plot.py +265 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_plot_style.py +2 -3
- nucleuskit_toolkit-2.3.0/tests/test_release_pip.py +342 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_ui_pages.py +27 -16
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/LICENSE +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/app.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/camera/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/camera/processing.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/config.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/hermes/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/hermes/constants.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/hermes/realtime/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/hermes/realtime/proxy.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/logging_utils.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/mqtt/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/position/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/session_job.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/shimmer/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/shimmer/constants.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/shimmer/realtime/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/shimmer/realtime/proxy.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/tools/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/tools/eeg_regression.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/tools/recording_merger.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/offline_job.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/about_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/channel_fixer_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/channel_gain_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/eeg_regression_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/recording_merge_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/revert_original_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/settings_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/pages/tools_menu_page.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/plot_style.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/realtime_eeg_plot.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/realtime_shimmer_plot.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/resources/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/resources/branding/__init__.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/session_inspect.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/theme.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit/ui/widgets.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit.egg-info/dependency_links.txt +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit.egg-info/entry_points.txt +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/nucleuskit_toolkit.egg-info/top_level.txt +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/setup.cfg +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_config.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_hermes_ble_stream.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_imports.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_logging_redirect.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_offline_job.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_open_core_references.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_pipeline_cancel.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_realtime_scan.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/tests/test_session_inspect.py +0 -0
- {nucleuskit_toolkit-2.2.1 → nucleuskit_toolkit-2.3.0}/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.
|
|
3
|
+
Version: 2.3.0
|
|
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.
|
|
24
|
+
Requires-Dist: re-ak-core<1.2,>=1.1.0
|
|
25
25
|
Requires-Dist: numpy>=2.5
|
|
26
26
|
Requires-Dist: pandas>=2.3
|
|
27
27
|
Requires-Dist: scipy<1.18,>=1.17
|
|
@@ -63,11 +63,12 @@ Since version 2.0.0 the processing itself (heart dynamics, arousal, cognition, e
|
|
|
63
63
|
- [Top-level folders](#top-level-folders)
|
|
64
64
|
- [rawData/ — typical inputs](#rawdata--typical-inputs)
|
|
65
65
|
- [features/ — notable outputs](#features--notable-outputs)
|
|
66
|
-
- [results/ — primary toolkit tables](#results--primary-
|
|
66
|
+
- [results/ — primary toolkit tables](#results--primary-toolkit-tables)
|
|
67
67
|
- [Optional POV movie conversion](#optional-pov-movie-conversion)
|
|
68
68
|
- [Technical documentation](#technical-documentation)
|
|
69
69
|
- [Trust and bundled models](#trust-and-bundled-models)
|
|
70
70
|
- [Tests](#tests)
|
|
71
|
+
- [Releasing (maintainers)](#releasing-maintainers)
|
|
71
72
|
- [License](#license)
|
|
72
73
|
|
|
73
74
|
## Requirements
|
|
@@ -88,22 +89,28 @@ upgraded by another tool installed next to it.
|
|
|
88
89
|
|
|
89
90
|
### From PyPI
|
|
90
91
|
|
|
92
|
+
The environment is created in the folder where you run these commands, as a `.venv` folder.
|
|
93
|
+
|
|
91
94
|
**Windows (PowerShell)**
|
|
92
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
|
+
|
|
93
98
|
```powershell
|
|
94
|
-
python -m venv
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
|
98
103
|
```
|
|
99
104
|
|
|
100
105
|
**macOS / Linux**
|
|
101
106
|
|
|
107
|
+
In a terminal, `cd` to the folder where Nucleus-Kit should be installed, then:
|
|
108
|
+
|
|
102
109
|
```bash
|
|
103
|
-
python3 -m venv
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
|
107
114
|
```
|
|
108
115
|
|
|
109
116
|
The `gui` extra installs the desktop interface (PySide6 / Qt 6), Bluetooth and serial streaming and MQTT. Without it
|
|
@@ -148,7 +155,7 @@ python3 -m venv .venv
|
|
|
148
155
|
.venv/bin/python -m pytest
|
|
149
156
|
```
|
|
150
157
|
|
|
151
|
-
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.1.0,<1.2` requirement, so pip keeps it instead of
|
|
152
159
|
downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
|
|
153
160
|
`[dev,gui]` extras (it needs re-ak-core on PyPI).
|
|
154
161
|
|
|
@@ -243,13 +250,14 @@ The environment variable `HERMES_FFMPEG_DIR` is the same folder and overrides th
|
|
|
243
250
|
|
|
244
251
|
### Upgrade and uninstall
|
|
245
252
|
|
|
246
|
-
```
|
|
247
|
-
python -m pip install --upgrade "nucleuskit-toolkit[gui]"
|
|
248
|
-
python -m pip uninstall nucleuskit-toolkit re-ak-core
|
|
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
|
|
249
256
|
```
|
|
250
257
|
|
|
251
|
-
|
|
252
|
-
|
|
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`.
|
|
253
261
|
|
|
254
262
|
## Run
|
|
255
263
|
|
|
@@ -258,8 +266,10 @@ Run the commands with the environment's executables (as below), or activate the
|
|
|
258
266
|
|
|
259
267
|
**Graphical mode** (see [Graphical interface](#graphical-interface); needs the `gui` extra):
|
|
260
268
|
|
|
269
|
+
From the folder that contains `.venv`:
|
|
270
|
+
|
|
261
271
|
```powershell
|
|
262
|
-
|
|
272
|
+
.\.venv\Scripts\nucleuskit-toolkit.exe
|
|
263
273
|
```
|
|
264
274
|
|
|
265
275
|
The same as `python -m nucleuskit_toolkit`. From a source checkout, `launch_app.bat` runs `python -m nucleuskit_toolkit`
|
|
@@ -267,8 +277,10 @@ with the first `python` on the PATH: activate the environment before running it.
|
|
|
267
277
|
|
|
268
278
|
**Headless mode** (one session, then exit; for automation and CI):
|
|
269
279
|
|
|
280
|
+
From the folder that contains `.venv`:
|
|
281
|
+
|
|
270
282
|
```powershell
|
|
271
|
-
nucleuskit-toolkit --session "D:\path\to\session_folder"
|
|
283
|
+
.\.venv\Scripts\nucleuskit-toolkit.exe --session "D:\path\to\session_folder"
|
|
272
284
|
```
|
|
273
285
|
|
|
274
286
|
Options:
|
|
@@ -288,29 +300,27 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
|
|
|
288
300
|
|
|
289
301
|
A desktop shortcut opens Nucleus-Kit like any other program. You do not type a Python command to start it.
|
|
290
302
|
|
|
291
|
-
The
|
|
303
|
+
The install creates a `.venv` folder in the folder where you ran the commands. `pythonw.exe` is inside it:
|
|
292
304
|
|
|
293
|
-
1.
|
|
294
|
-
2.
|
|
295
|
-
3. Type `%USERPROFILE%\nucleuskit\Scripts` and press Enter.
|
|
305
|
+
1. In File Explorer, open the folder where you ran the install (for example `D:\NucleusKit`).
|
|
306
|
+
2. Open `.venv`, then `Scripts`.
|
|
296
307
|
|
|
297
|
-
|
|
298
|
-
|
|
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`.
|
|
299
311
|
|
|
300
|
-
If
|
|
301
|
-
|
|
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.
|
|
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.
|
|
304
314
|
|
|
305
315
|
Create the shortcut from that file:
|
|
306
316
|
|
|
307
317
|
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 `"
|
|
318
|
+
already has quotes around it, for example `"D:\NucleusKit\.venv\Scripts\pythonw.exe"`.
|
|
309
319
|
2. Right-click the desktop, then **New → Shortcut**.
|
|
310
320
|
3. In **Type the location of the item**, paste that path, type a space, then type `-m nucleuskit_toolkit`.
|
|
311
321
|
The full line looks like this, with your own path in place of the example:
|
|
312
322
|
|
|
313
|
-
`"
|
|
323
|
+
`"D:\NucleusKit\.venv\Scripts\pythonw.exe" -m nucleuskit_toolkit`
|
|
314
324
|
|
|
315
325
|
`pythonw.exe` opens the application window and does not leave a black command window on the screen.
|
|
316
326
|
4. Click **Next**, name the shortcut **Nucleus-Kit**, and click **Finish**.
|
|
@@ -336,6 +346,7 @@ leave **Start in** empty.
|
|
|
336
346
|
|--------|---------|
|
|
337
347
|
| **Hermes headset** | EEG and EMG (including features used by the emotion model) |
|
|
338
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`) |
|
|
339
350
|
|
|
340
351
|
## Graphical interface
|
|
341
352
|
|
|
@@ -461,18 +472,15 @@ environment variables.
|
|
|
461
472
|
|
|
462
473
|
## Technical documentation
|
|
463
474
|
|
|
464
|
-
|
|
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).
|
|
465
476
|
|
|
466
|
-
| File |
|
|
477
|
+
| File | What it describes |
|
|
467
478
|
|------|----------|
|
|
468
|
-
| [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) |
|
|
469
|
-
| [`doc
|
|
470
|
-
| [`doc/
|
|
471
|
-
| [`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) |
|
|
472
|
-
| [`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) |
|
|
473
|
-
| [`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 |
|
|
474
|
-
| [`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 |
|
|
475
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) |
|
|
476
484
|
|
|
477
485
|
## Trust and bundled models
|
|
478
486
|
|
|
@@ -486,6 +494,20 @@ pytest
|
|
|
486
494
|
|
|
487
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.
|
|
488
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
|
+
|
|
489
511
|
## License
|
|
490
512
|
|
|
491
513
|
Copyright (C) 2026 RE-AK Technologies Inc.
|
|
@@ -22,11 +22,12 @@ Since version 2.0.0 the processing itself (heart dynamics, arousal, cognition, e
|
|
|
22
22
|
- [Top-level folders](#top-level-folders)
|
|
23
23
|
- [rawData/ — typical inputs](#rawdata--typical-inputs)
|
|
24
24
|
- [features/ — notable outputs](#features--notable-outputs)
|
|
25
|
-
- [results/ — primary toolkit tables](#results--primary-
|
|
25
|
+
- [results/ — primary toolkit tables](#results--primary-toolkit-tables)
|
|
26
26
|
- [Optional POV movie conversion](#optional-pov-movie-conversion)
|
|
27
27
|
- [Technical documentation](#technical-documentation)
|
|
28
28
|
- [Trust and bundled models](#trust-and-bundled-models)
|
|
29
29
|
- [Tests](#tests)
|
|
30
|
+
- [Releasing (maintainers)](#releasing-maintainers)
|
|
30
31
|
- [License](#license)
|
|
31
32
|
|
|
32
33
|
## Requirements
|
|
@@ -47,22 +48,28 @@ upgraded by another tool installed next to it.
|
|
|
47
48
|
|
|
48
49
|
### From PyPI
|
|
49
50
|
|
|
51
|
+
The environment is created in the folder where you run these commands, as a `.venv` folder.
|
|
52
|
+
|
|
50
53
|
**Windows (PowerShell)**
|
|
51
54
|
|
|
55
|
+
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.
|
|
56
|
+
|
|
52
57
|
```powershell
|
|
53
|
-
python -m venv
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
58
|
+
python -m venv .venv
|
|
59
|
+
.\.venv\Scripts\python.exe -m pip install --upgrade pip
|
|
60
|
+
.\.venv\Scripts\python.exe -m pip install "nucleuskit-toolkit[gui]"
|
|
61
|
+
.\.venv\Scripts\nucleuskit-toolkit.exe --help
|
|
57
62
|
```
|
|
58
63
|
|
|
59
64
|
**macOS / Linux**
|
|
60
65
|
|
|
66
|
+
In a terminal, `cd` to the folder where Nucleus-Kit should be installed, then:
|
|
67
|
+
|
|
61
68
|
```bash
|
|
62
|
-
python3 -m venv
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
69
|
+
python3 -m venv .venv
|
|
70
|
+
.venv/bin/python -m pip install --upgrade pip
|
|
71
|
+
.venv/bin/python -m pip install "nucleuskit-toolkit[gui]"
|
|
72
|
+
.venv/bin/nucleuskit-toolkit --help
|
|
66
73
|
```
|
|
67
74
|
|
|
68
75
|
The `gui` extra installs the desktop interface (PySide6 / Qt 6), Bluetooth and serial streaming and MQTT. Without it
|
|
@@ -107,7 +114,7 @@ python3 -m venv .venv
|
|
|
107
114
|
.venv/bin/python -m pytest
|
|
108
115
|
```
|
|
109
116
|
|
|
110
|
-
The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0
|
|
117
|
+
The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.1.0,<1.2` requirement, so pip keeps it instead of
|
|
111
118
|
downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
|
|
112
119
|
`[dev,gui]` extras (it needs re-ak-core on PyPI).
|
|
113
120
|
|
|
@@ -202,13 +209,14 @@ The environment variable `HERMES_FFMPEG_DIR` is the same folder and overrides th
|
|
|
202
209
|
|
|
203
210
|
### Upgrade and uninstall
|
|
204
211
|
|
|
205
|
-
```
|
|
206
|
-
python -m pip install --upgrade "nucleuskit-toolkit[gui]"
|
|
207
|
-
python -m pip uninstall nucleuskit-toolkit re-ak-core
|
|
212
|
+
```powershell
|
|
213
|
+
.\.venv\Scripts\python.exe -m pip install --upgrade "nucleuskit-toolkit[gui]"
|
|
214
|
+
.\.venv\Scripts\python.exe -m pip uninstall nucleuskit-toolkit re-ak-core
|
|
208
215
|
```
|
|
209
216
|
|
|
210
|
-
|
|
211
|
-
|
|
217
|
+
Run these from the folder that contains `.venv`. On macOS and Linux, use `.venv/bin/python` in place of
|
|
218
|
+
`.\.venv\Scripts\python.exe`. Deleting the `.venv` folder removes the install. With pipx:
|
|
219
|
+
`pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
|
|
212
220
|
|
|
213
221
|
## Run
|
|
214
222
|
|
|
@@ -217,8 +225,10 @@ Run the commands with the environment's executables (as below), or activate the
|
|
|
217
225
|
|
|
218
226
|
**Graphical mode** (see [Graphical interface](#graphical-interface); needs the `gui` extra):
|
|
219
227
|
|
|
228
|
+
From the folder that contains `.venv`:
|
|
229
|
+
|
|
220
230
|
```powershell
|
|
221
|
-
|
|
231
|
+
.\.venv\Scripts\nucleuskit-toolkit.exe
|
|
222
232
|
```
|
|
223
233
|
|
|
224
234
|
The same as `python -m nucleuskit_toolkit`. From a source checkout, `launch_app.bat` runs `python -m nucleuskit_toolkit`
|
|
@@ -226,8 +236,10 @@ with the first `python` on the PATH: activate the environment before running it.
|
|
|
226
236
|
|
|
227
237
|
**Headless mode** (one session, then exit; for automation and CI):
|
|
228
238
|
|
|
239
|
+
From the folder that contains `.venv`:
|
|
240
|
+
|
|
229
241
|
```powershell
|
|
230
|
-
nucleuskit-toolkit --session "D:\path\to\session_folder"
|
|
242
|
+
.\.venv\Scripts\nucleuskit-toolkit.exe --session "D:\path\to\session_folder"
|
|
231
243
|
```
|
|
232
244
|
|
|
233
245
|
Options:
|
|
@@ -247,29 +259,27 @@ Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/r
|
|
|
247
259
|
|
|
248
260
|
A desktop shortcut opens Nucleus-Kit like any other program. You do not type a Python command to start it.
|
|
249
261
|
|
|
250
|
-
The
|
|
262
|
+
The install creates a `.venv` folder in the folder where you ran the commands. `pythonw.exe` is inside it:
|
|
251
263
|
|
|
252
|
-
1.
|
|
253
|
-
2.
|
|
254
|
-
3. Type `%USERPROFILE%\nucleuskit\Scripts` and press Enter.
|
|
264
|
+
1. In File Explorer, open the folder where you ran the install (for example `D:\NucleusKit`).
|
|
265
|
+
2. Open `.venv`, then `Scripts`.
|
|
255
266
|
|
|
256
|
-
|
|
257
|
-
|
|
267
|
+
That `Scripts` folder contains `pythonw.exe`. A [source install](#from-source-development) uses the same
|
|
268
|
+
`.venv\Scripts` folder inside the cloned repository. After a pipx install the file is in
|
|
269
|
+
`%USERPROFILE%\pipx\venvs\nucleuskit-toolkit\Scripts`.
|
|
258
270
|
|
|
259
|
-
If
|
|
260
|
-
|
|
261
|
-
that folder is `%USERPROFILE%\pipx\venvs\nucleuskit-toolkit\Scripts`. After a [source install](#from-source-development)
|
|
262
|
-
it is the `.venv\Scripts` folder inside the cloned repository.
|
|
271
|
+
If you do not remember the folder, use the search box in File Explorer and search for `pythonw.exe`. Pick the copy
|
|
272
|
+
that is inside a `.venv\Scripts` folder.
|
|
263
273
|
|
|
264
274
|
Create the shortcut from that file:
|
|
265
275
|
|
|
266
276
|
1. In the `Scripts` folder, hold **Shift**, right-click `pythonw.exe`, and choose **Copy as path**. The copied text
|
|
267
|
-
already has quotes around it, for example `"
|
|
277
|
+
already has quotes around it, for example `"D:\NucleusKit\.venv\Scripts\pythonw.exe"`.
|
|
268
278
|
2. Right-click the desktop, then **New → Shortcut**.
|
|
269
279
|
3. In **Type the location of the item**, paste that path, type a space, then type `-m nucleuskit_toolkit`.
|
|
270
280
|
The full line looks like this, with your own path in place of the example:
|
|
271
281
|
|
|
272
|
-
`"
|
|
282
|
+
`"D:\NucleusKit\.venv\Scripts\pythonw.exe" -m nucleuskit_toolkit`
|
|
273
283
|
|
|
274
284
|
`pythonw.exe` opens the application window and does not leave a black command window on the screen.
|
|
275
285
|
4. Click **Next**, name the shortcut **Nucleus-Kit**, and click **Finish**.
|
|
@@ -295,6 +305,7 @@ leave **Start in** empty.
|
|
|
295
305
|
|--------|---------|
|
|
296
306
|
| **Hermes headset** | EEG and EMG (including features used by the emotion model) |
|
|
297
307
|
| **Shimmer wristband** | PPG and EDA (GSR processing in code maps to the Shimmer EDA channel) |
|
|
308
|
+
| **GPS** | Latitude and longitude, resampled to the shared 2 Hz timebase (`results/gpsDf.csv`) |
|
|
298
309
|
|
|
299
310
|
## Graphical interface
|
|
300
311
|
|
|
@@ -420,18 +431,15 @@ environment variables.
|
|
|
420
431
|
|
|
421
432
|
## Technical documentation
|
|
422
433
|
|
|
423
|
-
|
|
434
|
+
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).
|
|
424
435
|
|
|
425
|
-
| File |
|
|
436
|
+
| File | What it describes |
|
|
426
437
|
|------|----------|
|
|
427
|
-
| [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) |
|
|
428
|
-
| [`doc
|
|
429
|
-
| [`doc/
|
|
430
|
-
| [`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) |
|
|
431
|
-
| [`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) |
|
|
432
|
-
| [`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 |
|
|
433
|
-
| [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS Positioning |
|
|
438
|
+
| [`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 |
|
|
439
|
+
| [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 |
|
|
440
|
+
| [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS positioning |
|
|
434
441
|
| [`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 |
|
|
442
|
+
| [`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) |
|
|
435
443
|
|
|
436
444
|
## Trust and bundled models
|
|
437
445
|
|
|
@@ -445,6 +453,20 @@ pytest
|
|
|
445
453
|
|
|
446
454
|
`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.
|
|
447
455
|
|
|
456
|
+
## Releasing (maintainers)
|
|
457
|
+
|
|
458
|
+
Run this at the repository root, on an up-to-date `main`:
|
|
459
|
+
|
|
460
|
+
```bat
|
|
461
|
+
.\deploy_pip_package.bat
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
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.
|
|
465
|
+
|
|
466
|
+
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.
|
|
467
|
+
|
|
468
|
+
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.
|
|
469
|
+
|
|
448
470
|
## License
|
|
449
471
|
|
|
450
472
|
Copyright (C) 2026 RE-AK Technologies Inc.
|
|
@@ -39,6 +39,11 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
39
39
|
f"(default: {DEFAULT_MODEL}). Available: {', '.join(available_models())}."
|
|
40
40
|
),
|
|
41
41
|
)
|
|
42
|
+
parser.add_argument(
|
|
43
|
+
"--force",
|
|
44
|
+
action="store_true",
|
|
45
|
+
help="Recompute and replace existing features and results (other files in those folders are kept).",
|
|
46
|
+
)
|
|
42
47
|
ns = parser.parse_args(argv)
|
|
43
48
|
|
|
44
49
|
if ns.session:
|
|
@@ -46,7 +51,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
46
51
|
from nucleuskit_toolkit.session_job import session_job_from_folder
|
|
47
52
|
|
|
48
53
|
job = session_job_from_folder(ns.session, pov_config_json=ns.config)
|
|
49
|
-
pipe = NucleusKitProcessingToolkit(None, emotion_model=ns.emotion_model)
|
|
54
|
+
pipe = NucleusKitProcessingToolkit(None, emotion_model=ns.emotion_model, force=ns.force)
|
|
50
55
|
pipe.processSession(job)
|
|
51
56
|
return 0
|
|
52
57
|
|