pip install부터 실행 가능한 코드 스니펫을 통해 작동하는 다중 객체 추적기(multi-object tracker)를 구축하기까지 필요한 모든 것을 담았습니다.

kalbee는 상태 추정 (state estimation)을 위한 Python 라이브러리입니다. 상태 추정이란 노이즈가 있는 센서 데이터로부터 깨끗한 신호(위치, 속도, 온도 등 측정하고자 하는 모든 것)를 복원하는 기술을 의미합니다. 이 가이드는 기초부터 차근차근 안내합니다. 모든 코드 블록은 있는 그대로 실행 가능합니다. 코드를 파일에 복사하여 따라와 주세요.

설치 (Install)

pip install kalbee

유일한 런타임 의존성(runtime dependencies)은 NumPy와 SciPy입니다. 선택 사항으로 객체 탐지 (pip install "kalbee[yolo]") 및 시각화 (pip install "kalbee[viz]") 지원을 추가할 수 있습니다.

반드시 알아야 할 한 가지 아이디어: 예측(predict)과 업데이트(update)

kalbee의 모든 필터는 동일한 방식으로 작동합니다. 다음 두 단계를 번갈아 수행합니다:

• predict() — 모션 모델 (motion model)을 사용하여 시간을 따라 상태를 전진시킵니다 ("지금 객체가 어디에 있다고 생각하는가?").
• update(z) — 새로운 측정값 z를 사용하여 해당 예측을 수정합니다 ("센서가 실제로 무엇을 말하고 있는가?").

필터는 두 가지를 추적합니다: 상태 (state) x (최선의 추정치)와 공분산 (covariance) P (해당 추정치가 얼마나 불확실한지). 이 값들은 kf.x와 kf.P를 통해 확인할 수 있습니다.

첫 번째 필터

대략 일정한 속도로 움직이는 객체를 추적하며, 오직 (노이즈가 있는) 위치만을 측정한다고 가정해 보겠습니다. 행렬을 직접 구축하는 대신, kalbee의 준비된 **모델 (models)**을 사용합니다:

import numpy as np
from kalbee import KalmanFilter, rmse
from kalbee.models import constant_velocity, position_measurement_model
...

코드를 실행하면 필터링된 오차가 원본 측정 오차보다 유의미하게 낮다는 것을 확인할 수 있습니다. 즉, 필터가 노이즈를 매끄럽게 다듬어(smoothing) 주고 있는 것입니다. 이것이 핵심입니다.

파라미터(parameters)의 의미

• process_var — 모션 모델 (motion model)을 얼마나 신뢰할 것인가를 나타냅니다. 값이 높을수록 필터가 더 빠르게 반응하지만, 값이 더 튀게(jumpier) 됩니다.
• measurement_var (R) — 센서의 노이즈 (noise)가 얼마나 심한지를 나타냅니다. 값이 높을수록 필터는 자신의 예측 (predictions)에 더 의존하게 됩니다.
• 초기 P (Initial P) — 시작 시점의 불확실성 (uncertainty)입니다. 확신이 서지 않는다면 큰 값(예: 100 * I)으로 시작하세요. 필터가 빠르게 수렴 (converge)합니다.

process_var와 measurement_var를 튜닝 (tuning)하는 것이 여러분이 조절하게 될 주요 노브 (knob)입니다. (이들을 설정하는 자동화된 방법이 있습니다 — 아래 EM 섹션을 참조하세요.)

2차원 (및 그 이상)으로 확장하기

모든 모델은 n_dims 인자를 받습니다. 평면 상의 객체를 추적하고 싶나요? 두 차원을 요청하면 상태 (state)는 [x, vx, y, vy]가 됩니다:

F, Q = constant_velocity(dt=1.0, process_var=0.1, n_dims=2)   # 4x4
H, R = position_measurement_model(order=1, n_dims=2, measurement_var=0.5)

가속도 (acceleration)도 필요하신가요? constant_acceleration을 사용하세요 (상태가 축당 [pos, vel, acc]가 됩니다). 회전하는 무언가를 추적한다면? constant_turn이 조정된 회전 (coordinated-turn) 모델을 제공합니다.

비선형 시스템 (Nonlinear systems): EKF 및 UKF

모션이나 측정 (measurement)이 선형 (linear)이 아닐 때는 확장 칼만 필터 (Extended Kalman Filter, EKF) 또는 무향 칼만 필터 (Unscented Kalman Filter, UKF)로 교체하십시오. 행렬 (matrices) 대신 **함수 (functions)**를 전달합니다:

import numpy as np
from kalbee import UnscentedKalmanFilter

...

UKF는 미분 (derivatives)이 필요하지 않습니다. EKF (ExtendedKalmanFilter)는 유사하지만 야코비안 (Jacobian) 함수도 함께 받습니다. 동일한 predict/update 루프가 kalbee가 제공하는 Particle, Ensemble, Information, Square-Root, 그리고 Vectorized 필터를 포함한 10가지 모든 필터에 적용됩니다.

어떤 필터를 써야 할지 모르겠다면? 비교해 보세요

kalbee에는 합성 신호 (synthetic signal) 상에서 여러 필터를 경주시키는 내장 실험 실행기 (experiment runner)가 있습니다:

from kalbee import run_experiment

report = run_experiment(
...

각 필터에 대한 위치/속도 RMSE (Root Mean Square Error) 순위 표와 일관성 지표 (consistency metric, NEES)를 얻을 수 있습니다. 이는 본격적으로 적용하기 전에 적절한 도구를 선택할 수 있는 빠른 방법입니다.

여러 객체 추적하기

여러 객체를 추적하려면 (비디오 속의 사람들, 레이더의 신호 등), 필터를 MultiObjectTracker로 감싸면 됩니다. 각 새로운 객체에 대해 새로운 필터를 생성하는 작은 팩토리(factory)를 제공하면 됩니다:

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

트래커(tracker)가 어려운 부분들을 대신 처리해 줍니다: 기존 트랙(track)과 탐지(detection)를 매칭하는 작업(거리 게이팅을 사용하는 헝가리안 알고리즘 (Hungarian algorithm)) 및 각 트랙의 생명 주기(lifecycle) 관리입니다. 조절 가능한 파라미터는 다음과 같습니다:

• n_init — 트랙이 "확정(confirmed)"되기 전까지 필요한 연속적인 탐지 횟수 (깜빡임(flicker) 현상을 필터링함).
• max_age — 트랙이 삭제되기 전까지 허용되는 누락된 프레임 수 (폐쇄(occlusion) 현상을 처리함).
• gate — 유효한 매칭을 위한 최대 거리.

update() 함수를 통해서는 확정된 트랙만 반환됩니다. YOLO와 같은 탐지기(detector)로부터 얻은 박스 중심점(box centers)을 입력하면 완전한 추적 파이프라인(tracking pipeline)을 구축할 수 있습니다.

데이터가 노이즈 값을 선택하게 하세요

Q와 R을 선택하는 데 어려움을 겪고 계신가요? EM (Expectation-Maximization, 기댓값 최대화) 알고리즘을 사용하여 기록된 데이터로부터 이 값들을 학습하세요:

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

...

대표성 있는 데이터에 대해 한 번 적합(fit)시킨 후, result.Q와 result.R을 실시간 KalmanFilter에 삽입하세요. 이는 수동으로 튜닝하는 것에 대한 원칙적인 대안입니다.

몇 가지 팁

• 형태(Shapes)가 중요합니다. 상태(States)는 열 벡터 (n, 1)이며, 측정값(measurements)은 (m, 1)입니다. 확신이 서지 않을 때는 reshape(-1, 1)을 사용하세요.
• 불확실하게 시작하세요. 초기 P 값을 크게 설정하면 필터가 초기 측정값을 신뢰하여 빠르게 수렴할 수 있습니다.
• 오차뿐만 아니라 일관성(consistency)을 확인하세요. 평균 NEES가 상태 차원(state dimension)에서 멀리 떨어져 있다면 Q/R이 잘못 튜닝된 것입니다. 메트릭 모듈(nees, nis, log_likelihood)이 이를 알려줍니다.
• 재현성(Reproducibility)이 내장되어 있습니다. 샘플링 필터(입자 필터(particle filter), 앙상블 필터(ensemble filter))와 신호 생성기(signal generators)는 seed/rng 인자를 허용하므로, 원하는 경우 실행 결과를 결정론적(deterministic)으로 만들 수 있습니다.

다음 단계

• 문서(documentation)에는 각 필터별로 기초 수학 원리와 실습 예제가 포함된 전용 페이지가 마련되어 있습니다.
• examples/ 폴더에는 전체 멀티 객체 추적 (multi-object tracking) 데모와 YOLO 통합을 포함하여 바로 실행 가능한 스크립트들이 있습니다.
• 모든 요소가 동일한 predict/update 인터페이스를 공유합니다. 따라서 이 튜토리얼을 마치고 나면, 라이브러리의 나머지 부분은 이미 알고 있는 내용의 변형일 뿐입니다.

즐거운 추정 (estimating) 되시길 바랍니다.