MicGeom¶

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.

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

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)

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

Acoular 25.03 documentation

MicGeom

MicGeom¶