Last Updated: Sept 15, 2024
Welcome to HriPhysioLib! 🎉 This library is designed for researchers in Human-Robot Interaction (HRI), specifically tailored for physiological signal processing. Whether you're analyzing ECG data 🩺 or synchronizing robotic systems with physiological inputs 🤖, this library provides the tools to make that happen seamlessly!
With support for Lab Streaming Layer (LSL) and Robot Operating System (ROS), and advanced signal processing techniques like bi-quadratic filtering and the Hilbert Transform, it's ideal for cutting-edge research in physiological data analysis.
Let’s dive into the details!
HriPhysioLib integrates external submodules to extend its functionality. These are:
liblsl 🛠️: For streaming physiological data using Lab Streaming Layer (LSL).yaml-cpp 🗂️: For parsing and emitting YAML files, useful in handling configurations.The source folder is divided into several modules, each with a specific role:
The Core module provides essential data structures. The key component here is the Ring Buffer, a circular structure used for managing physiological data streams in FIFO (First In, First Out) order.
ringbuffer.h: The heart of this module, providing the ring buffer functionality.The Manager module handles the coordination between robotic systems 🤖 and physiological data. It includes multithreading for efficient, real-time operations.
robot_manager.h/cpp: Enables data exchange between robots and physiological data.thread_manager.h/cpp: Manages multithreaded processes for data streaming and processing.The Social module is all about integrating robots with the outside world using physiological signals to drive behaviors 🚶♂️→🤖.
robot_interface.h/cpp: The standard interface to communicate with robots.This is where the magic of transforming raw data into something meaningful happens! 🧙♂️ The Processing module includes:
hilbert_transform.h/cpp: For applying the Hilbert Transform to physiological signals.pocketfft.h: Handles Fourier Transforms for time-frequency analysis.spectrogram.h/cpp: Generates spectrograms for visualizing signal frequencies over time.The Stream module manages data flow from external sources to the processing pipeline 📊.
csv_streamer.h/cpp: Handles data in CSV format.lsl_streamer.h/cpp: Facilitates LSL-based physiological data streaming.The Utilities module offers various helper tools to smooth your workflow 🛠️.
arg_parser.h/cpp: Parses command-line arguments for easy library configuration.helper.h/cpp: Contains useful functions like data conversion and logging.The Tests module is vital for ensuring all the core functionalities work as intended. ✔️
Certainly! Here’s the updated Tests section with the details you provided about the test cases and how to run them.
The Tests module includes comprehensive test suites to verify the core functionalities of the library. These tests ensure that critical components, such as the RingBuffer and the HilbertTransform, behave as expected in various scenarios.
The RingBuffer test suite ensures that the circular buffer, essential for streaming continuous physiological data, operates correctly.
Test Cases:
InitializeBuffer
PushAndPop
OverflowHandling
This test suite ensures the HilbertTransform class, responsible for signal processing, works as expected across different use cases.
Test Cases:
ConstructorTest
ResizeTest
ProcessZeroInput
ProcessDifferentSizes
Helper Function:
To build and run the test suite, follow these steps:
# Create a build directory and navigate into it
mkdir build && cd build
# Generate the build system files
cmake ..
# Build the tests
make
# Run the test suite
./run-tests.shThis will execute all the test cases and display the results in the terminal.
The CLI testing framework 🖥️ allows you to test the library’s functionality directly from the command line, focusing on the Hilbert Transform application on ECG data generated using the NeuroKit library.
Key features of the cli testing setup:
Data Input and Output: The CLI reads ECG data from a CSV file, applies the Hilbert Transform to the data, and writes the results to a new CSV file. This allows for a straightforward method of verifying the functionality of the processing algorithms.
Hilbert Transform: The primary processing function tested is the Hilbert Transform, which is implemented in the library to compute the analytic signal of the ECG data, providing both amplitude and phase information.
CSV Streamers: The testing program utilizes CSVStreamer for both input and output operations, facilitating the reading and writing of data in CSV format. The CSV files are expected to contain single-channel ECG data, and the output file includes both the original data and the Hilbert-transformed data.
The cli folder contains a simple test program (main.cpp) that executes the entire process. This setup allows researchers and developers to verify the processing functions of the library before integrating it into larger systems. However, it does not utilize the full functionality of the library, such as streaming protocols or robotic control.
For more detailed instructions on using the example, visit the Instructions.
There are two methods to install HriPhysioLib:
This method automatically pulls the external submodules for you.
git clone --recursive https://github.com/HBRS-SDP/ss24-physiological-computing.git
cd hri-physio/HriPhysioLibThen, to build and test the library, simply use:
make build-library
make run-library-tests
make run-cliAlternatively, if you prefer manual control over submodules, follow these steps:
git clone https://github.com/HBRS-SDP/ss24-physiological-computing.git
cd hri-physio/HriPhysioLibNext, initialize and update the submodules:
git submodule init
git submodule updateThen, use the same Makefile commands as in Method 1 to build and run tests:
make build-library
make run-library-tests
make run-cliBig thanks to our amazing contributors who made HriPhysioLib possible! 🙌
HriPhysioLib is licensed under the MIT License 📜. For more details, please visit the GitHub Repository.
Enjoy exploring the world of Human-Robot Interaction with physiological data! 🧠🤖