`MKMOVIE` Make movie frames and animated GIF

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

## Contents

- Syntax
- The structure
`PARAM` - Other syntaxes
- Advanced options
- Note on BAFFLE property
- Note on CHIRP signals
- Example #1: Display the propagation of a focused wave
- Example #2: Display the backpropagation of a diverging wave
- Example #3: Display the backpropagation of a diverging wave from a convex array
- See also
- About the author
- Date modified

## 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 (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 a 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:

**MOVIE PROPERTIES**

`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)`]

**TRANSDUCER PROPERTIES**

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

**MEDIUM PARAMETERS**

`PARAM.c`: longitudinal velocity (in m/s, default = 1540 m/s)`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.

**TRANSMIT PARAMETERS**

`PARAM.TXdelay`: transmission law delays (in s).`PARAM.TXdelay`is required if the vector`DELAYS`is not given (seebelow).*Other syntaxes*`PARAM.TXapodization`: transmision apodization (default: no apodization)`PARAM.TXnow`: number of wavelengths of the TX pulse (default: 1). Use`PARAM.TXnow = Inf`for a mono-harmonic signal.`PARAM.TXfreqsweep`: frequency sweep for a linear chirp (default: [ ]). To be used to simulate a linear TX chirp. Seebelow for details.*Note on CHIRP signals*

## 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.

The syntaxes `F = MKMOVIE(PARAM)` or `F = MKMOVIE(X,Z,RC,PARAM)` use `DELAYS = param.TXdelay`.

`[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

**FREQUENCY SAMPLES**

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`).

**FULL-FREQUENCY DIRECTIVITY**

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`).

**ELEMENT SPLITTING**

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`.

**WAIT BAR**

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`:

`'rigid'``'soft'`(this is the default)- a nonnegative scalar , with = (medium impedance)/(baffle impedance). Note:
`'rigid'`;`'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.

- Rigid baffle obliquity factor = 1.
- Soft baffle obliquity factor = cos().
- General baffle obliquity factor = cos()/(cos() + ), with = (medium impedance)/(baffle impedance).

**References for baffle models**:

- Selfridge
*et al*.*A theory for the radiation pattern of a narrow-strip acoustic transducer*. Appl Phys Lett 37(1), 35-36 (1980) - Pesqué
*et al*.*Effect of the planar baffle impedance in acoustic radiation of a phased array element theory and experimentation*. IEEE Ultrasonics Symposium, (1984)

**Example**: For a baffle of impedance 2.8 MRayl (epoxy) adjacent to soft tissues of impedance 1.6 MRayls, = 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 = 5 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

## About the author

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

**websites**: **BioméCardio**, **MUST**

## Date modified