Ultrasound Image Formation Plugin
=================================

The **Ultrasound Image Formation Plugin (USImageFormation)** provides algorithms, stream interfaces, and data structures for the acquisition, recording, and processing of ultrasound data in low-level use cases.

Introduction
------------

The Ultrasound Image Formation Plugin is an extension to the ImFusion SDK designed to facilitate working with low-level ultrasound systems. It provides tools and functionalities for:

- **Acquisition Control**: Programming acquisition sequences of ultrasound systems with low-level programming capabilities and low-level data access.
- **Acquisition**: Acquisition of per-element raw channel data.
- **Raw Data Access**: Access and process raw channel data for advanced signal processing and research purposes.
- **Real-Time Processing**: Perform live processing of ultrasound data up to final B-Mode images for immediate feedback and visualization.
- **Offline Processing**: Load and process recorded data (from any stage) for post-acquisition studies.
- **Access to intermediate data**: Perform bespoke processing within the normal pipeline, or to create additional outputs.

Usage
-----

The functionality of the USImageFormation Plugin is accessible in the ImFusion Suite, the C++ SDK, and the Python API.

ImFusion Suite
~~~~~~~~~~~~~~

The USImageFormation Plugin is integrated into the ImFusion Suite, allowing users to access its features through the graphical user interface. See the User documentation.

Python
~~~~~~

The USImageFormation Plugin can be used in Python together with the ImFusion Python API. It can be used to process recorded ultrasound data, or to configure and control an input stream, record sequences from it, and then process the data. Live visualization of the data is not currently supported from Python.

See the Python example ``USImgFormationPlugin/python-examples/processing_recorded_data.ipynb`` for a complete example of how to use the USImageFormation Plugin in Python to process recorded data.

.. code-block:: python

    import imfusion as imf
    import imfusion.ultrasound_image_formation as usi
    # Load recorded RF ultrasound channel data from an imfusion file
    [rf_channel_data] = imf.load("simus_logo.imf")

    # Process the RF channel data using the USImageFormation Plugin
    filtered = usi.filter_channel_data(rf_channel_data)
    iqdemod = usi.iq_demodulation(filtered)
    beamformed = usi.beamforming(iqdemod)
    envelope = usi.envelope_detection(beamformed, reference_amplitude=100000.0, dynamic_range=45.0)
    scanconverted = imf.execute_algorithm('USExp.ScanConversion2', [envelope])[0]

C++ SDK
~~~~~~~

The USImageFormation Plugin is also available in the ImFusion C++ SDK, allowing developers to integrate ultrasound image formation capabilities into their applications.
See the C++ SDK documentation for more details on how to use the plugin in C++ applications.

API Reference
=============

.. automodule:: imfusion.ultrasound_image_formation
    :members:
    :undoc-members:
    :show-inheritance:
    :imported-members:
    :noindex:
    :special-members: __iter__, __next__, __getitem__, __setitem__