emg-gui 0.0.5__py3-none-any.whl

emg_gui/acquisition/data_source.py

@@ -0,0 +1,384 @@
+import platform
+import sys
+import time
+from typing import Protocol
+
+import numpy as np
+from brainflow.board_shim import BoardIds, BoardShim, BrainFlowInputParams
+from brainflow.data_filter import DataFilter
+from serial.tools import list_ports
+
+from emg_gui.acquisition.dataset_files import get_all_files
+from emg_gui.config.constants import (
+    IS_SYNTHETIC_BOARD,
+    MARKER_END_ACTIVITY,
+    MARKER_START_ACTIVITY,
+    SENSOR_POLL_INTERVAL_MS,
+)
+from emg_gui.core.enums import ActivityState, RecordingState, StreamingState
+from emg_gui.core.logger import Logger
+from emg_gui.core.types import EMGArray
+
+
+class DataSource(Protocol):
+
+    def start_stream(self) -> None: ...
+
+    def stop_stream(self) -> None: ...
+
+    def start_recording(self) -> None: ...
+
+    def stop_recording(self) -> None: ...
+
+    def record(self, data) -> None: ...
+
+    def insert_start_marker(self) -> None: ...
+
+    def insert_stop_marker(self) -> None: ...
+
+    def get_data(self) -> EMGArray: ...
+
+    def extract_emg_data(self, emg_with_marker_data: EMGArray) -> EMGArray: ...
+
+    def write_to_csv(self, datasplit: str, folder: str) -> None: ...
+
+    def release(self) -> None: ...
+
+    @property
+    def emg_channel_count(self) -> int: ...
+
+    @property
+    def is_streaming(self) -> bool: ...
+
+    @property
+    def is_recording(self) -> bool: ...
+
+    @property
+    def is_active(self) -> bool: ...
+
+    @property
+    def sampling_rate(self) -> int: ...
+
+
+class OpenBCIBoard:
+    _BOARD_ID = BoardIds.SYNTHETIC_BOARD if IS_SYNTHETIC_BOARD else BoardIds.CYTON_BOARD
+
+    _PORT_NAMES = ("FT231X USB UART", "VCP")
+
+    _instance = None
+
+    @classmethod
+    def _get_serial_port(cls) -> str:
+        ports = []
+
+        for port in list_ports.comports():
+            description = port.description or ""
+
+            if description.startswith(cls._PORT_NAMES):
+                if platform.system() == "Darwin" and port.device.startswith("/dev/tty"):
+                    continue
+
+                ports.append(port.device)
+
+        if not ports:
+            raise RuntimeError("DATASOURCE: No OpenBCI Cyton dongle found")
+
+        return ports[0]
+
+    def __init__(self, logger: Logger) -> None:
+        BoardShim.enable_dev_board_logger()
+        self._logger = logger
+
+        _params = BrainFlowInputParams()
+
+        if not IS_SYNTHETIC_BOARD:
+            _params.serial_port = self._get_serial_port()
+            self._logger.info(f"DATASOURCE: Port - {_params.serial_port}")
+
+        self._brainflow_emg_channels = BoardShim.get_emg_channels(
+            board_id=self._BOARD_ID
+        )
+        brainflow_marker_channel = BoardShim.get_marker_channel(board_id=self._BOARD_ID)
+
+        self._data_channels = self._brainflow_emg_channels + [brainflow_marker_channel]
+        self._emg_channel_count = len(self._brainflow_emg_channels)
+
+        self._board = BoardShim(board_id=self._BOARD_ID, input_params=_params)
+        self._board.prepare_session()
+        if not self._board.is_prepared():
+            self._logger.error("DATASOURCE: Board cannot be initialized")
+            sys.exit(1)
+
+        self._turn_off_srb(self._board)
+        self._logger.info("DATASOURCE: Board initialized and SRB channels turned-off")
+
+        self._streaming_state = StreamingState.IDLE
+        self._recording_state = RecordingState.IDLE
+        self._activity_state = ActivityState.INACTIVE
+
+        self._emg_recording: list[EMGArray] = []
+
+    @classmethod
+    def get_instance(cls, logger: Logger) -> DataSource:
+        if cls._instance is None:
+            cls._instance = cls(logger)
+        return cls._instance
+
+    @property
+    def emg_channel_count(self) -> int:
+        return self._emg_channel_count
+
+    def start_stream(self) -> None:
+        if self.is_streaming:
+            raise RuntimeError("DATASOURCE: Streaming has already started")
+
+        if self._board.is_prepared():
+            self._board.start_stream()
+            self._logger.info(
+                f"DATASOURCE: Data Stream Started (synthetic data: {IS_SYNTHETIC_BOARD})"
+            )
+        else:
+            self._logger.error("DATASOURCE: Unable to connect with OpenBCI board")
+            raise RuntimeError("DATASOURCE: Unable to connect with OpenBCI board")
+
+        self._streaming_state = StreamingState.STREAMING
+
+    def stop_stream(self) -> None:
+        if not self.is_streaming:
+            raise RuntimeError("DATASOURCE: Streaming has already stopped")
+
+        self._board.stop_stream()
+        self._logger.info("DATASOURCE: Data Stream closed successfully")
+
+        flush_data = self._board.get_board_data()
+        self._logger.info(
+            f"DATASOURCE: Brainflow ring buffer cleaned: {flush_data.shape[1]}"
+        )
+
+        self._logger.info(
+            f"DATASOURCE: Brainflow ring buffer after cleaning: {self._board.get_board_data_count()}"
+        )
+
+        self._streaming_state = StreamingState.IDLE
+
+    def start_recording(self) -> None:
+        if self.is_recording:
+            raise RuntimeError("DATASOURCE: Recording has already started")
+
+        self._recording_state = RecordingState.RECORDING
+
+    def stop_recording(self) -> None:
+        if not self.is_recording:
+            raise RuntimeError("DATASOURCE: Recording has already stopped")
+
+        self._recording_state = RecordingState.IDLE
+
+    def record(self, data) -> None:
+        if self.is_recording:
+            self._emg_recording.append(data)
+
+    def insert_start_marker(self) -> None:
+        if self.is_active:
+            raise RuntimeError("DATASOURCE: Activity has already started")
+
+        self._board.insert_marker(MARKER_START_ACTIVITY)
+        self._activity_state = ActivityState.ACTIVE
+
+    def insert_stop_marker(self) -> None:
+        if not self.is_active:
+            raise RuntimeError("DATASOURCE: Activity has already stopped")
+
+        self._board.insert_marker(MARKER_END_ACTIVITY)
+        self._activity_state = ActivityState.INACTIVE
+
+    def get_data(self) -> EMGArray:
+        all_board_data = self._board.get_board_data()
+        active_channel_data = all_board_data[self._data_channels, :]
+        return active_channel_data
+
+    def extract_emg_data(self, emg_with_marker_data: EMGArray) -> EMGArray:
+        emg_data = emg_with_marker_data[
+            : self.emg_channel_count, :
+        ]  # assumes marker is last
+        return emg_data
+
+    def write_to_csv(self, datasplit: str, folder: str) -> None:
+        emg_numpy = np.concatenate(self._emg_recording, axis=1)
+        file_path = (
+            f"data/csv/{datasplit}/{folder}/{str(int(time.time()))}__{folder}.csv"
+        )
+        DataFilter.write_file(data=emg_numpy, file_name=file_path, file_mode="w")
+        file_ds = get_all_files(
+            pattern=f"data/csv/{datasplit}/{folder}/*.csv", shuffle_flag=False
+        )  # hard-coded: [TECH DEBT]
+        self._logger.info(
+            f"DATASOURCE: File written @ {file_path} (Total files: {sum(1 for _ in file_ds)})"
+        )
+        self._emg_recording.clear()
+        self._logger.info("DATASOURCE: Source data storage cleaned(Reset)")
+
+    def release(self) -> None:
+        if self.is_streaming:
+            self.stop_stream()
+        if self._board.is_prepared():
+            self._board.release_session()
+
+    @property
+    def sampling_rate(self) -> int:
+        return self._board.get_sampling_rate(self._BOARD_ID)
+
+    @property
+    def is_streaming(self) -> bool:
+        return self._streaming_state is StreamingState.STREAMING
+
+    @property
+    def is_recording(self) -> bool:
+        return self._recording_state is RecordingState.RECORDING
+
+    @property
+    def is_active(self) -> bool:
+        return self._activity_state is ActivityState.ACTIVE
+
+    def _turn_off_srb(self, board):
+        for channel in self._brainflow_emg_channels:
+            board_response = board.config_board(f"x{channel}060100X")[:1]
+            if board_response not in {"S", "C"}:
+                sys.exit(1)
+
+
+class PlaybackRecording:
+    _instance = None
+
+    def __init__(self, logger: Logger, file_path: str) -> None:
+        self._logger = logger
+        self._file_path = file_path
+
+        self._data = np.loadtxt(self._file_path, delimiter="\t").T
+        self._current_idx = 0
+        self._max_idx = self._data.shape[1]
+
+        self._data_channels = list(range(self._data.shape[0]))
+        self._emg_channel_count = len(self._data_channels) - 1  # assumes marker is last
+
+        self._logger.info(
+            f"DATASOURCE: PlaybackRecording - file: {self._file_path} "
+            f"- Channels: {self._data_channels} "
+            f"- EMG Channels Count: {self._emg_channel_count}"
+        )
+
+        self._streaming_state = StreamingState.IDLE
+        self._recording_state = RecordingState.IDLE
+        self._activity_state = ActivityState.INACTIVE
+
+    @classmethod
+    def get_instance(cls, logger: Logger, file_path: str) -> DataSource:
+        if cls._instance is None:
+            cls._instance = cls(logger, file_path)
+        return cls._instance
+
+    def start_stream(self) -> None:
+        if self.is_streaming:
+            raise RuntimeError("DATASOURCE: Playback has already started")
+
+        self._logger.info("DATASOURCE: Playback Started (playing-recording)")
+        self._current_idx = 0
+        self._streaming_state = StreamingState.STREAMING
+
+    def stop_stream(self) -> None:
+        if not self.is_streaming:
+            raise RuntimeError("DATASOURCE: Playback has already stopped")
+
+        self._logger.info("DATASOURCE: Playback closed successfully")
+
+        self._streaming_state = StreamingState.IDLE
+
+    def start_recording(self) -> None:
+        if self.is_recording:
+            raise RuntimeError("DATASOURCE: Recording has already started")
+
+        self._recording_state = RecordingState.RECORDING
+
+    def stop_recording(self) -> None:
+        if not self.is_recording:
+            raise RuntimeError("DATASOURCE: Recording has already stopped")
+
+        self._recording_state = RecordingState.IDLE
+
+    def record(self, data) -> None:
+        pass
+
+    def insert_start_marker(self) -> None:
+        if self.is_active:
+            raise RuntimeError("DATASOURCE: Activity has already started")
+
+        self._activity_state = ActivityState.ACTIVE
+
+    def insert_stop_marker(self) -> None:
+        if not self.is_active:
+            raise RuntimeError("DATASOURCE: Activity has already stopped")
+
+        self._activity_state = ActivityState.INACTIVE
+
+    def get_data(self) -> EMGArray:
+        expected_sample_count = round(
+            self.sampling_rate * SENSOR_POLL_INTERVAL_MS / 1000
+        )  # playback speed
+
+        end_idx = min(self._current_idx + expected_sample_count, self._max_idx)
+        board_data = self._data[:, self._current_idx : end_idx]
+        self._current_idx = end_idx
+
+        return self._add_padding(
+            board_data, len(self._data_channels), expected_sample_count
+        )
+
+    def extract_emg_data(self, emg_with_marker_data: EMGArray) -> EMGArray:
+        emg_data = emg_with_marker_data[
+            : self.emg_channel_count, :
+        ]  # assumes marker is last
+        return emg_data
+
+    @staticmethod
+    def _add_padding(
+        board_data: EMGArray,
+        channel_count: int,
+        expected_samples: int,
+    ) -> EMGArray:
+        received_samples = board_data.shape[-1]
+
+        if received_samples == expected_samples:
+            return board_data
+
+        padded_data = np.zeros(
+            (channel_count, expected_samples),
+            dtype=board_data.dtype,
+        )
+        padded_data[:, :received_samples] = board_data
+
+        return padded_data
+
+    def write_to_csv(self, datasplit: str, folder: str) -> None:
+        return None
+
+    def release(self) -> None:
+        return None
+
+    @property
+    def sampling_rate(self) -> int:
+        return 250  # assumes cyton board
+
+    @property
+    def emg_channel_count(self) -> int:
+        return self._emg_channel_count
+
+    @property
+    def is_streaming(self) -> bool:
+        return self._streaming_state is StreamingState.STREAMING
+
+    @property
+    def is_recording(self) -> bool:
+        return self._recording_state is RecordingState.RECORDING
+
+    @property
+    def is_active(self) -> bool:
+        return self._activity_state is ActivityState.ACTIVE

emg_gui/acquisition/dataset_files.py

@@ -0,0 +1,20 @@
+import glob
+import os
+import random
+from pathlib import Path
+
+_CSV_PATH = Path("data/csv")
+
+
+def get_all_labels(selected_type="train") -> list[str]:  # Default from train
+    train_path = os.path.join(_CSV_PATH, selected_type)
+    return os.listdir(path=train_path)
+
+
+def get_all_files(pattern: str, shuffle_flag: bool) -> list[str]:
+    files = glob.glob(pattern)
+
+    if shuffle_flag:
+        random.shuffle(files)
+
+    return files

emg_gui/acquisition/sensor_worker.py

@@ -0,0 +1,108 @@
+import numpy as np
+from dvg_ringbuffer import RingBuffer
+from PyQt5.QtCore import QObject, QTimer, pyqtSignal, pyqtSlot
+
+from emg_gui.acquisition.data_source import DataSource
+from emg_gui.config.constants import (
+    EDGE_ARTIFACT_BUFFER,
+    SENSOR_POLL_INTERVAL_MS,
+    TIME_WINDOW_SAMPLES,
+)
+from emg_gui.core.logger import Logger
+from emg_gui.core.types import EMGArray
+
+
+class SensorWorker(QObject):
+
+    stream_changed = pyqtSignal(str)
+    record_changed = pyqtSignal(str)
+    marker_changed = pyqtSignal(str)
+    reset_changed = pyqtSignal(str)
+
+    def __init__(self, logger: Logger, board: DataSource) -> None:
+        super().__init__()
+        self._logger = logger
+        self._board = board
+
+        _buffer_length = TIME_WINDOW_SAMPLES + EDGE_ARTIFACT_BUFFER
+        self._emg_channel_count = board.emg_channel_count
+
+        self._zero_window = np.zeros(
+            (_buffer_length, self._emg_channel_count), dtype=np.float64
+        )
+
+        self._ring_buffer = RingBuffer(
+            capacity=_buffer_length,
+            dtype=(
+                np.float64,
+                self._emg_channel_count,
+            ),  # pyright: ignore[reportArgumentType]
+        )
+        self._ring_buffer.extend(self._zero_window)
+
+        self._latest_snapshot = self._zero_window.T.copy(order="C")
+
+        self._sensor_timer = QTimer(self)
+        self._sensor_timer.timeout.connect(self._receive_sensor_data)
+        self._sensor_timer.setInterval(SENSOR_POLL_INTERVAL_MS)
+
+    @pyqtSlot()
+    def _receive_sensor_data(self) -> None:
+        emg_with_marker_data = self._board.get_data()
+        self._board.record(emg_with_marker_data)
+        emg_data = self._board.extract_emg_data(emg_with_marker_data)
+        self._ring_buffer.extend(emg_data.T)
+        buffer_copy = self._ring_buffer[:].T.copy(order="C")
+        self._latest_snapshot = (
+            buffer_copy  # atomic assignment swaps without locks: thread safe
+        )
+
+    @pyqtSlot()
+    def publish_buffer_snapshot(self) -> tuple[EMGArray, bool]:
+        """Called/Runs directly by the GUI thread without any locks."""
+        return (self._latest_snapshot, self._board.is_streaming)
+
+    @pyqtSlot()
+    def stream(self) -> None:
+        if self._board.is_streaming:
+            self._sensor_timer.stop()
+            self._ring_buffer.extend(self._zero_window)
+            self._latest_snapshot = self._zero_window.T.copy(order="C")
+            self._board.stop_stream()
+            self.stream_changed.emit("Stream")
+            return
+
+        self._board.start_stream()
+        self._sensor_timer.start()
+        self.stream_changed.emit("Streaming")
+
+    @pyqtSlot()
+    def shutdown_timer(self) -> None:
+        if self._sensor_timer.isActive():
+            self._logger.info("SENSORWORKER: Killed QTimer in sensor thread")
+            self._sensor_timer.stop()
+
+    @pyqtSlot(str, str)
+    def record(self, selected_datasplit: str, selected_folder: str) -> None:
+        if self._board.is_recording:
+            self._board.stop_recording()
+            self._board.write_to_csv(selected_datasplit, selected_folder)
+            self.record_changed.emit("Record")
+            return
+
+        self._board.start_recording()
+        self.record_changed.emit("Recording")
+
+    @pyqtSlot()
+    def marker(self) -> None:
+        if self._board.is_active:
+            self._board.insert_stop_marker()
+            self.marker_changed.emit("Start Movement")
+            return
+
+        self._board.insert_start_marker()
+        self.marker_changed.emit("Stop Movement")
+
+    @pyqtSlot()
+    def reset(self) -> None:
+        self._ring_buffer.extend(self._zero_window)

emg_gui/app.py

@@ -0,0 +1,21 @@
+from emg_gui.acquisition.data_source import DataSource, OpenBCIBoard
+from emg_gui.core.logger import ConsoleLogger, Logger
+from emg_gui.ui.window import EMGVisualizerWindow
+
+
+def main() -> None:
+    logger: Logger = ConsoleLogger.get_instance()
+    board: DataSource = OpenBCIBoard.get_instance(logger)
+    # board: DataSource = PlaybackRecording.get_instance(
+    #     logger, "data/csv/train/sample/1785181476__sample.csv"
+    # )
+
+    try:
+        EMGVisualizerWindow.run(logger, board)
+    finally:
+        board.release()
+        logger.release()
+
+
+if __name__ == "__main__":
+    main()

emg_gui/config/constants.py

@@ -0,0 +1,17 @@
+IS_SYNTHETIC_BOARD = True
+
+SENSOR_POLL_INTERVAL_MS = 40
+
+TIME_WINDOW_SAMPLES = 1200
+SPECTROGRAM_WINDOW = 100
+EDGE_ARTIFACT_BUFFER = 500
+
+MARKER_START_ACTIVITY = 1.12345
+MARKER_END_ACTIVITY = 2.12345
+
+MAJOR_PIXEL_TICKS = 20
+MINOR_PIXEL_TICKS = 10
+
+TEXT_PIXEL_TICKS = 20
+TEXT_SCALE = 2
+TEXT_FONT_SIZE = 12

emg_gui/core/enums.py

@@ -0,0 +1,28 @@
+from enum import Enum, auto
+
+
+class StreamingState(Enum):
+    IDLE = auto()
+    STREAMING = auto()
+
+
+class RecordingState(Enum):
+    IDLE = auto()
+    RECORDING = auto()
+
+
+class ActivityState(Enum):
+    ACTIVE = auto()
+    INACTIVE = auto()
+
+
+class DatasetSplit(str, Enum):
+    TRAIN = "train"
+    VALIDATE = "validate"
+    TEST = "test"
+
+
+class DataSourceType(str, Enum):
+    REAL = "real"
+    SYNTHETIC = "synthetic"
+    PLAYBACK = "playback"

emg_gui/core/logger.py

@@ -0,0 +1,50 @@
+import logging
+from typing import Protocol
+
+
+class Logger(Protocol):
+    def info(self, message: str) -> None: ...
+
+    def error(self, message: str) -> None: ...
+
+    def release(self) -> None: ...
+
+
+class ConsoleLogger:
+    _instance = None
+
+    @classmethod
+    def get_instance(cls) -> Logger:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    def __init__(self) -> None:
+        self._logger = logging.getLogger("emg-gui")
+        self._logger.setLevel(logging.INFO)
+        self._logger.propagate = False
+
+        if not self._logger.handlers:
+            self._logger.addHandler(ConsoleLogger._get_handler())
+
+    def info(self, message: str) -> None:
+        self._logger.info(msg=message)
+
+    def error(self, message: str) -> None:
+        self._logger.error(msg=message)
+
+    def release(self) -> None:
+        handlers = self._logger.handlers[:]
+        for handler in handlers:
+            self._logger.removeHandler(handler)
+            handler.close()
+        ConsoleLogger._instance = None
+        print("Logger resources released successfully.")
+
+    @staticmethod
+    def _get_handler() -> logging.StreamHandler:
+        handler = logging.StreamHandler()
+        _format = "%(asctime)s - %(levelname)s - %(filename)s - %(message)s"
+        _formatter = logging.Formatter(_format)
+        handler.setFormatter(_formatter)
+        return handler

emg_gui/core/types.py

@@ -0,0 +1,5 @@
+from typing import Any
+
+import numpy as np
+
+EMGArray = np.ndarray[Any, np.dtype[np.float64]]

emg_gui/processing/filter.py

@@ -0,0 +1,44 @@
+from brainflow.board_shim import BoardIds, BoardShim
+from brainflow.data_filter import AggOperations, DataFilter, FilterTypes, NoiseTypes
+
+from emg_gui.config.constants import IS_SYNTHETIC_BOARD
+from emg_gui.core.types import EMGArray
+
+_BOARD_ID = BoardIds.SYNTHETIC_BOARD if IS_SYNTHETIC_BOARD else BoardIds.CYTON_BOARD
+
+
+def filter_data(time_series: EMGArray) -> None:
+
+    DataFilter.perform_rolling_filter(time_series, 3, AggOperations.MEAN.value)
+
+    DataFilter.perform_bandstop(
+        data=time_series,
+        sampling_rate=BoardShim.get_sampling_rate(_BOARD_ID),
+        start_freq=58.0,
+        stop_freq=62.0,
+        order=4,
+        filter_type=FilterTypes.BUTTERWORTH,
+        ripple=1.0,
+    )
+
+    DataFilter.perform_bandpass(
+        data=time_series,
+        sampling_rate=BoardShim.get_sampling_rate(_BOARD_ID),
+        start_freq=10.0,
+        stop_freq=125.0,
+        order=4,
+        filter_type=FilterTypes.BUTTERWORTH,
+        ripple=1.0,
+    )
+
+    DataFilter.remove_environmental_noise(
+        data=time_series,
+        sampling_rate=BoardShim.get_sampling_rate(_BOARD_ID),
+        noise_type=NoiseTypes.FIFTY.value,
+    )
+
+    DataFilter.remove_environmental_noise(
+        data=time_series,
+        sampling_rate=BoardShim.get_sampling_rate(_BOARD_ID),
+        noise_type=NoiseTypes.SIXTY.value,
+    )