Spot Tracking & Analysis for LEED (STAL)

O projekcie

Spot Tracking & Analysis for LEED (STAL) (nazwa pakietu: trackleed) to aplikacja desktopowa PyQt6 do analizy czasowo-rozdzielczych sekwencji obrazów LEED. Narzędzie pomaga wczytywać klatki LEED, wykrywać plamki dyfrakcyjne, śledzić ich ruch w czasie, doprecyzowywać pozycje przez dopasowanie 2D Gaussian oraz eksportować wyniki ilościowe do dalszej analizy.

Aplikacja jest aktywnie rozwijanym narzędziem badawczym. Stabilny bazowy workflow opiera się na klasycznym przetwarzaniu obrazu, detekcji YOLO, łączeniu detekcji przez Hungarian assignment oraz optycznym przepływie Lucas-Kanade. Aktualna gałąź rozwojowa rozszerza ten baseline o warstwę trackerów zorientowaną na benchmarki, w której wiele nowoczesnych trackerów punktowych, bounding-box i mask/video może być testowanych na tych samych sekwencjach LEED.

Co robi STAL?

STAL zamienia sekwencje obrazów LEED w uporządkowane, możliwe do przeglądu i eksportu trajektorie plamek dyfrakcyjnych. Jest przeznaczony do eksperymentów, w których plamki poruszają się, pojawiają, zanikają, słabną, poszerzają się, rozdzielają albo stają się trudne do ręcznego śledzenia.

Główne możliwości obejmują:

wczytywanie sekwencji klatek LEED z katalogów obrazów,
opcjonalny import GIF przez próbkowanie klatek do PNG,
opcjonalne wczytywanie i odejmowanie tła,
maskowanie obszarów, które nie powinny brać udziału w detekcji ani analizie,
detekcję plamek dyfrakcyjnych przez klasyczny pipeline white-top-hat + peak finding albo detektor YOLO,
ręczną edycję ROI do korekty, dodawania, usuwania albo doprecyzowania definicji plamek,
tracking między klatkami przez klasyczne i eksperymentalne backendy,
dopasowanie eliptycznego 2D Gaussian dla każdego śledzonego ROI,
estymację centrum wzoru dyfrakcyjnego i promienia względem tego centrum,
metryki per-track i per-frame, wykresy, tabele, overlaye, eksport CSV oraz zapisywanie sesji JSON.

Typowy workflow

Wczytanie danych - otwórz katalog z klatkami LEED przez File > Open Directory.... Parser obsługuje typowe konwencje nazw klatek LEED oraz prostsze nazwy numeryczne, takie jak 001.tif albo frame_001.png.
Przygotowanie klatek - opcjonalnie zaimportuj GIF, wczytaj tło i zdefiniuj maski dla beam-stopów, etykiet, artefaktów detektora albo innych ignorowanych regionów.
Detekcja plamek - użyj panelu Find Spots. Dla stabilnego baseline’u można zacząć od klasycznego detektora i dostroić blur, promień white-top-hat, minimalną odległość, threshold i rozmiar ROI. Dla trudniejszych danych można użyć checkpointów YOLO.
Tracking w czasie - wybierz algorytm w panelu Tracking. Baseline obejmuje Hungarian linking, directional Hungarian linking, Lucas-Kanade optical flow i wariant skip-anchor optical flow.
Przegląd i korekta trajektorii - otwórz wizualizer, usuń fałszywe tracki, dodaj albo przesuń ROI, połącz tracki lub wykonaj lokalny retrack wybranym backendiem.
Analiza ilościowa - użyj Analyze Tracks, aby dopasować 2D Gaussian do każdego ROI. STAL zapisuje środki plamek, amplitudy, szerokości, FWHM, asymetrię, objętość, jakość fitu, promień względem centrum wzoru i błędy, gdy są dostępne.
Eksport i zapis - eksportuj CSV, overlaye trajektorii, etykiety YOLO albo pełne sesje. Sesje przechowują pliki, definicje plamek, maski, trajektorie, wyniki analizy i ustawienia.

Detekcja

Klasyczny detektor

Klasyczny detektor jest transparentnym pipeline’em przetwarzania obrazu i działa jako powtarzalny baseline. Obejmuje opcjonalną normalizację albo odejmowanie tła, estymację tła przez Gaussian blur, filtrację white top-hat, detekcję lokalnych maksimów i konwersję pików na prostokątne obiekty SpotROI.

Ten tryb jest użyteczny, gdy wzór dyfrakcyjny jest relatywnie czysty, plamki są rozdzielone, a potrzebny jest nie-ML baseline.

Detektor YOLO

Detektor YOLO używa checkpointów Ultralytics .pt umieszczonych w tracking_models/yolo/. Wykryte bounding boxy są konwertowane do SpotROI, które można później śledzić, edytować, analizować albo eksportować jako etykiety YOLO.

YOLO jest przydatny, gdy kontrast plamek silnie się zmienia, artefakty tła destabilizują detekcję progową albo użytkownik chce budować i iterować adnotowany dataset detekcji plamek LEED.

Tracking i status rozwoju

STAL obsługuje warstwową strategię trackingu. Metody klasyczne zapewniają powtarzalny baseline, a eksperymentalne integracje trackerów pozwalają porównywać nowoczesne metody video/object tracking na tych samych danych LEED.

Baseline tracking

Detection Linking / Hungarian - łączenie detekcji z kolejnych klatek przez przypisanie dystansowe.
Directional Linking - radial-aware Hungarian linking z karami bocznymi, ring-bin gating, dynamicznym maksymalnym dystansem, obsługą zmiany kierunku i tolerancją luk.
Lucas-Kanade Optical Flow - rzadki optical flow z wybranej klatki referencyjnej.
Optical Flow with skip-anchor logic - bardziej odporny wariant LK z opcjonalnymi kontrolami forward-backward, NCC, centroid refinement i obsługą luk.

Eksperymentalna warstwa trackerów

Repozytorium zawiera architekturę trackerów opartą o rejestr backendów punktowych, bounding-box i mask/video. Te integracje są przeznaczone do benchmarkowania i rozwoju metod, zwłaszcza na trudnych sekwencjach LEED z plamkami słabymi, rozmytymi, poruszającymi się albo czasowo zanikającymi.

Rodzina trackerów	Backendy obecne w repozytorium	Typowe użycie
Trackery punktowe	TAPIR, BootsTAPIR Online/Causal, LocoTrack, CoTracker3, TAPNext, Track-On-R, PIPs++, MFTIQ	Śledzenie wybranych środków plamek jako punktów.
Trackery bounding-box	ToMP/TaMOs, OSTrack	Tracking ROI plamek jako obiektów i konwersja wyniku do reprezentatywnej pozycji plamki.
Trackery mask/video	SAM2, SAMURAI, DAM4SAM, DEVA, Cutie, XMem2	Propagacja masek albo segmentowanych regionów i ekstrakcja punktu reprezentatywnego, np. centroidu maski, peak-in-mask albo Gaussian-in-mask.

Nie każdy backend jest równie dojrzały ani równie łatwy w instalacji. Część wymaga zewnętrznego repozytorium, checkpointów, CUDA-kompatybilnego PyTorch albo osobnego środowiska Conda/Python. Z tego powodu integracje zewnętrzne powinny być traktowane jako eksperymentalne backendy benchmarkowe, dopóki nie zostaną zwalidowane na docelowym zbiorze danych.

Uruchamianie trackerów w subprocessach

Wiele nowoczesnych bibliotek trackingowych ma zależności trudne do pogodzenia z głównym środowiskiem aplikacji PyQt6. STAL obsługuje dlatego tryb subprocess dla wielu backendów. Główna aplikacja działa w swoim środowisku, a wybrany tracker uruchamiany jest w osobnym interpreterze Pythona, często z dedykowanego środowiska Conda.

Typowy wzorzec:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m trackleed

Dla zewnętrznych trackerów konfiguruje się w GUI ścieżkę do repozytorium trackera, dedykowany interpreter Python, checkpoint albo katalog modelu oraz tryb backendu: direct albo subprocess.

Wyniki ilościowe

Po trackingu STAL może uruchomić analizę opartą o dopasowanie Gaussian. Dla każdej śledzonej plamki i klatki może obliczyć:

dopasowane współrzędne środka globalnego,
amplitudę i offset Gaussian,
sigma_x, sigma_y i kąt orientacji,
FWHM X/Y oraz odpowiadające błędy,
zintegrowaną objętość Gaussian i jej błąd,
asymetrię,
R-squared i reduced chi-squared,
promień względem centrum wzoru,
błąd promienia, gdy dostępne są błędy centrum i fitu.

Tryby centrum wzoru obejmują estymację per-frame, dopasowanie koła, dopasowanie elipsy, globalną medianę, czasowe wygładzanie centrum oraz ręcznie definiowane overlaye koła albo elipsy. Podsumowania per-frame obejmują średni promień i błąd standardowy względem tracków.

Positions analysis

Oprócz standardowej analizy tracków STAL zawiera workflow analizy pozycji dla zgrupowanych tracków. Użytkownik może zdefiniować grupy składające się z jednego tracka referencyjnego i jednego lub wielu tracków satelitarnych. Narzędzie refituje pozycje klatka po klatce i raportuje geometrię względną: środki referencyjne i satelitarne, dx, dy, dystans radialny r, status jakości fitu, flagi walidacyjne, eksport CSV i overlaye.

Ten tryb jest przydatny, gdy pytanie badawcze dotyczy względnych pozycji plamek, a nie tylko ruchu absolutnego albo promienia względem globalnego centrum wzoru.

Przykładowe zastosowania

tracking ewolucji wzoru LEED podczas eksperymentu,
porównywanie algorytmów śledzenia na trudnych danych LEED,
budowanie i ulepszanie detektorów YOLO dla plamek dyfrakcyjnych,
ilościowa analiza kształtu plamki i jakości fitu,
pomiar geometrii względnej plamka referencyjna - plamki satelitarne,
przygotowywanie powtarzalnych figur, tabel, overlayów i sesji analitycznych.

Wejście i wyjście

Wejście

katalogi z klatkami obrazów LEED,
pliki .tif, .tiff i .png jako podstawowy format katalogowy,
import GIF przez ekstrakcję klatek,
opcjonalny obraz tła,
opcjonalne checkpointy YOLO i zewnętrznych backendów trackingowych,
opcjonalne metadane z nazw plików: element, powierzchnia, klatka/czas, temperatura, energia i pokrycie.

Wyjście

full_analysis_per_spot.csv - per-track, per-frame fit Gaussian i metryki pochodne,
pattern_center_data.csv - dane centrum wzoru dla przetworzonych klatek,
average_radius_per_frame.csv - podsumowania promieni per-frame,
track_legend.csv - identyfikatory tracków i pozycje startowe,
track_visualizations/ - overlaye PNG z trajektoriami,
CSV i overlaye z grouped positions analysis,
etykiety YOLO i obrazy do budowy datasetu,
sesje JSON do zapisu i odtworzenia stanu analizy.

Instalacja

git clone <repository-url>
cd trackleed-2704-samurai
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m trackleed

Podstawowe zależności obejmują NumPy, SciPy, scikit-image, OpenCV, Matplotlib, Pandas, Pillow, tifffile, imageio, PyQt6, pyqtgraph, PyOpenGL, Ultralytics, PyTorch i TorchVision. Dla YOLO na GPU oraz eksperymentalnych trackerów należy przygotować wersję PyTorch zgodną z lokalnym CUDA oraz zewnętrzne repozytoria i checkpointy.

Zakres i ograniczenia

STAL jest przeznaczony do workflow badawczych, w których inspekcja wizualna i walidacja pozostają ważne. Aplikacja automatyzuje dużą część analizy plamek LEED, ale trudne zbiory danych nadal wymagają strojenia parametrów i ręcznego przeglądu.

Najważniejsze ograniczenia:

zaawansowane integracje trackerów są w aktywnym rozwoju i powinny być walidowane względem klasycznych baseline’ów,
zewnętrzne trackery mogą wymagać osobnych procedur instalacji, repozytoriów, checkpointów, wersji CUDA albo uruchamiania w subprocessach,
bogate metadane z nazw plików zależą od konwencji nazewnictwa,
metryki z dopasowania Gaussian są sensowne tylko wtedy, gdy ROI zawiera właściwą plamkę i jakość fitu jest akceptowalna,
wyniki trackingu powinny być sprawdzane, gdy plamki się przecinają, zanikają, rozdzielają, saturują albo nachodzą na artefakty.

Licencja

Projekt jest rozpowszechniany na licencji MIT.