Metadata-Version: 2.4
Name: ultraspy
Version: 1.2.5
Summary: Ultrasound toolbox for GPU
Home-page: https://gitlab.com/pecarlat/ultraspy
Author: Pierre Ecarlat, Fabien Millioz
Author-email: pierre.ecarlat@gmail.com, fabien.millioz@univ-lyon1.fr
Project-URL: Documentation, https://ultraspy.readthedocs.io/en/latest/
Project-URL: Bug Tracker, https://gitlab.com/pecarlat/ultraspy/-/issues/
Keywords: ultrasound,python,beamforming,doppler
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: scipy>=1.10.1
Requires-Dist: matplotlib>=3.6.3
Requires-Dist: easydict>=1.10
Requires-Dist: numba>=0.56.4
Requires-Dist: h5py>=3.8.0
Requires-Dist: py7zr>=0.20.5
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

What is ultraspy?
-----------------
Ultraspy is a package designed to efficiently manipulate ultrasound data using
GPU. The most common beamforming or Doppler methods are implemented (such as
DAS, RF to I/Qs, Color/Power Doppler, ...), along with some state-of-the-art
methods (Capon beamforming, Vector Doppler, alias-free Doppler velocity, ...).
A set of metrics (PSL, FWHM, SNR) is also provided so anyone can validate the
quality of their ultrasound data and beamforming operations.

The package is designed to work with both RF and I/Q signals, in 2D or 3D, and
with any type of probe (linear, convex, or matrix). The core code can run both
on CPU and GPU, making it ideal for any real-time application. All beamforming
parameters (f-number, compounding, apodization…) can be freely customized at
any time for research purposes.

The package has been thought to be as flexible as possible, so that anyone
could eventually clone it and add its own research methods and test it in real
time. A set of tutorials is provided to facilitate user learning and adoption,
along with some instruction on how to contribute to the lib if you feel like
your research method should be added to help the community.


Features
========
- General beamforming methods, flexible to Radio-Frequency or In-phase
  Quadrature data, working on CPU and GPU. Mainly DAS and FDMAS for the
  plane-wave imaging, but also TFM for Beam Focusing imaging

- Advanced beamforming methods (p-DAS or Capon), with a dedicated tutorial to
  understand how these are implemented and how to implement your own methods

- Basic Doppler methods (Color and Power maps), and their dedicated utilities
  functions (matched filtering, RF to I/Qs conversion)

- Advanced Doppler methods, such as a proposition for alias-free alias-free
  Doppler velocities (using dual-wavelength method). This still lacks of
  methods, and should include Vector Doppler or so in future releases

- Basic metrics for evaluation of the data quality (SNR), or of our beamforming
  algorithms (FWHM, PSL, CNR)


Documentation
=============
Full documentation can be found in the 'docs' folder, and is also available at
https://ultraspy.readthedocs.io/en/latest. You will find there all the detailed
information about how to install ultraspy and how to use it.


Installation
============
Installation can be easily done using pypi:

.. code-block:: console

    $ pip install ultraspy

Also, if you want to run it on GPU, you need to install the proper version of
`cupy` based on your CUDA version:

.. code-block:: console

    $ pip install cupy-cudaXXx


Development (virtual environment)
=================================
For local development and tests, use a virtual environment so dependencies are
isolated (recommended on Linux distributions that mark the system Python as
externally managed).

.. code-block:: console

    $ cd ultraspy
    $ python3 -m venv .venv
    $ source .venv/bin/activate
    $ pip install -U pip
    $ pip install -r requirements_cpu.txt
    $ pip install -e .

For GPU tests, install CuPy after activating the venv (pick the wheel that
matches your CUDA version; the project’s ``requirements_gpu.txt`` uses the
CUDA 12.x line):

.. code-block:: console

    $ pip install -r requirements_gpu.txt

Run tests with ``pytest`` (or ``tox``, which creates its own envs), for example:

.. code-block:: console

    $ PYTHONPATH=src pytest tests/test_cpu
    $ PYTHONPATH=src pytest tests/test_gpu

The repository includes editor settings so Cursor / VS Code prefer
``.venv/bin/python`` once the venv exists.


GitLab CI runner setup (Ubuntu 24.04)
======================================
This repository now includes a ``.gitlab-ci.yml`` with:

- ``cpu_tests_py312`` / ``cpu_tests_py311`` / ``cpu_tests_py310``: CPU tests
  on the matching ``python:X.Y`` image
- ``docs``: Sphinx docs build with warnings as errors
- ``gpu_tests_py312``: optional GPU suite, enabled only when
  ``RUN_GPU_TESTS=1``

To register a project runner on Ubuntu 24.04:

.. code-block:: console

    $ curl -L --output gitlab-runner.deb https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb
    $ sudo dpkg -i gitlab-runner.deb
    $ sudo gitlab-runner register

Use these registration values:

- URL: your GitLab instance URL (for gitlab.com: ``https://gitlab.com``)
- Token: project/group runner token from GitLab UI
- Executor: ``shell`` (recommended for CUDA/GPU host access)
- Tags: ``gpu`` for GPU runner, or no tag for generic CPU runner

GPU job notes:

- Ensure ``python3.12`` is installed on the runner host.
- Ensure NVIDIA driver/CUDA are available to the runner user.
- In project CI/CD variables, set ``RUN_GPU_TESTS=1`` to enable GPU jobs.
- CuPy wheel line: set ``CUPY_VERSION`` to ``12`` (default) or ``13`` to pick
  ``cupy-cuda12x[ctk]`` vs ``cupy-cuda13x[ctk]``, or set ``CUPY_PIP_SPEC`` to
  override the full pip requirement (passed through to tox).


Contribute
==========

- Issue Tracker: https://gitlab.com/pecarlat/ultraspy/-/issues/

- Source Code: https://gitlab.com/pecarlat/ultraspy

- Documentation: https://ultraspy.readthedocs.io/en/latest


License
=======
The project is under the MIT license.
