Nanoparticle Analyzer (NaParA)

O projekcie

Nanoparticle Analyzer (NaParA) to desktopowa aplikacja PyQt6 do inspekcji obrazów STM, preprocessingu, detekcji obiektów przypominających nanocząstki oraz ilościowej analizy obrazu. Program jest przeznaczony do workflow badawczych, w których użytkownik musi wczytać dane STM, sprawdzić metadane i kalibrację, zdefiniować region zainteresowania, wykryć obiekty, zmierzyć ich geometrię i porównać wyniki pomiędzy obrazami albo seriami obrazów.

NaParA zamienia obrazy STM w powtarzalne pomiary na poziomie nanocząstek: kontury, centroidy, pola powierzchni, odległości do najbliższych sąsiadów, podsumowania per obraz, wykresy i eksport CSV.

Co robi NaParA?

NaParA koncentruje się na analizie nanocząstek prowadzonej w regionie zainteresowania. Taki model pracy jest praktyczny dla danych, w których nanocząstki, wyspy, jasne obiekty albo podobne cechy nanoskalowe muszą być wykrywane i mierzone wielokrotnie na wielu obrazach.

Główne funkcje obejmują:

wczytywanie danych STM z obsługiwanych formatów eksperymentalnych,
zachowanie kalibracji i metadanych, takich jak rozmiar skanu, skala pikseli, typ kanału, napięcie, prąd, kąt skanowania i indeks klatki,
wyświetlanie obrazów STM w jednostkach fizycznych, z osiami kalibrowanymi w nanometrach, gdy metadane są dostępne,
tworzenie i edycję prostokątnego regionu zainteresowania,
podgląd ROI z tymi samymi poziomami wyświetlania i LUT co obraz główny,
lekki preprocessing ROI przed detekcją,
progową detekcję konturów i obiektów wewnątrz ROI,
przechowywanie wykrytych obiektów jako edytowalnych nakładek konturowych,
obliczanie pola powierzchni, centroidu i odległości do najbliższego sąsiada dla każdego obiektu,
wizualizację rozkładów pól powierzchni i odległości sąsiedzkich per obraz,
wykresy średniego pola powierzchni i średniej odległości najbliższego sąsiada w serii obrazów,
eksport tabel i wykresów do dalszej analizy.

Obsługiwane dane wejściowe

Aktualny loader obsługuje pliki STM z czytników repozytorium:

Format	Zachowanie
`.stp`	Jednoklatkowy obraz STM Omicron. Parser odczytuje metadane nagłówka i binarne dane obrazu.
`.s94`	Obraz STM SPECS. Kanały topografii/prądu oraz fizyczne metadane skanu są odczytywane, gdy są dostępne.
`.mpp`	Plik movie/sequence Omicron. Plik jest rozwijany do osobnych klatek `STMImage`.

Wczytane obrazy są reprezentowane wewnętrznie jako obiekty STMImage, które przechowują surową tablicę pikseli, wymiary, fizyczny rozmiar skanu, offsety, kąt skanowania, napięcie, setpoint/prąd, typ obrazu i opcjonalne dane po preprocessingu.

Typowy workflow

1. Wczytanie obrazów STM

Aplikację można uruchomić z katalogu repozytorium:

python -m napara.main

W głównym oknie użytkownik dodaje jeden albo wiele plików STM z panelu listy obrazów. NaParA przyjmuje wiele obrazów .stp i .s94, a pliki .mpp może rozwinąć do sekwencji klatek. Każdy wczytany obraz pojawia się na liście i może być analizowany niezależnie.

Po wyborze obrazu panel metadanych pokazuje nazwę pliku, wymiary w pikselach, fizyczny rozmiar skanu, skalę pikseli i typ kanału. Główny widok pokazuje obraz z osiami skalibrowanymi, gdy dostępna jest informacja nm/px.

2. Inspekcja obrazu i definicja ROI

NaParA jest zbudowana wokół analizy ROI. Narzędzia ROI pozwalają utworzyć albo zresetować prostokątny region zainteresowania na aktywnym obrazie. ROI jest przechowywany osobno dla każdego obrazu i może być interaktywnie dopasowywany.

Podgląd ROI aktualizuje się z aktywnego obrazu i odzwierciedla aktualne ustawienia przetwarzania. Dzięki temu parametry detekcji można stroić lokalnie przed zapisaniem detekcji jako nakładek na obrazie.

3. Preprocessing

NaParA ma dwa poziomy preprocessingu.

Lekki pipeline ROI/obrazu w głównym panelu przetwarzania obejmuje:

filtr Gaussa,
filtr medianowy,
filtr white top-hat,
progowanie Otsu albo Sauvola,
usuwanie obiektów poniżej minimalnego pola powierzchni,
przełącznik detekcji konturów/obiektów.

Pełnoobrazowe okno preprocessingu udostępnia cięższe operacje dla trudnych danych STM:

filtrowanie medianowe,
plane albo polynomial leveling,
korekcję linii skanowania i destriping,
usuwanie trendu linii metodą LOWESS,
korekcję baseline linii przez RANSAC,
usuwanie smug prowadzone przez transformację Hougha,
dekonwolucję,
odszumianie waveletowe,
non-local means,
dyfuzję Perona-Malika,
directional total variation,
BM3D,
directional morphological reconstruction,
opcjonalne odszumianie U-Net, gdy dostępne są kompatybilne wagi PyTorch.

Obrazy po preprocessingu mogą być używane jako źródło dla podglądu ROI i detekcji, przy zachowaniu oryginalnych danych.

4. Detekcja nanocząstek w ROI

Po włączeniu progowania i detekcji konturów użytkownik uruchamia detekcję dla aktywnego ROI. Detektor stosuje skonfigurowany preprocessing, progowanie i ekstrakcję połączonych konturów wewnątrz regionu zainteresowania.

Wykryte obiekty są zapisywane jako nakładki konturowe. Każdy obiekt otrzymuje ID, kontur wielokątny w współrzędnych pikselowych, centroid i pole powierzchni. Nowy przebieg detekcji zastępuje detekcje wewnątrz aktywnego ROI, ale zachowuje detekcje poza nim.

5. Przegląd, edycja i pomiar detekcji

Panel detekcji pokazuje obiekty dla aktywnego obrazu wraz z:

ID obiektu,
polem powierzchni w nm², gdy dostępna jest kalibracja,
ID najbliższego sąsiada,
odległością do najbliższego sąsiada w nm.

Użytkownik może pokazywać albo ukrywać kontury, pokazywać albo ukrywać etykiety, usuwać wybrane detekcje, czyścić wszystkie detekcje aktywnego obrazu i obliczać najbliższych sąsiadów. Odległości sąsiedzkie są liczone z centroidów w skalibrowanych współrzędnych nanometrowych przy użyciu KD-tree.

6. Podsumowanie i eksport wyników

Okno wyników udostępnia dwa widoki analizy:

Per image - rozkład pól powierzchni i rozkład odległości najbliższego sąsiada dla wybranego obrazu, prezentowane jako wykresy KDE/histogramy, gdy liczba danych jest wystarczająca.
Summary - średnie pole powierzchni i średnia odległość najbliższego sąsiada dla wszystkich wczytanych obrazów.

Oś X w podsumowaniu może używać:

indeksu obrazu,
zaimportowanych wartości czasu,
zaimportowanych wartości potencjału elektrochemicznego Ep vs RHE.

Eksport wyników tworzy katalog wyniki z plikami:

summary.csv - jeden wiersz per obraz,
detections_long.csv - jeden wiersz per wykryty obiekt,
summary_mean_area.png,
summary_mean_nn.png,
obrazy PNG rozkładów pola powierzchni dla poszczególnych obrazów,
obrazy PNG rozkładów odległości najbliższego sąsiada dla poszczególnych obrazów.

7. Zapis i odczyt projektów

Projekty NaParA są zapisywane jako pliki .napara. Archiwum projektu przechowuje:

listę obrazów i relatywne ścieżki źródłowe,
indeks aktywnego obrazu,
prostokąty ROI,
detekcje,
wartości najbliższych sąsiadów,
opcjonalne tablice po preprocessingu.

Aplikacja wspiera również szybki zapis i odczyt slotów w lokalnym katalogu saves/.

Główne zastosowania

Analiza populacji nanocząstek

NaParA może służyć do liczenia cząstek i porównywania rozkładów rozmiarów pomiędzy obrazami STM. Jest to przydatne, gdy celem jest ilościowe określenie pokrycia, pozornego rozmiaru albo odległości sąsiedzkich w zależności od próbki, warunków preparatyki albo stanu elektrochemicznego.

Serie STM zależne od czasu albo potencjału

Dla serii obrazów, w których nazwa pliku albo importowane metadane mogą być powiązane z czasem albo potencjałem elektrody, okno wyników może pokazywać średnie pole powierzchni i średnią odległość sąsiedzką względem indeksu obrazu, czasu albo Ep vs RHE.

Detekcja lokalna na niejednorodnych powierzchniach

Wiele obrazów STM zawiera regiony o różnym kontraście, dryfie, smugach albo tle. NaParA pozwala ograniczyć detekcję do zdefiniowanego ROI, więc parametry mogą być dopasowane do naukowo istotnego obszaru zamiast wymuszać jeden globalny próg dla całej klatki.

Eksperymenty z preprocessingiem i odszumianiem

Pełnoobrazowe okno preprocessingu pozwala testować wpływ levelingu, destripingu, odszumiania, dekonwolucji i operacji morfologicznych na późniejszą detekcję obiektów. To pomaga porównywać strategie przetwarzania bez odrywania ich od wyników ilościowych.

Kuracja danych do dalszych workflow

NaParA przechowuje wykryte kontury i pomiary w pliku projektu oraz eksportuje wyniki w formacie long-form CSV. Dzięki temu nadaje się do budowania skuratowanych datasetów referencyjnych i porównywania strategii detekcji w trakcie rozwoju oprogramowania.

Instalacja i uruchomienie

Aktualne archiwum nie zawiera przypiętego requirements.txt, więc zależności powinny być instalowane zgodnie z workflow, który ma być używany.

Praktyczne środowisko bazowe dla GUI NaParA:

pip install PyQt6 pyqtgraph numpy scipy scikit-image matplotlib statsmodels bm3d torch

bm3d i torch są częścią praktycznego środowiska bazowego, ponieważ aktualny kod rozwojowy importuje moduły preprocessingu i U-Net przez ścieżkę GUI. Jeżeli te importy zostaną później opóźnione, torch może stać się opcjonalny dla użytkowników, którzy nie korzystają z denoisera U-Net.

Dla eksportu par HDF5 należy dodatkowo zainstalować:

pip install h5py

Aktualny status

NaParA jest badawczą aplikacją desktopową w aktywnym rozwoju. Aktualny kod obejmuje działającą ścieżkę dla wczytywania obrazów STM, podglądu ROI, preprocessingu, detekcji konturów, metryk per obiekt, analizy najbliższych sąsiadów, wykresów wyników, eksportu CSV i zapisu projektu .napara.

Ważne informacje o bieżącym stanie:

główny workflow detekcji NaParA jest oparty o ROI, progowanie i kontury,
eksport PDF/raportów nie jest obecnie zaimplementowany; aktualny eksport obejmuje CSV i wykresy PNG,
odszumianie U-Net wymaga kompatybilnych wag PyTorch i wag modelu; kod zgłasza czytelny błąd, gdy wagi nie są dostępne,
dla zastosowań publikacyjnych każdy dataset powinien nadal zostać przejrzany wizualnie po preprocessingu i detekcji.

Zakres NaParA

NaParA jest narzędziem do ilościowej analizy obiektów w obrazach STM: cech przypominających nanocząstki, konturów, centroidów, pól powierzchni, odległości do najbliższych sąsiadów, podsumowań serii obrazów i powtarzalnego eksportu danych.

Licencja

Repozytorium jest dystrybuowane na licencji MIT.