filters Reference

Module defined in lua/common/filters.lua. Comprehensive signal processing library providing frequency filters, temporal smoothing, frequency detection, exponential smoothing, line fitting, and more. Core infrastructure for vehicle physics simulation.

---

Exports

All exports are global constructors (no module table).

Frequency Domain

newFreqFilter1()

Creates a 1st-order frequency filter with low-pass, high-pass, band-pass, and band-stop modes.

• Returns: freqFilter1 - Filter object

Methods:

• filter:getLowPassFreq(sample, dt, cutOffFreq) → number
• filter:getLowPassPeriod(sample, dt, cutOffPeriod) → number
• filter:getHighPassFreq(sample, dt, cutOffFreq) → number
• filter:getHighPassPeriod(sample, dt, cutOffPeriod) → number
• filter:getBandPassFreq(sample, dt, lowFreq, highFreq) → number
• filter:getBandPassPeriod(sample, dt, lowPeriod, highPeriod) → number
• filter:getBandStopFreq(sample, dt, lowFreq, highFreq) → number
• filter:getBandStopPeriod(sample, dt, lowPeriod, highPeriod) → number

newFreqDetector()

Creates a frequency detector that estimates period, amplitude, and DC bias of an oscillating signal.

• Returns: freqDetector

Methods:

• detector:get(sample, dt) → period, amplitude, peakDt, bias
• detector:reset()
• detector:value(dt) → period, amplitude, peakDt, bias

newFreqExists()

Goertzel algorithm implementation - detects the presence/amplitude of a specific frequency in a signal.

• Returns: freqExists

Methods:

• fe:get(sample, dt, freq, cycleCount) → amplitude
• fe:getS(sample, dt, freq, winCoef) → sliding amplitude
• fe:bufferStart(dt, freq) / fe:bufferAdd(sample) / fe:bufferEnd() → amplitude
• fe:reset()

freqGenC(period, ampl, t)

Generates a cosine wave value: cos(t * 2π / period) * ampl.

• Returns: number

Temporal Smoothing

newTemporalSpring(spring, damp, startingValue)

Spring-damper temporal smoother.

• Methods: get(sample, dt), getWithSpringDamp(sample, dt, spring, damp), set(sample), value()

newTemporalSigmoidSmoothing(inRate, startAccel, stopAccel, outRate, startingValue)

S-curve temporal smoother with acceleration control.

• Methods: get(sample, dt), getWithRateAccel(sample, dt, ratelimit, startAccel, stopAccel), set(window, weight, bias), reset(), value()

newTemporalSmoothingNonLinear(inRate, outRate, startingValue)

Exponential/non-linear temporal smoother.

• Methods: get(sample, dt), getWithRate(sample, dt, rate), set(window, weight, bias), value(), reset()

newTemporalSmoothing(inRate, outRate, autoCenterRate, startingValue)

Linear temporal smoother with separate in/out rates and optional auto-centering.

• Methods: get(sample, dt), getUncapped(sample, dt), getCapped(sample, dt), getWithRate(sample, dt, rate), getWithRateCapped(sample, dt, rate), set(v), reset(), value()

Fixed-dt Smoothing

newLinearSmoothing(dt, inRate, outRate)

Linear smoother for fixed timestep use (pre-bakes dt into rates).

• Methods: get(sample), set(v), reset()

newNopSmoothing()

Bypass/passthrough filter - returns input unchanged.

• Methods: get(sample), set(), reset()

Exponential Smoothing

newExponentialSmoothing(window, startingValue, fixedDt)

EMA (Exponential Moving Average) filter.

• Methods: get(sample), getWindow(sample, window, window2), value(), set(value), reset(value)

newExponentialSmoothingT(window, window2, startingValue)

EMA with trend tracking for improved responsiveness to direction changes.

• Methods: get(sample), getWindow(sample, window, window2), value(), set(value), reset(value)

Line Fitting

newLineFitting(window, weight, bias, scale)

Exponentially weighted least-squares linear regression.

• Methods: get(x, y) → weight, bias; value() → weight, bias; getY(x) → number; set(window, weight, bias); reset()

Note: The following are instance methods on specific filter types, not standalone globals:

• temporalSmoothing:getCapped(sample, dt) - Filtered value capped to max magnitude
• exponentialSmoothing:getWindow(sample, window) - EMA with custom window
• temporalSmoothing:getWithRate(sample, dt, rate) - Rate-limited filtering
• temporalSigmoidSmoothing:getWithRateAccel(sample, dt, ratelimit, startAccel, stopAccel) - Rate+accel limited
• temporalSmoothing:getWithRateCapped(sample, dt, rate) - Rate-limited and capped
• temporalSpring:getWithSpringDamp(sample, dt, spring, damp) - Spring-damper dynamics
• lineFitting:getY(x) → number - Predicted Y from fitted line
• lineFitting:set(window, weight, bias) - Sets internal state

Metamethods

__index

Metatable index method for OOP-style method dispatch. Internal implementation detail.

Internal Notes

• All temporal smoothers support asymmetric rates: different speeds for "toward zero" vs "away from zero"
• The temporal smoothing convention: self[false] = inRate, self[true] = outRate (using boolean keys for branchless selection)
• temporalSmoothing auto-switches to getUncappedAutoCenter when autoCenterRate differs from inRate
• freqExists implements the Goertzel algorithm for O(1) per-sample frequency detection