`microphones`#

Implements support for array microphone arrangements.

MicGeom

Provide the geometric arrangement of microphones in an array.

class acoular.microphones.MicGeom#

Bases: HasStrictTraits

Provide the geometric arrangement of microphones in an array.

This class allows you to define, import, and manage the spatial positions of microphones in a microphone array. The positions can be read from an XML file or set programmatically. Invalid microphones can be excluded by specifying their indices via invalid_channels.

Unit of length

The source code is agnostic to the unit of length. The microphone positions’ coordinates are assumed to be in meters. This is consistent with the standard Environment class which uses the speed of sound at 20°C at sea level under standard atmosphere pressure in m/s. If the microphone positions’ coordinates are provided in a unit other than meter, it is advisable to change the c attribute to match the given unit.

Notes

The microphone geometry as in total_pos is automatically changed if the file attribute is updated.
Small numerical values in the computed center are set to zero for numerical stability.

Examples

To set a microphone geomerty for n programmatically, first a (3,n) array is needed. In this case we’ll use n=9 and generate an array containing the positional data.

>>> import numpy as np
>>>
>>> # Generate a (3,3) grid of points in the x-y plane
>>> x = np.linspace(-1, 1, 3)  # Generate 3 points for x, from -1 to 1
>>> y = np.linspace(-1, 1, 3)  # Generate 3 points for y, from -1 to 1
>>>
>>> # Create a meshgrid for 3D coordinates, with z=0 for all points
>>> X, Y = np.meshgrid(x, y)
>>> Z = np.zeros_like(X)  # Set all z-values to 0
>>>
>>> # Stack the coordinates into a single (3,9) array
>>> points = np.vstack([X.ravel(), Y.ravel(), Z.ravel()])
>>> points
array([[-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.],
       [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])

Now, to implement this array as a microphone geomertry, create a MicGeom object and assign the array to it the by using the pos_total attribute:

>>> from acoular import MicGeom
>>> mg = MicGeom(pos_total=points)
>>> mg.pos
array([[-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.],
       [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])

The microphones along the diagonal can be removed by setting their indices in the invalid_channels attribute:

>>> mg.invalid_channels = [0, 4, 9]
>>> mg.pos
array([[ 0.,  1., -1.,  1., -1.,  0.,  1.],
       [-1., -1.,  0.,  0.,  1.,  1.,  1.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.]])

But they will still be included in pos_total:

>>> mg.pos_total
array([[-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.],
       [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])

To export this microphone geometry, use the export_mpos() method. Note that the microphones marked as invalid in invalid_channels will not be exported.

>>> mg.export_mpos('micgeom.xml')

The newly generated micgeom.xml file looks like this:

<?xml version="1.1" encoding="utf-8"?><MicArray name="micgeom">
  <pos Name="Point 1" x="0.0" y="-1.0" z="0.0"/>
  <pos Name="Point 2" x="1.0" y="-1.0" z="0.0"/>
  <pos Name="Point 3" x="-1.0" y="0.0" z="0.0"/>
  <pos Name="Point 4" x="1.0" y="0.0" z="0.0"/>
  <pos Name="Point 5" x="-1.0" y="1.0" z="0.0"/>
  <pos Name="Point 6" x="0.0" y="1.0" z="0.0"/>
  <pos Name="Point 7" x="1.0" y="1.0" z="0.0"/>
</MicArray>

Note that when importing a microphone geometry, the XML file needs to look similar to this one: There must be <pos> elements with Name, x, y, and z attributes.

To load this same file as a new MicGeom object, the micgeom.xml file can be assigned to the file attribute:

>>> new_mg = MicGeom(file='micgeom.xml')
>>> new_mg.pos
array([[ 0.,  1., -1.,  1., -1.,  0.,  1.],
       [-1., -1.,  0.,  0.,  1.,  1.,  1.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.]])

file = Union(None, File(filter=['*.xml'], exists=True), desc='name of the xml file to import')#: Path to the XML file containing microphone positions. The XML file should have elements with the tag pos and attributes Name, x, y, and z.

pos_total = CArray(dtype=float, shape=(3, None), desc='x, y, z position of all microphones')#: Array containing the x, y, z positions of all microphones, including invalid ones, shape (3, num_mics ). This is set automatically when file changes or explicitly by assigning an array of floats. All coordinates are in meters by default (see here).

pos = Property(depends_on=['pos_total', 'invalid_channels'], desc='x, y, z position of used microphones')#: Array containing the x, y, z positions of valid microphones (i.e., excluding those in invalid_channels), shape (3, num_mics ). (read-only) All coordinates are in meters by default (see here).

invalid_channels = List(int, desc='list of invalid channels')#: List of indices indicating microphones to be excluded from calculations and results. Default is [].

num_mics = Property(depends_on=['pos'], desc='number of microphones in the geometry')#: Number of valid microphones in the array. (read-only)

center = Property(depends_on=['pos'], desc='array center')#: The geometric center of the array, calculated as the arithmetic mean of the positions of all valid microphones. (read-only)

aperture = Property(depends_on=['pos'], desc='array aperture')#: The maximum distance between any two valid microphones in the array. (read-only)

digest = Property(depends_on=['pos'])#: A unique identifier for the geometry, based on its properties. (read-only)

export_mpos(filename)#

Export the microphone positions to an XML file.

This method generates an XML file containing the positions of all valid microphones in the array. Each microphone is represented by a <pos> element with Name, x, y, and z attributes. The generated XML is formatted to match the structure required for importing into the MicGeom class.

Parameters:

filenamestr: The path to the file to which the microphone positions will be written. The file extension must be .xml.

Raises:

OSError: If the file cannot be written due to permissions issues or invalid file paths.

Notes

The file will be saved in UTF-8 encoding.
The Name attribute for each microphone is set as "Point {i+1}", where i is the index of the microphone.
This method only exports the positions of the valid microphones (those not listed in invalid_channels).
All coordinates (x, y, z) are exported in meters by default (see here).

microphones#

`microphones`#