Python API
Preprocess
- 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.
cutoffselects 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
- 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
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.
M0sets the low-frequency region: spatial frequencies 0..M0 and -M0..-1 of the aperture (and/or wave) FFT. After go(), the factor is inself.GCF.
- class ustb.postprocess.PhaseCoherenceFactor
Port of MATLAB postprocess.phase_coherence_factor.
After go(),
self.FCC(complex factor, used for the output) andself.FCA(absolute factor) hold the two factors.
- class ustb.postprocess.CaponMinimumVariance
Port of MATLAB postprocess.capon_minimum_variance.
Set
scanandchannel_databeforeK_in_lambda(it is converted to a number of depth samples, as in MATLAB).L_elementsis 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_freqsoptionally 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_lambdagives 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 inself.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.
cutoffas inustb.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_datagives 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_frequencyholds 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
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
urltofileif it is not already present.Mirrors MATLAB tools.download(file, url). If
local_pathis given,fileis treated as just the filename: it is joined withurlto build the source URL and withlocal_pathto 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.
- 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
Nframes.- 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).
thetasandrangesmust 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.
frameselects 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.