Skip to content

README.md

Latest commit

 

History

History
173 lines (141 loc) · 6.02 KB

README.md

File metadata and controls

173 lines (141 loc) · 6.02 KB

MoBI-View

A real-time biosignal visualization tool for Lab Streaming Layer (LSL) streams.

Build codecov Ruff stability-stable LGPL--2.1 License pages

Welcome to MoBI-View, a Python application designed for real-time visualization of biosignal data from Lab Streaming Layer (LSL) streams. This tool allows researchers and clinicians to monitor and analyze various biosignals like EEG, eye-tracking data, and other physiological measurements through an intuitive and responsive interface.

Features

  • Real-time signal visualization from any LSL-compatible device streaming numerical data.
  • Multi-stream support for simultaneous monitoring of different data sources.
  • Specialized plot types optimized for different signal types.
  • EEG plot widgets for neurophysiological data.
  • Numeric plot widgets for other sensor data.
  • Channel / Stream visibility control for focusing on specific data channels.
  • Hierarchical stream organization through a tree-based interface.
  • Automatic stream discovery.

Installation

Installing uv

First, install uv, a fast package installer and resolver for Python:

macOS/Linux:

curl --proto '=https' --tlsv1.2 -sSf https://astral.sh/uv/install.sh | sh

Windows (Powershell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

⚠️ Import Note for MoBI-View Installation

MoBI-View depends on pylsl, which utilizes liblsl, a system-level dependency that is not installed by default. Install it by following the instructions from the Installing liblsl section below.

Installing MoBI-View

Option 1: Install from PyPI

pip install mobi-view

Option 2: Install from Github

# Clone the repository
git clone https://github.com/childmindresearch/MoBI-View.git
cd MoBI-View

# Optional: Create virtual environment
uv venv

# Optional: Activate the environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install all dependencies including the package itself
uv sync

⚠️ Installing liblsl

The pylsl package requires the liblsl binaries for your platform. You can install them using one of the following methods:

Option 1: Package Managers
  • Conda (all platforms): conda install -c conda-forge liblsl
  • vcpkg (Windows/Linux): vcpkg install liblsl
  • Conan (Windows): conan install liblsl
  • Homebrew (macOS): brew install labstreaminglayer/tap/lsl
Option 2: Build from Source
git clone --depth=1 https://github.com/sccn/liblsl.git
cd liblsl
mkdir build && cd build
cmake ..
cmake --build . --config Release
cmake --install .
Option 3: Precompiled Binaries
  • Download the latest release for your platform from the liblsl Releases page
  • Extract the zip file and add the library to your system's path:

Windows:

  1. Download the Windows ZIP file (e.g., liblsl-1.16.2-Win64.zip)
  2. Extract the Zip file, which contains: - bin/lsl.dll - lib/lsl.dll - header files in include/ directory
  3. Add the extracted bin directory to your PATH environment variable
# Example: If unzipped to C:\liblsl
$env:PATH += ";C:\liblsl\bin"

macOS:

  1. Download the macOS package (e.g., liblsl-1.16.2-OSX-amd64.tar.bz2)
  2. Extract the archive:
tar -xf liblsl-1.16.2-OSX-amd64.tar.bz2
  1. Inside you'll find: - lib/liblsl.dylib - header files in include/ directory
  2. You can either: - Copy lib/liblsl.dylib to lib - Or set the DYLD_LIBRARY_PATH to include the lib directory

Linux:

  1. Download the appropriate Debian package (e.g., liblsl-1.16.2-Linux64-focal.deb for Ubuntu 20.04)
  2. Install using:
sudo dpkg -i liblsl-1.16.2-Linux64-focal.deb

Or download the liblsl-1.16.2-Linux64.tar.bz2 and extract:

tar -xf liblsl-1.16.2-Linux64.tar.bz2
sudo cp lib/liblsl.so* /usr/local/lib/
sudo ldconfig

Quick start Guide

  1. Activate your environment (if not already activated):

  2. Run MoBI-View (either method works):

# Method 1: Using uv run
uv run mobi-view

# Method 2: Direct execution
python -m src/main.py
  1. Select LSL streams from the tree view to visualize data:
    • EEG data appears in the EEG tab.
    • Other physiological signals appear in the Numeric tab.
    • Toggle streams and channels on/off by clicking checkboxes.

Application Interface

When you launch MoBI-View:

  1. Stream Discovery: The application automatically discovers available LSL streams.
  2. Visualization: Streams are displayed in appropriate plot widgets based on their type (EEG vs non-EEG).
  3. Control Panel: A tree view on the left shows available streams and channels. This control panel can be moved or separated out of the main window.
  4. Channel Selection: Toggle visibility of individual channels by clicking on their boxes in the Control Panel.

Future Directions

  • Support for additional visualization types (non-numeric data and event markers).
  • Custom filtering and signal processing options.
  • Extended analysis tools for common biosignal metrics.
  • EEG impedance checker for ease of setup.