feat: add OneEuro (1€ filter) smoothing utility

[edumeneses]

Summary

Adds puara_gestures::utils::OneEuro, an implementation of the 1€ filter (Casiez, Roussel & Vogel, CHI 2012). It is a speed-adaptive low-pass: it filters hard when the signal is still (removes jitter) and eases off when the signal moves fast (keeps responsiveness), trading jitter against lag far better than a fixed low-pass or moving average.

This is the de-facto standard smoothing stage for interactive sensors and controllers, and slots in front of any Puara descriptor.

API

puara_gestures::utils::OneEuro smoother{1.0, 0.007}; // mincutoff, beta
double clean = smoother.filter(analogRead(A0));       // clock-timed
double clean = smoother.filter(value, dt);            // explicit step (seconds)

• mincutoff — cutoff (Hz) at rest; lower = smoother but laggier
• beta — how much the cutoff opens with speed; higher = less lag on fast moves
• dcutoff — derivative cutoff (Hz), rarely changed
• current_value — last output; reset() clears state

Conventions kept

• Header-only, #pragma once, puara_gestures::utils namespace
• Public current_value like LeakyIntegrator
• Monotonic clock (getCurrentTimeMicroseconds) → Arduino loop(), thread, or ossia process
• Doubles only, self-contained pi constant — no STL/Boost/allocation

Files

• include/puara/utils/oneeuro.h
• registered in include/puara/utils.h
• examples/arduino/utils/oneeuro/oneeuro.ino
• Catch2 tests in tests/test_utils.cpp ([utils][oneeuro])
• README utility list entry

Testing

• OneEuro: 21 assertions / 4 cases pass (first-sample passthrough, constant-signal stability, monotonic step-response lag, jitter-rejection vs fast-tracking tradeoff)
• Full utils suite: 156 assertions / 27 cases pass (no regressions)

🤖 Generated with Claude Code

https://claude.ai/code/session_0163cH7Znu2oYvnaP7fTEQMN

[jcelerier]

std::numbers::pi

[edumeneses]

Hi @jcelerier — I'm an AI assistant (Claude Code) working on this branch with @emeneses; flagging that up front.

I looked into using std::numbers::pi here and decided against it, for portability reasons:

• std::numbers::pi requires C++20 <numbers>. It compiles fine in the desktop test build (it forces -std=c++20), but on the embedded side it is a regression: older arduino-esp32 cores (2.x) and various Arduino IDE cores default to gnu++11, where <numbers> is unavailable, so the header would fail to compile there.
• The library already standardizes on M_PI with a Boost fallback for exactly this reason — see utils.h and wrap.h:

  #ifndef M_PI
  #define M_PI boost::math::constants::pi<double>()
  #endif

  Boost is already a hard dependency (shimmed on Arduino via boost-embedded-190).

So instead of the hardcoded literal I switched to M_PI — same value, matches the surrounding code, and stays portable across cores. oneeuro.h does not include puara/utils.h, so it carries the same guarded M_PI define locally, like wrap.h does. I applied the same change to the two other new headers that had a hardcoded pi (heading.h, multitouch.h).

Happy to move everything to std::numbers::pi if you would rather set a C++20 floor for the library as a whole — just let me know and I will switch them over.