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 diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 91% rename from .github/CONTRIBUTING.md rename to CONTRIBUTING.md index 79830587..ab1999bc 100644 --- a/.github/CONTRIBUTING.md +++ b/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.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 6d0b82fa..00000000 --- a/README.rst +++ /dev/null @@ -1,160 +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 on Windows or Linux. - -Create Virtual Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Windows: - -.. code:: sh - - C:\Users\\AppData\Local\Programs\Python\Python311\python.exe -m venv env - .\env\Scripts\activate - -Linux: - -.. code:: sh - - python3.11 -m venv env - -Install project (editable) -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -With this repo as the working directory: - -Basic mode -^^^^^^^^^^ -.. code:: sh - - pip install -e . - -Dev mode -^^^^^^^^ -.. code:: sh - - pip install -e '.[dev]' - -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..4652de68 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 = [ @@ -85,6 +85,7 @@ dev = [ "dvc[gdrive]", ] docs = [ + "openlifu[mesh, db, cloud]", "sphinx>=7.0", "myst_parser>=0.13", "sphinx_copybutton",