plasma-app 2.1.3__tar.gz

plasma_app-2.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SenSE Lab at The Ohio State University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plasma_app-2.1.3/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: plasma-app
+Version: 2.1.3
+Summary: PLASMA — Platform for LSL-based Acquisition of Sensor Metrics and Analytics
+License: MIT
+Project-URL: Homepage, https://github.com/YuyiChang/PLASMA
+Project-URL: Repository, https://github.com/YuyiChang/PLASMA
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gradio
+Requires-Dist: plotly
+Requires-Dist: pylsl
+Requires-Dist: numpy
+Provides-Extra: msense
+Requires-Dist: simplepyble; extra == "msense"
+Requires-Dist: bleak; extra == "msense"
+Requires-Dist: scipy; extra == "msense"
+Requires-Dist: matplotlib; extra == "msense"
+Requires-Dist: psutil; extra == "msense"
+Requires-Dist: Pillow; extra == "msense"
+Requires-Dist: pandas; extra == "msense"
+Requires-Dist: pyarrow; extra == "msense"
+Requires-Dist: tqdm; extra == "msense"
+Provides-Extra: qb2
+Requires-Dist: blickfeld-qb2; extra == "qb2"
+Provides-Extra: pupil
+Requires-Dist: pupil-labs-realtime-api; extra == "pupil"
+Provides-Extra: shimmer
+Requires-Dist: pyshimmer; extra == "shimmer"
+Requires-Dist: pyserial; extra == "shimmer"
+Provides-Extra: obs
+Requires-Dist: obsws-python; extra == "obs"
+Provides-Extra: all
+Requires-Dist: plasma-app[msense,obs,pupil,qb2,shimmer]; extra == "all"
+Provides-Extra: desktop
+Requires-Dist: pyshortcuts; extra == "desktop"
+Provides-Extra: build
+Requires-Dist: pyinstaller; extra == "build"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pyxdf; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-glightbox; extra == "docs"
+Requires-Dist: playwright; extra == "docs"
+Dynamic: license-file
+
+# PLASMA
+
+PLASMA: Platform for LSL-based Acquisition of Sensor Metrics and Analytics
+
+**📖 Operator handbook: <https://yuyichang.github.io/PLASMA/>** — install,
+configure, pair MSense wristbands, run a session, read the memo panel, recover
+from faults.
+
+## quickstart
+
+- `conda create -n plasma python=3.12`
+- `conda activate plasma`
+- `pip install -e ".[all]"` — or a lean subset, e.g. `".[msense]"` / `".[qb2,pupil]"`
+- `python -m plasma` (or the `plasma` console script)
+
+`pip install -r requirements.txt` still works — it's a shim for `-e .[all,build,test]`.
+
+Want a double-clickable icon instead of running `plasma` from a terminal?
+`pip install -e ".[desktop]"` then `plasma-install-shortcut` — see
+[Install & first launch](https://yuyichang.github.io/PLASMA/playbook/install/).
+
+Writable state (device config, gyro-bias calibration, `data/` recordings, session
+log) location, in order: `$PLASMA_HOME` if set → a per-user app-data dir when
+running as a packaged app (`~/Library/Application Support/PLASMA` on macOS,
+`%LOCALAPPDATA%\PLASMA` on Windows, `~/.local/share/plasma` on Linux) → the
+working directory when running from source. Resolved once at import — set
+`PLASMA_HOME` before launching to override.
+
+### use PLASMA from another project
+
+```
+pip install "plasma-app[msense] @ git+https://github.com/YuyiChang/PLASMA@v2.0.0"
+```
+
+The distribution is `plasma-app`; the import package is `plasma`. Extras map to
+plugins: `msense`, `qb2`, `pupil`, `shimmer`, `obs` (and `all`).
+
+## Known issue / future works
+
+- [ ] need manually set lidar ip addr
+- [ ] the built-in LSL→XDF recorder captures **every** stream on the default
+      liblsl session, so a concurrent `pytest` run or another lab tool leaks
+      into the recording; re-Initialize doesn't fully tear down old outlets.
+      Direction (SessionID scoping, outlet lifecycle): [`docs/reference/lsl-lifecycle-and-scoping.md`](docs/reference/lsl-lifecycle-and-scoping.md)
+- [ ] interactive=false on ses/sub when collection started
+- [x] linux aarch64 build — `PLASMA_Linux_arm64` for Jetson Orin (JetPack 6); CI job `build-linux-arm64`
+- [ ] infrequent stream (e.g., PLASMA journaler) shows green after recording stop
+- [ ] doc for msense workflow with better screenshots
+- [ ] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
+
+## developing a sensor plugin
+
+Every sensor is a plugin: a `PlasmaDevice` subclass plus a registration entry in
+`plasma/plugins.py`. Core code never imports a concrete device.
+
+> full guide: [`plasma/devices/README.md`](plasma/devices/README.md)
+> base class: `PlasmaDevice` in `plasma/devices/template.py`
+> reference package (config section + tabs + multi-unit): `plasma/devices/msense/`
+
+## documentation
+
+The playbook is a MkDocs Material site under `docs/`, deployed to GitHub Pages
+by `.github/workflows/docs.yml` on every push to `main`.
+
+```
+pip install -e ".[docs]"        # mkdocs-material + mkdocs-glightbox + playwright
+mkdocs serve                     # preview at http://127.0.0.1:8000
+```
+
+Screenshots (`docs/assets/screenshots/*.png`, Git LFS) are regenerated by a
+Playwright script that drives PLASMA with the simulated MSense device:
+
+```
+brew install git-lfs && git lfs install     # one-time
+python scripts/capture_screenshots.py        # ~4 min; needs Google Chrome
+```
+
+It uses `PLASMA_HOME=~/Library/Application Support/PLASMA` by default so the
+paths shown in the memo panel match a packaged install; pass `--home /tmp/x` for
+a disposable run.
+
+## references
+
+- qb2: https://docs.blickfeld.com/qb2/Qb2/v1.10/guides/api.html
+- pupil-labs: https://pupil-labs.github.io/pl-realtime-api/dev/

plasma_app-2.1.3/README.md

@@ -0,0 +1,85 @@
+# PLASMA
+
+PLASMA: Platform for LSL-based Acquisition of Sensor Metrics and Analytics
+
+**📖 Operator handbook: <https://yuyichang.github.io/PLASMA/>** — install,
+configure, pair MSense wristbands, run a session, read the memo panel, recover
+from faults.
+
+## quickstart
+
+- `conda create -n plasma python=3.12`
+- `conda activate plasma`
+- `pip install -e ".[all]"` — or a lean subset, e.g. `".[msense]"` / `".[qb2,pupil]"`
+- `python -m plasma` (or the `plasma` console script)
+
+`pip install -r requirements.txt` still works — it's a shim for `-e .[all,build,test]`.
+
+Want a double-clickable icon instead of running `plasma` from a terminal?
+`pip install -e ".[desktop]"` then `plasma-install-shortcut` — see
+[Install & first launch](https://yuyichang.github.io/PLASMA/playbook/install/).
+
+Writable state (device config, gyro-bias calibration, `data/` recordings, session
+log) location, in order: `$PLASMA_HOME` if set → a per-user app-data dir when
+running as a packaged app (`~/Library/Application Support/PLASMA` on macOS,
+`%LOCALAPPDATA%\PLASMA` on Windows, `~/.local/share/plasma` on Linux) → the
+working directory when running from source. Resolved once at import — set
+`PLASMA_HOME` before launching to override.
+
+### use PLASMA from another project
+
+```
+pip install "plasma-app[msense] @ git+https://github.com/YuyiChang/PLASMA@v2.0.0"
+```
+
+The distribution is `plasma-app`; the import package is `plasma`. Extras map to
+plugins: `msense`, `qb2`, `pupil`, `shimmer`, `obs` (and `all`).
+
+## Known issue / future works
+
+- [ ] need manually set lidar ip addr
+- [ ] the built-in LSL→XDF recorder captures **every** stream on the default
+      liblsl session, so a concurrent `pytest` run or another lab tool leaks
+      into the recording; re-Initialize doesn't fully tear down old outlets.
+      Direction (SessionID scoping, outlet lifecycle): [`docs/reference/lsl-lifecycle-and-scoping.md`](docs/reference/lsl-lifecycle-and-scoping.md)
+- [ ] interactive=false on ses/sub when collection started
+- [x] linux aarch64 build — `PLASMA_Linux_arm64` for Jetson Orin (JetPack 6); CI job `build-linux-arm64`
+- [ ] infrequent stream (e.g., PLASMA journaler) shows green after recording stop
+- [ ] doc for msense workflow with better screenshots
+- [ ] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
+
+## developing a sensor plugin
+
+Every sensor is a plugin: a `PlasmaDevice` subclass plus a registration entry in
+`plasma/plugins.py`. Core code never imports a concrete device.
+
+> full guide: [`plasma/devices/README.md`](plasma/devices/README.md)
+> base class: `PlasmaDevice` in `plasma/devices/template.py`
+> reference package (config section + tabs + multi-unit): `plasma/devices/msense/`
+
+## documentation
+
+The playbook is a MkDocs Material site under `docs/`, deployed to GitHub Pages
+by `.github/workflows/docs.yml` on every push to `main`.
+
+```
+pip install -e ".[docs]"        # mkdocs-material + mkdocs-glightbox + playwright
+mkdocs serve                     # preview at http://127.0.0.1:8000
+```
+
+Screenshots (`docs/assets/screenshots/*.png`, Git LFS) are regenerated by a
+Playwright script that drives PLASMA with the simulated MSense device:
+
+```
+brew install git-lfs && git lfs install     # one-time
+python scripts/capture_screenshots.py        # ~4 min; needs Google Chrome
+```
+
+It uses `PLASMA_HOME=~/Library/Application Support/PLASMA` by default so the
+paths shown in the memo panel match a packaged install; pass `--home /tmp/x` for
+a disposable run.
+
+## references
+
+- qb2: https://docs.blickfeld.com/qb2/Qb2/v1.10/guides/api.html
+- pupil-labs: https://pupil-labs.github.io/pl-realtime-api/dev/

plasma_app-2.1.3/plasma/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "2.1.3"
+
+# Short git commit hash baked in by CI (.github/workflows/build.yml) just
+# before a release build is frozen with PyInstaller — a frozen bundle ships no
+# .git directory to introspect at runtime. None from a source checkout;
+# plasma.build_info.git_commit_hash() resolves that case live from git.
+__git_commit__ = None

plasma_app-2.1.3/plasma/__main__.py

@@ -0,0 +1,207 @@
+import atexit
+import os
+import signal
+import sys
+import gradio as gr
+from plasma import plugins
+from plasma.app_context import app_context
+from plasma.integrated_panel import IntegratedPanel
+from plasma.config import device_config
+from plasma import api as plasma_api
+
+
+def _handle_sigterm(signum, frame):
+    # run atexit hooks (device shutdown-cleanup handlers) then exit hard, so
+    # `kill <pid>` doesn't leave a device mid-transfer holding a resource
+    # (e.g. a BLE connection slot) until its own supervision timeout
+    atexit._run_exitfuncs()
+    os._exit(143)
+
+
+def _relaunch_argv():
+    """argv for re-launching this same PLASMA. Under PyInstaller (onefile)
+    `sys.executable` IS the bundle exe; from source it's the interpreter plus
+    `-m plasma`. Any extra CLI args are preserved."""
+    if getattr(sys, "frozen", False):
+        return [sys.executable, *sys.argv[1:]]
+    return [sys.executable, "-m", "plasma", *sys.argv[1:]]
+
+
+# set by main() so shutdown() can stop the server (frees the port before a
+# restart re-binds it)
+app = None
+
+
+def shutdown(restart=False):
+    """Run every registered cleanup hook (each MSense driver's
+    `_shutdown_cleanup`, the recording flush + device disconnect from
+    `IntegratedPanel._atexit_cleanup`), stop the Gradio server, then re-exec
+    PLASMA (`restart=True`) or exit the process. Safe to call from a Gradio
+    event-handler thread — mirrors `_handle_sigterm`'s
+    `atexit._run_exitfuncs()` + hard-exit pattern."""
+    atexit._run_exitfuncs()
+    if app is not None:
+        try:
+            app.close()
+        except Exception:
+            pass
+    if restart:
+        argv = _relaunch_argv()
+        if os.name == "nt":
+            # execv on Windows is spawn-then-exit, which flickers the console;
+            # an explicit Popen + exit is more predictable there.
+            import subprocess
+            subprocess.Popen(argv, close_fds=False)
+            os._exit(0)
+        os.execv(argv[0], argv)
+    os._exit(0)
+
+js_func = """
+function refresh() {
+    const url = new URL(window.location);
+
+    if (url.searchParams.get('__theme') !== 'light') {
+        url.searchParams.set('__theme', 'light');
+        window.location.href = url.href;
+    }
+
+    // Gradio 5's gr.Plot destroys and recreates the whole Plotly <div> on
+    // every value it receives (a <svelte:component> {#key}), and its Plotly
+    // wrapper never calls Plotly.purge — so a plot on a gr.Timer orphans a
+    // graph div (event handlers, internal caches, a WebGL context for 3D /
+    // scattergl) roughly once a second, until the tab runs out of memory
+    // (gradio#10252). One <body> observer purges each removed graph div, and
+    // also re-applies the scroll position Plotly's DOM swap resets to top.
+    let lastScrollY = window.scrollY;
+    window.addEventListener('scroll', () => { lastScrollY = window.scrollY; },
+                            {passive: true});
+
+    const purge = (node) => {
+        if (!node || node.nodeType !== 1) return;
+        const divs = node.matches && node.matches('.js-plotly-plot')
+            ? [node]
+            : Array.from(node.querySelectorAll?.('.js-plotly-plot') || []);
+        for (const gd of divs) {
+            try { window.Plotly && window.Plotly.purge(gd); } catch (e) {}
+        }
+    };
+
+    let sawSwap = false;
+    const obs = new MutationObserver((records) => {
+        for (const r of records) {
+            for (const n of r.removedNodes) purge(n);
+            if (r.removedNodes.length || r.addedNodes.length) sawSwap = true;
+        }
+        if (sawSwap && Math.abs(window.scrollY - lastScrollY) > 1) {
+            window.scrollTo(0, lastScrollY);
+        }
+        sawSwap = false;
+    });
+    obs.observe(document.body, {childList: true, subtree: true});
+    window.addEventListener('pagehide', () => obs.disconnect(), {once: true});
+}
+"""
+
+def build_blocks(ip):
+    """Assemble the full PLASMA `gr.Blocks` (every tab + the headless API) for
+    the given `IntegratedPanel`. Shared by `main()` and the screenshot-capture
+    tool (`scripts/capture_screenshots.py`) so both build the identical UI.
+    Does not launch the server."""
+    with gr.Blocks(title=app_context().app_name, theme=gr.themes.Ocean(), js=js_func) as app:
+        yams_title = None
+        with gr.Tabs() as top_tabs:
+            with gr.Tab("Session Dashboard"):
+                ip.interface()
+            with gr.Tab("Data Dashboard"):
+                ip.visualizer_interface()
+            # extra tabs contributed by enabled plugins (e.g. MSense SQC / IMU).
+            # The real and the simulated MSense plugins both contribute the same
+            # "🍠 YAMS (MSense Tools)" tab — de-dupe by title so enabling both
+            # doesn't build it twice.
+            seen_tabs = set()
+            for plugin in device_config.get_active_table().values():
+                for tab_title, builder in plugin.tabs:
+                    if tab_title in seen_tabs:
+                        continue
+                    seen_tabs.add(tab_title)
+                    if "YAMS" in tab_title:
+                        yams_title = tab_title
+                    with gr.Tab(tab_title):
+                        builder(ip)
+            with gr.Tab("Configuration"):
+                device_config.interface()
+            # with gr.Tab("PL"):
+            #     pl.interface()
+
+        _wire_plot_timer_gate(ip, top_tabs, yams_title)
+
+        # stop any live MSense stream when the last browser tab goes away — a
+        # continuous stream with nobody watching just churns the BLE radio and
+        # (pre-fix) the plot memory. Best-effort; streams aren't multi-viewer.
+        def _on_unload():
+            for dev in list(getattr(ip, "available_devices", []) or []):
+                fn = getattr(dev, "stop_all_live_streams", None)
+                if callable(fn):
+                    try:
+                        fn()
+                    except Exception:
+                        pass
+        app.unload(_on_unload)
+
+        # headless control + situational-awareness endpoints (/status, /start,
+        # /stop, /mark, /events) + the 1 Hz durable event-log pump. Additive —
+        # no UI. See docs/headless.md.
+        plasma_api.register(ip)
+    return app
+
+
+def _wire_plot_timer_gate(ip, top_tabs, yams_title):
+    """Run each live-plot refresh timer only while its tab is on screen.
+    gr.Plot recreates its whole Plotly <div> for every value it receives
+    (gradio#10252), so a timer ticking behind a hidden tab is a memory leak.
+    The MSense sub-tab gate is in panels/tools.py; this adds the top-level one."""
+    from plasma.devices.msense.panels.tools import _SQC_SUBTAB, _IMU_SUBTAB
+
+    specs = [(ip._viz_timer, "Data Dashboard", None)]
+    if getattr(ip, "_sqc_timer", None) is not None:
+        specs.append((ip._sqc_timer, yams_title, _SQC_SUBTAB))
+    if getattr(ip, "_imu_timer", None) is not None:
+        specs.append((ip._imu_timer, yams_title, _IMU_SUBTAB))
+
+    sub_state = getattr(ip, "_yams_sub", None) or gr.State("")
+
+    def _on_top(sub, evt: gr.SelectData):
+        top = evt.value or ""
+        updates = [
+            gr.Timer(active=(top == want_top
+                             and (want_sub is None or sub == want_sub)))
+            for _, want_top, want_sub in specs
+        ]
+        return updates if len(updates) > 1 else updates[0]
+
+    top_tabs.select(_on_top, inputs=sub_state, outputs=[t for t, _, _ in specs])
+
+
+def main():
+    global app
+
+    try:
+        signal.signal(signal.SIGTERM, _handle_sigterm)
+    except ValueError:
+        pass  # not the main thread (e.g. imported oddly) — atexit still covers normal exit
+
+    plugins.load_plugins()
+    device_config.refresh_defaults()
+
+    ip = IntegratedPanel()
+    # pl = PupilLabsDashboard()
+
+    app = build_blocks(ip)
+    app.launch(inbrowser=True, share=False)
+
+
+if __name__ == '__main__':
+    main()
+
+    
+

plasma_app-2.1.3/plasma/__pyinstaller/__init__.py

@@ -0,0 +1,12 @@
+"""PyInstaller hook directory for the ``plasma`` package.
+
+Registered via the ``pyinstaller40`` entry point in ``pyproject.toml`` so any
+``pyinstaller`` build of an app that imports ``plasma`` picks up
+``hook-plasma.py`` automatically — no hand-maintained ``hiddenimports`` list in
+the spec files.
+"""
+import os
+
+
+def get_hook_dirs():
+    return [os.path.dirname(__file__)]

plasma_app-2.1.3/plasma/__pyinstaller/hook-plasma.py

@@ -0,0 +1,16 @@
+"""Best-effort collection of every ``plasma`` submodule + data file.
+
+Device plugins are imported dynamically by ``plasma.plugins`` (dotted strings in
+``_STATIC`` / ``_DISCOVERY``), so PyInstaller's static analysis never sees them.
+
+This hook is a **fallback** for downstream apps that freeze ``plasma`` without
+using our spec files. The project's own builds do not rely on it: ``app_*.spec``
+call ``spec_common.plasma_hiddenimports()`` (a filesystem walk), because
+``collect_submodules`` resolves ``plasma`` through the setuptools editable-install
+finder, which under newer setuptools fails to enumerate the ``plasma.devices.*``
+sub-packages.
+"""
+from PyInstaller.utils.hooks import collect_data_files, collect_submodules
+
+hiddenimports = collect_submodules("plasma")
+datas = collect_data_files("plasma")