From 966ce870b61b825e2f17a771932d70d45b596849 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Thu, 11 Jun 2026 10:54:11 -0400 Subject: [PATCH 1/5] Update install documentation for dependency extras (#338) --- .github/CONTRIBUTING.md | 8 +++++-- README.rst | 53 +++++++++++++++++++++++++++-------------- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 79830587..ab1999bc 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -39,16 +39,20 @@ You can set up a development environment by running: ```bash python3 -m venv .venv source ./.venv/bin/activate -pip install -v -e '.[dev]' +python -m pip install -v -e '.[test]' ``` +The `test` extra installs the optional feature dependencies exercised by the +test suite, plus pytest tooling. If you also need development-only DVC tooling, +install `.[test,dev]`. + If you have the [Python Launcher for Unix](https://github.com/brettcannon/python-launcher), you can instead do: ```bash py -m venv .venv -py -m install -v -e '.[dev]' +py -m pip install -v -e '.[test]' ``` # Post setup diff --git a/README.rst b/README.rst index 6d0b82fa..0689d6ad 100644 --- a/README.rst +++ b/README.rst @@ -20,40 +20,57 @@ Installation Requirements ~~~~~~~~~~~~ -Python 3.10-3.12 on Windows or Linux. +Python 3.10-3.12. -Create Virtual Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~ +We recommend installing ``openlifu`` in a virtual environment. -Windows: +Recommended install +~~~~~~~~~~~~~~~~~~~ + +For most users, install the application dependency set: .. code:: sh - C:\Users\\AppData\Local\Programs\Python\Python311\python.exe -m venv env - .\env\Scripts\activate + python -m pip install "openlifu[app]" + +This installs the core package plus dependencies for database and volume I/O, +simulation, mesh and photogrammetry workflows, cloud sync, and hardware +communication support via ``openlifu-sdk``. + +Minimal install +~~~~~~~~~~~~~~~ -Linux: +If you only need the lightweight core package: .. code:: sh - python3.11 -m venv env + python -m pip install openlifu -Install project (editable) -~~~~~~~~~~~~~~~~~~~~~~~~~~ +The minimal install does not include optional dependencies for simulation, +DICOM/NIfTI volume loading, mesh/VTK workflows, photogrammetry, cloud sync, or +hardware communication. -With this repo as the working directory: +Install selected features +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also install only the optional dependency groups you need: -Basic mode -^^^^^^^^^^ .. code:: sh - pip install -e . + python -m pip install "openlifu[sim,db]" + python -m pip install "openlifu[io]" + python -m pip install "openlifu[jupyter]" -Dev mode -^^^^^^^^ -.. code:: sh +Useful extras include: - pip install -e '.[dev]' +* ``app``: recommended application set +* ``sim``: k-Wave simulation support +* ``db``: DICOM/NIfTI and database volume support +* ``mesh``: mesh and VTK support +* ``photogrammetry``: photo-based mesh reconstruction dependencies +* ``io``: hardware communication dependencies, including ``openlifu-sdk`` +* ``cloud``: cloud sync dependencies +* ``jupyter``: notebook support Installing Meshroom ------------------- From 5b9faaf9cec2ca89d20bce20ef4fe1540f9d33fd Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Thu, 11 Jun 2026 10:56:49 -0400 Subject: [PATCH 2/5] Move contributing guide to repository root (#338) Keep the contributing guide in the repository root so it is easier to find in local checkouts and the GitHub file browser. GitHub recognizes root CONTRIBUTING.md for contributor prompts, so the move preserves the existing GitHub behavior. --- .github/CONTRIBUTING.md => CONTRIBUTING.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/CONTRIBUTING.md => CONTRIBUTING.md (100%) diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 100% rename from .github/CONTRIBUTING.md rename to CONTRIBUTING.md From 8772a963381d1aaf2ebce7fdf35cab58c520ad21 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Thu, 11 Jun 2026 11:14:14 -0400 Subject: [PATCH 3/5] Convert README to Markdown (#338) --- README.md | 157 ++++++++++++++++++++++++++++++++++++++++ README.rst | 177 --------------------------------------------- docs/includeme.md | 5 ++ docs/includeme.rst | 5 -- pyproject.toml | 2 +- 5 files changed, 163 insertions(+), 183 deletions(-) create mode 100644 README.md delete mode 100644 README.rst create mode 100644 docs/includeme.md delete mode 100644 docs/includeme.rst diff --git a/README.md b/README.md new file mode 100644 index 00000000..9bfe63f1 --- /dev/null +++ b/README.md @@ -0,0 +1,157 @@ +# openlifu + +[![Actions Status](https://github.com/OpenwaterHealth/OpenLIFU-python/workflows/CI/badge.svg)](https://github.com/OpenwaterHealth/OpenLIFU-python/actions) +[![Documentation Status](https://readthedocs.org/projects/openlifu/badge/?version=latest)](https://openlifu.readthedocs.io/en/latest/?badge=latest) + +[![PyPI version](https://img.shields.io/pypi/v/openlifu)](https://pypi.org/project/openlifu/) +[![PyPI platforms](https://img.shields.io/pypi/pyversions/openlifu)](https://pypi.org/project/openlifu/) + +[![GitHub Discussion](https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github)](https://github.com/OpenwaterHealth/OpenLIFU-python/discussions) + + + +`openlifu` is a toolbox for planning and controlling focused ultrasound +treatments. It generally replicates the functionality developed in the MATLAB +[open-TFUS toolbox](https://github.com/OpenwaterHealth/opw_neuromod_sw). + +## Installation + +### Requirements + +Python 3.10-3.12. + +We recommend installing `openlifu` in a virtual environment. + +### Recommended install + +For most users, install the application dependency set: + +```sh +python -m pip install "openlifu[app]" +``` + +This installs the core package plus dependencies for database and volume I/O, +simulation, mesh and photogrammetry workflows, cloud sync, and hardware +communication support via `openlifu-sdk`. + +### Minimal install + +If you only need the lightweight core package: + +```sh +python -m pip install openlifu +``` + +The minimal install does not include optional dependencies for simulation, +DICOM/NIfTI volume loading, mesh/VTK workflows, photogrammetry, cloud sync, or +hardware communication. + +### Install selected features + +You can also install only the optional dependency groups you need: + +```sh +python -m pip install "openlifu[sim,db]" +python -m pip install "openlifu[io]" +python -m pip install "openlifu[jupyter]" +``` + +Useful extras include: + +- `app`: recommended application set +- `sim`: k-Wave simulation support +- `db`: DICOM/NIfTI and database volume support +- `mesh`: mesh and VTK support +- `photogrammetry`: photo-based mesh reconstruction dependencies +- `io`: hardware communication dependencies, including `openlifu-sdk` +- `cloud`: cloud sync dependencies +- `jupyter`: notebook support + +## Installing Meshroom + +If you are using `openlifu.nav.photoscan` to reconstruct meshes from photo +collections, then you will need to set up **Meshroom 2025.1.0**. + +### Ubuntu + +#### Download and Extract + +1. Download Meshroom 2025.1.0 for Linux from + . + +2. Extract the downloaded archive: + + ```bash + tar -xvf Meshroom-2025.1.0-Linux.tar.gz + ``` + +#### Add Meshroom to PATH + +**Temporary (Current Session)** Run: + +```bash +export PATH="/Meshroom-2025.1.0-Linux:$PATH" +``` + +Replace `` with the actual path where Meshroom was extracted. + +**Permanent (Persistent Across Sessions)** For Bash users: + +```bash +echo 'export PATH="/Meshroom-2025.1.0-Linux:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +### Windows + +#### Download and Extract + +1. Download Meshroom 2025.1.0 for Windows from + . +2. Extract the downloaded archive to a directory of your choice. + +#### Add Meshroom to PATH + +1. Open **Edit environment variables for your account** from the Start menu. +2. In the **Environment Variables** window, under **User variables**, select + **Path** and click **Edit**. +3. Click **New**, and add the path to the folder containing `Meshroom.exe`. +4. Click **OK** to save the changes. + +#### Enable GPU Acceleration + +To ensure Meshroom uses your NVIDIA GPU: + +1. Open **NVIDIA Control Panel**. +2. In the left sidebar under **3D Settings**, click **Manage 3D settings**. +3. Go to the **Program Settings** tab. +4. Click **Add**, then browse to and select `Meshroom.exe` from the folder + where you extracted Meshroom. +5. Under **Select the preferred graphics processor for this program**, choose + **High-performance NVIDIA processor**. +6. Click **Apply**. + +## Getting Sample Data + +A sample database for testing and examples is maintained in the +[openlifu-sample-database](https://github.com/OpenwaterHealth/openlifu-sample-database) +repository. Its files are tracked with Git LFS, so first +[install Git LFS](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage). + +Then check out the tagged version of the sample database that is compatible with +this version of `openlifu`: + +```bash +git clone --depth 1 --branch openlifu-v0.20.0 https://github.com/OpenwaterHealth/openlifu-sample-database.git +cd openlifu-sample-database +git lfs pull +``` + +## Disclaimer + +CAUTION - Investigational device. Limited by Federal (or United States) law to +investigational use. The system described here has _not_ been evaluated by the +FDA and is not designed for the treatment or diagnosis of any disease. It is +provided AS-IS, with no warranties. User assumes all liability and +responsibility for identifying and mitigating risks associated with using this +software. diff --git a/README.rst b/README.rst deleted file mode 100644 index 0689d6ad..00000000 --- a/README.rst +++ /dev/null @@ -1,177 +0,0 @@ -openlifu -======== - -|Actions Status| |Documentation Status| - -|PyPI version| |PyPI platforms| - -|GitHub Discussion| - -.. SPHINX-START - -``openlifu`` is a toolbox for planning and controlling focused -ultrasound treatments. It generally replicates the functionality -developed in the MATLAB `open-TFUS -toolbox `__. - -Installation ------------- - -Requirements -~~~~~~~~~~~~ - -Python 3.10-3.12. - -We recommend installing ``openlifu`` in a virtual environment. - -Recommended install -~~~~~~~~~~~~~~~~~~~ - -For most users, install the application dependency set: - -.. code:: sh - - python -m pip install "openlifu[app]" - -This installs the core package plus dependencies for database and volume I/O, -simulation, mesh and photogrammetry workflows, cloud sync, and hardware -communication support via ``openlifu-sdk``. - -Minimal install -~~~~~~~~~~~~~~~ - -If you only need the lightweight core package: - -.. code:: sh - - python -m pip install openlifu - -The minimal install does not include optional dependencies for simulation, -DICOM/NIfTI volume loading, mesh/VTK workflows, photogrammetry, cloud sync, or -hardware communication. - -Install selected features -~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can also install only the optional dependency groups you need: - -.. code:: sh - - python -m pip install "openlifu[sim,db]" - python -m pip install "openlifu[io]" - python -m pip install "openlifu[jupyter]" - -Useful extras include: - -* ``app``: recommended application set -* ``sim``: k-Wave simulation support -* ``db``: DICOM/NIfTI and database volume support -* ``mesh``: mesh and VTK support -* ``photogrammetry``: photo-based mesh reconstruction dependencies -* ``io``: hardware communication dependencies, including ``openlifu-sdk`` -* ``cloud``: cloud sync dependencies -* ``jupyter``: notebook support - -Installing Meshroom -------------------- - -If you are using ``openlifu.nav.photoscan`` to reconstruct meshes from photo collections, then you will need to set up **Meshroom 2025.1.0**. - -Ubuntu -~~~~~~ - -Download and Extract -^^^^^^^^^^^^^^^^^^^^ -1. Download Meshroom 2025.1.0 for Linux from ``_. -2. Extract the downloaded archive: - - .. code:: bash - - tar -xvf Meshroom-2025.1.0-Linux.tar.gz - -Add Meshroom to PATH -^^^^^^^^^^^^^^^^^^^^ - -**Temporary (Current Session)** -Run: - -.. code:: bash - - export PATH="/Meshroom-2025.1.0-Linux:$PATH" - -Replace ```` with the actual path where Meshroom was extracted. - -**Permanent (Persistent Across Sessions)** -For Bash users: - -.. code:: bash - - echo 'export PATH="/Meshroom-2025.1.0-Linux:$PATH"' >> ~/.bashrc - source ~/.bashrc - -Windows -~~~~~~~ - -Download and Extract -^^^^^^^^^^^^^^^^^^^^ - -1. Download Meshroom 2025.1.0 for Windows from ``_. -2. Extract the downloaded archive to a directory of your choice. - -Add Meshroom to PATH -^^^^^^^^^^^^^^^^^^^^ - -1. Open **Edit environment variables for your account** from the Start menu. -2. In the **Environment Variables** window, under **User variables**, select **Path** and click **Edit**. -3. Click **New**, and add the path to the folder containing ``Meshroom.exe``. -4. Click **OK** to save the changes. - -Enable GPU Acceleration -^^^^^^^^^^^^^^^^^^^^^^^ - -To ensure Meshroom uses your NVIDIA GPU: - -1. Open **NVIDIA Control Panel**. -2. In the left sidebar under **3D Settings**, click **Manage 3D settings**. -3. Go to the **Program Settings** tab. -4. Click **Add**, then browse to and select ``Meshroom.exe`` from the folder where you extracted Meshroom. -5. Under **Select the preferred graphics processor for this program**, choose **High-performance NVIDIA processor**. -6. Click **Apply**. - -Getting Sample Data -------------------- - -A sample database for testing and examples is maintained in the -`openlifu-sample-database `_ -repository. Its files are tracked with Git LFS, so first `install Git LFS -`_. - -Then check out the tagged version of the sample database that is compatible -with this version of ``openlifu``: - -.. code:: bash - - git clone --depth 1 --branch openlifu-v0.20.0 https://github.com/OpenwaterHealth/openlifu-sample-database.git - cd openlifu-sample-database - git lfs pull - -Disclaimer ----------- - -CAUTION - Investigational device. Limited by Federal (or United States) -law to investigational use. The system described here has *not* been -evaluated by the FDA and is not designed for the treatment or diagnosis -of any disease. It is provided AS-IS, with no warranties. User assumes -all liability and responsibility for identifying and mitigating risks -associated with using this software. - -.. |Actions Status| image:: https://github.com/OpenwaterHealth/OpenLIFU-python/workflows/CI/badge.svg - :target: https://github.com/OpenwaterHealth/OpenLIFU-python/actions -.. |Documentation Status| image:: https://readthedocs.org/projects/openlifu/badge/?version=latest - :target: https://openlifu.readthedocs.io/en/latest/?badge=latest -.. |PyPI version| image:: https://img.shields.io/pypi/v/openlifu - :target: https://pypi.org/project/openlifu/ -.. |PyPI platforms| image:: https://img.shields.io/pypi/pyversions/openlifu - :target: https://pypi.org/project/openlifu/ -.. |GitHub Discussion| image:: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github - :target: https://github.com/OpenwaterHealth/OpenLIFU-python/discussions diff --git a/docs/includeme.md b/docs/includeme.md new file mode 100644 index 00000000..d3716988 --- /dev/null +++ b/docs/includeme.md @@ -0,0 +1,5 @@ +# Home + +```{include} ../README.md +:start-after: +``` diff --git a/docs/includeme.rst b/docs/includeme.rst deleted file mode 100644 index 67d00e34..00000000 --- a/docs/includeme.rst +++ /dev/null @@ -1,5 +0,0 @@ -Home -======== - -.. include:: ../README.rst - :start-after: .. SPHINX-START diff --git a/pyproject.toml b/pyproject.toml index 6e8265c8..5b75059b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,7 +9,7 @@ authors = [ { name = "Peter Hollender", email = "peterhollender@gmail.com" }, ] description = "Openwater Focused Ultrasound Toolkit" -readme = "README.rst" +readme = "README.md" license.file = "LICENSE" requires-python = ">=3.10" classifiers = [ From d77af14bde348ba8e77bb6d5ea48ebda41e858c5 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Thu, 11 Jun 2026 11:17:26 -0400 Subject: [PATCH 4/5] Add docs build runtime extras (#337) The Sphinx API docs recursively import openlifu modules. After the optional-dependency split, the docs environment needs the mesh, db, and cloud extras so those imports resolve during autosummary generation without pulling in simulation binaries or hardware SDK dependencies. --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 5b75059b..4652de68 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -85,6 +85,7 @@ dev = [ "dvc[gdrive]", ] docs = [ + "openlifu[mesh, db, cloud]", "sphinx>=7.0", "myst_parser>=0.13", "sphinx_copybutton", From 37ac92068158a44ca00631cbef2d11779d5502c1 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Thu, 11 Jun 2026 11:19:57 -0400 Subject: [PATCH 5/5] Rename CLAUDE.md to AGENTS.md to be more general (#337) --- .pre-commit-config.yaml | 4 ++-- CLAUDE.md => AGENTS.md | 0 2 files changed, 2 insertions(+), 2 deletions(-) rename CLAUDE.md => AGENTS.md (100%) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3293d715..bdd42be8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -39,7 +39,7 @@ repos: - id: prettier types_or: [yaml, markdown, html, css, scss, javascript, json] args: [--prose-wrap=always] - exclude: ^CLAUDE\.md$ + exclude: ^AGENTS\.md$ - repo: https://github.com/astral-sh/ruff-pre-commit rev: "v0.4.1" @@ -75,7 +75,7 @@ repos: name: Disallow improper capitalization language: pygrep entry: PyBind|Numpy|Cmake|CCache|Github|PyTest - exclude: (?x)(^\.pre-commit-config\.yaml$|^CLAUDE\.md$) + exclude: (?x)(^\.pre-commit-config\.yaml$|^AGENTS\.md$) - repo: https://github.com/python-jsonschema/check-jsonschema rev: "0.28.2" diff --git a/CLAUDE.md b/AGENTS.md similarity index 100% rename from CLAUDE.md rename to AGENTS.md