Molecule Detection, Annotation and Analysis (MolDetA)

O projekcie

Molecule Detection, Annotation and Analysis (MolDetA) v2 to desktopowa aplikacja PyQt do kuracji i analizy zsynchronizowanych zbiorów STM na poziomie pojedynczych molekuł. Program jest projektowany dla eksperymentów, w których ten sam obszar próbki jest mierzony jako rodzina czterech skanów:

• fwd_topo - topografia w kierunku forward,
• bwd_topo - topografia w kierunku backward,
• fwd_current - mapa prądu w kierunku forward,
• bwd_current - mapa prądu w kierunku backward.

Najważniejsza zasada projektowa jest taka, że wszystkie widoki pokazują oryginalne, niewarpowane obrazy STM. Rejestracja działa wewnętrznie jako warstwa mapowania współrzędnych: do propagacji pozycji molekuł, sprawdzania spójności i uruchamiania dalszej analizy. Dzięki temu użytkownik kurator pracuje na danych pomiarowych, a nie na wizualnie przekształconych obrazach.

Co robi MolDetA v2?

MolDetA v2 prowadzi użytkownika od surowych skanów STM do skuratowanych zbiorów molekuł i tabel gotowych do dalszej analizy. W jednym workflow łączy wczytywanie danych czteroskanowych, rejestrację, detekcję, ręczną anotację, grupowanie, przegląd kategorii, analizę siatki akwizycji i eksport.

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

• wczytywanie pojedynczego pliku STM z automatycznym wyszukiwaniem powiązanych skanów z tej samej rodziny,
• zsynchronizowane widoki 2×2 dla jednoczesnego przeglądu topografii i prądu w kierunku forward/backward,
• wewnętrzną rejestrację i mapowanie współrzędnych oparte o wstępne dopasowanie sztywne i optical flow,
• detekcję molekuł na wybranym skanie źródłowym przez YOLO albo klasyczne pipeline’y przetwarzania obrazu,
• propagację bounding boxów ze skanu źródłowego do pozostałych ról skanów,
• ręczną kurację bboxów: przesuwanie, zmianę rozmiaru, usuwanie, blokowanie, kategoryzację i edycję powiązaną,
• grupowanie molekuł pomiędzy czterema rolami skanów,
• osobne okno listy molekuł do pracy na drugim monitorze,
• numeryczne kategorie i filtrowanie dla gęstych scen,
• analizę siatki akwizycji, czasu, intensywności i obserwacji linia-po-linii,
• analizę wyższego poziomu: podglądy tabel, wykresy Hopkinsa, rozkłady warunkowe i widoki przejść pomiędzy grupami,
• natywny zapis/odczyt sesji .molda2 oraz import starszych sesji MolDetA v1.

Dlaczego przegląd oryginalnych obrazów jest ważny?

Skany STM są wykonywane sekwencyjnie i mogą różnić się geometrią, kontrastem, kierunkiem skanowania, kanałem topografia/prąd i warunkami tunelowania. Wyświetlanie obrazów po deformacji geometrycznej może utrudnić kurację, ponieważ użytkownik nie widzi już dokładnie tego, co zostało zmierzone.

MolDetA v2 rozwiązuje ten problem inaczej:

• cztery widoki zawsze pokazują oryginalne klatki STM,
• wyniki rejestracji są zapisywane jako wewnętrzne artefakty mapowania,
• propagowane bboxy są nakładkami obliczanymi z mapowania,
• ręczne korekty są jawne i nie są ukrywane w transformacji obrazu.

Ten model pracy jest szczególnie przydatny przy przeglądzie molekuła-po-molekule, gdy topografia i kanał prądowy mają różny kontrast albo gdy skany forward/backward zawierają niewielkie przesunięcia pozycji.

Typowy workflow

1. Wczytanie jednego pliku STM

Użytkownik wybiera File → Open one STM file… i wskazuje jeden plik z rodziny skanów. MolDetA v2 próbuje odnaleźć pliki powiązane z rolami:

• fwd_topo,
• bwd_topo,
• fwd_current,
• bwd_current.

Aktualny workflow edycyjny v2 jest przeznaczony dla kompletnego zestawu czterech obrazów. Jeżeli którejś roli brakuje, aplikacja raportuje dokładnie brakujące elementy, aby zbiór danych mógł zostać poprawiony przed analizą.

2. Ocena jakości rejestracji

Przed zaufaniem propagowanej geometrii użytkownik może uruchomić Tools → Registration Sandbox (4 scans)…. Sandbox wspiera rejestrację anchor-based, domyślnie z fwd_topo jako obrazem odniesienia, i pokazuje diagnostykę: przesunięcia, zachowanie optical flow, residuals, maski oraz wskaźniki jakości mapowania.

Warstwa rejestracji służy do mapowania współrzędnych pomiędzy rolami skanów, a nie do zastępowania oryginalnie wyświetlanych obrazów.

3. Detekcja molekuł na skanie źródłowym

Użytkownik wybiera aktywny obraz źródłowy i uruchamia detektor. MolDetA v2 obsługuje dwie rodziny detekcji:

• detekcję YOLO dla propozycji opartych o model,
• detekcję klasyczną opartą o preprocessing, lokalne maksima, Difference of Gaussians i workflow typu Laplacian of Gaussian.

Detekcje są konwertowane do kanonicznych obiektów molekuła/bbox. Ich środki mogą być następnie propagowane do pozostałych ról przez wewnętrzne mapowanie współrzędnych.

4. Ręczna kuracja bboxów

Po detekcji i propagacji użytkownik przegląda wszystkie bboxy bezpośrednio na oryginalnych obrazach STM. Może:

• dodać bbox ręcznie,
• przesunąć albo zmienić rozmiar bboxa w jednej roli skanu,
• przesuwać albo skalować powiązane bboxy razem,
• usunąć geometrię wybranej roli,
• zablokować obiekty przed przypadkową edycją,
• przypisać albo wyczyścić kategorię numeryczną,
• używać filtrów i trybów przyciemnienia, aby skupić się na wybranych klasach molekuł.

Geometria ręczna ma pierwszeństwo przed geometrią propagowaną albo wykrytą automatycznie. Praktyczna hierarchia źródeł wygląda tak:

manual > propagated > detected

5. Grupowanie molekuł pomiędzy czterema rolami

MolDetA v2 reprezentuje tożsamość molekuły przez grupy bboxów specyficznych dla ról skanów. Jedna grupa może zawierać po jednym bboxie dla każdej roli. Tryb grupowania pozwala tworzyć i edytować relacje pomiędzy:

• topografią forward,
• topografią backward,
• prądem forward,
• prądem backward.

Dzięki temu pojedyncza molekuła może być śledzona spójnie pomiędzy kierunkiem skanowania i kanałem obrazowania, przy zachowaniu oryginalnej geometrii każdej roli.

6. Zapis sesji

Opcja File → Save Session v2… zapisuje kompletny projekt jako natywną sesję .molda2. Sesja przechowuje referencje do danych, artefakty rejestracji, geometrię bboxów, grupowanie, kategorie, stan przeglądu wizualnego i ustawienia analizy akwizycji.

Opcja File → Load Session v2… pozwala później kontynuować pracę.

7. Analiza akwizycji i dalsze workflow

Po zakończeniu kuracji molekuł użytkownik może uruchomić narzędzia analityczne:

1. Acquisition Grid Setup - konfiguracja odtworzonej albo natywnej siatki akwizycji, orientacji, odbić, offsetów, kontekstu prędkości skanowania i synchronizacji linii anchor dla kierunków forward/backward.
2. BBox Intensity / Time Analysis - ekstrakcja intensywności i statystyk czasowych na poziomie molekuł dla widoków pojedynczych i parowanych.
3. Line-Wise Analysis - ekstrakcja obserwacji linia-po-linii dla molekuł przecinających linie akwizycji albo komórki siatki.
4. Higher-Level Analysis - przegląd wyników BBox/Line-Wise przez tabele, wykresy Hopkinsa, rozkłady warunkowe i widoki przypisań oraz przejść grup.

Eksport CSV jest dostępny z narzędzi BBox i Line-Wise analysis.

Główne zastosowania

Kuracja molekuł w czterech skanach

MolDetA v2 pozwala kuratorowi pracować na pozycjach molekuł jednocześnie w skanach forward/backward oraz topografia/prąd, bez odrywania się od oryginalnych danych pomiarowych.

Mapowanie molekuł pomiędzy kanałami

Molekuły można wykryć w skanie o najlepszym kontraście, a następnie przenieść środki bboxów do pozostałych ról przez mapowanie rejestracyjne. Jest to przydatne, gdy molekuła jest łatwiejsza do detekcji w jednym kanale, ale analiza wymaga porównania wszystkich czterech skanów.

Ręczna korekta po automatycznej detekcji

YOLO albo detekcja klasyczna mogą pełnić rolę szybkiego pierwszego przebiegu. Użytkownik może następnie ręcznie poprawić poszczególne bboxy. Edycje ręczne są jawnie śledzone i mają pierwszeństwo przed geometrią automatyczną.

Przegląd gęstych scen i kategoryzacja

Kategorie numeryczne, filtry, przyciemnienie, blokady i osobna lista molekuł wspierają przegląd zatłoczonych pól molekularnych. Ułatwia to klasyfikację, ponowne przypisanie i kontrolę jakości.

Analiza spójności forward/backward

Grupowanie bboxów pomiędzy skanami forward i backward pozwala porównywać geometrię, intensywność, czas i obserwacje linia-po-linii między kierunkami skanowania.

Analiza czasu akwizycji i linii skanowania

Konfiguracja siatki akwizycji umożliwia powiązanie pozycji molekuł z czasem skanowania, liniami akwizycji i zachowaniem intensywności.

Migracja starszych projektów

MolDetA v2 może importować historyczne, parowe sesje MolDetA v1 i kontynuować pracę w modelu czterech ról. Sesje legacy są traktowane jako dane wejściowe do migracji, a MolDetA v2 jest głównym workflow dla aktualnych prac.

Przygotowanie datasetów detekcyjnych

Skuratowane anotacje molekuł można eksportować w układzie images/labels zgodnym ze stylem YOLO, co pozwala trenować albo ulepszać kolejne modele detekcji.

Wejście i wyjście

Obsługiwane wejścia STM

• .stp,
• .s94.

Format sesji

• natywna sesja MolDetA v2: .molda2,
• import legacy MolDetA v1: .pkl z plikiem towarzyszącym _alignment.npz.

Eksport

• eksport danych treningowych YOLO ze stanu bieżącej kuracji,
• eksport CSV z BBox Intensity / Time Analysis,
• eksport CSV z Line-Wise Analysis,
• artefakty walidacji geometrycznej CSV/JSON/Markdown generowane przez skrypt walidacyjny.

Instalacja i uruchomienie

Podstawowe zależności:

pip install -r requirements.txt

Zalecane pakiety opcjonalne dla workflow przetwarzania obrazu:

pip install scikit-image bm3d

Dla workflow detekcji YOLO potrzebne są również Ultralytics i kompatybilna wersja PyTorch:

pip install ultralytics torch

Uruchomienie MolDetA v2:

python -m moldeta_v2.main

MolDetA v2 jest rozwijana jako desktopowa aplikacja PyQt. Zalecany jest Python 3.10+. Workflow CPU są wspierane, a GPU NVIDIA jest opcjonalne i może przyspieszyć detekcję YOLO.

Relacja do MolDetA v1

Repozytorium zawiera również starszą aplikację moldeta. Jest użyteczna dla historycznych workflow parowych i walidacji ścieżki migracji, ale MolDetA v2 jest aktualną wersją i głównym celem testów.

Projekty legacy MolDetA v1 mogą być importowane do MolDetA v2 w celu dalszego czteroskanowego przeglądu i analizy.

Relacja do LFA

MolDetA v2 i LFA rozwiązują różne problemy analizy STM:

• LFA skupia się na metrologii sieciowej w przestrzeni odwrotnej: FFT, kalibracji afinicznej, parametrach sieci podłoża i adsorbatu, okresowościach superstruktur oraz metrykach sieciowych z niepewnościami.
• MolDetA v2 skupia się na anotacji i analizie molekuł w zsynchronizowanych skanach STM: detekcji, propagacji bboxów, ręcznej kuracji, grupowaniu, analizie czasu/intensywności i eksporcie.

Razem obejmują komplementarne części szerszego workflow analizy STM/EC-STM.

Aktualny status

MolDetA v2 jest na etapie testowania i stabilizacji. Główny kontrakt implementacyjny jest funkcjonalnie kompletny: wczytywanie, rejestracja, detekcja, propagacja, edycja ręczna, grupowanie, zapis sesji, migracja z v1, analiza akwizycji, eksporty i narzędzia przeglądu wyższego poziomu są zaimplementowane.

Pozostała praca dotyczy przede wszystkim walidacji, testów regresyjnych i praktycznej weryfikacji na docelowych zbiorach danych, a nie dodawania kolejnych dużych obszarów funkcjonalnych.