{"id":29032503,"url":"https://github.com/raviumadi/array_wah","last_synced_at":"2025-10-15T04:03:13.315Z","repository":{"id":296923145,"uuid":"994699828","full_name":"raviumadi/Array_WAH","owner":"raviumadi","description":"MATLAB tool for evaluating microphone array configurations via 3D localisation metrics. Generates error heatmaps and statistical insights to guide array design in acoustic research.","archived":false,"fork":false,"pushed_at":"2025-06-18T15:25:55.000Z","size":3154,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-16T22:32:37.649Z","etag":null,"topics":["bat-call-localisation","bioacoustics","echolocation","field-experiments","matlab","microphone-array","tdoa"],"latest_commit_sha":null,"homepage":"","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raviumadi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-02T10:51:18.000Z","updated_at":"2025-06-18T15:25:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"152f73f8-777e-4dfc-ad5b-7e602f10f93e","html_url":"https://github.com/raviumadi/Array_WAH","commit_stats":null,"previous_names":["raviumadi/array_wah"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/raviumadi/Array_WAH","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raviumadi%2FArray_WAH","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raviumadi%2FArray_WAH/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raviumadi%2FArray_WAH/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raviumadi%2FArray_WAH/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raviumadi","download_url":"https://codeload.github.com/raviumadi/Array_WAH/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raviumadi%2FArray_WAH/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270781195,"owners_count":24643804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bat-call-localisation","bioacoustics","echolocation","field-experiments","matlab","microphone-array","tdoa"],"created_at":"2025-06-26T11:00:40.551Z","updated_at":"2025-10-15T04:03:13.288Z","avatar_url":"https://github.com/raviumadi.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Array WAH: Widefield Acoustics Heuristic for 3D Localisation of Bat Calls\n\n**Author**: Ravi Umadi\n**Affiliation**: Technical University of Munich\n**License**: [CC BY-NC-SA 4.0](LICENSE.md)\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15691372.svg)](https://doi.org/10.5281/zenodo.15691372)\n\n##  Cite This Toolkit\n\nThis toolkit was developed for the research article:  \n**Widefield Acoustics Heuristic: Advancing Microphone Array Design for Accurate Spatial Tracking of Echolocating Bats**  \n\nPublished article: [https://doi.org/10.1186/s12862-025-02441-4](https://doi.org/10.1186/s12862-025-02441-4)\n\nIf you use this toolkit, please also cite:\n\n\u003e **Ravi Umadi**. (2025). *Array WAH: Microphone Array Design Tool V1.1.0*. Zenodo.  \n\u003e [https://doi.org/10.5281/zenodo.15691371](https://doi.org/10.5281/zenodo.15691371)\n\u003e\n\u003e \n---\n## Overview\n\n**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.\n\nIt supports:\n\n- Virtual bat call simulation\n- Frequency-dependent propagation\n- Time Difference of Arrival (TDOA) multilateration\n- 3D grid sweep error mapping\n- Statistical and visual analyses of localisation performance\n\nThe toolkit supports multiple array geometries, including:\n\n- Tetrahedron\n- Planar Square\n- Pyramid\n- Octahedron\n- Custom Geometry\n\n---\n\n## Theory and Approach\n\nArray WAH models the entire localisation chain:\n\n###  1. Call Generation\n\nSimulated bat calls are generated using two biologically relevant signal types:\n\n#### **• Frequency-Modulated (FM) Sweeps**\n\nFM 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.\n\nKey features:\n\n- **Quadratic chirp** generation using MATLAB’s chirp() function.\n- **Hanning window** applied to taper onset and offset, minimising spectral leakage.\n- A **spectral shaping filter** (optional) is included in the code for more naturalistic bandwidth control.\n- An **optional Doppler shift** is applied by resampling the chirp to simulate relative motion between the bat and the microphone.\n- **Zero-padding** is added before and after the signal based on a user-specified tail percentage of the call duration.\n\n#### **• Constant-Frequency (CF) Calls**\n\nCF 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*.\n\nFeatures:\n\n- **Sinusoidal tone** generation at a fixed frequency f1.\n- **Hanning window** applied to prevent sharp transitions.\n- **Doppler resampling** is supported for simulating motion.\n- **Zero-padding** is added on both sides as with FM calls.\n\n#### **• Doppler Shift Support**\n\nBoth 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.\n\n###  2. Signal Propagation\n\nSignals experience frequency-dependent **atmospheric attenuation** and **geometric spreading**. Delays are applied using **fractional delay filters**.\n\n###  3. Microphone Reception\n\nEach mic receives a scaled and delayed version of the original call, according to its distance and orientation relative to the source.\n\n### 4. TDoA Estimation\n\nCross-correlation is used to estimate **relative time delays** between each mic and a reference.\n\n###  5. Localisation (Multilateration)\n\nUsing the TDoA vector, **nonlinear least squares** is used to estimate the 3D source position via multilateration.\n\n###  6. Grid Sweep \u0026 Error Mapping\n\nThe process is repeated over a 3D grid of source locations. Positional and angular errors are computed and saved.\n\n###  7. Analysis and Visualisation\n\n- 3D scatter plots\n- Histograms and boxplots\n- Contour maps across elevation slices\n- Statistics\n\n---\n\n##  Folder Structure\n\n```\nArray_WAH/\n│\n├── src/                      # All class definitions\n│   ├──wah_analyzer.m\n│   ├──mic_array_configurator.m\n│   ├──BatCallLocaliser.m\n│\n├── configs/                  # Saved mic array configurations (auto-generated)\n├── results/                  # Output CSVs and figures\n│   └── figures/\n│\n├── simulate_batcall_localisation.m      # Simulates calls and saves localisation results\n├── demo_wah_analyzer.m       # Loads CSVs and performs statistical analysis\n├── demo_mic_array_configurator.m      # Demo for mic_array_configurator\n├── demo_test_single_point.m # Run a single point analysis for test mic configration and source location\n├── effect_of_source_motion.m # Demonstrates source velocity effect on localisation accuracy of two call types.\n├── startup.m          # Adds src/ to path and checks dependencies\n├── LICENSE\n└── README.md\n```\n\n---\n\n##  Quickstart\n\n### 1. Initialise\n\n```matlab\nrun startup.m\n```\n\nThis script:\n\n- Adds `src/` to path\n- Verifies required toolboxes\n\n### 2. Simulate Localisation Data\n\n```matlab\nrun simulate_batcall_localisation.m\n```\n\nGenerates TDOA-based localisation results over a 3D grid for each array config.\n\n### 3. Run Analysis\n\n```matlab\nrun demo_wah_analyzer.m\n```\n\nLoads results and:\n\n- Separates inliers/outliers\n- Generates visualisations\n- Performs ANOVA and Tukey tests\n\n### 4. Visualise and Export Microphone Arrays\n\n```matlab\nrun demo_mic_array_configurator.m\n```\n\n---\n\n### Test Run a Single Point\n```matlab\nrun demo_test_single_point.m\n```\n\n---\n## 📦 Dependencies\n\n| Toolbox                                 | Required                        |\n| --------------------------------------- | ------------------------------- |\n| Signal Processing Toolbox               | ✅                               |\n| Statistics and Machine Learning Toolbox | ✅                               |\n| Curve Fitting Toolbox                   | ⚠️ Optional (for fitting trends) |\n\nIf any are missing, install via:\n\n```matlab\nmatlab.addons.install('toolboxName.mltbx')\n```\n\n---\n\n## License\n\nThis 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/)).\n\n\u003e ✔️ Free to use and modify  \n\u003e ❌ No commercial use  \n\u003e 📝 Please attribute: \"Ravi Umadi, Array WAH (2025)\"\n\n---\n\n##  Acknowledgements\n\nThis 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.\n\n### Related Work\n\n- My work on BATSY4-Pro, codebase https://github.com/raviumadi/Embedded_Ultrasonics\n- 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)\n\n---\n\n##  Bug Reports / Feature Requests\n\nPlease open an issue or pull request on GitHub.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraviumadi%2Farray_wah","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraviumadi%2Farray_wah","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraviumadi%2Farray_wah/lists"}