Overview

The imfusion.ultrasound package exposes Python bindings for offline (non-streaming) ultrasound processing in ImFusion: freehand sweeps, frame geometry and metadata, compounding and reslicing, scan conversion, clip processing, and related registration or calibration helpers.

Typical use is to start from an UltrasoundSweep (or data convertible to one) and call the high-level free functions or algorithm classes bound on the module. Install the ultrasound module with pip install 'imfusion-sdk[ultrasound]' (see Installation).

For detailed documentation of specific classes and functions, use Python’s built-in help() function or access the docstrings directly.

Examples

Short workflows below complement the full API listing in Reference.

Loading sweeps

imfusion.load() returns a list of all Data subclasses which are stored in the file (see its docstring). Native ultrasound sweep blocks in .imf files deserialize as UltrasoundSweep. Many acquisitions are stored instead as TrackedSharedImageSet or SharedImageSet; those are not automatically an UltrasoundSweep. In that case call convert_to_sweep() on the image set (and pass tracking_sequence= explicitly when tracking is not already attached to the set).

import imfusion
import imfusion.ultrasound as us

first = imfusion.load("/path/to/sweep.imf")[0]
sweep = first if isinstance(first, us.UltrasoundSweep) else us.convert_to_sweep(first)

# view and scroll through the sweep using the ImFusionVisualizer
imfusion.show([sweep])

Exploring an UltrasoundSweep

UltrasoundSweep subclasses TrackedSharedImageSet, so you can use inherited methods for frames, poses, and tracking (for example len(sweep), sweep.focus, sweep.mem(i), sweep.tracking()). Ultrasound-specific helpers also expose frame_geometry(), bounding-box queries and other sweep properties.

import imfusion
import imfusion.ultrasound as us

sweep = imfusion.load("/path/to/sweep.imf")[0]

n = len(sweep)
geom = sweep.frame_geometry()
gbox = sweep.global_bounding_box(use_selection=False, use_frame_geometry=True)

print(sweep)
print(geom)
print("Depth:", geom.depth, "Coordinate system:", geom.coordinate_system)
print("Global bbox center:", gbox.center, "Extent:", gbox.extent)

ts = sweep.tracking()
print("tracking samples:", ts.size if ts is not None else None)

Compounding

An UltrasoundSweep can be compounded into a regularly sampled 3D volume for tasks that cannot be performed with sweeps natively, such as the application of 3D machine learning models (e.g. segmentation)”.

import imfusion
import imfusion.ultrasound as us

first = imfusion.load("/path/to/sweep.imf")[0]
sweep = first if isinstance(first, us.UltrasoundSweep) else us.convert_to_sweep(first)

volume = us.compound_sweep(
    sweep,
    mode=us.CompoundingMode.GPU,
    bounding_box_mode=us.CompoundingBoundingBoxMode.HEURISTIC_ALIGNMENT,
)

Registration

register_sweep_to_volume() aligns a sweep to a tomographic reference (for example CT or MRI). The sweep must carry a valid tracking sequence (see sweep.tracking() above). LC2 similarity is the standard intensity-based option; DISA is available only when the ML stack is present—see Similarity and the reference.

import imfusion
import imfusion.ultrasound as us

sweep = imfusion.load("/path/to/sweep.imf")[0]
ct = imfusion.load("/path/to/ct.imf")[0]

us.register_sweep_to_volume(
    sweep,
    ct,
    similarity=us.Similarity.LC2,
    move_sweep=True,
    spacing_mm=1.0,
)

For finer control (modes, initialization, slice-based registration), use UltrasoundRegistrationAlgorithm and its methods such as prepare_data() and compute().

Note: This module requires the ImFusion US plugin to be properly installed and licensed.