Python API

Preprocess

Input: channel data → Output: channel data
class ustb.preprocess.FastDemodulation

Fast IQ demodulation for channel data.

Mirrors MATLAB preprocess.fast_demodulation: mixes to baseband, low-pass filters, and optionally decimates.

go()

Execute demodulation. Returns a modified channel_data copy.

class ustb.preprocess.Demodulation

IQ demodulation for channel data.

Mirrors MATLAB preprocess.demodulation: band-pass filters, down-mixes to baseband, low-pass filters, and decimates.

go()

Execute demodulation. Returns a modified channel_data copy.

class ustb.preprocess.SVDFilter

Spatiotemporal SVD clutter filter applied across the frames of channel data.

cutoff selects the temporal singular components to keep (1-based, as in MATLAB): a scalar c keeps c..N_frames (e.g. 2 removes the strongest, tissue, component), [a, b] keeps a..b, and any other vector keeps exactly those components. A cutoff starting at 1 leaves the data unfiltered, as in MATLAB. The output has the input’s probe, sequence etc. with filtered data.

Reference: C. Demene et al., IEEE TMI 34(11):2271-2285, 2015.

Midprocess

Input: channel data → Output: beamformed data
class ustb.midprocess.DAS

Generalized DAS beamformer matching MATLAB midprocess.das.

Properties mirror the MATLAB class: channel_data, scan, dimension, receive_apodization, transmit_apodization.

Example

mid = DAS() mid.channel_data = channel_data mid.scan = scan mid.dimension = Dimension.both b_data = mid.go()

go()

Execute the DAS beamformer. Returns BeamformedData.

Postprocess

Input: beamformed data → Output: beamformed data

Compounding

class ustb.postprocess.CoherentCompounding

Coherent compounding postprocess matching MATLAB postprocess.coherent_compounding.

class ustb.postprocess.IncoherentCompounding

Incoherent compounding postprocess matching MATLAB postprocess.incoherent_compounding.

Adaptive beamforming

class ustb.postprocess.CoherenceFactor

Coherence factor postprocess matching MATLAB postprocess.coherence_factor.

Properties mirror the MATLAB class: dimension, active_element_criterium, receive_apodization, transmit_apodization. After go(), the raw coherence-factor weight map is available as self.CF (a BeamformedData with the same scan).

class ustb.postprocess.GeneralizedCoherenceFactor

Port of MATLAB postprocess.generalized_coherence_factor.

M0 sets the low-frequency region: spatial frequencies 0..M0 and -M0..-1 of the aperture (and/or wave) FFT. After go(), the factor is in self.GCF.

class ustb.postprocess.PhaseCoherenceFactor

Port of MATLAB postprocess.phase_coherence_factor.

After go(), self.FCC (complex factor, used for the output) and self.FCA (absolute factor) hold the two factors.

class ustb.postprocess.CaponMinimumVariance

Port of MATLAB postprocess.capon_minimum_variance.

Set scan and channel_data before K_in_lambda (it is converted to a number of depth samples, as in MATLAB). L_elements is the subarray length for the full aperture; it is scaled to the number of active elements per pixel.

class ustb.postprocess.DelayMultiplyAndSum

Port of MATLAB postprocess.delay_multiply_and_sum.

Needs RF beamformed data (the real part is used), a linear scan with a fine enough depth sampling for the band around 2 * f0, and channel_data (for the sound speed). filter_freqs optionally gives the four band edges [Hz] of the band-pass filter; by default they are set from the estimated center frequency f0 as [1.5 f0, 1.75 f0, 2.5 f0, 2.75 f0].

class ustb.postprocess.ShortLagSpatialCoherence

Python counterpart of MATLAB postprocess.short_lag_spatial_coherence.

MATLAB computes the per-lag correlations in a compiled MEX (mex.slsc_mex) whose source is not in the repository; this implements the published definition. K_in_lambda gives the depth kernel, converted to an odd number of samples K as in MATLAB and used as a centered window of K samples (truncated at the image edges). Elements whose data are zero over the whole image line are left out, and lags count active elements, as in MATLAB. After go(), the per-lag values are in self.slsc_values ([depth, lateral, lag] per wave or channel processed last).

No apodization may be used (receive and transmit window none).

Flow

class ustb.postprocess.SVDFilter

Spatiotemporal SVD clutter filter applied across the frames of beamformed data.

cutoff as in ustb.preprocess.SVDFilter: 1-based temporal singular components to keep; a scalar c keeps c..N_frames.

Reference: C. Demene et al., IEEE TMI 34(11):2271-2285, 2015.

class ustb.postprocess.AutocorrelationDisplacementEstimation

Port of MATLAB postprocess.autocorrelation_displacement_estimation.

Input: beamformed IQ data with one channel and one wave and more frames than packet_size; channel_data gives the sound speed and the pulse center frequency. Output: displacement [m] for each packet, i.e. N_frames - packet_size + 1 frames, zero outside the gate-valid region.

class ustb.postprocess.ModifiedAutocorrelationDisplacementEstimation

Port of MATLAB postprocess.modified_autocorrelation_displacement_estimation.

Like AutocorrelationDisplacementEstimation, but the center frequency is estimated per pixel from the axial lag-one autocorrelation (Loupas et al.). After go(), estimated_center_frequency holds it as [depth, lateral, frame] (zero outside the gate-valid region and for the last packet_size - 1 frames, as in MATLAB).

Image processing

class ustb.postprocess.Median

2D median filter postprocess matching MATLAB postprocess.median.

Data and apodization

class ustb.beamformed_data.BeamformedData(scan=None, data=None)

Container for beamformed data with associated scan grid.

Properties mirror the MATLAB uff.beamformed_data class.

get_image(compression='log')

Reshape (and optionally compress) the beamformed data into an image.

Mirrors MATLAB uff.beamformed_data.get_image(compression). Assumes data has a single receive/transmit column (e.g. dimension.both, or after compounding) – shape (N_pixels, 1, N_waves_or_1, N_frames).

Parameters:

compression – one of “log” (dB, normalized to peak), “sqrt”, “abs”, “none”, “none-complex” (the last two are equivalent in Python – both return the raw data).

Returns:

Array of shape (N_rows, N_cols, N_waves_or_1, N_frames).

save_as_gif(filename, dynamic_range=60, fps=10, title='')

Save a multi-frame B-mode image sequence as an animated GIF.

Mirrors MATLAB uff.beamformed_data.save_as_gif(filename). Requires a single-channel image stack (e.g. dimension.both output).

class ustb.apodization.Apodization

Apodization weights for receive or transmit channels.

Mirrors MATLAB uff.apodization. For receive apodization, set probe and focus. For transmit apodization, set sequence and focus.

property data

Compute apodization matrix [N_pixels x N_elements_or_waves].

class ustb.enums.Dimension(*values)

Controls which axes are summed in the generalized beamformer.

both = 3
none = 0
receive = 1
transmit = 2
class ustb.enums.Window(*values)

Window functions for apodization.

boxcar = 1
hamming = 3
hanning = 2
none = 0
rectangular = 1
scanline = 8
sta = 7
triangle = 9
tukey25 = 4
tukey50 = 5
tukey75 = 6
class ustb.enums.Wavefront(*values)

Type of transmitted wave.

photoacoustic = 2
plane = 0
spherical = 1

Pipeline

class ustb.Pipeline

Chains processing steps, matching MATLAB pipeline.

Example

pipe = Pipeline() pipe.channel_data = channel_data pipe.scan = scan b_data = pipe.go([DAS(), CoherentCompounding()])

Tools

ustb.tools.download(file, url, local_path=None)

Download a dataset from url to file if it is not already present.

Mirrors MATLAB tools.download(file, url). If local_path is given, file is treated as just the filename: it is joined with url to build the source URL and with local_path to build the destination path, matching the legacy 3-argument MATLAB call signature.

Example

url = tools.zenodo_dataset_files_base() tools.download(“my_dataset.uff”, url, data_path)

ustb.tools.zenodo_dataset_files_base()

Base URL for USTB example datasets hosted on Zenodo.

Mirrors MATLAB tools.zenodo_dataset_files_base(). Returns the …/files path without a trailing slash.

Record: https://zenodo.org/records/20261898

ustb.tools.power_spectrum(data, fs, normalised=True, N=None)

Compute the averaged power spectrum of channel data.

Mirrors MATLAB tools.power_spectrum(data, fs, normalised, N). The spectrum is averaged over channels, waves, and the first N frames.

Parameters:
  • data – array with time as its first axis (1-D to 4-D).

  • fs – sampling frequency [Hz].

  • normalised – if True, normalize the spectrum to a peak of 1.

  • N – number of frames to average (default: min(100, N_frames)).

Returns:

frequency axis [Hz] and averaged power spectrum.

Return type:

(fx, pw)

ustb.tools.estimate_frequency(time, data)

Estimate the center frequency and -6 dB bandwidth of data.

Mirrors MATLAB tools.estimate_frequency(time, data): the averaged power spectrum is smoothed with a 26-point moving average, and the center frequency is the middle of the -6 dB band around the positive-frequency peak.

Returns:

center frequency and bandwidth [Hz].

Return type:

(fc, bw)

ustb.tools.scan_convert(input_image, thetas, ranges, size_x=512, size_z=512, method='linear')

Convert an image from polar (range, beam angle) to Cartesian coordinates.

Mirrors MATLAB tools.scan_convert(inputImage, thetas, ranges, sizeX, sizeZ, interpolationMethod). thetas and ranges must be strictly increasing.

Parameters:
  • input_image – 2-D array of shape (len(ranges), len(thetas)).

  • thetas – beam angles [rad], increasing.

  • ranges – sample ranges [m], increasing.

  • size_x – pixel size of the output image.

  • size_z – pixel size of the output image.

  • method – interpolation method passed to RegularGridInterpolator (“linear” or “nearest”).

Returns:

(scan_converted_image, xs, zs) where scan_converted_image has shape (size_z, size_x) and xs, zs are the output Cartesian axes [m]. Pixels outside the polar footprint are filled with -inf, matching MATLAB’s fill value.

ustb.tools.uniform_fov_weighting(mid)

Calculate weighting to give a uniform field of view.

Compensates for the varying number of transmit/receive combinations that contribute to each pixel (e.g. due to f-number-limited receive apertures or scanline transmit apodization) plus r^2 geometrical spreading. Mirrors MATLAB tools.uniform_fov_weighting(mid).

Parameters:

mid – a midprocess-like object with channel_data, scan, transmit_apodization, and receive_apodization attributes (e.g. ustb.midprocess.DAS).

Returns:

(apod, array_gain_compensation, geo_spreading_compensation), each shaped (N_rows, N_cols) matching the scan grid.

ustb.plotting.plot_beamformed_data(b_data, title='', dynamic_range=60, frame=0)

Plot beamformed data as a B-mode image.

For sector scans, displays scan-converted (fan-shaped) images using the physical (x, z) pixel coordinates, matching MATLAB’s pcolor-based display. For linear scans, displays a rectangular image.

frame selects which frame of multi-frame data to plot (0-based). The image is normalized to the peak of that frame.

ustb.plotting.plot_channel_data(channel_data, n_wave=None, plot_abs=True, title=None)

Plot raw or demodulated channel data as a (channel, time) image.

Mirrors MATLAB uff.channel_data.plot(figure, n_wave, plot_abs).

Parameters:
  • channel_data – object with .data [samples x channels x waves x frames], .sampling_frequency, .initial_time.

  • n_wave – which transmit wave to plot (default: the middle one).

  • plot_abs – if True, plot the envelope magnitude; if False, plot the real and imaginary parts side by side (for IQ data).

  • title – plot title.