kWaveArray

Class definition for k-Wave array.

Syntax

karray = kWaveArray
karray = kWaveArray(...)

Description

kWaveArray is a class definition that allows the definition of multi-element transducer arrays in 1D, 2D, and 3D for use with the k-Wave simulation functions. The individual elements are defined using physical (rather than grid) parameters in Cartesian coordinates, and their representation on the grid is automatically calculated using off-grid sources as described in [1].

There are two key advantages of using the kWaveArray class to define arrays. (1) The geometry is stair-case free. (2) The transmit signals (for sources) and receive signals (for sensors) are defined per physical transducer element, rather than per grid point.

No information about the actual simulation grid is stored within objects of the kWaveArray class. The idea is that an array can be defined using physical characteristics, and then re-used for many different simulations. Note, some methods do use the grid information for calculations, and therefore take an object of the kWaveGrid class as an input. The implementation assumes that the grid sampling is uniform, i.e., dx = dy = dz.

To calculate the off-grid source, first a uniform sampling of Cartesian points is generated covering the element shape (e.g., bowl, disc, etc). For each sample point, a band-limited interpolant is computed corresponding to a point source at that location. These point source responses are summed and scaled to give the source mask for that element. This means the source mask will be non-local, i.e., will extend spatially beyond where the physical source lies on the grid. Note, any Cartesian points that are outside the grid are automatically removed.

In the current version, objects of the kWaveArray class cannot be passed directly to the simulation functions in place of the source and sensor structures. Instead, methods of the kWaveArray class can be used to automatically create these inputs and process the outputs. See examples for further details.

[1] Wise, E. S., Cox, B. T., Jaros, J., & Treeby, B. E. (2019). Representing arbitrary acoustic source and sensor distributions in Fourier collocation methods. The Journal of the Acoustical Society of America, 146(1), 278-288.

Optional Inputs

Optional 'string', value pairs that may be used to modify the default computational settings.

Input	Valid Settings	Default	Description
'BLITolerance'	(numeric scalar)	0.05	Scalar value controlling where the spatial extent of the BLI at each point is trunctated as a portion of the maximum value.
'BLIType'	'sinc' 'exact'	'sinc'	String controlling the BLI expression that is used for each point source (see offGridPoints). 'BLITolerance' is ignored if 'exact' is specified.
'SinglePrecision'	(Boolean)	false	Boolean controlling whether the calculation of the off-grid mask and distributed source are performed in single precision to improve performance.
'UpsamplingRate'	(numeric scalar)	10	Oversampling used to distribute the off-grid points compared to the equivalent number of on-grid points.

Outputs

karray

kWaveArray object which can be used to define source and sensor inputs for the kWave simulation functions.

Properties

Properties of the kWaveArray class which can be queried, but not directly modified.

Property	Description
karray.array_transformation	Position of the array defined by an affine transform. Used to move the array without needing to redefine the individual positions of the elements. Set by using the setArrayPosition and setAffineTransform methods.
karray.dim	Number of spatial dimensions.
karray.elements	Structure containing the properties for each element in the array. New elements are added using the addXXXElement methods.
karray.number_elements	Number of transducer elements in the array.

Methods

Methods of the kWaveArray class. After creating a kWaveArray object, methods are called using the syntax:

karray = kWaveArray;
karray.methodName(inputs);
output = karray.methodName(inputs);

The first syntax is used for methods with no output, and the second for methods with an output.

addAnnularArray

Add annular array (3D simulations). The array elements are indexed from the inner-most element outwards. If radius ~= inf, then the annular array is positioned over the surface of a bowl.

addAnnularArray(position, radius, diameters, focus_pos)

position	Centre of rear surface [bx, by, bz] [m].
radius	Radius of curvature of a bowl on which the annular array lies [m].
diameters	2 x num_elements array containing pairs of inner and outer aperture diameter (diameter of opening) [m].
focus_pos	Any point on the beam axis [fx, fy, fz] [m].

addAnnularElement

Add annular element (3D simulations). Setting diameter = [0, diameter] will generate a bowl the same as addBowlElement.

addAnnularElement(position, radius, diameters, focus_pos)

position	Centre of rear surface [bx, by, bz] [m].
radius	Radius of curvature of a bowl on which the annular element lies [m].
diameters	2 element array containing inner and outer aperture diameter (diameter of opening) [m].
focus_pos	Any point on the beam axis [fx, fy, fz] [m].

addArcElement

Add arc-shaped element to the array (2D simulations).

addArcElement(position, radius, diameters, focus_pos)

position	Centre of rear surface (arc midpoint) [bx, by] [m].
radius	Radius of curvature of arc [m].
diameters	Diameter of arc opening [m].
focus_pos	Any point on the beam axis [fx, fy] [m].

addBowlElement

Add bowl-shaped element to the array (3D simulations).

addBowlElement(position, radius, diameter, focus_pos)

position	Centre of rear surface [bx, by, bz] [m].
radius	Radius of curvature of bowl [m].
diameters	Diameter of bowl opening [m].
focus_pos	Any point on the beam axis [fx, fy, fz] [m].

addCustomElement

Add custom volume, area, or line element to the array defined as a series of integration points (see [1]; 1D/2D/3D simulations). Note, for custom elements, the integration point density should be sufficient relative the intended grid spacing (see [1]).

addCustomElement(integration_points, measure, element_dim, label)

integration_points	1 x num_points (1D), 2 x num_points (2D) or 3 x num_points (3D) array of Cartesian coordinates [m].
measure	Length [m] of line element, area [m^2] of area element, or volume [m^3] of volume element corresponding to element_dim.
element_dim	Integer specifying whether the custom element is a line element (1), area element (2), or volume element (3). Note, element_dim does not need to match the dimension of the simulation, i.e., it is possible to use a line element in a 3D array.
label	String identifier.

addDiscElement

Add disc-shaped element to the array (2D/3D simulations).

addDiscElement(position, diameter, focus_pos)

position	Centre of disc surface [bx, by] or [bx, by, bz] [m].
diameter	Diameter of the disc [m].
focus_pos	Any point on beam axis [fx, fy, fz] (not used for 2D simulations) [m].

addRectElement

Add rectangular element to the array (2D/3D simulations). The rectangle is created in the x-y plane and then rotated.

addRectElement(position, Lx, Ly, theta)

position	Centre of rect [bx, by] or [bx, by, bz] [m].
Lx	Height of rect (along x-axis before rotation) [m].
Ly	Width of rect (along y-axis before rotation) [m].
theta	Either a scalar (2D) or three element vector (3D) [tx, ty, tz] specifying the orientation of the rectangle [deg]. In 3D, the rotations are specified about x-y'-z'' (intrinsic rotations) or z-y-x (extrinsic rotations). All rotations are counter-clockwise. Can be set to [] if no rotation.

addLineElement

Add line element to the array (1D/2D/3D simulations).

addLineElement(start_point, end_point)

start_point	Start coordinate for the line given as a one (1D), two (2D), or three (3D) element vector [m].
end_point	End coordinate for the line given as a one (1D), two (2D), or three (3D) element vector [m].

combineSensorData

When using array.getArrayBinaryMask to define a sensor mask for the k-Wave simulation functions, the returned sensor data is defined for every grid point that forms part of the array. This method combines the sensor data with the appropriate weights and returns a single time series (or value) for each physical array element (rather than each grid point). The data is returned in the same order as the transducer elements were added to the array.

combined_sensor_data = combineSensorData(kgrid, sensor_data)

combined_sensor_data	Combined sensor data (one time series per transducer element).
kgrid	Grid object returned by kWaveGrid.
sensor_data	Sensor data returned by simulation functions for a sensor mask given by getArrayBinaryMask.

getArrayBinaryMask

Returns binary mask containing all grid points that form part of the array. Note, as the array elements use off-grid sources (see [1]), this will be non-local to some extent (depending on the values set for 'BLITolerance' and 'BLIType').

mask = getArrayBinaryMask(kgrid)

mask	Binary mask (matrix of 1s and 0s) specifying the grid points that form part of the array.
kgrid	Grid object returned by kWaveGrid.

getArrayGridWeights

Returns matrix containing sum of off-grid source weights for each grid point in the domain (defined by kgrid).

grid_weights = getArrayGridWeights(kgrid)

grid_weights	Matrix of grid weights.
kgrid	Grid object returned by kWaveGrid.

getDistributedSourceSignal

When defining a source input, a binary source mask (e.g, source.p_mask) should be defined using getArrayBinaryMask, and the time varying source (e.g., source.p) should be defined using this method. This automatically calculates the appropriate weighted source signal for each grid point that forms part of the off-grid source. The source data is assigned in the same order as the transducer elements were added to the array.

distributed_source = getDistributedSourceSignal(kgrid, source_signal)

distributed_source	Source signal used to define time-varying source inputs for the k-Wave simulations functions, e.g, source.p.
kgrid	Grid object returned by kWaveGrid.
source_signal	Source signal for each transducer element defined as an array [number_elements, Nt].

getElementBinaryMask

Returns binary mask containing all grid points that form part of the specified element. Note, as the array elements use off-grid sources (see [1]), this will be non-local (depending on the values set for 'BLITolerance' and 'BLIType').

mask = getElementBinaryMask(kgrid, element_num)

mask	Binary mask (matrix of 1s and 0s) specifying the grid points that form part of the element.
kgrid	Grid object returned by kWaveGrid.
element_num	Element number to return binary mask for.

getElementGridWeights

Returns matrix containing off-grid source weights for the transducer element defined as element_num (see [1]).

grid_weights = getElementGridWeights(kgrid, element_num)

grid_weights	Matrix of grid weights.
kgrid	Grid object returned by kWaveGrid.
element_num	Element number to return grid weights for.

getElementPositions

Returns a [dim, num_elements] array containing the positions of each array element after applying array_transformation (if defined).

element_pos = getElementPositions()

element_pos

Matrix of element positions [m].

plotArray

Plot the array elements. If new_figure is true (the default), a new figure window is created, otherwise the elements are added to the currently active figure window.

plotArray(new_figure)

new_figure

Boolean controlling whether a new figure window is created.

removeElement

Remove specified element from the array.

removeElement(element_num)

element_num

Element number to remove from the array.

setAffineTransform

Sets value for array_transformation defined as an affine transformation matrix.

setAffineTransform(affine_transform)

affine_transform

Affine transform given as a [3, 3] matrix in 2D or [4, 4] matrix in 3D.

setArrayPosition

Sets the property array_transformation (an affine transform) based on the values for translation and rotation. The translations are given as [dx, dy] in 2D and [dx, dy, dz] in 3D. The rotations angle/s are given as [th] in 2D (counter-clockwise) and [x_th, y_th, z_th] in 3D (rotation about x then y' then z'').

setArrayPosition(translation, rotation)

translation	Array translation [m].
rotation	Array rotation [degrees].

setOptionalInputs

Method to define the optional inputs (see Optional Inputs above). Can be called when the kWaveArray object is defined, or later.

setOptionalInputs(...)

See Also

offGridPoints, getDeltaBLI