CHANGELOG.md

Changelog - Ulepszenia Systemu ReID

Data: 2025-12-02

🚀 Główne Ulepszenia

1. Time-based Gallery Management

• Problem: Galeria rośnie w nieskończoność, niewidziane osoby pozostają w pamięci
• Rozwiązanie:
  • Dodano last_seen timestamp dla każdej osoby w galerii
  • Dodano clean_inactive_persons() - automatyczne usuwanie osób niewidzianych przez >30s
  • Czyszczenie galerii wykonywane co 100 klatek
• Efekt: Brak "zombie IDs", stabilna wielkość galerii, lepsza reidentyfikacja

2. Hungarian Algorithm dla Optymalnego Matchingu

• Problem: Greedy matching dawał suboptymalne przypisania, szczególnie gdy było wiele osób
• Rozwiązanie:
  • Utworzono hungarian_matcher.py z implementacją algorytmu węgierskiego
  • Używa scipy.optimize.linear_sum_assignment dla globalnego optimum
  • Buduje macierz podobieństw (detekcje × galeria) i znajduje najlepsze przypisanie
• Efekt: Optymalne dopasowanie detekcji do ID, mniej błędnych przypisań

3. Stabilniejsze Embeddingi (Alpha Tuning)

• Problem: Alpha=0.5 powodowało zbyt szybką zmianę embeddingów
• Rozwiązanie: Obniżono alpha z 0.5 → 0.3
• Efekt: Wolniejsza adaptacja = bardziej stabilne ID przy powrocie do kadru

4. Tracking Statystyk

• Dodano licznik appearances - ile razy osoba była widziana
• last_seen timestamp aktualizowany przy każdej detekcji i update
• Dodano removed_ids set - zapobiega ponownemu użyciu usuniętych ID

---

📊 Zmiany w Plikach

reid_engine.py

# Nowe parametry
__init__(inactive_timeout=30.0)  # timeout dla nieaktywnych osób

# Nowa struktura galerii
gallery = [
    {
        'id': int,
        'embedding': (body_emb, face_emb),
        'last_seen': float,      # timestamp ostatniego widzenia
        'appearances': int        # licznik wystąpień
    }
]

# Nowe metody
clean_inactive_persons(current_time) -> int  # usuwa stare osoby

main.py

# Import Hungarian matcher
from hungarian_matcher import hungarian_match

# W _process_capture():
if processed_count % 100 == 0:
    self.reid_engine.clean_inactive_persons(time.time())

# Nowy matching pipeline:
similarity_matrix = build_similarity_matrix()
matched, unmatched_dets, unmatched_gal = hungarian_match(similarity_matrix, threshold)
# Optymalnie przypisz matched pary

hungarian_matcher.py (NOWY PLIK)

def hungarian_match(similarity_matrix, threshold):
    """Globalnie optymalne dopasowanie detekcji do ID"""
    cost_matrix = 1.0 - similarity_matrix
    row_ind, col_ind = linear_sum_assignment(cost_matrix)
    # Filtruj przez threshold
    return matched, unmatched_detections, unmatched_gallery

def greedy_match(similarity_matrix, threshold):
    """Zachłanne dopasowanie - szybsze ale gorsze"""

requirements.txt

scipy>=1.10.0  # Hungarian algorithm

---

🎯 Oczekiwane Rezultaty

1. Stabilniejsze ID: Osoba wracająca do kadru dostaje to samo ID (jeśli <30s)
2. Brak podmiany ID: Hungarian algorithm zapobiega sytuacji gdzie osoba A dostaje ID osoby B
3. Lepsza wydajność: Czyszczenie galerii = mniej porównań = szybsze przetwarzanie
4. Skalowalność: System działa stabilnie nawet z wieloma osobami

---

🧪 Jak Przetestować

# Test podstawowy
python main.py --live --camera 1 --yolo-imgsz 384 --skip 2

# Test z zapisem crops
python main.py --live --camera 1 --save-crops --threshold 0.5

# Test z niższym progiem (jeśli nadal są problemy)
python main.py --live --camera 1 --threshold 0.45

Scenariusz testowy:

1. Pojaw się w kadrze → dostaniesz ID 1
2. Zniknij z kadru na 10s
3. Wróć do kadru → powinieneś dostać ID 1 (nie ID 2!)
4. Druga osoba wejdzie → dostanie ID 2
5. Obie osoby w kadrze → każda ma unikalne ID

---

🔧 Parametry do Tuningu

Jeśli nadal są problemy, można dostroić:

# reid_engine.py
inactive_timeout = 30.0  # zwiększ do 60.0 dla dłuższej pamięci

# main.py  
similarity_threshold = 0.5  # obniż do 0.45 dla łatwiejszej reidentyfikacji
alpha = 0.3  # obniż do 0.2 dla wolniejszej adaptacji

# CLI
--threshold 0.45  # niższy próg
--skip 1  # przetwarzaj każdą klatkę (wolniej ale dokładniej)

---

📈 Oczekiwane Metryki

• FPS: ~6-7 FPS (nieznacznie wolniej przez Hungarian, ale wciąż OK)
• Gallery Size: Stabilna wielkość (2-5 osób w typowym scenariuszu)
• ID Persistence: >95% accuracy dla powrotu tej samej osoby <30s
• Multi-person: Każda osoba unikalny ID w jednej klatce

---

🐛 Debugging

Jeśli problem z ID nadal występuje, sprawdź:

# Dodaj debug output w main.py po hungarian_match:
print(f"[DEBUG] Matched: {len(matched)}, Unmatched dets: {len(unmatched_dets)}, Gallery: {len(gallery_ids)}")
print(f"[DEBUG] Similarity matrix shape: {similarity_matrix.shape}")
print(f"[DEBUG] Max similarity: {similarity_matrix.max():.3f}, Min: {similarity_matrix.min():.3f}")

To pomoże zrozumieć dlaczego matching nie działa.