MKMOVIE Make movie frames and animated GIF

MKMOVIE creates movie frames and animated GIF for wave propagation and backpropagation.

Contents



Syntax

F = MKMOVIE(DELAYS,PARAM) simulates ultrasound RF radio-frequency signals by using PFIELD and returns movie frames. The array elements are excited at different time delays, given by DELAYS (in s). The characteristics of the transmit and receive must be given in the structure PARAM (see below for details).

TRY IT! Enter mkmovie in the command window for an example.

By default, the ROI is of size 2L-by-2L, with L being the aperture length of the array [i.e. L = pitch $\times$ (Number_of_elements-1)], and its resolution is 50 pix/cm. These values can be modified through PARAM.movie:

e.g. PARAM.movie = [ROI_width ROI_height resolution]

IMPORTANT: Pay attention to the units! Width and height are in cm, resolution is in pix/cm.

The output variable F is an 8-bit 3-D array that contains the frames along the third dimension.

MKMOVIE uses PFIELD during transmit and receive. The parameters that must be included in the structure PARAM are similar as those in PFIELD.



The structure PARAM

PARAM is a structure that contains the following fields:

  1. PARAM.movie = [width height resolution duration fps]

IMPORTANT: Pay attention to the units !

ROI width and height are in cm, resolution is in pix/cm, duration is in s, fps is frame per second. The default is [2L 2L 50 15 10], with L (in cm) being the aperture length of the array [i.e. L = pitch*(Number_of_elements-1)]


  1. PARAM.fc: central frequency (in Hz, required)
  2. PARAM.pitch: pitch of the linear array (in m, required)
  3. PARAM.width: element width OR PARAM.kerf: kerf width (in m, required; width = pitch-kerf)
  4. PARAM.radius: radius of curvature (in m). The default is Inf (rectilinear array)
  5. PARAM.bandwidth: pulse-echo (2-way) 6dB fractional bandwidth (in %). The default is 75%.
  6. PARAM.baffle: property of the baffle: 'soft' (default), 'rigid' or a scalar > 0. See Note on BAFFLE property below for details.


  1. PARAM.c: longitudinal velocity (in m/s, default = 1540 m/s)
  2. PARAM.attenuation: attenuation coefficient (dB/cm/MHz, default: 0). A linear frequency-dependence is assumed. A typical value for soft tissues is ~0.5 dB/cm/MHz.


  1. PARAM.TXapodization: transmision apodization (default: no apodization)
  2. PARAM.TXnow: number of wavelengths of the TX pulse (default: 1). Use PARAM.TXnow = Inf for a mono-harmonic signal.
  3. PARAM.TXfreqsweep: frequency sweep for a linear chirp (default: [ ]). To be used to simulate a linear TX chirp. See Note on CHIRP signals below for details.



Other syntaxes

F = MKMOVIE(X,Z,RC,DELAYS,PARAM) also simulates backscattered echoes. The scatterers are characterized by their coordinates (X,|Z|) and reflection coefficients RC. X, Z and RC must be of same size.

[F,INFO] = MKMOVIE(...) returns image information in the structure INFO. INFO.Xgrid and INFO.Zgrid are the x- and z-coordinates of the image. INFO.TimeStep is the time step between two consecutive frames.

[F,INFO,PARAM] = MKMOVIE(...) updates the fields of the PARAM structure.

[...] = MKMOVIE without any input argument provides an interactive example designed to produce a movie using a 2.7 MHz phased-array transducer.

[...] = MKMOVIE(...,OPTIONS) uses the structure OPTIONS to adjust the simulations performed by PFIELD:



Advanced options

Only frequency components of the transmitted signal in the range [|0|, 2fc] with significant amplitude are considered. The default relative amplitude is -60 dB in MKMOVIE. You can change this value by using the following:

[...] = MKMOVIE(...,OPTIONS),

where OPTIONS.dBThresh is the threshold in dB (default = -60).


By default, the directivity of the elements depends on the center frequency only. This makes the algorithm faster. To make the directivities fully frequency-dependent, use:

[...] = MKMOVIE(...,OPTIONS),

with OPTIONS.FullFrequencyDirectivity = true (default = false).


Each transducer element of the array is split into small segments. The length of these small segments must be small enough to ensure that the far-field model is accurate. By default, the elements are split into M segments, with M being defined by:

M = ceil(element_width/smallest_wavelength);

To modify the number M of subelements by splitting, you may adjust OPTIONS.ElementSplitting. For example, OPTIONS.ElementSplitting = 1.


If OPTIONS.WaitBar is true, a wait bar appears (only if the number of frequency samples >10). Default is true.



Note on BAFFLE property

In PFIELD, it is assumed by default that the array elements are embedded in an infinite SOFT baffle. To modify the property of the baffle, modify the field PARAM.baffle:

  1. 'rigid'
  2. 'soft' (this is the default)
  3. a nonnegative scalar ${\alpha}$ , with ${\alpha}$ = (medium impedance)/(baffle impedance). Note: ${\alpha}=0 \Rightarrow$ 'rigid'; ${\alpha}>>1 \Rightarrow$ 'soft'.

The baffle property affects the obliquity factor included in the directivity of the elements. This obliquity factor is not 1 if the baffle is not rigid. A general case (see case #3 below) can be chosen by specifying an impedance ratio. For details, refer to the corresponding papers.

  1. Rigid baffle $\Rightarrow$ obliquity factor = 1.
  2. Soft baffle $\Rightarrow$ obliquity factor = cos(${\theta}$).
  3. General baffle $\Rightarrow$ obliquity factor = cos(${\theta}$)/(cos(${\theta}$) + ${\alpha}$), with ${\alpha}$ = (medium impedance)/(baffle impedance).

References for baffle models:

Example: For a baffle of impedance 2.8 MRayl (epoxy) adjacent to soft tissues of impedance 1.6 MRayls, ${\alpha}$ = 1.75.



Note on CHIRP signals

Linear chirps are characterized by PARAM.TXnow, PARAM.fc and PARAM.TXfreqsweep. The transmitted pulse has a duration of approximately T (= PARAM.TXnow/PARAM.fc), with the amplitude and phase defined over the time interval -T/2 to +T/2.

The total frequency sweep is DeltaF (= PARAM.TXfreqsweep): the frequencies increase linearly from (PARAM.fc - DeltaF/2) to (PARAM.fc + DeltaF/2) in the defined time interval.

Documentation: Chirp spectrum in Wikipedia.



Example #1: Display the propagation of a focused wave

This example shows how to simulate and display the wave propagation of RF signals that focus to a given location.

Download the properties of a 2.7-MHz 64-element cardiac phased array in a structure param by using GETPARAM.

param = getparam('P4-2v');

Choose a focus location at xf = 0 cm, zf = 3 cm.

xf = 0e-2; zf = 3e-2; % focus position (in m)

Obtain the corresponding transmit time delays (in s) with TXDELAY.

txdel = txdelay(xf,zf,param); % in s

Define the image size (in cm) and its resolution (in pix/cm).

param.movie = [3 6 100];

Make movie frames by using MKMOVIE and create an animated GIF.

[F,info] = mkmovie(txdel,param,'focused_wave.gif');

Display nine movie frames.

colormap([1-hot(128); hot(128)]);
framenum = round(linspace(1,size(F,3),9));
for k = 1:9
    image(info.Xgrid*100,info.Zgrid*100,F(:,:,framenum(k)))
    axis equal ij tight
    title([int2str(info.TimeStep*framenum(k)*1e6) ' \mus'])
    ylabel('[cm]')
    set(gca,'XColor','none','box','off')
    snapnow
end


Here is the movie 'focused_wave.gif'



Example #2: Display the backpropagation of a diverging wave

This example shows how to simulate and display a diverging wave backpropagated by a few scatterers.

Download the properties of a 2.7-MHz 64-element cardiac phased array in a structure param by using GETPARAM.

param = getparam('P4-2v');

Obtain the transmit time delays (in s) for a 90-degree wide diverging wave with TXDELAY.

txdel = txdelay(param,0,pi/2); % in s

Define 20 random scatterers and their bacskscattering coefficients.

n = 20;
x = rand(n,1)*8e-2-4e-2; % (in m)
z = rand(n,1)*10e-2; % (in m)
RC = (rand(n,1)+1)/2;

Define the image size (in cm) and its resolution (in pix/cm).

param.movie = [8 10];

Make movie frames by using MKMOVIE and create an animated GIF.

[F,info] = mkmovie(x,z,RC,txdel,param,'diverging_wave.gif');

Display nine movie frames.

colormap([1-hot(128); hot(128)]);
framenum = round(linspace(1,size(F,3),9));
for k = 1:9
    image(info.Xgrid*100,info.Zgrid*100,F(:,:,framenum(k)))
    hold on
    scatter(x*100,z*100,10,'w','filled')
    hold off
    axis equal ij tight
    title([int2str(info.TimeStep*framenum(k)*1e6) ' \mus'])
    ylabel('[cm]')
    set(gca,'XColor','none','box','off')
    snapnow
end


Here is the movie 'diverging_wave.gif'



Example #3: Display the backpropagation of a diverging wave from a convex array

This example shows how to simulate and display a diverging wave generated by a convex array and backpropagated by a few scatterers.

Download the properties of a 3.6-MHz 128-element convex array in a structure param by using GETPARAM.

param = getparam('C5-2v');

Design a few scatterers.

xs = [4.3 3.2 1.7 0 -1.7 -3.2 -4.3 0 -2.5 2.5]*1e-2; % in m
zs = [7 8.1 8.8 9 8.8 8.1 7 5 2 2]*1e-2; % in m

Set all the transmit delays to 0.

txdel = zeros(1,param.Nelements);

Calculate and display the pressure field.

[x,z] = meshgrid(linspace(-.1,.1,256),linspace(0,.1,128));
P = pfield(x,z,txdel,param);

imagesc(x(1,:)*1e2,z(:,1)*1e2,20*log10(P/max(P,[],'all')))
axis equal ij tight
caxis([-20 0]) % dynamic range = [-20,0] dB
c = colorbar;
c.YTickLabel{end} = '0 dB';
colormap hot
xlabel('x (cm)'), ylabel('z (cm)')
title('Circular wave with a convex array')

hold on
plot(xs*1e2,zs*1e2,'bo','Linewidth',2)
hold off
legend('scatterers')

Add a "ghost" scatterer (its reflection coefficient is zero) at 10 cm deep to ensure that RF are simulated till 10-cm depth.

RC = [ones(1,numel(xs)) 0];
xs = [xs 0]; zs = [zs 1e-2];

Create a GIF movie named 'convexSmiley.gif' with MKMOVIE.

param.movie = [10 10 30]; % 10-cm-by-10-cm ROI, resolution = 30 pix/cm
mkmovie(xs,zs,RC,txdel,param,'convexSmiley.gif');



See also

pfield, simus, txdelay



About the author

Damien Garcia, Eng., Ph.D.
INSERM researcher
Creatis, University of Lyon, France

websites: BioméCardio, MUST



Date modified


Published with MATLAB® R2020a