k-Wave Toolbox

Using A Binary Sensor Mask Example

This example demonstrates how to use a binary sensor mask for the detection of the pressure field generated by an initial pressure distribution within a two-dimensional homogeneous propagation medium. It builds on the Homogeneous Propagation Medium Example.


Defining a binary sensor mask

In the Homogeneous Propagation Medium Example, the sensor mask (which defines where the pressure field is recorded at each time-step) is defined as a 2 x N matrix of Cartesian points. It is also possible to define the sensor mask as binary matrix (i.e., a matrix of 1's and 0's) representing the grid points within the computational domain that will collect the data. In this case, the sensor mask must have the same dimensions as the computational grid (i.e., it must have Nx rows and Ny columns). Here makeCircle is used (instead of makeCartCircle) to define a binary sensor mask of an arc created using the midpoint circle algorithm. It is also possible to explicitly create an arbitrary binary sensor mask, or to load one from an external image map (see the Loading External Image maps Example).

% define a binary sensor mask
sensor_x_pos = Nx/2;        % [grid points]
sensor_y_pos = Ny/2;        % [grid points]
sensor_radius = Nx/2 - 22;  % [grid points]
sensor_arc_angle = 3*pi/2;  % [radians]
sensor.mask = makeCircle(Nx, Ny, sensor_x_pos, sensor_y_pos, sensor_radius, sensor_arc_angle);

A plot of the initial pressure distribution and the sensor mask is given below.

Running the simulation

The computation is again started by calling kspaceFirstOrder2D. For a Cartesian sensor mask (as in the Homogeneous Propagation Medium Example), the returned time-series are ordered the same way as the set of Cartesian sensor points. For a binary sensor mask (as in this example), the time-series are instead returned using MATLAB's standard column-wise linear matrix index ordering. As an example, if the sensor mask is defined as

0     1     0
1     0     1
1     0     1
0     1     0

the ordering of the recorded time series will be

0     3     0
1     0     5
2     0     6
0     4     0

For both Cartesian and binary sensor masks, the data is indexed as sensor_data(sensor_point_index, time_index). A visualisation of the recorded time data is given below. The data ordering is clearly visible; the data is returned column-wise from top to bottom, and left to right.

For 2D simulations, it is possible to reorder the sensor data returned by a binary sensor mask based on the angle that each sensor point makes with the grid origin using reorderSensorData. The angles are defined from the upper left quadrant or negative y-axis in the same way as within makeCircle and makeCartCircle.

% reorder the simulation data
sensor_data_reordered = reorderSensorData(kgrid, sensor, sensor_data);

The recorded data at a particular time step can also be restored to its original position in the grid using unmaskSensorData.