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

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:

from smoothiepy import SmootherBuilder, ExponentialMovingAverageFilter1D

# Create a smoother with an exponential moving average filter
smoother = (
  SmootherBuilder()
  .one_dimensional()
  .continuous()
  .attach_filter(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 add_and_get to add a value and get the result in one step
smoothed_value = smoother.add_and_get(3.0)
print(f"Smoothed value: {smoothed_value}")

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

from smoothiepy import SmootherBuilder, MedianAverageFilter1D

# Create a smoother with a median moving average filter
smoother = (
    SmootherBuilder()
    .one_dimensional()
    .list_based()
    .attach_filter(MedianAverageFilter1D(window_size=2))
    .build()
)

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

result_list = smoother.apply_filter(data_list)

print(f"Original data list: {data_list}")
print(f"Smoothed data list: {result_list}")

✨ 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:

from smoothiepy import SmootherBuilder, SimpleMovingAverageFilter1D, GaussianAverageFilter1D

# Create a smoother with multiple filters
smoother = (
  SmootherBuilder()
  .one_dimensional()
  .continuous()
  .attach_filter(SimpleMovingAverageFilter1D(window_size=5))
  .attach_filter(GaussianAverageFilter1D(window_size=3, std_dev=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