Smooth real-time data streams like eye tracking or sensor input with this lightweight package.

📋 Overview

SmoothiePy is a Python library designed for smoothing real-time data streams with minimal latency. It provides a collection of filters and smoothers that can be applied to one-dimensional and two-dimensional data, making it ideal for applications such as:

• Eye tracking and gaze analysis
• Sensor data processing
• Motion tracking
• Financial data analysis
• Time series preprocessing
• Signal processing

The library is built with a focus on flexibility, performance, and ease of use, allowing you to quickly implement sophisticated data smoothing pipelines.

🚀 Installation

bash pip install smoothiepy

SmoothiePy requires Python 3.10 or later.

🏁 Quick Start

Here's a simple example of how to use SmoothiePy to smooth a data stream:

```python from smoothiepy import SmootherBuilder, ExponentialMovingAverageFilter1D

Create a smoother with an exponential moving average filter

smoother = ( SmootherBuilder() .onedimensional() .continuous() .attachfilter(ExponentialMovingAverageFilter1D(alpha=0.2)) .build() )

Process data points

smoother.add(20.0) print(f"Smoothed value: {smoother.get()}")

smoother.add(60.0) print(f"Smoothed value: {smoother.get()}")

Alternatively, use addandget to add a value and get the result in one step

smoothedvalue = smoother.addandget(3.0) print(f"Smoothed value: {smoothedvalue}") ```

You can also use a list-based smoother for batch processing of data:

```python from smoothiepy import SmootherBuilder, MedianAverageFilter1D

Create a smoother with a median moving average filter

smoother = ( SmootherBuilder() .onedimensional() .listbased() .attachfilter(MedianAverageFilter1D(windowsize=2)) .build() )

data_list = [1.0, 2.0, 3.0] # Example data list

resultlist = smoother.applyfilter(data_list)

print(f"Original data list: {datalist}") print(f"Smoothed data list: {resultlist}") ```

✨ Features

Available Filters

SmoothiePy provides a variety of filters:

One-Dimensional Filters

• Offset Filter: Adds a constant offset to the data
• Simple Moving Average: Computes the arithmetic mean over a window
• Weighted Moving Average: Applies linearly decreasing weights
• Gaussian Average: Applies a Gaussian weighting function
• Median Average: Computes the median of values in a window
• Exponential Moving Average: Applies exponential weighting
• Cumulative Moving Average: Computes the cumulative average
• Fixation Smooth Filter: Sort of Deadband filter. Specialized for fixation-like data (e.g., eye tracking)
• Multi-Pass Moving Average: Applies multiple passes of a specified moving average type

Two-Dimensional Filters

Each 1D filter is also available in a 2D version, allowing you to smooth data in two dimensions (e.g., x-y coordinates).

Many more filters are work in progress, including advanced filters like Kalman filters and more complex multidimensional filters.

Builder Pattern

SmoothiePy uses a builder pattern to create smoothers, making it easy to configure and chain multiple filters:

```python from smoothiepy import SmootherBuilder, SimpleMovingAverageFilter1D, GaussianAverageFilter1D

Create a smoother with multiple filters

smoother = ( SmootherBuilder() .onedimensional() .continuous() .attachfilter(SimpleMovingAverageFilter1D(windowsize=5)) .attachfilter(GaussianAverageFilter1D(windowsize=3, stddev=1.0)) .build() ) ```

📚 Documentation

For detailed documentation, visit the GitHub Wiki. Work in progress...

API Reference

1D Filters

• OffsetFilter1D: Adds a constant offset
• SimpleMovingAverageFilter1D: Simple arithmetic mean
• WeightedMovingAverageFilter1D: Linearly decreasing weights
• GaussianAverageFilter1D: Gaussian weighting function
• MedianAverageFilter1D: Median of values
• ExponentialMovingAverageFilter1D: Exponential weighting
• CumulativeMovingAverageFilter1D: Cumulative average
• FixationSmoothFilter1D: For fixation-like data
• MultiPassMovingAverage1D: Multiple passes of a specified filter

2D Filters

• OffsetFilter2D: Adds a constant offset in 2D
• SimpleMovingAverageFilter2D: Simple arithmetic mean in 2D
• WeightedMovingAverageFilter2D: Linearly decreasing weights in 2D
• GaussianAverageFilter2D: Gaussian weighting function in 2D
• MedianAverageFilter2D: Median of values in 2D
• ExponentialMovingAverageFilter2D: Exponential weighting in 2D
• CumulativeMovingAverageFilter2D: Cumulative average in 2D
• FixationSmoothFilter2D: For fixation-like data in 2D
• MultiPassMovingAverage2D: Multiple passes of a specified filter in 2D

Builder

• SmootherBuilder: Entry point for creating smoothers

🛠️ Development

Features work in progress:

• More filters 1D and 2D, including more advanced ones (no specific list exists)

📄 License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0) — see the LICENSE file in the git repo for details.

📬 Contact

Timo Seyfarth - timo@seyfarth.dev