smg-interface: Optical-Flow-Based Sonomyography (SMG) Signal Extraction

Code for interfacing with an ultrasound system and generating continuous 1-degree-of-freedom (1-DOF) sonomyographic (SMG) control signals from a B-mode ultrasound time series.

This code is a refined version of our 1-DOF SMG algorithm published in "Sensor-Placement-Agnostic Sonomyography: Toward Continuous High-Dimensional Control by Users with Tetraplegia" submitted to the 2026 IEEE International Conference on Biomedical Robotics and Biomechatronics (BioRob). For the exact code used in this publication, visit our 2026-biorob-smg repository.

This repo is set up to work with the Telemed ArtUs EXT-2H, but telemed_class.py could be replaced with a class for interfacing with a different ultrasound device and run_telemed.py modified accordingly to use a different hardware system.

License

The data, documentation and associated code is provided as-is; however, we invite anyone who wishes to adapt and use it under a Creative Commons Attribution 4.0 International License. Please cite the following publication if you use this code or data in your research:

@inproceedings{sueltz2026biorob,
  title={Sensor-Placement-Agnostic Sonomyography: Toward Continuous High-Dimensional Control by Users with Tetraplegia},
  booktitle={IEEE RAS/EMBS International Conference on Biomedical Robotics and Biomechatronics (BioRob)},
  author={Sueltz, Gavin and Athithan*, Vikram and Ferran*, Emma and Herrera*, Maria and Wynn*, Carson J. and Laura A. Hallock},
  year={2026. *Equal contribution},
  organization={IEEE}
}

Setup

Step 1: Cloning the Repo and Setting up Virtual Environment

First, navigate to whatever directory on your local machine you want to save this project in, and clone this repo with the following command:

git clone git@github.com:hrelab/smg-interface.git

(Note that this workflow assumes you have an SSH key setup; instructions for that can be found here. Use a different cloning workflow if preferred.)

Download and install Python here if not yet installed. We recommend running the code in a Python virtual environment inside the repository folder, which can be accomplished via

cd telemed-interface
python -m venv <env_name> 

Activate the virtual environment via (for gitbash/Windows systems):

source <env_name>\Scripts\activate

You can verify that you've entered your virtual environment by running which python, which should point inside your new <env_name> folder, and/or observing that (<env_name>) prepends your command line.

Download all the required dependencies:

pip install -r requirements.txt

All code below should be run inside the virtual environment; when finished, it can be closed via the bash command deactivate.

Step 2: Downloading Required Telemed Files

This code requires the relevant Telemed ArtUS EXT-2H library files. These files can be found on the USB that ships with the device at the following file path: ArtUs EXT-2H\3_Telemed_Software for Research\Research_3_TELEMED Real-time Imaging for Research, ver. 1.0.2\Real-time_imaging_for_the_research and the relevant folder is called usgfw2wrapper_C++_sources. Copy this folder into the telemed_dll/ directory of this repository.

By default, the .dll found here: usgfw2wrapper_C++_sources\usgfw2wrapper\x64\Debug\usgfw2wrapper.dll does not support the use of both probes available on the Telemed ArtUS EXT-2H, so the --twoprobe functionality of this system will not work. It is possible to fix this, but requires reaching out to a Telemed representative for assistance.

Running the Code

This code has a few runtime commands; to view them all, run

python run_telemed.py --help

To actually run the system, run

python run_telemed.py <commands_here>

You can run the system with any combination of commands you need. For example, if you want to run the 1-DOF algorithm on just one probe and see the ultrasound image with optical flow points, then run

python run_telemed.py --onedof --visualize

If you run the system without specifying --onedof, then it will just run the imaging loop on the Telemed without doing any processing.