RL R. Lewandków computer vision / teaching

Software / 2026

NanoTrack

Desktopowa aplikacja PyQt6 do analizy czasowo-rozdzielczych sekwencji STM: rejestracja klatek, seedy cząstek i krawędzi stopni, tracking, ręczny przegląd oraz eksport metryk.

Powrót do sekcji

O projekcie

NanoTrack to desktopowa aplikacja PyQt6 do przeglądu sekwencji klatek STM, rejestracji obrazów, tworzenia seedów cząstek i krawędzi stopni, śledzenia ich w czasie oraz eksportu wyników ilościowych.

Narzędzie jest projektowane dla filmów STM i serii klatek, w których istotny jest nie tylko kształt pojedynczego obrazu, ale również to, jak cząstki, defekty, adsorbaty albo krawędzie stopni zmieniają się w czasie trwania sekwencji.

NanoTrack należy do tego samego ekosystemu repozytorium co NaParA, ale jest prezentowany jako osobna aplikacja. NaParA koncentruje się na detekcji nanocząstek i ilościowej analizie pojedynczych obrazów, natomiast NanoTrack skupia się na czasowo-rozdzielczych workflow sekwencji STM.

Co robi NanoTrack?

NanoTrack prowadzi użytkownika przez workflow analizy dynamiki STM:

  1. Wczytanie sekwencji STM z filmów MPP albo uporządkowanych serii klatek STM.
  2. Inspekcja metadanych i nawigacja po klatkach z kontrolkami przypominającymi odtwarzanie.
  3. Preprocessing trudnych sekwencji przez naprawę artefaktów poziomych i odszumianie BM3D.
  4. Rejestracja dryfu klatka-po-klatce z użyciem kilku backendów.
  5. Tworzenie seedów trackingu ręcznie albo z detekcji YOLO.
  6. Tracking cząstek albo krawędzi stopni przy użyciu backendów mask, point i edge.
  7. Interaktywny przegląd i korekta tracków w GUI.
  8. Eksport metryk i sesji do powtarzalnej dalszej analizy.

Aplikacja przechowuje anotacje cząstek i krawędzi w układzie współrzędnych klatek. Widoki aligned i expanded aligned służą głównie do przeglądu oraz kontroli jakości rejestracji.

Obsługiwane dane wejściowe

NanoTrack jest obecnie przeznaczony dla sekwencji obrazów przypominających szare obrazy STM.

Typ wejściaUżycie w NanoTrack
.mppNatywny loader filmu STM albo sekwencji wieloklatkowej. Metadane czasu klatek są odczytywane, gdy są dostępne.
.stpPojedyncza klatka STM; wiele plików .stp może zostać wczytanych jako uporządkowana seria.
.s94Pojedyncza klatka STM; wiele plików .s94 może zostać wczytanych jako uporządkowana seria.

Dla serii .stp i .s94 klatki muszą mieć zgodne wymiary obrazu. Aplikacja wczytuje je w kolejności wybranej przez użytkownika. Dostępna jest również opcja reverse-open dla sekwencji, w których kolejność eksperymentalna musi zostać odwrócona.

Główny workflow

1. Wczytanie sekwencji

Sekwencję można wczytać przez:

File -> Open STM...

albo, gdy trzeba odwrócić kolejność:

File -> Open STM Reverse...

NanoTrack tworzy wewnętrzny obiekt STMSequence, który przechowuje:

  • surowy stos klatek,
  • ścieżkę źródłową albo listę plików źródłowych,
  • liczbę klatek,
  • rozmiar obrazu i skalę pikseli,
  • metadane kanału,
  • rozmiar skanu,
  • napięcie i setpoint, gdy są dostępne,
  • timing klatek, gdy można go odczytać z metadanych MPP.

Główny widok pokazuje aktywną klatkę i pozwala nawigować po sekwencji. Pojedyncze klatki mogą zostać wykluczone z późniejszej analizy i eksportu.

2. Inspekcja i preprocessing

Centralny widok jest wspierany przez metadane, nawigację po klatkach, warstwy overlay i panele boczne narzędzi trackingowych.

Dostępne narzędzia preprocessingu obejmują:

  • horizontal dropout repair dla liniowych braków albo uszkodzonych artefaktów skanowania,
  • podgląd naprawy i workflow apply-to-all,
  • podgląd odszumiania BM3D,
  • batchowe zastosowanie BM3D do wszystkich klatek,
  • opcjonalne wyświetlanie zcache’owanych klatek po preprocessingu w głównym widoku.

Preprocessing ma poprawić trackability i jakość detekcji krawędzi. Nie zastępuje ręcznego przeglądu wyników.

3. Rejestracja sekwencji

NanoTrack zawiera workflow rejestracji do inspekcji dryfu i wyrównania klatek.

Akcje na pasku narzędzi:

Registration Preview...
Run Registration...
View Registration...
Show Aligned
Show Expanded Aligned

Backendy rejestracji dostępne w GUI:

  • Phase correlation,
  • Tile + RANSAC,
  • ECC translation,
  • Optical-flow median shift,
  • Deep matcher translation.

Wyniki rejestracji obejmują diagnostykę per klatka:

  • przesunięcia dx, dy,
  • moduł przesunięcia,
  • quality score,
  • status,
  • phase peak ratio,
  • ECC score,
  • liczbę inlier tiles,
  • tile residual,
  • optical-flow MAD.

Wyniki rejestracji można eksportować do CSV jako metryki i pliki podsumowania.

4. Tworzenie seedów cząstek

Tracking cząstek zaczyna się od seed bounding boxów.

NanoTrack obsługuje dwa główne źródła seedów.

Seedy ręczne

Panel bbox pozwala:

  • ustawić domyślny rozmiar bboxa,
  • umieścić bbox na bieżącej klatce,
  • dodać go jako seed track,
  • wczytać bbox tracka do korekty,
  • zapisać ręczną korektę,
  • wznowić track z poprawionej geometrii.

Detekcja seedów YOLO

Panel detekcji YOLO może:

  • wykrywać lokalne checkpointy modeli YOLO,
  • uruchamiać detekcję na bieżącej klatce,
  • uruchamiać detekcję na wszystkich klatkach,
  • skalować bounding boxy wokół ich środków,
  • edytować wybrane detekcje,
  • zaznaczać i odznaczać detekcje globalnie albo per klatka,
  • konwertować wybrane detekcje na seedy trackingu.

Checkpointy YOLO są wykrywane z katalogu:

nanotrack/yolo_models/

Obsługiwane rozszerzenia checkpointów:

.pt, .pth, .onnx, .engine

Inferencja YOLO wymaga ultralytics i kompatybilnej instalacji torch.

5. Tracking cząstek w czasie

NanoTrack rozdziela etap tworzenia seedów od etapu trackingu. Po utworzeniu seedów użytkownik może uruchomić tracking dla wybranego seedu albo dla wszystkich seedów.

Backendy mask trackingu dostępne w UI:

  • SAM2,
  • DAM4SAM,
  • SAMURAI.

Wynik trackingu jest zapisywany jako anotacje indeksowane numerem klatki dla każdego tracka cząstki. W zależności od backendu i stanu przeglądu anotacje mogą zawierać:

  • geometrię bbox,
  • maskę segmentacji,
  • stan widoczności,
  • backend źródłowy,
  • widok źródłowy,
  • metryki per klatka.

Metryki cząstek obejmują:

  • pole powierzchni w pikselach,
  • pole powierzchni w nm², gdy dostępna jest kalibracja,
  • obwód w pikselach,
  • obwód w nm, gdy dostępna jest kalibracja,
  • sumę intensywności,
  • średnią intensywność,
  • maksymalną intensywność.

6. Tworzenie i tracking ROI krawędzi stopni

NanoTrack obsługuje również workflow krawędzi stopni przez wielokątne ROI i polilinie krawędzi.

Panel polygon ROI pozwala:

  • narysować wielokątne ROI na klatce,
  • podejrzeć detekcję krawędzi wewnątrz ROI,
  • uruchomić detekcję krawędzi dla wybranego zakresu klatek,
  • wczytać i poprawić bieżącą krawędź,
  • zapisać ręczne korekty krawędzi,
  • wznowić tracking krawędzi,
  • ponownie wykryć jedną klatkę albo zakres,
  • uruchomić hybrydową stabilizację krawędzi z użyciem point trackerów.

Backendy detekcji krawędzi dostępne w UI:

  • DexiNed,
  • TEED,
  • NBED,
  • DDN,
  • PiDiNet,
  • UAED,
  • MuGE.

Opcje ekstrakcji i doprecyzowania polilinii krawędzi obejmują:

  • graph path extraction,
  • PCA + binning,
  • combined refinement score,
  • edge-probability refinement,
  • gradient-based refinement,
  • konfigurowalny promień doprecyzowania w kierunku normalnym.

Metryki krawędzi obejmują:

  • długość polilinii w pikselach,
  • długość w nm, gdy dostępna jest kalibracja,
  • RMS roughness,
  • RMS roughness w nm, gdy dostępna jest kalibracja,
  • średnią krzywiznę,
  • maksymalną krzywiznę,
  • amplitudę waviness.

7. Hybrydowa stabilizacja krawędzi przez point trackery

Dla workflow krawędzi stopni NanoTrack może próbkować punkty kontrolne z polilinii anchor i stabilizować albo propagować krawędź w czasie przy użyciu backendów point tracking.

Point trackery spięte przez subprocess launchery:

  • TAPIR,
  • LocoTrack,
  • Track-On-R.

Te trackery są opcjonalne i wymagają osobnych instalacji lokalnych, checkpointów modeli oraz konfiguracji backendu.

8. Przegląd wyników

NanoTrack udostępnia osobne okna wyników dla:

  • tracków cząstek,
  • tracków krawędzi stopni,
  • jakości rejestracji.

Okna wyników są przeznaczone do ręcznej kontroli przed eksportem. Pokazują tabele i wykresy potrzebne do oceny, czy tracki, wykluczenia klatek, jakość rejestracji i obliczone metryki nadają się do dalszej analizy.

9. Eksport i zapis sesji

NanoTrack wspiera powtarzalny zapis sesji i eksport CSV.

Format sesji

Natywne sesje używają rozszerzenia:

.nanotrack

Plik sesji jest snapshotem projektu opartym o zip. Przechowuje:

  • referencję do sekwencji źródłowej,
  • aktywną klatkę,
  • wykluczone klatki,
  • tracki cząstek,
  • tracki krawędzi,
  • detekcje YOLO,
  • robocze bboxy,
  • robocze wielokątne ROI,
  • robocze polilinie krawędzi,
  • metadane cache naprawy i odszumiania,
  • wyniki rejestracji,
  • flagi widoków aligned.

Eksport wyników cząstek

Eksport cząstek tworzy:

<name>_metrics.csv
<name>_summary.csv

Plik metrics zawiera pomiary per track i per klatka. Plik summary agreguje statystyki per track.

Eksport wyników krawędzi

Eksport krawędzi tworzy:

<name>_edge_metrics.csv
<name>_edge_summary.csv

Plik metrics zawiera geometrię per edge i per klatka. Plik summary agreguje statystyki per edge.

Eksport rejestracji

Eksport rejestracji tworzy:

<name>_registration_metrics.csv
<name>_registration_summary.csv

Te pliki są przydatne do dokumentowania jakości korekcji dryfu i wykluczania problematycznych klatek.

Typowe zastosowania

Czasowo-rozdzielczy tracking cząstek STM

NanoTrack pozwala śledzić jasne cząstki, adsorbaty, defekty albo lokalne cechy w filmach STM. Workflow łączy ręczne albo YOLO-based seedowanie z mask trackingiem i ilościowymi pomiarami per klatka.

Inspekcja dryfu STM i QA rejestracji

Podgląd rejestracji i rejestracja batchowa pozwalają sprawdzić, jak bardzo sekwencja dryfuje w czasie. Eksport metryk rejestracji dokumentuje przesunięcia, jakość i tryby awarii.

Dynamika krawędzi stopni

Wielokątne ROI i backendy detekcji krawędzi pozwalają identyfikować krawędzie stopni i śledzić ich położenie w sekwencji klatek. Metryki krawędzi mogą opisywać długość, chropowatość, krzywiznę i waviness.

Benchmarking metod trackingu

NanoTrack może służyć jako środowisko testowe do porównywania rejestracji klasycznej, mask trackingu, point trackingu i backendów detekcji krawędzi na tej samej sekwencji STM.

Ręczna kuracja przed analizą ilościową

Aplikacja nie jest czarną skrzynką do w pełni automatycznej analizy. Wspiera ręczne umieszczanie seedów, korekty, usuwanie tracków, wykluczanie klatek i przegląd wyników.

Powtarzalna analiza filmów STM

Sesje .nanotrack pozwalają zachować stan analizy, a eksport CSV przenosi wyniki do notebooków, narzędzi statystycznych albo figur manuskryptu.

Instalacja i uruchomienie

Minimalny lokalny workflow:

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install PyQt6 pyqtgraph numpy scipy scikit-image matplotlib
python -m nanotrack.main

W zależności od wybranego workflow mogą być potrzebne dodatkowe zależności:

pip install bm3d
pip install ultralytics torch

Zewnętrzne backendi AI, takie jak SAM2, DAM4SAM, SAMURAI, TAPIR, LocoTrack, Track-On-R, TEED, NBED, DDN, PiDiNet, UAED, MuGE i DexiNed, mogą wymagać osobnych repozytoriów, checkpointów i dedykowanych środowisk Python albo Conda.

Opcjonalne backendi subprocess

NanoTrack używa wrapperów subprocess dla kilku ciężkich zewnętrznych modeli AI. Pozwala to oddzielić główne środowisko aplikacji PyQt od środowisk specyficznych dla trackerów.

Point trackery są konfigurowane przez zmienne środowiskowe z prefiksami takimi jak:

NANOTRACK_TAPIR_PYTHON
NANOTRACK_TAPIR_REPO
NANOTRACK_TAPIR_CHECKPOINT
NANOTRACK_TAPIR_DEVICE
NANOTRACK_TAPIR_TIMEOUT_SEC

NANOTRACK_LOCOTRACK_PYTHON
NANOTRACK_LOCOTRACK_REPO
NANOTRACK_LOCOTRACK_CHECKPOINT
NANOTRACK_LOCOTRACK_DEVICE
NANOTRACK_LOCOTRACK_TIMEOUT_SEC

NANOTRACK_TRACKONR_PYTHON
NANOTRACK_TRACKONR_REPO
NANOTRACK_TRACKONR_CHECKPOINT
NANOTRACK_TRACKONR_DEVICE
NANOTRACK_TRACKONR_TIMEOUT_SEC

Mask trackery i detektory krawędzi również zależą od konfiguracji backendów i lokalnych ścieżek modeli. W czystym wdrożeniu te ścieżki powinny zostać przejrzane i zastąpione konfiguracją specyficzną dla danej stacji roboczej albo bardziej przenośną warstwą konfiguracji.

Aktualny status

NanoTrack jest aplikacją w aktywnym rozwoju. Główne GUI, wczytywanie sekwencji, workflow rejestracji, zarządzanie seedami, zapis sesji, metryki cząstek, metryki krawędzi i eksport CSV są obecne w repozytorium, ale kilka backendów wspieranych przez AI zależy od opcjonalnych środowisk zewnętrznych.

Podsumowanie bieżącego stanu:

  • Wystarczająco stabilne dla wewnętrznych workflow eksperymentalnych: wczytywanie sekwencji, ręczne seedy, zapis/odczyt sesji, podgląd i wyniki rejestracji, eksport wyników cząstek i krawędzi.
  • Zależne od backendu: YOLO, SAM2, DAM4SAM, SAMURAI, TAPIR, LocoTrack, Track-On-R i głębokie detektory krawędzi.
  • Wymaga ręcznego przeglądu: jakość tracków, jakość ekstrakcji krawędzi, nieudane klatki, wykluczenia klatek i status rejestracji.
  • Nie jest jeszcze gotowym publicznym pakietem turnkey: zewnętrzne ścieżki modeli, checkpointy i konfiguracja środowiska mogą wymagać ustawień specyficznych dla projektu.

Najważniejsze funkcje

  • viewer filmów STM i serii klatek,
  • obsługa .mpp, .stp i .s94,
  • metadane klatek i nawigacja w stylu odtwarzania,
  • naprawa artefaktów poziomych i odszumianie BM3D,
  • podgląd rejestracji i rejestracja batchowa,
  • rejestracja przez phase, Tile+RANSAC, ECC, optical flow i deep matcher,
  • ręczne seedy bbox i detekcja seedów YOLO,
  • mask tracking SAM2 / DAM4SAM / SAMURAI,
  • point tracking TAPIR / LocoTrack / Track-On-R dla stabilizacji krawędzi,
  • polygon ROI workflow dla trackingu krawędzi stopni,
  • backendy krawędzi DexiNed / TEED / NBED / DDN / PiDiNet / UAED / MuGE,
  • metryki pola, obwodu i intensywności cząstek,
  • metryki długości, roughness, krzywizny i waviness krawędzi,
  • metryki QA rejestracji i eksport CSV,
  • zapis/odczyt sesji .nanotrack.

Licencja

Repozytorium jest dystrybuowane na licencji MIT.