Install the standalone App — or run from source at whichever layer of the stack you need.
Open-LIFU is Openwater's programmable Low Intensity Focused Ultrasound platform — a console, transducer, and a software stack that goes from a one-click standalone App down to a Python SDK that talks directly to the hardware. This page is the single source of truth for getting started. Repositories, READMEs, and the device user manual all link here.
Either install the top of the stack (the App) or run from source at the layer that matches what you're doing. You don't need to install multiple layers — pick one entry point.
Two entry points. Don't install both — pick the one that matches what you're doing today.
Download the installer, run. Bundles its own Slicer and all OpenLIFU modules. No framework setup. No Python.
Build/run from any layer of the stack. Three sub-paths depending on whether you want a UI, a library, or raw hardware I/O.
openlifu — scripting & pipelinesopenlifu-sdk — firmware & hardware commsThree steps. The App bundles its own Slicer — do not install 3D Slicer separately for this path.
Grab the system-specific installer (.exe on Windows, .tar.gz on Linux). Approve the security warning if prompted.
Start the installer and follow the prompts.
Launch the app. First run finishes installing dependencies before opening to the home page. That's it — you're in the guided workflow. Use PrePlanning → pick a target, then SonicationPlanner → simulate.
Pick the layer that matches what you're building. Each sub-path is independent — you don't stack them.
Use your own 3D Slicer install. SlicerOpenLIFU exposes all ten OpenLIFU modules (Home, Database, Login, Data, PrePlanning, TransducerLocalization, SonicationPlanner, SonicationControl, ProtocolConfig, Lib). Every parameter is reachable; no curated wrapper.
Follow the standard Slicer extension build process for the SlicerOpenLIFU repository.
openlifu-sample-database.example_admin.openlifu library)The core Python library. Algorithms, planning, simulation, protocols, database structures. No GUI. Used as a standalone library or as the engine that drives SlicerOpenLIFU.
Install the published package from PyPI:
pip install openlifuOr for development (Python 3.10–3.12 on Windows or Linux):
git clone https://github.com/<your-username>/openlifu-python.git
cd openlifu-python
git remote add upstream https://github.com/OpenwaterHealth/openlifu-python.git
python -m venv env
# Linux:
source env/bin/activate
# Windows:
.\env\Scripts\activate
pip install -e . # basic
# or: pip install -e '.[dev]' # with dev tools
# Smoke test
python -c "import openlifu; print(openlifu.__version__)"Then pull the sample database via Git LFS and browse examples/:
git lfs install
git clone https://github.com/OpenwaterHealth/openlifu-sample-databaseThe lowest layer: direct communication with the TX module and HV controller. Use this if you're working on firmware, debugging hardware, or building tooling that needs raw device I/O without the planning layer on top.
Published to PyPI:
pip install openlifu-sdkOr for development:
git clone https://github.com/OpenwaterHealth/openlifu-sdk.git
cd openlifu-sdk
pip install -e ".[dev]"Sanity check the hardware connection:
from openlifu_sdk import LIFUInterface
interface = LIFUInterface()
tx_connected, hv_connected = interface.is_device_connected()
print("TX:", tx_connected, " HV:", hv_connected)For end-to-end hardware bring-up, verification, and diagnostics, use the OpenLIFU Test App — a QML-based engineering UI with dedicated pages for console/transmitter bring-up, sonication, automated verification scripts, firmware updates, and PDF reporting.
Easiest: grab the prebuilt Windows binary from the openlifu-test-app releases page and run TestApp.exe (or TestApp_console.exe to see console output).
From source (Python 3.10+, requires both openlifu-sdk and openlifu installed):
git clone https://github.com/OpenwaterHealth/openlifu-test-app.git
cd openlifu-test-app
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e . # or .[dev], .[test], .[dev,test]openlifu can be developed together. Inside Slicer's Python console, use slicer.util.pip_install / slicer.util.pip_uninstall to side-load your local openlifu build, and add your local SlicerOpenLIFU clone to Slicer's Application Settings → Modules so it loads from your working tree. This is the recommended workflow for active extension development — you're running customized versions of both the UI and the engine simultaneously. You own compatibility when you do this; SlicerOpenLIFU normally pins a tested openlifu version on purpose.
The fork → branch → commit → PR → CLA → merge loop is the same regardless of which layer you started at.
Pick one of these and ship it:
examples/.git checkout -b fix/short-description
# make changes
git add .
git commit -m "Docs: fix typo in transducer README"
git push origin fix/short-description
# then open a PR on GitHubSlicerOpenLIFU or OpenLIFU-Appopenlifu-pythonopenlifu-sdkOnly needed if you're running transducer-tracking workflows with the Android scanner. Applies to all paths above.
Required if you're using openlifu.nav.photoscan (Python) or running transducer tracking through the App.
Meshroom.exe to your user PATH (Start menu → "Edit environment variables for your account" → User variables → Path → Edit → New).export PATH="<path-to-meshroom>/Meshroom-2025.1.0-Linux:$PATH", or persist by appending to ~/.bashrc).Meshroom.exe → set "High-performance NVIDIA processor".Option 1: Download Google's platform-tools, extract, and add the folder containing adb.exe to your PATH. Verify with adb --version.
Option 2 (PowerShell):
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install android-platform-tools.apk.The fastest path to unstuck.
Browse open issues, pick one, and we'll review within 48 hours.