Welcome to lakeator’s documentation!

class lakeator.Lakeator(mic_locations=((0.325, 0.0), (-0.16, 0.248), (-0.146, -0.258), (-0.001, 0.002)), file_path=None)

Used to locate the source of a sound in a multi-track .wav file.

The lakeator class may also be used to generate simulated data by means of the shift_sound method, which takes in a mono wav file and a set of coordinates and produces a multi-track wav simulating the data which would have been recorded were the signal to have came from the provided location.

Parameters:
  • mic_locations (array) – This is an Mx2 array containing the x,y coordinates of the M microphones in the array.
  • file_path (str) – If provided, the file at this filepath will be loaded into the lakeator.
sound_speed

The speed of sound in air. Defaults to 343.1 m/s.

Type:float
data

Numpy array to store the loaded data. Left public for convenience.

Type:np.array
sample_rate

The sample rate of the currently loaded WAV file.

Type:int
data = None

The current data, stored in a numpy array.

estimate_DOA_heatmap(method, xrange=(-50, 50), yrange=(-50, 50), xstep=False, ystep=False, colormap='bone', shw=True, block_run=True, no_fig=False, freq=False, signals=1, AF_freqs=(False, False), f_0=-1, array_GPS=False, save_GIS=False)

Displays a heatmap for visual inspection of correlation-based location estimation.

Generates a grid of provided dimension/resolution, and evaluates the selected DOA-estimation at each point on the grid. Vectorised for fast execution.

Parameters:
  • method (str) – One of; “GCC”, “MUSIC” or “AF-MUSIC”. The method to be used in heatmap generation.
  • xrange ((float, float)) – The lower and upper bound in the x-direction.
  • yrange ((float, float)) – The lower and upper bound in the y-direction.
  • xstep (float) – If given, determines the size of the steps in the x-direction. Otherwise defaults to 1000 steps.
  • ystep (float) – If given, determines the size of the steps in the y-direction. Otherwise defaults to 1000 steps.
  • colormap (str) – The colour map for the heatmap. See https://matplotlib.org/examples/color/colormaps_reference.html
  • shw (bool) – If False, return the axis object rather than display.
  • block_run (bool) – Pause execution of the file while the figure is open? Set to True for running in the command-line.
  • no_fig (bool) – If True, return the heatmap grid rather than plot it.
  • freq (float) – Frequency, in Hz, at which to calculate the MUSIC spectrum.
  • signals (int) – The number of signals to be localised. Only relevant for MUSIC-based methods.
  • AF_freqs ((float, float)) – Lower and upper bounds on the frequencies (in Hz) at which to evaluate the AF-MUSIC algorithm.
  • f_0 (float) – The reference frequency at which to calculate AF-MUSIC. Default of -1 uses the the midway point between AF_freqs.
  • array_GPS ((float, float)) – False, or tuple of GPS lat/long.
  • save_GIS (bool) – Save the image as a tif wth a corresponding .tif.points file for use in GIS software? Requires array_GPS
Returns:

Returns EITHER the current (filled) heatmap domain if no_fig == True, OR a handle to the displayed figure.
Return type:

np.array
estimate_DOA_path(method, path=<function Lakeator.<lambda>>, array_GPS=False, npoints=2500, map_zoom=20, map_scale=2, freq=False, AF_freqs=(False, False))

Gives an estimate of the source DOA along the path provided, otherwise along the unit circle if path is not present.

Parameters:
  • method (str) – One of; “GCC”, “MUSIC”, or “AF-MUSIC”. The method to use for DOA estimation.
  • path (str/function) – A filepath to a saved Google Earth path (in .kmz form), else a function f: [0,1]->R^2 to act as a parametrisation of the path at which to evaluate the DOA estimator.
  • npoints (int) – The number of points along the path to sample.
  • array_GPS (()) – !! REQUIRES CONVERSION TO PYPROJ !!
  • map_zoom (int) – Zoom level of GEarth imagery. See motionless documentation for more details.
  • map_scale (int) – Map scale of GEarth imagery. See motionless documentation for more details.
  • freq (float) – The frequency at which to evaluate the narrowband MUSIC algorithm, if using.
  • AF_freqs ((float, float)) – A lower and upper limit on the frequncies at which to eveluate the AF-MUSIC algorithm, if using.
heatmap_to_GIS(array_coords, EPSG, projected_EPSG=2193, target_EPSG=3857, filepath='./heatmap.tif')

Export the current heatmap domain to ./heatmap.tif, as well as an auxillary CPS file ./heatmap.tif.points which contains the georeferencing data for QGIS. Converts from `EPSG’ to `target_EPSG’ (default NZTM2000) (default WGS84/Pseudo-Mercator; the “Web Mecator Projection”) If changing target_EPSG, must be in cartesian coordinates to allow for addition of array_coords to bounding box dimensions.

Parameters:
  • array_coords ((float, float)) – The GPS coordinates of the center of the array (i.e. (0.0, 0.0)) in the order governed by ISO19111 (see https://proj.org/faq.html#why-is-the-axis-ordering-in-proj-not-consistent).
  • EPSG (int) – The EPSG code for the coordinate system which array_coords is in. See https://epsg.io/ for help finding the code.
  • projected_EPSG (int) – A local projected EPSG code. May be the same as the ‘EPSG’ argument, or may be different. This is used for calculation of the heatmap bounds.
  • target_EPSG (int) – The EPSG of your QGIS project. This will be the coordinate system in which the georeferencing data will be saved.
  • filepath (str) – The filepath for the saved heatmap output.
load(file_path, normalise: bool = True, GCC_processor='p-PHAT', do_FFTs=True, filter_f=(False, False), rho=0.73)

Loads the data from the .wav file, and computes the inter-channel correlations.

Correlations are computed, interpolated, and then stored within the lakeator object for use in the optimisation function or wherever necessary. Pass in a numpy array of data rather than loading from a file by setting raw_data = True.

Parameters:
  • file_path (str) – The file path of the WAV file to be read.
  • normalise (bool) – Normalise the data? This is a good idea, hence the truthy default state.
  • GCC_processor (str) – Which GCC processor to use. Options are: CC, PHAT, Scot, & RIR. See Table 1 of Knapp, C. et. al. (1976) “The Generalised Correlation Method for Estimation of Time Delay”
  • do_FFTs (bool) – Calculate the cross-correlations? Worth turning off to save time if only MUSIC-based algorithms are to be used.
  • filter_f ((float, float)) – Tuple of frequencies (in Hertz) between which to apply a bandpass filter.
sample_rate = None

The sample rate of the currently loaded data.

shift_sound(location, inputfile, output_filename, noisescale=0)

Creates a multi-track wav file from a mono one, simulating the array recordings had the sound came from the provided location and were recorded on the current virtual array’s microphone configuration.

Saves the resultant file in the current working directory with the provided filename, at the same sample rate as the input data.

Parameters:
  • location ((float, float)) – A tuple (x,y) providing the location in meters relative to the array at which to simulate the sound as having came from.
  • inputfile (str) – File path for the mono wav file to be used.
  • output_filename (str) – The desired file name for the output file.
  • noisescale (float) – Adds Gaussian white noise with standard deviation noisescale*(standard deviation of input file)
sound_speed = 343.1

The speed of sound in air to use in the calculations.

lakeator.UCA(n, r, centerpoint=True, show=False)

A helper function to easily set up UCAs (uniform circular arrays).

Parameters:
  • n (int) – The number of microphones in the array.
  • r (float) – The radius of the array, in meters.
  • centerpoint (bool) – Include a microphone at (0,0)? This will be one of the n points.
  • show (bool) – If True, shows a scatterplot of the array
Returns:

An (n x 2) numpy array, containing the x and y positions of the n microphones in the UCA.
Return type:

np.array
lakeator.UMA8(bearing=0, center=0)

Return an array containing the positions of the microphones in a miniDSP UMA-8 USB mic array, if centered at center and facing bearing bearing.

Parameters:
  • bearing (float) – Compass bearing of the USB port on the UMA-8.
  • center ((float, float)) – The coordinates at which to place the UMA-8.

Indices and tables