Metadata-Version: 2.4
Name: kalbee
Version: 0.6.0
Summary: A clean, modular Python implementation of Kalman Filters and estimation algorithms.
Author-email: Le Duc Minh <minh.leduc.0210@gmail.com>
Maintainer-email: Le Duc Minh <minh.leduc.0210@gmail.com>
Project-URL: Homepage, https://github.com/MinLee0210/kalbee
Project-URL: Repository, https://github.com/MinLee0210/kalbee
Project-URL: Documentation, https://minlee0210.github.io/kalbee
Keywords: kalman-filter,extended-kalman-filter,ekf,unscented-kalman-filter,ukf,particle-filter,ensemble-kalman-filter,information-filter,state-estimation,sensor-fusion,tracking,alpha-beta-gamma,rts-smoother,adaptive-filter,robotics,signal-processing,python
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.4
Requires-Dist: scipy>=1.10.0
Provides-Extra: yolo
Requires-Dist: ultralytics>=8.0.0; extra == "yolo"
Requires-Dist: opencv-python>=4.8.0; extra == "yolo"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7.0; extra == "viz"
Provides-Extra: polars
Requires-Dist: polars>=0.20.0; extra == "polars"
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == "pandas"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.7.2; extra == "docs"
Dynamic: license-file

# kalbee

<div align="center">
  <img src="https://raw.githubusercontent.com/MinLee0210/kalbee/main/docs/kalbee.png" alt="kalbee logo" width="300"/>
</div>

<br>

`kalbee` is a clean, modular Python implementation of Kalman Filters and related estimation algorithms. Designed for simplicity and performance, it provides a standard interface for state estimation in various applications.

## Features

- **15 Filters**: KF, EKF, UKF, SigmaPointUKF, Particle Filter, Ensemble KF, Information Filter, Alpha-Beta-Gamma, Adaptive KF, Square-Root KF, Vectorized KF, Fading Memory KF, H-Infinity, and Interacting Multiple Model (IMM)
- **Sigma Points**: Pluggable strategies — SimplexSigmaPoints, MerweScaledSigmaPoints, JulierSigmaPoints
- **Motion Models**: Ready-made constant-velocity, constant-acceleration, and coordinated-turn `(F, Q)` builders plus position measurement models
- **Multi-Object Tracking**: SORT-style `MultiObjectTracker` with Hungarian association, Mahalanobis/IoU gating, and track lifecycle management — built on top of any filter
- **Innovation Gating**: Chi-squared and Mahalanobis gating for outlier rejection
- **Outlier Detection**: Real-time `Chi2OutlierDetector` with adaptive thresholds
- **Parameter Learning**: Offline EM (`em_kalman`) that fits `Q`/`R` from data by maximum likelihood, complementing the online Adaptive KF
- **Auto-Tuning**: NIS-based automatic `Q`/`R` tuning (`tune_kalman_filter`, `quick_tune`)
- **RTS Smoother**: Rauch-Tung-Striebel backward smoother for post-processing
- **Diagnostics**: `FilterDiagnostics` for real-time monitoring, NIS/NEES consistency tests, innovation whiteness test
- **Metrics**: RMSE, NEES, NIS, Log-Likelihood for filter diagnostics
- **Batch Processing**: `filter_sequence()` with missing data handling
- **State Persistence**: `save_state()` / `load_state()` for JSON serialization
- **Control Inputs**: B matrix support in KF predict step
- **Experiment Runner**: Compare filters on synthetic signals with one line
- **AutoFilter Factory**: Switch between filters by name
- **Numerical Stability**: Joseph form covariance updates, Cholesky factor stabilization, and symmetry enforcement
- **NumPy/SciPy Integration**: Optimized for numerical computations

## Installation

```bash
pip install kalbee
```

Or from source:

```bash
git clone https://github.com/MinLee0210/kalbee.git
cd kalbee
pip install -e .
```

Optional extras: `pip install "kalbee[yolo]"` (object-tracking examples), `"kalbee[viz]"` (plotting), or `"kalbee[docs]"` (documentation site).

## Quick Start

### 1. Standard Kalman Filter

```python
import numpy as np
from kalbee import KalmanFilter

state = np.zeros((2, 1))  # [position, velocity]
cov = np.eye(2)
F = np.array([[1, 1], [0, 1]])  # Constant velocity model
Q = np.eye(2) * 0.01
H = np.array([[1, 0]])
R = np.array([[0.1]])

kf = KalmanFilter(state, cov, F, Q, H, R)
kf.predict()
kf.update(np.array([[1.2]]))
print(f"Estimated State:\n{kf.x}")
```

### 2. Interacting Multiple Model (IMM) Filter

```python
import numpy as np
from kalbee import KalmanFilter, InteractingMultipleModel

kf_cv = KalmanFilter(state_init, cov_init, F_cv, Q_cv, H, R)
kf_ca = KalmanFilter(state_init, cov_init, F_ca, Q_ca, H, R)

model_transition = np.array([[0.95, 0.05], [0.05, 0.95]])
model_probabilities = np.array([0.8, 0.2])

imm = InteractingMultipleModel([kf_cv, kf_ca], model_transition, model_probabilities)
imm.predict()
imm.update(measurement)
```

### 3. SigmaPointUKF with Pluggable Sigma Points

```python
import numpy as np
from kalbee import SigmaPointUKF, MerweScaledSigmaPoints

state = np.zeros((2, 1))
cov = np.eye(2) * 10.0
Q = np.eye(2) * 0.01
R = np.array([[0.5]])

def f(x, dt):
    return np.array([[x[0, 0] + x[1, 0] * dt], [x[1, 0]]])

def h(x):
    return np.array([[x[0, 0]]])

sigma_pts = MerweScaledSigmaPoints(n=2, alpha=0.1, beta=2.0, kappa=0.0)
ukf = SigmaPointUKF(state, cov, Q, R, f, h, sigma_points=sigma_pts)

ukf.predict(dt=1.0)
ukf.update(np.array([[1.2]]))
```

### 4. Compare Filters with Experiments

```python
from kalbee import run_experiment

report = run_experiment(
    signal="sine",
    filters=["kf", "ekf", "ukf", "pf"],
    noise_std=0.5,
)
print(report.summary())
```

### 5. AutoFilter Factory

```python
from kalbee import AutoFilter

kf = AutoFilter.from_filter(state, cov, F, Q, H, R, mode="kf")
# Available modes: kf, ekf, ukf, abg, pf, enkf, if, akf, srkf, vkf, imms
```

### 6. Multi-Object Tracking

```python
import numpy as np
from kalbee import KalmanFilter, MultiObjectTracker
from kalbee.models import constant_velocity, position_measurement_model

F, Q = constant_velocity(dt=1.0, process_var=0.1, n_dims=2)
H, R = position_measurement_model(order=1, n_dims=2, measurement_var=0.25)

def new_track(z):
    x0 = np.array([[z[0]], [0.0], [z[1]], [0.0]])
    return KalmanFilter(x0, np.eye(4) * 10.0, F, Q, H, R)

tracker = MultiObjectTracker(new_track, n_init=3, max_age=5)

for detections in detection_stream:
    confirmed = tracker.update(detections)
    for t in confirmed:
        print(t.id, t.state[0, 0], t.state[2, 0])
```

See [`examples/multi_object_tracking.py`](examples/multi_object_tracking.py) for a full runnable demo.

### 7. Learn Noise Covariances from Data (EM)

```python
from kalbee import em_kalman
from kalbee.models import constant_velocity, position_measurement_model

F, _ = constant_velocity(dt=1.0, n_dims=1)
H, _ = position_measurement_model(order=1, n_dims=1)

result = em_kalman(measurements, F, H, n_iter=50)
print("Learned Q:\n", result.Q)
print("Learned R:\n", result.R)
```

### 8. Auto-Tuning

```python
from kalbee import tune_kalman_filter, quick_tune

# Iterative NIS-based tuning
result = tune_kalman_filter(measurements, F, H, n_iter=50)
print(f"Q:\n{result.Q}\nR:\n{result.R}")

# Quick single-pass tuning
Q, R = quick_tune(measurements, F, H)
```

### 9. Real-Time Diagnostics

```python
from kalbee import KalmanFilter, FilterDiagnostics

kf = KalmanFilter(state, cov, F, Q, H, R)
diag = FilterDiagnostics(m=1, n=2)

for z in measurements:
    kf.predict()
    kf.update(z)
    snapshot = diag.collect(kf, ground_truth=true_state)

print(diag.summary())
```

## Documentation

Full documentation with theory, code examples, and experiments for each filter:

```bash
pip install mkdocs-material
mkdocs serve
```

- [Getting Started](docs/getting_started.md)
- **Filters**: [KF](docs/filters/kalman_filter.md) · [EKF](docs/filters/extended_kalman_filter.md) · [UKF](docs/filters/unscented_kalman_filter.md) · [SigmaPointUKF](docs/filters/sigma_point_ukf.md) · [PF](docs/filters/particle_filter.md) · [EnKF](docs/filters/ensemble_kalman_filter.md) · [IF](docs/filters/information_filter.md) · [ABG](docs/filters/alpha_beta_gamma_filter.md) · [AKF](docs/filters/adaptive_kalman_filter.md) · [Fading Memory KF](docs/filters/fading_memory_kf.md) · [H-Infinity](docs/filters/hinfinity_filter.md) · [SRKF](docs/filters/square_root_kalman_filter.md) · [Vectorized KF](docs/filters/vectorized_kalman_filter.md) · [IMM](docs/filters/interacting_multiple_model.md)
- **Features**: [Gating](docs/features/gating.md) · [Outlier Detection](docs/features/outlier_detection.md) · [Auto-Tuning](docs/features/auto_tuning.md) · [Diagnostics](docs/features/diagnostics.md) · [Consistency Tests](docs/features/consistency_tests.md) · [RTS Smoother](docs/features/rts_smoother.md) · [Metrics](docs/features/metrics.md) · [Experiments](docs/features/experiments.md) · [Maneuvering Target Tracking](docs/features/maneuvering_target.md) · [YOLO Object Tracking](docs/features/yolo_tracking.md)
- [Architecture](docs/architecture.md)

## Testing

```bash
uv run pytest tests/                                  # run the suite
uv run pytest tests/ --cov=kalbee --cov-report=term   # with coverage
```

## License

This project is licensed under the Apache License 2.0.
