Beamforming (dsptoolbox.beamforming)

Beamforming

This module contains basic beamforming algorithms and classes used for their implementation.

Classes:

  • Grid()

  • Regular2DGrid()

  • Regular3DGrid()

  • LineGrid()

  • MicArray()

  • SteeringVector()

  • BeamformerDASFrequency()

  • BeamformerDASTime()

  • BeamformerCleanSC()

  • BeamformerOrthogonal()

  • BeamformerFunctional()

  • BeamformerMVDR()

  • Source()

Functions:

  • mix_sources_on_array(): produces a mixed multi-channel signal on a given microphone array by receiving multiple source objects.

References:

  • For a more powerful and flexible beamforming library, please refer to the acoular package: http://acoular.org

class dsptoolbox.beamforming.BeamformerCleanSC(multi_channel_signal: Signal, mic_array: MicArray, grid: Grid, steering_vector: SteeringVector, c: float = 343)

Bases: BeamformerGridded

This class performs beamforming using the CLEAN-SC method presented in [1].

Methods

get_beamformer_map(center_frequency_hz[, ...])

Returns a deconvolved beaforming map.

get_frequency_range_from_he([range_he])

Takes in frequency range in He (Helmholtz number) and returns it in Hz.

plot_setting()

Plots spatial setting of microphones and grid.

show_info()

Helper for creating a string containing metadata.

References

  • [1]: Sijtsma P. CLEAN Based on Spatial Source Coherence. International Journal of Aeroacoustics. 2007;6(4):357-374. doi: 10.1260/147547207783359459.

beamformer_type = 'CleanSC'
get_beamformer_map(center_frequency_hz: float, octave_fraction: int = 3, maximum_iterations: int | None = None, safety_factor: float = 0.5, remove_csm_diagonal: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]

Returns a deconvolved beaforming map.

Parameters:
center_frequenc_hzfloat

Center frequency for which to compute map.

octave_fractionint, optional

Fractional octave bandwidth for computing the map. For instance, 8 means 1/8-octave bandwidth. Default: 3.

maximum_iterationsint, optional

Set a maximum number of iterations for acquiring the degraded CSM. If None is passed, the double of the number of microphones is taken as the maximum iteration number. The stopping criterion given in [1] is always checked. Default: None.

safety_factorfloat, optional

Also called loop gain, the safety factor dampens the result from each iteration during deconvolution. Should be between 0 and 1. See [1] for more details. Default: 0.5.

remove_csm_diagonalbool, optional

When True, the main diagonal of the CSM is removed for a cleaner map (source powers might be wrongly estimated). Default: False.

Returns:
mapNDArray[np.float64]

Beamformer map.

References

  • [1]: Sijtsma P. CLEAN Based on Spatial Source Coherence. International Journal of Aeroacoustics. 2007;6(4):357-374. doi: 10.1260/147547207783359459.

class dsptoolbox.beamforming.BeamformerDASFrequency(multi_channel_signal: Signal, mic_array: MicArray, grid: Grid, steering_vector: SteeringVector, c: float = 343)

Bases: BeamformerGridded

This is the base class for beamforming in frequency-domain.

Methods

get_beamformer_map(center_frequency_hz[, ...])

Run delay-and-sum beamforming in the given frequency range.

get_frequency_range_from_he([range_he])

Takes in frequency range in He (Helmholtz number) and returns it in Hz.

plot_setting()

Plots spatial setting of microphones and grid.

show_info()

Helper for creating a string containing metadata.
beamformer_type = 'Delay-and-sum (Frequency)'
get_beamformer_map(center_frequency_hz: float, octave_fraction: int = 3, remove_csm_diagonal: bool = True) → ndarray[tuple[Any, ...], dtype[float64]]

Run delay-and-sum beamforming in the given frequency range.

Parameters:
center_frequenc_hzfloat

Center frequency for which to compute map.

octave_fractionint, optional

Fractional octave bandwidth for computing the map. For instance, 8 means 1/8-octave bandwidth. Default: 3.

remove_csm_diagonalbool, optional

When True, the diagonal of the cross-spectral matrix is removed. Default: True.

Returns:
mapNDArray[np.float64]

Beamforming map

class dsptoolbox.beamforming.BeamformerDASTime(multi_channel_signal: Signal, mic_array: MicArray, grid: Grid, c: float = 343)

Bases: BaseBeamformer

Conventional delay-and-sum beamformer in time-domain.

Methods

get_beamformer_output()

Triggers the computation for beamforming in time domain.

get_frequency_range_from_he([range_he])

Takes in frequency range in He (Helmholtz number) and returns it in Hz.

plot_setting()

Plots spatial setting of microphones and grid.

show_info()

Helper for creating a string containing metadata.
get_beamformer_output() → Signal

Triggers the computation for beamforming in time domain.

Returns:
out_sigSignal

Output signal focused to the points of the grid.

class dsptoolbox.beamforming.BeamformerFunctional(multi_channel_signal: Signal, mic_array: MicArray, grid: Grid, steering_vector: SteeringVector, c: float = 343)

Bases: BeamformerGridded

This class performs functional beamforming using the method presented in [1].

Methods

get_beamformer_map(center_frequency_hz[, ...])

Returns a beaforming map created with functional beamforming.

get_frequency_range_from_he([range_he])

Takes in frequency range in He (Helmholtz number) and returns it in Hz.

plot_setting()

Plots spatial setting of microphones and grid.

show_info()

Helper for creating a string containing metadata.

References

  • [1]: Dougherty, Robert. (2014). Functional Beamforming.

beamformer_type = 'Functional'
get_beamformer_map(center_frequency_hz: float, octave_fraction: int = 3, gamma: float = 10) → ndarray[tuple[Any, ...], dtype[float64]]

Returns a beaforming map created with functional beamforming.

Parameters:
center_frequenc_hzfloat

Center frequency for which to compute map.

octave_fractionint, optional

Fractional octave bandwidth for computing the map. For instance, 8 means 1/8-octave bandwidth. Default: 3.

gammafloat, optional

Set a gamma value as the power of the CSM. Default: 10.

Returns:
mapNDArray[np.float64]

Beamformer map.

References

  • [1]: Dougherty, Robert. (2014). Functional Beamforming.

class dsptoolbox.beamforming.BeamformerMVDR(multi_channel_signal: Signal, mic_array: MicArray, grid: Grid, steering_vector: SteeringVector, c: float = 343)

Bases: BeamformerGridded

This class performs minimum variance distortionless response (MVDR) beamforming using the method presented in [1]. This formulation is also referred to as Capon beamformer.

Methods

get_beamformer_map(center_frequency_hz[, ...])

Returns a beaforming map created with MVDR beamforming.

get_frequency_range_from_he([range_he])

Takes in frequency range in He (Helmholtz number) and returns it in Hz.

plot_setting()

Plots spatial setting of microphones and grid.

show_info()

Helper for creating a string containing metadata.

References

  • [1]: J. Capon, “High-resolution frequency-wavenumber spectrum analysis,” in Proceedings of the IEEE, vol. 57, no. 8, pp. 1408-1418, Aug. 1969, doi: 10.1109/PROC.1969.7278.

beamformer_type = 'MVDR'
get_beamformer_map(center_frequency_hz: float, octave_fraction: int = 3, gamma: float = 10) → ndarray[tuple[Any, ...], dtype[float64]]

Returns a beaforming map created with MVDR beamforming.

Parameters:
center_frequenc_hzfloat

Center frequency for which to compute map.

octave_fractionint, optional

Fractional octave bandwidth for computing the map. For instance, 8 means 1/8-octave bandwidth. Default: 3.

Returns:
mapNDArray[np.float64]

Beamformer map.

References

  • [1]: J. Capon, “High-resolution frequency-wavenumber spectrum analysis,” in Proceedings of the IEEE, vol. 57, no. 8, pp. 1408-1418, Aug. 1969, doi: 10.1109/PROC.1969.7278.

class dsptoolbox.beamforming.BeamformerOrthogonal(multi_channel_signal: Signal, mic_array: MicArray, grid: Grid, steering_vector: SteeringVector, c: float = 343)

Bases: BeamformerGridded

This class performs orthogonal beamforming using the method presented in [1].

Methods

get_beamformer_map(center_frequency_hz[, ...])

Returns a beaforming map created with orthogonal beamforming.

get_frequency_range_from_he([range_he])

Takes in frequency range in He (Helmholtz number) and returns it in Hz.

plot_setting()

Plots spatial setting of microphones and grid.

show_info()

Helper for creating a string containing metadata.

References

  • [1]: Ennes Sarradj, A fast signal subspace approach for the determination of absolute levels from phased microphone array measurements, Journal of Sound and Vibration, Volume 329, Issue 9, 2010, Pages 1553-1569, ISSN 0022-460X, https://doi.org/10.1016/j.jsv.2009.11.009.

beamformer_type = 'Orthogonal (Grid)'
get_beamformer_map(center_frequency_hz: float, octave_fraction: int = 3, number_eigenvalues: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Returns a beaforming map created with orthogonal beamforming.

Parameters:
center_frequenc_hzfloat

Center frequency for which to compute map.

octave_fractionint, optional

Fractional octave bandwidth for computing the map. For instance, 8 means 1/8-octave bandwidth. Default: 3.

number_eigenvaluesint, optional

Set a number of eigenvalues to be regarded. Pass None to use at least half of what is possible (number of microphones). Default: None.

Returns:
mapNDArray[np.float64]

Beamformer map.

References

  • [1]: Ennes Sarradj, A fast signal subspace approach for the determination of absolute levels from phased microphone array measurements, Journal of Sound and Vibration, Volume 329, Issue 9, 2010, Pages 1553-1569, ISSN 0022-460X, https://doi.org/10.1016/j.jsv.2009.11.009.

class dsptoolbox.beamforming.Grid(positions: dict)

Bases: BasePoints

This class contains a grid to use for beamforming and all its metadata. This class is implemented only for right-hand systems with cartesian coordinates (in meters).

Attributes:
coordinates
extent
number_of_points

Methods

find_nearest_point(point)

This method returns the coordinates and index of the nearest point to a given point using euclidean distance.

get_distances_to_point(point)

Compute distances (euclidean) from given point to all points of the object efficiently.

plot_points([projection])

Plot points in 2D or 3D plot depending on the actual points.

reconstruct_map_shape(map)

Placeholder for a user-defined map reconstruction.
reconstruct_map_shape(map: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Placeholder for a user-defined map reconstruction. Here, it returns same given map. Use inheritance from the Grid class to overwrite this with an own implementation.

Parameters:
mapNDArray[np.float64]

Map to be reshaped.

Returns:
mapNDArray[np.float64]

Reshaped map. Here with same passed shape as before.

class dsptoolbox.beamforming.LineGrid(line, dimension: str, value2: float, value3: float)

Bases: Grid

Class for a line grid.

Attributes:
coordinates
extent
number_of_points

Methods

find_nearest_point(point)

This method returns the coordinates and index of the nearest point to a given point using euclidean distance.

get_distances_to_point(point)

Compute distances (euclidean) from given point to all points of the object efficiently.

plot_points([projection])

Plot points in 2D or 3D plot depending on the actual points.

reconstruct_map_shape(map)

Placeholder for a user-defined map reconstruction.
class dsptoolbox.beamforming.MicArray(positions: dict)

Bases: BasePoints

This class contains a microphone array with all its metadata.

Attributes:
aperture
array_center_channel_number
array_center_coordinates
coordinates
extent
min_distance
number_of_points

Methods

find_nearest_point(point)

This method returns the coordinates and index of the nearest point to a given point using euclidean distance.

get_distances_to_point(point)

Compute distances (euclidean) from given point to all points of the object efficiently.

get_maximum_frequency_range([lowest_he, c])

Computes maximum recommended frequency range in Hz for this microphone array based on lowest Helmholtz number and the criterion min_distance = wavelength/2 (to avoid spatial aliasing).

he_to_hz(he[, c])

This method returns the frequency in Hz that corresponds to a given Helmholtz number based on array's aperture.

hz_to_he(f_hz[, c])

This method returns the Helmholtz number corresponds to a given frequency based on array's aperture.

plot_points([projection])

Plot points in 2D or 3D plot depending on the actual points.
property aperture
property array_center_channel_number
property array_center_coordinates
get_maximum_frequency_range(lowest_he: float = 4, c: float = 343) → list

Computes maximum recommended frequency range in Hz for this microphone array based on lowest Helmholtz number and the criterion min_distance = wavelength/2 (to avoid spatial aliasing).

Parameters:
lowest_hefloat, optional

Lowest Helmholtz number to be regarded as valid. Default: 4.

cfloat, optional

Speed of sound in m/s. Default: 343.

Returns:
f_range_hzlist

Array with frequency range for this microphone array.

he_to_hz(he: float, c: float = 343) → float

This method returns the frequency in Hz that corresponds to a given Helmholtz number based on array’s aperture.

Parameters:
hefloat

Helmholtz number.

cfloat

Speed of sound in m/s. Default: 343.

Returns:
f_hzfloat

Frequency in Hz that corresponds to the passed Helmholtz number.

hz_to_he(f_hz: float, c: float = 343) → float

This method returns the Helmholtz number corresponds to a given frequency based on array’s aperture.

Parameters:
f_hzfloat

Frequency in Hz.

cfloat

Speed of sound in m/s. Default: 343.

Returns:
hefloat

Helmholtz number corresponding to passed frequency.

property min_distance
class dsptoolbox.beamforming.MonopoleSource(signal: Signal, coordinates)

Bases: object

Base class for all sources. It has a monopole characteristic by default.

Methods

get_signals_on_array(mics[, c])

Simulate transmission of emitted signal onto microphone array.
get_signals_on_array(mics: MicArray, c: float = 343) → Signal

Simulate transmission of emitted signal onto microphone array.

Parameters:
micsMicArray

Microphone array.

cfloat, optional

Speed of sound in m/s. Default: 343.

Returns:
multi_channel_signalSignal

Multi-channel signal corresponding array’s microphones.

class dsptoolbox.beamforming.Regular2DGrid(line1, line2, dimensions, value3)

Bases: Grid

This class creates a Grid object with a 2D, rectangular shape.

Attributes:
coordinates
extent
number_of_points

Methods

find_nearest_point(point)

This method returns the coordinates and index of the nearest point to a given point using euclidean distance.

get_distances_to_point(point)

Compute distances (euclidean) from given point to all points of the object efficiently.

plot_map(map[, range_db])

Plot a map done with this type of grid.

plot_points([projection])

Plot points in 2D or 3D plot depending on the actual points.

reconstruct_map_shape(map_vector)

Reshapes the map to be a matrix that fits the grid.
plot_map(map: ndarray[tuple[Any, ...], dtype[float64]], range_db: float = 20) → tuple[Figure, Axes]

Plot a map done with this type of grid.

Parameters:
mapNDArray[np.float64]

Beamformer map.

range_dbfloat, optional

Range in dB to plot.

Returns:
figmatplotlib.figure.Figure

Figure.

axmatplotlib.axes.Axes

Axes.

reconstruct_map_shape(map_vector: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Reshapes the map to be a matrix that fits the grid.

Parameters:
map_vectorNDArray[np.float64]

Map (as a vector) to be reshaped.

Returns:
mapNDArray[np.float64]

Reshaped map.

class dsptoolbox.beamforming.Regular3DGrid(line_x, line_y, line_z)

Bases: Grid

Class for 3D regular Grids.

Attributes:
coordinates
extent
number_of_points

Methods

find_nearest_point(point)

This method returns the coordinates and index of the nearest point to a given point using euclidean distance.

get_distances_to_point(point)

Compute distances (euclidean) from given point to all points of the object efficiently.

plot_map(map, third_dimension, ...[, range_db])

Plot a map done with this type of grid.

plot_points([projection])

Plot points in 2D or 3D plot depending on the actual points.

reconstruct_map_shape(map_vector)

Reshapes the map to be a matrix that fits the grid.
plot_map(map: ndarray[tuple[Any, ...], dtype[float64]], third_dimension: str, value_third_dimension: float, range_db: float = 20) → tuple[Figure, Axes]

Plot a map done with this type of grid.

Parameters:
mapNDArray[np.float64]

Beamformer map.

third_dimensionstr

Choose the dimension that is normal to plane. Choose from ‘x’, ‘y’ or ‘z’.

value_third_dimensionfloat

Value for third dimension that should be plotted. The nearest possible value will be taken if it is not exact.

range_dbfloat, optional

Range in dB to plot.

Returns:
figmatplotlib.figure.Figure

Figure.

axmatplotlib.axes.Axes

Axes.

reconstruct_map_shape(map_vector: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Reshapes the map to be a matrix that fits the grid.

Parameters:
map_vectorNDArray[np.float64]

Map (as a vector) to be reshaped.

Returns:
mapNDArray[np.float64]

Reshaped map.

class dsptoolbox.beamforming.SteeringVector(formulation: SteeringVectorType = SteeringVectorType.TrueLocation)

Bases: object

This class hosts the main equation to be used for the steering vector.

class dsptoolbox.beamforming.SteeringVectorType(*values)

Bases: Enum

Types of steering vectors. See [1] for details.

References

  • [1]: Sarradj, Ennes. (2012). Three-Dimensional Acoustic Source Mapping with Different Beamforming Steering Vector Formulations. Advances in Acoustics and Vibration. 2012. 10.1155/2012/292695.

Classic = 1
Inverse = 2
TrueLocation = 4
TruePower = 3
dsptoolbox.beamforming.mix_sources_on_array(sources: list | MonopoleSource, mics: MicArray, c: float = 343) → Signal

This function takes in a list containing multiple sources and gives back the multi-channel signal on the array of the combined sources.

Parameters:
sourceslist or MonopoleSource

List containing sources of object type MonopoleSource. It is also possible to pass a Source directly.

micsMicArray

Microphone array on which to mixed the sources.

cfloat, optional

Speed of sound in m/s. Default: 343.

Returns:
multi_channel_sigSignal

Multi-channel signal containing combined source’s signals.