Rozdział 4 — Okna pomocnicze
Oprócz okna głównego (widok 3D plus Inspector) RadianceKit zarządza trzema innymi oknami, które można otworzyć z menu Pomoc. Menu zawiera pięć pozycji, od góry do dołu: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder… oraz Manage Storage…. Obie pozycje „Open …" nie otwierają okna aplikacji, lecz Findera; dlatego nie są tu dalej omawiane.
Trzy proste okna (User Guide, Keyboard Shortcuts, Manage Storage) oraz dwie pozycje menu prowadzące do folderów (Open Training Logs / Open Exports Folder) otrzymują po jednym krótkim wpisie na każdy element sterujący.
Na końcu rozdziału znajduje się sekcja odsyłaczy do Inspectora okna głównego: co sensownie możesz odczytać z wykresu straty na żywo (Live-Loss-Chart) i ze wskaźnika liczby gaussianów podczas trwającego treningu.
Przewodnik użytkownika (W1–W4)

Co to jest: Wbudowane okno pomocy, które renderuje dostarczony z aplikacją plik guide_<sprache>.md. Język jest ustalany na podstawie ustawień (zakładka General → Language) lub, jeśli tam wybrano „System", na podstawie preferencji językowych macOS. Układ jest klasyczny: po lewej pasek boczny ze wszystkimi nagłówkami, po prawej tekst główny.
Gdy potrzebujesz szybkiego przypomnienia pojedynczej kwestii — czyli jako zamiennik hasła w encyklopedii. Szczegółowym odniesieniem jest ten podręcznik; wbudowane okno pomocy to skrócona wersja do szybkiego sprawdzenia. Jest aktualizowane przy każdym wydaniu aplikacji, ale treściowo pozostaje bardziej powierzchowne.
W1NavigationSplitView (Sidebar + Detail)
GDZIE
Help → User Guide (⌘?).
TECHNICZNIE
Dwukolumnowy układ z wąskim paskiem bocznym (o szerokości co najmniej 180 pt) na drzewo treści oraz przewijanym obszarem szczegółów na właściwą treść Markdown. Okno ma minimalny rozmiar 700 × 500 pt. Przy pierwszym otwarciu okno ładuje odpowiedni plik guide_<lang>.md z pakietu aplikacji (domyślnie guide_en.md), parsuje go na rekordy blokowe (nagłówki H1–H4, akapity, listy, tabele, linie oddzielające) i osobno wyodrębnia strukturę nagłówków na potrzeby paska bocznego. Formatowanie inline (pogrubienie, kursywa, fragmenty kodu) jest renderowane przez wbudowany silnik Markdown. Język jest odczytywany z ustawień aplikacji, ze specjalnym przypadkiem chińskiego (zh-Hans) i portugalskiego brazylijskiego (pt-BR), które są zachowywane jako pełne tagi locale, ponieważ te warianty różnią się od zwykłego zh czy pt.
W2List (pasek boczny z nagłówkami)
GDZIE
Lewa kolumna w oknie przewodnika użytkownika.
TECHNICZNIE
Lista wszystkich nagłówków H2 i H3 bieżącego dokumentu Markdown. Wpisy H2 pojawiają się bez wcięcia, z pogrubioną czcionką (medium weight), wpisy H3 z wcięciem 16 pt po lewej i zredukowanym stylem koloru pierwszoplanowego. Wszystkie inne poziomy — zarówno H1, jak i H4 oraz głębsze — nie pojawiają się w pasku bocznym, ponieważ w przeciwnym razie uczyniłyby go nieprzejrzystym. Identyfikatory kotwic są generowane z tekstu nagłówka poprzez slugifikację (małe litery + spacje zamienione na myślniki + filtrowanie do liter/cyfr/myślników — ten sam algorytm, którego GitHub używa do swoich kotwic Markdown, więc także zewnętrzne adresy URL do dokumentacji mogłyby potencjalnie trafić na tę samą kotwicę). Lista wykorzystuje natywny styl macOS.
W3Button (przejście nagłówek → kotwica)
GDZIE
Po jednym przycisku dla każdego wiersza paska bocznego.
TECHNICZNIE
Każdy wpis w pasku bocznym jest przyciskiem, który ustawia aktualną kotwicę, ale wizualnie wygląda jak element listy. Zmienna obserwująca uruchamia wtedy skok przewijania do odpowiedniej kotwicy z płynną animacją trwającą 0,3 s. Po skoku wartość kotwicy jest resetowana, aby kolejne kliknięcie w tę samą kotwicę ponownie zadziałało (w przeciwnym razie obserwator nie zareagowałby ponownie, ponieważ wartość by się nie zmieniła).
W4ScrollView (treść szczegółowa)
GDZIE
Prawa kolumna.
TECHNICZNIE
Przewijany, pionowo ułożony obszar treści z leniwym renderowaniem (lazy rendering), ponieważ dłuższe przewodniki mogą łatwo mieć ponad 200 bloków Markdown — wariant bez leniwego renderowania instancjonowałby wszystkie naraz. Każdy blok otrzymuje własny identyfikator, albo kotwicę nagłówka (którą otrzymuje każdy nagłówek, niezależnie od poziomu), albo zastępczy indeks. Maksymalna szerokość wynosi 720 pt, wypełnienie 32 poziomo / 24 pionowo, dzięki czemu długie wiersze zachowują czytelny układ. Tabele są renderowane komórka po komórce za pomocą poziomych stosów i linii oddzielających; kod inline przez wbudowany silnik Markdown. Prawdziwe bloki kodu są obecnie traktowane jak akapit — to znane ograniczenie okna pomocy.
Skróty klawiszowe (W5–W6)

Statyczna lista referencyjna w pięciu sekcjach. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (ruch typu Fly-Through), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (regulacja FoV). Views: R (Reset Camera), T (Auto-Rotation), P (Camera Playback), B (Background-Cycle), 0–9 (przeskocz do Training-Cam 1=10%/5=50%/0=ostatnia), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (wideo Turntable), C (Copy Camera Info). Editor: Tab (tryb edycji), Click/Drag (Paint-Select), Option+Click (odznacz), X / Delete (usuń zaznaczenie), Cmd-Z (cofnij ostatnie usunięcie), [ / ] (mniejszy/większy pędzel), Esc (anuluj zaznaczenie). Training: Option+Space (wstrzymaj/wznów trening), Cmd+E (eksportuj scenę). Nic więcej tu nie ma — Start, Cancel oraz przedłużenia treningu znajdziesz w menu Training (rozdział 1).
Co to jest: Prosty, statyczny przegląd wszystkich skrótów klawiszowych — Navigation, Views, Capture, Editor, Training. Zawartość jest zapisana na stałe i nie jest wczytywana z żadnego pliku.
Gdy szukasz najszybszego sposobu, by coś zrobić w Viewport. WASD-Fly-Through, R do resetu kamery, B do przełączania tła — wszystko znajdziesz tutaj.
W5ScrollView (obszar treści)
GDZIE
Help → Keyboard Shortcuts (⌘/).
TECHNICZNIE
Prosty obszar przewijania z pionową listą w środku. Padding 20 dookoła, brak drzewa nawigacji w Sidebar (lista jest wystarczająco krótka). Treść jest pogrupowana w pięć sekcji (Navigation, Views, Capture, Editor, Training). Na każdą kombinację klawiszy przypada jeden wiersz z tekstem podlegającym tłumaczeniu w obu kolumnach. Lewa kolumna (kod klawisza) ma stałą szerokość 180 pt, dzięki czemu opisy po prawej pozostają wyrównane pionowo. Brak interakcji poza przewijaniem — kliknięcie w wiersz niczego nie uruchamia, skróty klawiszowe to prawdziwe modyfikatory klawiatury w menu i w Viewport.
W6VStack (sekcje skrótów)
GDZIE
Wewnątrz ScrollView.
TECHNICZNIE
Sekcje ułożone do lewej krawędzi z odstępem 16 pt. W obrębie każdej z pięciu sekcji znajduje się nagłówek + ciąg wierszy. Nagłówki wykorzystują drugorzędny styl Subheadline — celowo bez formatu Title, bo sekcje nie muszą być nawigowalne. Treść jest celowo płaska (brak Disclosure, brak Search, brak filtra), dzięki czemu komponent działa bez zmian na każdej wersji macOS, a plik pozostaje czytelny.
Zarządzanie pamięcią (W7–W12)

Widok tabelaryczny wszystkich plików zarządzanych przez RadianceKit. Nagłówek pokazuje 1356 elementów, łącznie 55,1 GB. Pasek narzędzi u góry: „Show in Finder" + „Refresh". Każdy wiersz: ikona eksportu, nazwa pliku (np. training_20260718T194416Z.ply), data eksportu, rozmiar (waha się tutaj od 7,8 MB do 2,24 GB), ikona lupy (Reveal) i ikona kosza (Move to Trash). Sortowanie odbywa się najpierw wg kategorii, a w ramach kategorii wg daty, najnowsze na górze. Na tym zrzucie dominują eksporty PLY, ponieważ w tym magazynie zabezpieczono przede wszystkim wyniki treningów.
Co to jest: Przegląd zużycia dysku dla wszystkiego, co RadianceKit zapisuje w ~/Documents/RadianceKit/ — logi, eksporty, sceny, pakiety przechwytywania (z towarzyszącej aplikacji iOS), importy (kopie robocze obrazów wejściowych). Przy każdej pozycji rozmiar w bajtach oraz dwa przyciski: „pokaż w Finderze" i „przenieś do kosza". To NIE jest automatyczne czyszczenie — aplikacja sama niczego nie usuwa; decydujesz o każdej pozycji z osobna. To okno jest przetłumaczone: po niemiecku nazywa się „Speicher verwalten", oba przyciski w nagłówku to „Im Finder anzeigen" i „Aktualisieren", a przyciski w wierszach to „Im Finder anzeigen" i „In den Papierkorb legen". Angielskie nazwy w poniższych pozycjach to oznaczenia z wersji angielskiej.
Gdy dysk zaczyna się zapełniać. Zwłaszcza logi się kumulują (jeden JSONL na próbę treningu, plus _qualityMetrics.json); eksporty oczywiście też (PLY to 100% surowych danych, jeden na eksport). Przydatne również po awarii, gdy w katalogu roboczym importów wciąż leżą stare kopie obrazów wejściowych.
W7Przycisk „Show in Finder"
GDZIE
Nagłówek, prawy górny róg okna przeglądarki pamięci.
TECHNICZNIE
Otwiera folder danych RadianceKit w Finderze — dokładnie ten katalog, którego zawartość wyświetla to okno. Dzięki temu widzisz strukturę folderów (Logs, Exports, Scenes, Captures, Imports) bezpośrednio i możesz przenosić lub kopiować pliki także za pomocą samego Findera. Akcja otwiera nowe okno Findera; lista w oknie się przy tym nie odświeża — do tego służy „Refresh" (W8).
W8Przycisk „Refresh"
GDZIE
Nagłówek, obok przycisku Finder.
TECHNICZNIE
Uruchamia skanowanie w tle, działające jako asynchroniczne zadanie zainicjowane przez użytkownika, dzięki czemu skanowanie dużych drzew katalogów nie blokuje interfejsu. Właściwe przechodzenie odwiedza każdy znany podfolder (Logs, Exports, Scenes, Captures, Imports) i tworzy wpis pamięci dla każdego bezpośredniego elementu potomnego. Dla każdego wpisu ustalany jest rozmiar rekurencyjny — preferowane jest rzeczywiste zużycie dysku (z uwzględnieniem współdzielenia twardych dowiązań APFS), z fallbackiem na logiczny rozmiar pliku.
W9Lista (wpisy pamięci)
GDZIE
Główna treść pod nagłówkiem.
TECHNICZNIE
Lista z takim układem w każdym wierszu: ikona SF Symbols specyficzna dla kategorii (dokument dla Logs, strzałka w górę dla Exports, sześcian dla Scenes, iPhone dla pakietów Capture, tacka dla Imports), nazwa + podtytuł (etykieta rodzaju + sformatowana data modyfikacji), licznik bajtów po prawej (wyrównany do prawej, czcionka monospaced), przycisk Reveal (ikona lupy), przycisk Trash (kosz). Sortowanie: najpierw wg rodzaju (najpierw Scenes, potem Exports, Logs, Captures, Imports, Other), a w ramach tego wg daty modyfikacji malejąco (najnowsze na górze). Jeśli skanowanie wciąż trwa, w tym miejscu wyświetlany jest postęp „Scanning…". Jeśli nic nie znaleziono, pokazywany jest stan pusty z ikoną tacki.
W10Przycisk wiersza „Reveal in Finder"
GDZIE
Przy każdym wierszu, ikona lupy po prawej.
TECHNICZNIE
Otwiera Finder i zaznacza konkretny element (plik lub folder). Różnica względem W7: W7 otwiera katalog główny; W10 zaznacza dokładnie ten jeden wpis. Praktyczny sposób pracy: znajdź duży wpis, kliknij lupę, a następnie skopiuj go np. na dysk zewnętrzny.
W11Przycisk wiersza „Move to Trash"
GDZIE
Przy każdym wierszu, ikona kosza po prawej obok lupy.
TECHNICZNIE
Uruchamia okno dialogowe potwierdzenia (W12). Dopiero po potwierdzeniu wykonywana jest standardowa operacja macOS „przenieś do kosza" (czyli odwracalna, bez bezpośredniego usunięcia). Po pomyślnym przeniesieniu do kosza wpis jest usuwany z listy, a łączny licznik bajtów aktualizowany. W razie błędów wyświetlane jest modalne okno błędu.
W12ConfirmationDialog (potwierdzenie usunięcia)
GDZIE
Wywoływane przez W11, wyświetlane jako arkusz (sheet) macOS.
TECHNICZNIE
Standardowe okno potwierdzenia z dynamicznym tytułem „Delete <name>?" oraz wierszem komunikatu, który wyraźnie informuje, że wpis trafi do kosza i można go stamtąd przywrócić (dopóki kosz nie zostanie opróżniony). Dwa przyciski: „Move to Trash" jako akcja destrukcyjna (wyświetlana na czerwono) oraz „Cancel" z automatycznym przypisaniem do klawisza Esc. Dialog jest niemodalny w tym sensie, że blokuje tylko to okno, nie całą aplikację — to standard macOS dla odwracalnych operacji usuwania.
Główne okno: przebieg straty i liczba Gaussianów (I39–I41, odwołanie krzyżowe)
Trzy ze wskaźników Inspectora w głównym oknie zasługują na osobne wyjaśnienie, ponieważ są stale widoczne podczas trwającego treningu i istnieją ważne reguły kciuka, kiedy przebieg wygląda zdrowo. Wskaźniki znajdują się w Inspectorze w sekcji Postęp, w rozwijanej grupie Przebieg straty (patrz rozdział 2 — Inspector), i pomagają interpretować postęp treningu.
Kiedy krzywa straty (loss) jest zdrowa? Zdrowa krzywa straty pokazuje trzy fazy: (1) Warmup — w pierwszych 200–500 iteracjach strata spada gwałtownie z wysokiego poziomu (typowo 0.15–0.25 dla połączenia L1+SSIM, zależnie od sceny) do mniej więcej połowy. Jeśli strata w tej fazie NIE spada, zwykle winne jest wejście (uszkodzone obrazy, złe pozycje SfM, zbyt mała liczba początkowych Gaussianów). (2) Densification — pomiędzy ~500 a densifyUntilIteration (klasycznie 15K, MCMC do 20K lub 25K) strata spada dalej, często z małymi skokami w dół, gdy operacje densyfikacji wstawiają nowe Gaussiany, a optymalizator je wykorzystuje. Liczba Gaussianów rośnie w tej fazie. (3) Refinement — potem strata wchodzi w coraz bardziej płaski ogon (tail). Typowe wartości końcowe dla orientacji: dobrze oświetlona scena obiektowa (np. Tanks-&-Temples Truck z presetem P4 Quality) osiąga L1 ≈ 0.023, rozległe sceny plenerowe jak te z Mip-NeRF 360 z natury pozostają powyżej tego (0.04–0.07).
Co oznacza plateau? Plateau (krzywa straty przebiega poziomo przez kilka tysięcy iteracji) ma dwie interpretacje: (a) model osiągnął zbieżność, dalszy trening niczego już nie daje — to dobry przypadek. (b) model utknął (lokalne minimum, słaba informacja gradientowa, ograniczenie limitem bufora) — to zły przypadek. Oba wyglądają na wykresie identycznie. Rozróżnienie: spójrz na liczbę Gaussianów. Jeśli ona też jest płaska I bliska limitowi MCMC (np. 150K ze 150K przy presecie P8 Quality (MCMC)), jesteś przy granicy — albo podnieś limit, albo zaakceptuj plateau. Jeśli liczba Gaussianów wciąż rośnie, ale strata nie spada, to jest to utknięcie.
Kiedy przerwać, a kiedy trenować dalej? Reguła kciuka: brak poprawy minimalnej straty przez 10K iteracji → przerwij, dalsze iteracje są zmarnowane. Wcześniej: przez menu Training → Continue Training → „+5,000 iterations" możesz doczepić przedłużenie, jeśli widzisz graniczną poprawę (nie ma do tego skrótu klawiszowego). Uwaga: przy MCMC plateau jest często rzeczywiste — limit to naturalna granica.
Plateau liczby Gaussianów NIE jest sygnałem „gotowe". Oznacza tylko, że MCMC osiągnął swój limit albo że Classic Densification jest wyczerpana. Na prawdziwe pytanie „czy gotowe" odpowiadają dopiero PSNR/SSIM/LPIPS na niezależnym zestawie testowym. Niezależny zestaw testowy pokazuje też, czy twój zestaw kamer pozwala na sprawiedliwy podział na widoki treningowe i testowe.
PSNR/Holdout to prawda, strata to tylko przybliżenie. Strata jest metryką względną: spada, gdy twój model dopasowuje się do widoków treningowych. Niska strata nie oznacza jednak automatycznie dobrego modelu — jeśli model nauczył się obrazów treningowych na pamięć (overfitting), strata byłaby niska, ale PSNR na niewidzianych wcześniej widokach (Holdout) byłby słaby. Dlatego: do końcowej oceny jakości zawsze patrz na metryki Holdout, nie tylko na końcową wartość straty.
Zasada praktyczna
- User Guide i Keyboard Shortcuts to statyczna pomoc — szybka przy pytaniach o konkretne hasła, ale do głębszej wiedzy służy niniejszy podręcznik. - Otwórz Manage Storage, gdy tylko wolne miejsce na dysku spadnie poniżej 10%. Logi i staging importów to zwykli winowajcy. - Plateau strat i plateau liczby gaussianów należy interpretować osobno. Limit cap nie jest sygnałem „gotowe". Prawdziwą jakość mierzy wyłącznie PSNR na zbiorze holdout. - 10 000 iteracji bez poprawy min-loss → zatrzymaj trening.