EchoMap

Summary

Note

EchoMap is a work in progress.

EchoMap is an experimental cross-platform digital signal processing application for sound-source localisation (SSL). In particular, given a series of co-located audio sensors (such as a towed array sonar), and associated time-varying signals captured from the sensors, the application attempts to determine the precise location of the source of the recorded signal.

The problem of SSL is not new, but this implementation strives to provide several interesting "quirks":

• Extremely user-friendly cross-platform interface with a pluggable architecture.
• Capability to delegate computationally intensive work to hardware accelerators, such as a graphics processing unit.
• Targets the WebAssembly platform to run entirely within any modern browser, using the WebGPU standard to make use of the accelerators.
• Free, open-source, permissively licensed, portable, modern C++26, interoperable persistence format (JSON and SQLite3) etc.

Existing FOSS implementations of SSL in desktop/web applications, such as ODAS, are widely available. Most will lack one of the above features, but will likely excel in many more unlisted capabilities!

Live Deployment

Pre-packaged native builds aren't available yet, but users wanting a taste of EchoMap can use the WebAssembly deployment available at https://www-users.york.ac.uk/~od641/echomap. Sample project files (JSON metadata and wave files) are similarly available to download at https://www-users.york.ac.uk/~od641/echomap/sample-resources.

For technical reasons (or, more precisely, because EchoMap intentionally uses modern features), the live deployment is only functional on Google Chrome or development builds of Firefox. This is due to the availability of a web technology called JavaScript Promise Integration (JSPI), which is elaborated upon in the Detailed Procedure subsection.

As the GitHub Action responsible for building and deploying EchoMap must be run manually by @oliverdixon with workflow_dispatch, it is possible that the live deployment may lag a couple of revisions behind master/HEAD.

Build Instructions

All build environments must have git and CMake >=4.0 available on the $PATH. Additional third-party dependencies are automatically fetched or recovered from the system cache during the bootstrap phase, which must be sourced for each terminal session in which CMake is invoked.

Quick Start for Desktop Users

$ source bootstrap.sh
$ cmake --preset native-release
$ cmake --build cmake-build-native-release
$ cmake-build-native-release/EchoMap

Quick Start for Web Users

$ source bootstrap.sh
$ cmake --preset wasm-release
$ cmake --build cmake-build-wasm-release
$ ./miniserve.sh cmake-build-wasm-release &
$ xdg-open http://localhost:8080/EchoMap.html
$ # Interact with EchoMap in the browser...
$ fg
$ # Control-C to kill the server.

miniserve is used to host the files in the above example, but any HTTP server will work. Users without a Rust toolchain installed may look to Python's http.server or Node's http-server.

Detailed Procedure

1. Source the /bootstrap.sh script into a Bash-compatible shell.

   • If the VCPKG_ROOT environment variable is unset, or does not indicate a valid vcpkg installation, the bootstrap script will fetch and configure the upstream into /third-party/vcpkg and export VCPKG_ROOT in the environment.
   • Likewise, if EMSDK is unset or does not indicate a valid Emscripten SDK installation, the bootstrap script will fetch, install, and activate the upstream SDK into /third-party/emsdk. EMSDK will be exported into the environment. At present, the SDK is bootstrapped for all Wasm and non-Wasm builds alike; this is inconsequential on subsequent invocations, and saves the inconvenience of configuring multiple toolchains in IDEs.
   • If you're using an IntelliJ-based IDE (CLion etc.), configure your toolchain to source /bootstrap.sh as an environment file. The script is sourced into a non-interactive shell, so a wrapper should be used to export any local environment variables prior to running the bootstrapper.
   • Advanced users with existing VCPKG or Emscripten SDK toolchains can skip the bootstrap and simply export VCPKG_ROOT or EMSDK in the CMakeUserPresets.json file, as demonstrated in the sample, to avoid duplicating existing toolchains.

2. Run CMake on one of the presets defined in /CMakePresets.json depending on build type and target type:

   • native-debug
   • native-release
   • wasm-debug
   • wasm-release

   For example, cmake --preset native-debug produces (by default) a Ninja script in cmake-build-native-debug. Note that CMake generation also sources the vcpkg toolchain file, which may incur a long runtime if dependencies are not already extant in the binary cache.

   Advanced users with a custom toolchain (e.g. upstream LLVM) can provide a /CMakeUserPresets.json to define a local profile, which is used to generate local variants of the existing presets. An example is given in /cmake/CMakeUserPresets_SAMPLE.json.

3. Build EchoMap. For example, cmake --build cmake-build-native-debug.

   • For native targets, this produces a statically linked Dawn executable in the build directory.
   • For wasm targets, this produces a WebAssembly bundle (WASM code and some HTML/CSS/JS boilerplate) in the build directory. Use any HTTP server, such as miniserve, to host the build directory. Note that since the Emscripten threading implementation uses a SharedArrayBuffer, the site must be cross-origin isolated. A helper script is provided for this purpose: /miniserve.sh cmake-build-wasm-debug.

4. For use of WebAssembly deployments, browsers must support JavaScript promise integration. Technically, this is necessary to support exception-handling and access to the asynchronous WebGPU API, which are both two sides of the same (stack-unwinding) coin. As of June 2026, Chrome stable supports JSPI; Firefox stable does not.

Documentation

"Documentation" refers to generated HTML from Doxygen. The HTML is fully reproducible from the source, so anybody wishing the review the docs can do any of the following:

• view the /** ... */ Doxygen comments in the source directly;
• view the rendered documentation online at https://www-users.york.ac.uk/~od641/echomap/docs/html/;
• clone the repo and run doxygen in the root; or
• clone the repo and use the CMake preset:

  $ cmake --preset documentation
  $ cmake --build docs/out/ --target EchoMapHTMLDocumentation
  $ docs/open.sh