Skip to content

added Brainflow SpO2 example #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

added Brainflow SpO2 example #19

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f7d91b4
added Brainflow SpO2 example
jaketheduque Aug 17, 2025
16ff0b4
typos
jaketheduque Aug 17, 2025
2a1e72e
Removes SpO2 algorithm and Python bindings integration
jaketheduque Aug 17, 2025
a77cd26
updated Brainflow SpO2 example to point to specific commit
jaketheduque Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 33 additions & 45 deletions README_py.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
# Porting an algorithm from C++ to Python

## Table of Contents
- [Why?](#why?)
- [Why?](#why)
- [How it works](#how-it-works)
- [Requirements](#Requirements)
- [Creating python-env with pybind11](#Creating-python-env-with-pybind11)
- [Using venv (recommended)](#Using-venv)
- [Using anaconda](#Using-anaconda)
- [Examples](#Examples)
- [Rounder](#Rounder)
- [EmotiBitPacket](#EmotiBitPacket)
- [Adapting this to your C++ code](#Adapting-this-to-your-C++-code)
- [Requirements](#requirements)
- [Setting up Python virtual environment](#setting-up-python-virtual-environment)
- [Adapting this to your C++ code](#adapting-this-to-your-c-code)
- [Examples](#examples)
- [Rounder](#rounder)
- [EmotiBitPacket](#emotibitpacket)
- [Brainflow SpO2 Algorithm](#brainflow-spo2-algorithm)

## Why?
The goal of this project is to allow users to take an algorithm written in C++ and translate it into runnable Python code.
Expand All @@ -37,62 +36,51 @@ PYBIND11_MODULE(EmotiBitPacket, m) {
- Build the files created in the previous step to create the `.pyd` file

## Requirements
### Creating python-env with pybind11
#### Using venv
### Setting up Python Virtual Environment
- Open a new command prompt window
- `cd` to the EmotiBit_Plugins repository
- Run the following command `python -m venv .\py_envs\<env-name>`
- replace `<env-name>` with the environment name
- Activate the new environment by running the command `.\py_envs\<env-name>\Scripts\activate.bat`
- You will see the prompt in the terminal change. It now shows the python environment in parenthesis.
- Run the following command to install bypind11. `pip install pybind11==2.13.5`
- `cd` to `EmotiBit_Plugins/py_envs`
- Run the following command `python -m venv emotibit_plugins`
- This creates a new folder called `plugins` containing the virtual Python environment
- Activate the new environment:
- Windows (cmd): `.\emotibit_plugins\Scripts\activate.bat`
- Windows (PowerShell): `.\emotibit_plugins\Scripts\Activate.ps1`
- macOS/Linux (bash/zsh): `source emotibit_plugins/bin/activate`
- Run the following command to install pybind11. `pip install pybind11==2.13.5`

Comment on lines +39 to 49
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Fix venv name mismatch and strengthen cross‑platform install notes

  • Line 43 says the venv folder will be named “plugins” but the command creates “emotibit_plugins”. This will confuse users.
  • Prefer “python -m pip …” to ensure the venv’s pip is used.
  • Add a macOS/Linux variant for the venv creation command.

Apply:

- - Run the following command `python -m venv emotibit_plugins`
- -  - This creates a new folder called `plugins` containing the virtual Python environment
+ - Run the following command `python -m venv emotibit_plugins`
+   - On macOS/Linux you may need: `python3 -m venv emotibit_plugins`
+ -  This creates a new folder called `emotibit_plugins` containing the virtual Python environment
@@
-- Run the following command to install pybind11. `pip install pybind11==2.13.5`
+- Run the following command to install pybind11. `python -m pip install pybind11==2.13.5`

Follow-up: please standardize this venv name (“emotibit_plugins”) across CMake and the rest of the repo to avoid breakage when locating pybind11.

I can scan the repo and draft diffs to align the venv name everywhere if helpful.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### Setting up Python Virtual Environment
- Open a new command prompt window
- `cd` to the EmotiBit_Plugins repository
- Run the following command `python -m venv .\py_envs\<env-name>`
- replace `<env-name>` with the environment name
- Activate the new environment by running the command `.\py_envs\<env-name>\Scripts\activate.bat`
- You will see the prompt in the terminal change. It now shows the python environment in parenthesis.
- Run the following command to install bypind11. `pip install pybind11==2.13.5`
- `cd` to `EmotiBit_Plugins/py_envs`
- Run the following command `python -m venv emotibit_plugins`
- This creates a new folder called `plugins` containing the virtual Python environment
- Activate the new environment:
- Windows (cmd): `.\emotibit_plugins\Scripts\activate.bat`
- Windows (PowerShell): `.\emotibit_plugins\Scripts\Activate.ps1`
- macOS/Linux (bash/zsh): `source emotibit_plugins/bin/activate`
- Run the following command to install pybind11. `pip install pybind11==2.13.5`
### Setting up Python Virtual Environment
- Open a new command prompt window
- `cd` to `EmotiBit_Plugins/py_envs`
- Run the following command `python -m venv emotibit_plugins`
- On macOS/Linux you may need: `python3 -m venv emotibit_plugins`
- This creates a new folder called `emotibit_plugins` containing the virtual Python environment
- Activate the new environment:
- Windows (cmd): `.\emotibit_plugins\Scripts\activate.bat`
- Windows (PowerShell): `.\emotibit_plugins\Scripts\Activate.ps1`
- macOS/Linux (bash/zsh): `source emotibit_plugins/bin/activate`
- Run the following command to install pybind11. `python -m pip install pybind11==2.13.5`
🧰 Tools
🪛 LanguageTool

[grammar] ~39-~39: There might be a mistake here.
Context: ....pyd` file ## Requirements ### Setting up Python Virtual Environment - Open a new...

(QB_NEW_EN)

[grammar] ~39-~39: There might be a mistake here.
Context: ...## Setting up Python Virtual Environment - Open a new command prompt window - cd ...

(QB_NEW_EN)

[grammar] ~44-~44: There might be a mistake here.
Context: ...ironment - Activate the new environment: - Windows (cmd): `.\emotibit_plugins\Scrip...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
In README_py.md around lines 39 to 49, the venv creation notes are inconsistent
and not cross-platform: the text incorrectly claims the venv folder will be
named "plugins" while the command creates "emotibit_plugins"; the pip install
should use the venv's pip via "python -m pip"; and there is no macOS/Linux
variant for the venv creation command. Update the paragraph to consistently use
"emotibit_plugins" as the venv name, change the install command to use "python
-m pip install pybind11==2.13.5", add a macOS/Linux venv creation example (e.g.,
python3 -m venv emotibit_plugins), and add a short note to standardize this venv
name across CMake and the repo (or link to a follow-up task to align
references).

#### Using anaconda
- Download [Anaconda](https://www.anaconda.com/download/) as shown here.
- ***Do not close out of the Anaconda Powershell Prompt until completely done with an example***
- Open an Anaconda Powershell Prompt through the search feature on your machine and run the command below
```bash
cd C:\path\to\your\EmotiBit_Plugins\pyExample_alg01
conda config --set channel_priority flexible
conda env update --name EmotiBit-pyenv-modern --file .\EmotiBit-pyenv-modern.yml
conda activate EmotiBit-pyenv-modern
```
## Adapting this to your C++ code
- Add pybind11 bindings to a file `bindings_<srcName>.cpp`. Refer the [pybind11 documentation](https://pybind11.readthedocs.io/en/stable/basics.html) for more information.
- Create a new CMakeLists.txt file that
- Builds a library from your source files
- Builds the Python module (`.pyd` or `.so`) file from that library
- Run the `cmake` commands from the examples below to create a build the project.

Refer to the examples below to see what `bindings.cpp` and `CMakeLists.txt` should look like.

## Examples
### Rounder
#### Steps to Run Example

- cd to `pyExample_alg01`
- run the following commands
```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
cmake -B build
cmake --build build --config Release
```
- The following command runs the python example. The expected result is for the script to round the input.
```bash
python example.py -i 3.4
```

### EmotiBitPacket
#### Building the example
- To make this example work, you will need to copy/clone the `EmotiBit_XPlat_Utils` repository into the `src` folder.
- cd to the `src` folder.
- clone using `git clone https://github.com/EmotiBit/EmotiBit_XPlat_Utils`. Checkout the following commit `393b611ee0d0c1f1cec70e243fd5b643c2e25250`
- cd to `pyExample_emotibitPacket` and run the following commands
Comment on lines 72 to 76
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix directory name casing: “pyExample_EmotiBitPacket”

The current path uses a lowercase/typo’d name and will fail on case-sensitive filesystems.

Apply:

-- cd to `pyExample_emotibitPacket` and run the following commands
+- cd to `pyExample_EmotiBitPacket` and run the following commands
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### EmotiBitPacket
#### Building the example
- To make this example work, you will need to copy/clone the `EmotiBit_XPlat_Utils` repository into the `src` folder.
- cd to the `src` folder.
- clone using `git clone https://github.com/EmotiBit/EmotiBit_XPlat_Utils`. Checkout the following commit `393b611ee0d0c1f1cec70e243fd5b643c2e25250`
- cd to `pyExample_emotibitPacket` and run the following commands
### EmotiBitPacket
- To make this example work, you will need to copy/clone the `EmotiBit_XPlat_Utils` repository into the `src` folder.
- cd to the `src` folder.
- clone using `git clone https://github.com/EmotiBit/EmotiBit_XPlat_Utils`. Checkout the following commit `393b611ee0d0c1f1cec70e243fd5b643c2e25250`
- cd to `pyExample_EmotiBitPacket` and run the following commands
🤖 Prompt for AI Agents 
In README_py.md around lines 72 to 76, the example uses the incorrect lowercased
directory name "pyExample_emotibitPacket" which will break on case-sensitive
filesystems; update the README to use the correct casing
"pyExample_EmotiBitPacket" wherever that path is referenced (e.g., "cd to
`pyExample_EmotiBitPacket`") and scan the file for any other occurrences of the
incorrect casing and fix them to match the actual directory name.

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
cmake -B build
cmake --build build --config Release
```
- Run the Python example script `pyExample_emotibitPacket\example.py`

## Adapting this to your C++ code
- Add pybind11 bindings to a file `bindings_<srcName>.cpp`. Refer the [pybind11 documentation](https://pybind11.readthedocs.io/en/stable/basics.html) for more information.
- Create a new CMakeLists.txt file that
- creates a lib from your source files
- creates the pyd file from the src library
- Run the cmake commands above to create a build the project.

### Brainflow SpO2 Algorithm
- Clone the EmotiBit Brainflow SpO2 Algorithm [repo](https://github.com/EmotiBit/EmotiBit_Brainflow_SpO2_Algorithm) into any directory
- `cd` into the `EmotiBit Brainflow SpO2 Algorithm` folder and checkout the following commit: `7bc9dc3b02f361c37e9e917477abefe9f5468a68`
- Follow the instructions under `pybind/README.md` to finish building the algorithm