https://github.com/raviumadi/array_wah
MATLAB tool for evaluating microphone array configurations via 3D localisation metrics. Generates error heatmaps and statistical insights to guide array design in acoustic research.
https://github.com/raviumadi/array_wah
bat-call-localisation bioacoustics echolocation field-experiments matlab microphone-array tdoa
Last synced: 8 months ago
JSON representation
MATLAB tool for evaluating microphone array configurations via 3D localisation metrics. Generates error heatmaps and statistical insights to guide array design in acoustic research.
- Host: GitHub
- URL: https://github.com/raviumadi/array_wah
- Owner: raviumadi
- License: other
- Created: 2025-06-02T10:51:18.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-18T15:25:55.000Z (12 months ago)
- Last Synced: 2025-08-16T22:32:37.649Z (10 months ago)
- Topics: bat-call-localisation, bioacoustics, echolocation, field-experiments, matlab, microphone-array, tdoa
- Language: MATLAB
- Homepage:
- Size: 3.01 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
# Array WAH: Widefield Acoustics Heuristic for 3D Localisation of Bat Calls
**Author**: Ravi Umadi
**Affiliation**: Technical University of Munich
**License**: [CC BY-NC-SA 4.0](LICENSE.md)
[](https://doi.org/10.5281/zenodo.15691372)
## Cite This Toolkit
This toolkit was developed for the research article:
**Widefield Acoustics Heuristic: Advancing Microphone Array Design for Accurate Spatial Tracking of Echolocating Bats**
Published article: [https://doi.org/10.1186/s12862-025-02441-4](https://doi.org/10.1186/s12862-025-02441-4)
If you use this toolkit, please also cite:
> **Ravi Umadi**. (2025). *Array WAH: Microphone Array Design Tool V1.1.0*. Zenodo.
> [https://doi.org/10.5281/zenodo.15691371](https://doi.org/10.5281/zenodo.15691371)
>
>
---
## Overview
**Array WAH** is a MATLAB-based simulation and analysis toolkit designed for designing, simulating, and benchmarking 3D microphone array geometries for precise acoustic localisation of ultrasonic bat calls.
It supports:
- Virtual bat call simulation
- Frequency-dependent propagation
- Time Difference of Arrival (TDOA) multilateration
- 3D grid sweep error mapping
- Statistical and visual analyses of localisation performance
The toolkit supports multiple array geometries, including:
- Tetrahedron
- Planar Square
- Pyramid
- Octahedron
- Custom Geometry
---
## Theory and Approach
Array WAH models the entire localisation chain:
### 1. Call Generation
Simulated bat calls are generated using two biologically relevant signal types:
#### **• Frequency-Modulated (FM) Sweeps**
FM calls are created as **quadratic down-sweeps** from a starting frequency f0 to an ending frequency f1 over a duration d. These mimic broadband echolocation signals produced by many insectivorous bats.
Key features:
- **Quadratic chirp** generation using MATLAB’s chirp() function.
- **Hanning window** applied to taper onset and offset, minimising spectral leakage.
- A **spectral shaping filter** (optional) is included in the code for more naturalistic bandwidth control.
- An **optional Doppler shift** is applied by resampling the chirp to simulate relative motion between the bat and the microphone.
- **Zero-padding** is added before and after the signal based on a user-specified tail percentage of the call duration.
#### **• Constant-Frequency (CF) Calls**
CF calls are generated as **pure tones** at a single frequency f1 over the duration d, typically used to simulate calls of species like horseshoe bats (*Rhinolophus*) or *Hipposideros*.
Features:
- **Sinusoidal tone** generation at a fixed frequency f1.
- **Hanning window** applied to prevent sharp transitions.
- **Doppler resampling** is supported for simulating motion.
- **Zero-padding** is added on both sides as with FM calls.
#### **• Doppler Shift Support**
Both FM and CF calls optionally include a **Doppler-induced time scaling**, simulating the compression or dilation of the waveform due to relative radial motion between the emitter and the microphones. This is controlled via the velocity parameter.
### 2. Signal Propagation
Signals experience frequency-dependent **atmospheric attenuation** and **geometric spreading**. Delays are applied using **fractional delay filters**.
### 3. Microphone Reception
Each mic receives a scaled and delayed version of the original call, according to its distance and orientation relative to the source.
### 4. TDoA Estimation
Cross-correlation is used to estimate **relative time delays** between each mic and a reference.
### 5. Localisation (Multilateration)
Using the TDoA vector, **nonlinear least squares** is used to estimate the 3D source position via multilateration.
### 6. Grid Sweep & Error Mapping
The process is repeated over a 3D grid of source locations. Positional and angular errors are computed and saved.
### 7. Analysis and Visualisation
- 3D scatter plots
- Histograms and boxplots
- Contour maps across elevation slices
- Statistics
---
## Folder Structure
```
Array_WAH/
│
├── src/ # All class definitions
│ ├──wah_analyzer.m
│ ├──mic_array_configurator.m
│ ├──BatCallLocaliser.m
│
├── configs/ # Saved mic array configurations (auto-generated)
├── results/ # Output CSVs and figures
│ └── figures/
│
├── simulate_batcall_localisation.m # Simulates calls and saves localisation results
├── demo_wah_analyzer.m # Loads CSVs and performs statistical analysis
├── demo_mic_array_configurator.m # Demo for mic_array_configurator
├── demo_test_single_point.m # Run a single point analysis for test mic configration and source location
├── effect_of_source_motion.m # Demonstrates source velocity effect on localisation accuracy of two call types.
├── startup.m # Adds src/ to path and checks dependencies
├── LICENSE
└── README.md
```
---
## Quickstart
### 1. Initialise
```matlab
run startup.m
```
This script:
- Adds `src/` to path
- Verifies required toolboxes
### 2. Simulate Localisation Data
```matlab
run simulate_batcall_localisation.m
```
Generates TDOA-based localisation results over a 3D grid for each array config.
### 3. Run Analysis
```matlab
run demo_wah_analyzer.m
```
Loads results and:
- Separates inliers/outliers
- Generates visualisations
- Performs ANOVA and Tukey tests
### 4. Visualise and Export Microphone Arrays
```matlab
run demo_mic_array_configurator.m
```
---
### Test Run a Single Point
```matlab
run demo_test_single_point.m
```
---
## 📦 Dependencies
| Toolbox | Required |
| --------------------------------------- | ------------------------------- |
| Signal Processing Toolbox | ✅ |
| Statistics and Machine Learning Toolbox | ✅ |
| Curve Fitting Toolbox | ⚠️ Optional (for fitting trends) |
If any are missing, install via:
```matlab
matlab.addons.install('toolboxName.mltbx')
```
---
## License
This project is licensed under the **Creative Commons Attribution-NonCommercial-ShareAlike 4.0** license ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)).
> ✔️ Free to use and modify
> ❌ No commercial use
> 📝 Please attribute: "Ravi Umadi, Array WAH (2025)"
---
## Acknowledgements
This project is part of my ongoing research and technological development into field-deployable, portable MCU-based multichannel microphone arrays. I thank my supervisor and colleagues at the Lehrstuhl für Zoologie at Weihenstephan.
### Related Work
- My work on BATSY4-Pro, codebase https://github.com/raviumadi/Embedded_Ultrasonics
- The preprint of BATSY4-Pro Multichannel Ultrasound Field Recorder is now available at : [10.1101/2025.08.11.669530](https://www.biorxiv.org/content/10.1101/2025.08.11.669530v1)
---
## Bug Reports / Feature Requests
Please open an issue or pull request on GitHub.