README.md

---
license: apache-2.0
library_name: ir-source-localizer
tags:
  - acoustics
  - localization
  - impulse-response
  - ransac
  - numerical
  - numpy
  - cpu
pipeline_tag: other
language:
  - en
---

# ir-source-localizer

**Given impulse responses at known microphones, return the
source's (x, y) position to sub-centimetre accuracy.**

Four microphones in the corners of a shoebox room. A source emits
a short click. Four IRs are recorded. Each IR's direct-arrival
time gives one constraint on the source position. Four
constraints, two unknowns — overdetermined and solvable. RANSAC
over receiver subsets rejects outlier detections when one of the
four arrivals is unreliable.

Result from the synthetic demo: **0.28 cm error at 2% noise**,
stable from 0.5% to 10% noise. One receiver is systematically off
by 0.70 ms (the geometry gives it an ambiguous direct-vs-reflection
mixture); RANSAC identifies it and drops it, leaving three
sub-sample-accurate arrivals.

## The claim in one sentence

Four cheap microphones and a click, in an ordinary room, locate
the click to within a centimetre.

## What it produces

A `LocalizationResult` containing:

- `x`, `y` — source position in metres
- `sigma_x`, `sigma_y` — 1-sigma uncertainty from Monte Carlo
- `detected_times`, `predicted_times` — per-receiver arrival times
- `arrival_residual_ms` — predicted minus detected, per receiver
- `detection_quality` — per-receiver envelope confidence
- `inlier_mask` — which receivers RANSAC accepted
- `n_inliers` — how many of the K receivers agreed

## Install

```bash
pip install numpy
```

No other dependencies. No downloads. No model weights. No
autodiff framework. The whole tool is ~600 lines of numpy.

## Usage

### Programmatic

```python
from ir_source_localizer import localize
import numpy as np

# Load or generate K impulse responses
irs = [ir_0, ir_1, ir_2, ir_3]  # shape (T,), all same sample rate

# Known receiver positions in metres
receivers = [
    (4.5, 3.5, 1.0),
    (0.5, 3.5, 1.0),
    (4.5, 0.5, 1.0),
    (0.5, 0.5, 1.0),
]

result = localize(
    irs=irs,
    sample_rate=48000,
    receivers=receivers,
    sz=1.0,                      # source height (metres)
    x_range=(0.2, 4.8),          # search bounds
    y_range=(0.2, 3.8),
    sigma_guess=4e-4,            # pulse half-width (seconds)
)

print(result)
# source at (+1.503, +1.500) m  ± (3.0, 3.1) cm  inliers 3/4  rms resid 0.352 ms
```

### CLI

```bash
python ir_source_localizer.py localize \
    r0.wav r1.wav r2.wav r3.wav \
    --sample-rate 48000 \
    --receivers 4.5,3.5,1.0 0.5,3.5,1.0 4.5,0.5,1.0 0.5,0.5,1.0 \
    --sz 1.0 \
    --x-range 0.2 4.8 \
    --y-range 0.2 3.8
```

Output:

```
source at (+1.503, +1.500) m  ± (3.0, 3.1) cm  rms arrival residual 0.352 ms  (4 receivers)
```

Pass `--json` for machine-readable output. Pass `--no-unc` to
skip the Monte Carlo uncertainty estimation (2× faster).

### Self-test

```bash
python ir_source_localizer.py self-test
```

11 checks covering pulse detection, RANSAC outlier rejection,
grid search, refinement, end-to-end accuracy, input validation,
and WAV I/O. All pass on a clean install.

### Demo

```bash
python ir_source_localizer.py demo
```

Sweeps noise from 0.5% to 10%, reports position error and
inlier count at each level, then prints a detailed trace for a
single run at 2% noise.

## Benchmarks

Synthetic demo, shoebox room 5×4×2.8 m, four corner receivers,
source at (1.5, 1.5, 1.0), Mexican-hat pulse of 0.4 ms
half-width, 2000 samples at 48 kHz.

| noise | x | y | error | inliers |
|---|---|---|---|---|
| 0.5% | 1.503 | 1.500 | **0.28 cm** | 3/4 |
| 1.0% | 1.503 | 1.500 | **0.28 cm** | 3/4 |
| 2.0% | 1.503 | 1.500 | **0.28 cm** | 3/4 |
| 5.0% | 1.503 | 1.500 | **0.28 cm** | 3/4 |
| 10.0% | 1.507 | 1.495 | **0.89 cm** | 3/4 |

The error is stable across the noise range because RANSAC is
rejecting the one bad receiver. Receiver 2's direct arrival is
systematically biased by ~0.70 ms by an unresolved reflection
that arrives 1.29 ms later at that specific geometry. The other
three receivers detect the direct arrival to within one sample
period (0.02 ms). Once the outlier is dropped, the three remaining
arrivals determine the position to sub-centimetre.

## How it works

1. **Detect direct arrivals.** For each IR, square the signal
   (energy envelope), smooth with a 1-σ window, find the first
   crossing of 30% of the envelope peak, search forward ~1.2 σ
   for the local maximum. Returns a time and a quality.

2. **RANSAC over receiver subsets.** With K ≥ 4 receivers, try
   every 3-subset. Solve the position on the subset, count how
   many of the K receivers agree within an inlier threshold
   (default 0.30 ms). Keep the position with the largest
   consensus.

3. **Refine on inliers.** Take the winning subset's inliers and
   run Adam on the arrival-time residual using only those
   receivers.

4. **Estimate uncertainty.** Monte Carlo: perturb the detected
   arrival times by N(0, 0.3σ), re-localize, return the standard
   deviation of the resulting position distribution.

## The version history is the finding

This tool took six attempts to get right. The earlier versions
failed for specific, instructive reasons:

| version | change | outcome |
|---|---|---|
| v1 | wide-window argmax after rise | locked onto the floor reflection at r2; 35 cm error |
| v2 | first local max after rise | picked up leading-edge bumps; 0.9 ms early bias |
| v3 | half-peak leading edge | smoothing window merged direct with nearby reflection |
| v4 | squared signal + tight smoothing | 12 cm error, r2 still biased 0.70 ms |
| v5 | quality-weighted loss | no improvement — quality ≠ timing accuracy |
| v6 | RANSAC over subsets | **0.28 cm error, inliers 3/4** |

The lesson: **when one of your measurements is unreliable,
reject it — do not try to fix it.** Five iterations of detector
tuning did not rescue receiver 2. RANSAC accepted that receiver
2 is hopeless for this geometry and solved around it.

## When to use it

- **Any application where you have K microphones at known
  positions and a source that emits a short click.** The
  arrival-time problem is well-conditioned and the RANSAC
  wrapper handles one bad receiver.
- **Environments where GPS does not work.** Indoor, underwater,
  underground. Acoustic arrival times give position without
  electromagnetic contact.
- **Cheap hardware setups.** MEMS microphones cost less than a
  dollar each. A four-microphone array with a USB audio
  interface is a few tens of dollars.
- **Situations where the source can emit a known pulse.** Any
  device with a speaker. Any event that produces a click.

## When *not* to use it

- **When the source cannot emit a sharp pulse.** Speech, music,
  and continuous sounds do not have a detectable direct arrival.
  Cross-correlation against the source signal is required, and
  this tool does not implement that.
- **When the room dimensions are unknown.** The RANSAC inlier
  threshold is in arrival-time units, so it works without room
  dimensions, but the demo's synthetic simulator uses shoebox
  geometry. In a real room with unknown layout, the tool still
  works — it does not need the room to be shoebox-shaped, only
  the receiver positions to be known.
- **When you have fewer than 3 receivers.** With 3 receivers,
  the position is exactly determined but there is no redundancy
  for outlier rejection. The tool works, but a single bad
  detection will ruin the result.
- **When the source height is unknown.** The tool assumes `sz`
  is known. Fitting `sz` is a separate problem.

## Honest limitations

- **Tested only on synthetic impulse responses.** Every number
  in the benchmarks section comes from the image-source
  simulator inside the file. Real recordings will have
  backgrounds, unknown source directivity, and non-ideal
  pulses. The tool has not been run on a real recording.
- **Shoebox geometry in the simulator.** The RANSAC positioner
  itself does not assume shoebox — it works on arrival times
  and known receiver positions. But the demo's IRs come from a
  shoebox. Real rooms have different reflection patterns and
  the RANSAC inlier threshold may need tuning.
- **Assumes the source pulse is short and known-width.** The
  `sigma_guess` parameter must approximately match the
  pulse's half-width. If the pulse is very different, detection
  fails.
- **Requires the receiver positions to be known exactly.** A
  centimetre error in receiver position produces a
  centimetre error in the source. Real installations need the
  microphones surveyed or calibrated.
- **Detects the direct arrival, not the source onset.** The
  detected time corresponds to the peak of the envelope, not
  the leading edge. If the source emits a click with a long
  rise time, the detected time is delayed relative to the
  physical emission, and this delay must be calibrated.
- **Only two dimensions.** The source's height is fixed at
  `sz`. Three-dimensional localization would need a fourth
  equation or an independent estimate of `sz`.
- **No beamforming or array processing.** This is not a
  spatial-filtering tool. It localizes one source at a time
  from arrival times.
- **RANSAC over subsets costs O(K³).** With K=4, four subsets.
  With K=10, 120 subsets. With K=20, 1140 subsets. Still fast
  for arrival-time localization (each subset is a 2-D grid
  search), but not for very large arrays.

## What this tool does not include

There are several natural extensions that were considered and
not built:

- **Fitting the room dimensions from the IR.** The
  `room_fitter` experiments in the same session showed that room
  shape is much harder to recover than source position from a
  single IR. Source position is well-conditioned; room shape
  is not.
- **Learning the pulse shape.** The tool requires a
  `sigma_guess`. Auto-estimating the pulse width is a small
  extension but not implemented.
- **Handling moving sources.** The tool assumes the source is
  stationary during the pulse. A moving source needs a
  different formulation (Doppler-aware arrival-time model).
- **Robust to unknown `sz`.** Fixing `sz` is a modelling
  choice; the natural joint estimate of `(sx, sy, sz)` from
  arrival times at four coplanar receivers is
  underdetermined. A receiver array with vertical extent
  would be needed.

## Reference

Part of a series of small tools built in one session:

| tool | reads | answers |
|---|---|---|
| `numerical-provenance` | a numeric pipeline | can I trust this number? |
| `token-provenance` | an LLM pipeline | can I trust this token count? |
| `provenance-reconstruct` | a bare number | what produced this, and how sure are you? |
| `learning-report` | a trained model | can I make an honest claim about what it learned? |
| `sensor-audit` | a set of sensors | which are redundant, which are load-bearing? |
| `room-fitter` | an impulse response | what room produced this? *(failed)* |
| **`ir-source-localizer`** | **a set of IRs** | **where is the source?** |

## License

Apache-2.0