Metadata-Version: 2.3
Name: bioview
Version: 0.9.2
Summary: A versatile, extensible, and performant cross-platform app for biomedical and human-computer interface instrumentation control
License: GPL-v3
Author: Aakash Kapoor
Author-email: 113218196+meowkash@users.noreply.github.com
Requires-Python: >=3.12, <3.13
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: darkdetect (>=0.8.0,<0.9.0)
Requires-Dist: h5py (>=3.13.0,<4.0.0)
Requires-Dist: matplotlib (>=3.10.1,<4.0.0)
Requires-Dist: numpy (<2.0.0)
Requires-Dist: pygame (>=2.6.1,<3.0.0)
Requires-Dist: pyqt6 (>=6.9.0,<7.0.0)
Requires-Dist: pyqtgraph (>=0.13.7,<0.14.0)
Requires-Dist: qtawesome (>=1.4.0,<2.0.0)
Requires-Dist: scipy (>=1.15.2,<2.0.0)
Requires-Dist: uhd (>=4.8.0.0,<5.0.0.0) ; sys_platform == "win32"
Description-Content-Type: text/markdown

# BioView

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

BioView is a versatile, extensible, and performant cross-platform app for biomedical and human-computer interface instrumentation control, including Ettus USRPs and BIOPAC devices.

## Features

* **Real-time USRP Control:** Interface with Ettus USRP devices for high-throughput transceiving
* **BIOPAC Integration:** Synchronized physiological data collection alongside RF measurements
  * *You must already possess a copy of the BIOPAC Hardware API purchased from BIOPAC Systems Inc. for this to work*
* **Live Data Visualization:** Sensor data is visualized in real-time
* **Synchronized Data Acquisition:** Save synchronized hardware data streams with precise timing control
* **Experiment Management:** Configure and control experimental routines and settings
* **Event Annotation:** Mark and annotate events during data collection
* **Multi-format Data Storage:** Flexible data saving with multiple format support

## Installation

BioView should run on all platforms but is officially supported on the following platforms -

* **Windows**
* **Linux:** Ubuntu LTS, Debian, and derivative distributions.
  * Fedora and RHEL based distributions do not bundle in Python bindings for ```uhd``` and require manually buildng from source.
  * Non-LTS versions of Ubuntu are not supported due to missing packages.
  
### Dependencies

* **Python:** Ensure Python 3.12 is installed on your system. *For Windows, use the Microsoft Store app instead of the website executable.*
* **UHD:** You can install it by following the [official instructions](https://files.ettus.com/manual/page_install.html) for your operating system.
* **UHD Python Bindings (Linux users only):** For Ubuntu/Debian users, python bindings are installed using ```sudo apt install python3-uhd```. For RHEL/Fedora users, these need to be manually generated by building from source.

Once all the dependencies are installed, installing BioView is as simple as running ```pip install bioview```. We recommend running this command in a virtual environment so as to not pollute your operating system Python. 

## Usage

In order to run an experiment using bioview, you need to create an executable file similar to the example below -

```Python
import sys 
import faulthandler

from bioview.app import Viewer
from bioview.types import UsrpConfiguration, ExperimentConfiguration, BiopacConfiguration

from PyQt6.QtWidgets import QApplication

# Usually a good idea to have a crash log 
faulthandler.enable(open('crash.log', 'w'), all_threads=True)

# Experiment variables 
exp_config = ExperimentConfiguration(
    save_dir = '/home',
    file_name = 'example', 
    save_ds = 100,    
    disp_ds = 10, 
    disp_filter_spec = {
        'bounds': 10,
        'btype': 'low',
        'ftype': 'butter' 
    },
    disp_channels = ['Tx1Rx1', 'Tx2Rx2', 'Tx1Rx2', 'Tx2Rx1'],
)

# USRP variables 
usrp = UsrpConfiguration(
    device_name = 'MyB210_4', 
    if_freq = [100e3, 110e3],
    if_bandwidth = 5e3, 
    rx_gain = [25, 35], 
    tx_gain = [43, 37], 
    samp_rate = 1e6, 
    carrier_freq = 9e8,
)

# Biopac Control
bio = BiopacConfiguration(
    device_name = 'MyBIOPAC', 
    channels = [1, 1, 0, 0]
)

# Run application
app = QApplication(sys.argv)

window = Viewer(exp_config=exp_config,
                usrp_config=[usrp], 
                bio_config=bio)
window.show()

sys.exit(app.exec())
```

## Performance Considerations

* Real-time data acquisition requires sufficient system resources
* Large data streams may require SSD storage for optimal performance
* Memory usage scales with buffer sizes and visualization complexity. Visualization is kept efficient by only updating data streams for source that are actually visible
* Spikes may occur in the data if receive buffer is kept low in size due to filtering edge effects
* B210 devices work poorly with default frame sizes, which is why default receive frame size has been kept at 1024

## Troubleshooting

Common issues and solutions:

1. **USRP Device Not Detected**: Verify hardware connections and driver installation
2. **High CPU Usage**: Adjust buffer sizes and visualization update rates
3. **Data Loss**: Check storage write speeds and available disk space
4. **Synchronization Issues**: Verify system clock accuracy and BIOPAC timing

Check `crash.log` for detailed error information and diagnostic data.

## Development

### Structure

```bash
bioview/
├── app.py              # Main application
├── usrp/               # USRP core functionality
├── common/             # Common functionality
├── components/         # GUI components
├── biopac/             # BIOPAC integration
├── utils/              # Utility functions
├── types/              # Custom data-types 
└── constants/          # App-specific constants
```

### Instructions

Contributing changes requires you to have ```git``` installed in your system to be able to install the editable version of the app. In a terminal window, follow the steps listed below. *On Windows, use Git Bash for this. On Linux and macOS, use the native terminal app.*

```bash
# Clone repository 
cd ~ 
git clone https://github.com/meowkash/bioview.git 

# Run installer script
cd bioview
chmod +x install.sh
./install.sh 
```

Ensure you make your changes in forks and submit PRs for review.

## License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for the complete license text.

