Ultrasonic level measurement, simulated.
Configure a vessel and a stored material, pick a real ultrasonic sensor from a catalog of ten real devices, and watch it work - or fail - with the acoustic physics rendered in 3D view with real-time measurement data.
Echogram is a simulation tool for the visual demonstration and analysis of ultrasonic level measurement. It puts the concepts and characteristics that define the technique - blind zone, beam spread and beam footprint, time of flight, echo amplitude against a detection threshold, angle of repose, signal loss to dust and foam, and the analog and discrete output behaviour built on top of them - into a model you can configure, run, and watch respond. This is a proof of concept, not an engineering tool.
- Application setup. Build the vessel and its contents: silo or tank geometry, the stored material from a cited library, sensor mounting position and offset, ambient temperature, and the process conditions the measurement has to survive.
- Sensor selection. Ten real devices with their datasheet specifications, ranked against the application you configured, or a custom sensor defined by hand for comparison.
- Live measurement. Reported distance and level alongside the true values, with the inventory error between them - updating at the selected device's own repetition rate rather than the frame rate, so response lag is something you can see.
- Output configuration and behaviour. A 4-20 mA or 0-10 V span, discrete switching in hysteresis or window mode, and the fault behaviour on echo loss - hold, downscale or upscale - all simulated as the level moves. Feed the output back into two-point or modulating control and run the loop.
- 3D view and A-scan. The beam, the surface it lands on and the echo it returns, drawn next to the amplitude-versus-time-of-flight trace an ultrasonic engineer actually reads.
- Failure modes, made legible. Repose bias that changes sign between a fill and a discharge; a wall echo that is weaker than the surface echo but arrives earlier and wins; material sitting inside the blind zone; echoes that fall under threshold as dust rises or foam builds. Each one raises a warning explaining what broke and why.
- Portable configurations. The whole setup exports to a JSON parameter file and imports back, the way an instrument tool saves a device configuration.
Inputs are sourced. Every sensor specification is transcribed from the manufacturer's datasheet and carries a source URL. A value that could not be found is null and handled as null, never estimated - data/ is TypeScript so source can be non-optional and an uncited entry is a compile error. Material constants are cited the same way.
The model is not validated. Nothing here has been checked against a real device on a real vessel. The formulas are textbook acoustics and the behaviour is internally consistent, which is weaker than correct. Trust the ordering and sign of an effect, not the magnitude.
Three quantities cannot be sourced and are labelled as assumptions in the app's modelling panel:
| assumption | what it is |
|---|---|
| beam angle | digitized off each manufacturer's published response curve, not a tabulated figure - treat as ±1–2° |
| surface return & path attenuation | ordinal reasoning about scattering; no published table of ultrasonic reflectivity for bulk solids in air exists |
| scatter in the 3D view | drawn as illustration, never solved - it reaches no A-scan, reported value or rule |
None of them live in the physics core: every unsourceable value is injected, so a module that cannot be given a hidden constant cannot acquire one. A fourth, the acoustic power adjustment, was removed rather than assumed - no manufacturer publishes its numeric span, so sensitivity is modelled where it physically acts, as the detection threshold, which needs no constant.
Simplified on purpose. Beam and wall intersection is analytic rather than a wave solver, angle of repose is a material constant rather than a granular simulation, and diffuse scattering and multipath beyond the first wall echo are not solved at all.
Manufacturer names and part numbers appear as factual reference. This project is not affiliated with, endorsed by, or connected to any manufactor or company.
src/
sim/ physics core - pure, tested, no React, no Three, no DOM
rules/ applicability + live warning rules - pure, tested
data/ sensor catalog, material library, presets, assumptions - each entry cited
state/ configuration store, URL serialization
scene/ React Three Fiber components
ui/ wizard steps and panels
sim/ and rules/ know nothing about React, Three or the DOM; everything else may depend on them, never the reverse. Enforced by lint, not by good intentions - see eslint.config.js.
npm install
npm test # 414 tests over sim, rules, data and state - pure, no browser
npm run dev
npm run buildnpm run typecheck and npm run lint complete the set CI runs. The test suite pins the model's internal consistency; it is not evidence that the model matches reality.
MIT. See LICENSE.