Användarguide

Kapitel 4 — Aux-Fönster

Förutom huvudfönstret (3D-viewport plus Inspector) hanterar RadianceKit tre ytterligare fönster, som alla öppnas via Hjälp-menyn. Menyn har fem poster, uppifrån och ned: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder… och Manage Storage…. De båda „Open …"-posterna öppnar inget appfönster utan Finder; därför behandlas de inte vidare här.

De tre enkla fönstren (User Guide, Keyboard Shortcuts, Manage Storage) och de två mappmenyposterna (Open Training Logs / Open Exports Folder) får en kort post per kontroll.

I slutet av kapitlet finns ett avsnitt med korsreferenser till Inspector i huvudfönstret: vad du på ett meningsfullt sätt kan avläsa i det levande förlust-diagrammet och i visningen av antalet gaussianer under en pågående träning.

Användarguide (W1–W4)

Användarguide-fönster med sidopanel till vänster och renderat Markdown-innehåll till höger
Användarguide-fönster med sidopanel till vänster och renderat Markdown-innehåll till höger

Vad det är: Ett inbyggt hjälpfönster som renderar den guide_<sprache>.md som medföljer appen. Språket härleds från inställningarna (fliken General → Language) eller, om där står „System", från macOS språkinställningar. Layouten är klassisk: till vänster en sidopanel med alla rubriker, till höger löptexten.

När du behöver en snabb påminnelse om en enskild punkt — alltså som ersättning för nyckelord. Den utförliga referensen är denna manual; det inbyggda hjälpfönstret är kortversionen för snabb uppslagning. Det uppdateras vid varje app-release, men hålls innehållsmässigt mer ytligt.

W1NavigationSplitView (sidopanel + detalj)

VAR

Help → User Guide (⌘?).

TEKNISKT

Tvåkolumns-layout med smal sidopanel (minst 180 pt bred) för innehållsträdet och ett rullbart detaljområde för själva Markdown-innehållet. Fönstret har en minimistorlek på 700 × 500 pt. Vid första öppningen laddar fönstret lämplig guide_<lang>.md från app-bundlen (fallback guide_en.md), parsar den till block-poster (rubriker H1–H4, stycken, listor, tabeller, avdelare) och extraherar separat rubrikstrukturen för sidopanelen. Inline-formatering (fetstil, kursiv, kodspann) renderas via den inbyggda Markdown-motorn. Språket läses från appens inställningar, med specialfallen kinesiska (zh-Hans) och brasiliansk portugisiska (pt-BR), som behålls som fullständiga locale-taggar eftersom dessa varianter skiljer sig från zh respektive pt.

W2List (rubrik-sidopanel)

VAR

Vänster kolumn i användarguide-fönstret.

TEKNISKT

Lista över alla H2- och H3-rubriker i det aktuella Markdown-dokumentet. H2-poster visas utan indrag med medium teckensnittsvikt, H3-poster med 16 pt indrag till vänster och nedtonad förgrundsstil. Alla andra nivåer — H1 liksom H4 och djupare — visas inte i sidopanelen, eftersom de annars skulle göra den svåröverskådlig. Anker-ID:n skapas från rubriktexten genom slugifiering (gemener + mellanslag till bindestreck + filtrering till bokstäver/siffror/bindestreck — samma algoritm som GitHub använder för sina Markdown-ankare, så att även externa URL:er till dokumentationen potentiellt skulle landa på samma ankare). Listan använder den native macOS-stilen.

W3Button (rubrik → ankare-hopp)

VAR

En knapp per sidopanelsrad.

TEKNISKT

Varje post i sidopanelen är en knapp som sätter det aktuella ankaret, men som visuellt ser ut som en listpost. En observatörsvariabel utlöser sedan scroll-hoppet till motsvarande ankare med en mjuk animation över 0,3 s. Efter hoppet återställs ankarvärdet, så att nästa klick på samma ankare utlöser hoppet igen (annars skulle observatören inte utlösas på nytt, eftersom värdet inte har ändrats).

W4ScrollView (detaljinnehåll)

VAR

Höger kolumn.

TEKNISKT

Rullbart, vertikalt staplande innehållsområde med lat rendering (lazy rendering), eftersom längre guider lätt kan ha över 200 Markdown-block — en icke-lat variant skulle instansiera alla samtidigt. Varje block får ett eget ID, antingen rubrikankaret (det får varje rubrik, oavsett nivå) eller en indexplatshållare. Maxbredden är 720 pt, padding 32 horisontellt / 24 vertikalt, så att långa rader behåller en lättläst layout. Tabeller renderas cellvis med horisontella staplar och avdelare; inline-kod via den inbyggda Markdown-motorn. Riktiga kodblock behandlas för närvarande som stycken — en känd begränsning i hjälpfönstret.

Tangentbordsgenvägar (W5–W6)

Keyboard Shortcuts Fenster — fünf Gruppen Navigation/Views/Capture/Editor/Training mit Hotkey-Spalte links och Beschreibung rechts
Fönstret Keyboard Shortcuts — fem grupper Navigation/Views/Capture/Editor/Training med kolumn för snabbtangenter till vänster och beskrivning till höger

Statisk referenslista i fem sektioner. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (Fly-Through-rörelse), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (FoV-justering). Views: R (Reset Camera), T (Auto-Rotation), P (Camera Playback), B (Background-Cycle), 0–9 (Hoppa till Training-Cam 1=10%/5=50%/0=last), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (Turntable-Video), C (Copy Camera Info). Editor: Tab (Edit-läge), Click/Drag (Paint-Select), Option+Click (Deselect), X / Delete (radera markering), Cmd-Z (ångra senaste raderingen), [ / ] (mindre/större penselstorlek), Esc (avmarkera). Training: Option+Space (pausa/återuppta träning), Cmd+E (exportera scen). Mer finns inte här — Start, Cancel och förlängningarna når du via Training-menyn (kapitel 1).

Vad det är: En enkel statisk översikt över alla tangentbordsgenvägar — Navigation, Views, Capture, Editor, Training. Innehållet är fast inbyggt och laddas inte från en fil.

När du letar efter det snabbaste sättet att göra något i Viewport. WASD-Fly-Through, R för Camera-Reset, B för Background-Cycling — alla finns här.

W5ScrollView (innehållsområde)

VAR

Help → Keyboard Shortcuts (⌘/).

TEKNISKT

Ett enkelt scrollområde med en vertikal lista inuti. Padding 20 runt om, ingen Sidebar-navigationsträd (listan är kort nog). Innehållet är grupperat i fem sektioner (Navigation, Views, Capture, Editor, Training). Per tangentkombination en rad med översättningsbar text i båda kolumnerna. Vänsterkolumnen (tangentkod) är fixerad till 180 pt bredd, så att beskrivningarna till höger förblir vertikalt inriktade. Ingen interaktion förutom scrollning — att klicka på en rad utlöser inget, tangentbordsgenvägarna är riktiga tangentbordsmodifierare i menyn och i Viewport.

W6VStack (genvägssektioner)

VAR

Inuti ScrollView.

TEKNISKT

Vänsterjusterade staplade sektioner med 16 pt mellanrum. Inom de fem sektionerna finns respektive Heading + radföljd. Headings använder en sekundär subheadline-stil — medvetet inget Title-format, eftersom sektionerna inte behöver vara navigerbara. Innehållet är medvetet platt (ingen Disclosure, ingen Search, inget Filter), så att komponenten fungerar oförändrad på varje macOS-version och filen förblir läsbar.

Hantera lagring (W7–W12)

Manage Storage Fenster — Header zeigt „1,356 items · 55.1 GB total”, Tabelle mit Export-PLY-Dateien sortiert nach Datum, jeweils Icon + Dateiname + Größe + Datum
Fönstret Manage Storage — Rubriken visar „1,356 items · 55.1 GB total", tabell med PLY-exportfiler sorterade efter datum, med ikon + filnamn + storlek + datum för varje rad

Tabellvy över alla filer som RadianceKit hanterar. Rubriken räknar 1 356 objekt, 55,1 GB totalstorlek. Verktygsrad högst upp: „Show in Finder" + „Refresh". Varje rad: export-ikon, filnamn (t.ex. training_20260718T194416Z.ply), exportdatum, storlek (varierar här från 7,8 MB till 2,24 GB), lupp-ikon (Reveal) och papperskorgs-ikon (Move to Trash). Sorteringen sker först efter kategori och inom en kategori efter datum, nyaste överst. I den här skärmdumpen dominerar PLY-exporter, eftersom det framför allt är träningsresultat som har sparats i den här mappen.

Vad det är: En översikt över diskanvändning för allt som RadianceKit sparar under ~/Documents/RadianceKit/ — loggar, exporter, scener, capture-paket (från iOS-följeslagaren), imports (staging-kopior av indatabilderna). Per post visas en storlek i byte och två knappar: „visa i Finder" och „flytta till papperskorgen". Detta är INTE automatisk städning — appen tar inte bort något själv; du bestämmer för varje post. Det här fönstret är översatt: på svenska heter det „Hantera lagring", de två rubrikknapparna heter „Visa i Finder" och „Uppdatera", radknapparna heter „Visa i Finder" och „Lägg i papperskorgen". De engelska namnen i posterna nedan är beteckningarna från den engelska versionen.

När hårddisken börjar bli full. Framför allt loggarna samlas på hög (en JSONL per träningsförsök, plus _qualityMetrics.json); exporterna förstås också (PLY är 100 % rådata, en per export). Även användbart efter en krasch, när imports-staging-katalogen fortfarande har gamla kopior av indatabilderna liggandes.

W7Knappen „Show in Finder"

VAR

Rubriken uppe till höger i storage-webbläsarfönstret.

TEKNISKT

Öppnar RadianceKits datamapp i Finder — just den katalog vars innehåll det här fönstret listar. Så ser du mappstrukturen (Logs, Exports, Scenes, Captures, Imports) direkt och kan även flytta eller kopiera filerna själv med Finder. Åtgärden öppnar ett nytt Finder-fönster; listan i fönstret ändras inte av detta — det är „Refresh" (W8) till för.

W8Knappen „Refresh"

VAR

Rubriken, bredvid Finder-knappen.

TEKNISKT

Utlöser en bakgrundsskanning som körs på en användarinitierad asynkron uppgift, så att skanningen av stora katalogträd inte blockerar gränssnittet. Själva genomgången går igenom varje känd undermapp (Logs, Exports, Scenes, Captures, Imports) och skapar en lagringspost för varje direkt barn. För varje post beräknas den rekursiva storleken — helst den faktiska diskanvändningen (inklusive delning av APFS-hårda länkar) med reservlösning till den logiska filstorleken.

W9Listan (lagringsposter)

VAR

Huvudinnehåll under rubriken.

TEKNISKT

Lista där varje rad har följande layout: kategori- specifik SF Symbol-ikon (dokument för loggar, uppåtpil för exporter, tärning för scener, iPhone för capture-paket, bricka för imports), namn + undertext (typ-etikett + formaterat ändringsdatum), byte-räknare till höger (högerjusterad, monospace), Reveal-knapp (luppsymbol), papperskorgs-knapp (soptunna). Sortering: primärt efter typ (scener först, sedan exporter, loggar, captures, imports, övrigt), sekundärt efter ändringsdatum fallande (nyaste överst). Om skanningen fortfarande pågår visas i stället ett „Scanning…"-förloppsindikator. Om inget hittades, visas ett tomt tillstånd med bricksymbol.

W10Radknappen „Reveal in Finder"

VAR

Per rad, luppsymbol till höger.

TEKNISKT

Öppnar Finder och markerar det specifika objektet (fil eller mapp). Skillnad mot W7: W7 öppnar rotkatalogen; W10 markerar exakt den här enskilda posten. Praktiskt arbetsflöde: identifiera en stor post, klicka på luppen, kopiera den sedan till exempelvis en extern volym.

W11Radknappen „Move to Trash"

VAR

Per rad, papperskorgssymbol till höger om luppen.

TEKNISKT

Utlöser bekräftelsedialogrutan (W12). Först efter bekräftelse körs macOS standardåtgärden „flytta till papperskorgen" (alltså reversibelt, ingen direkt radering). Efter lyckad flytt till papperskorgen tas posten bort från listan och den totala byte-räknaren uppdateras. Vid fel visas en modal felmeddelanderuta.

W12ConfirmationDialog (bekräftelse av radering)

VAR

Utlöses av W11, visas som ett macOS-blad (sheet).

TEKNISKT

Standardbekräftelsedialog med dynamisk titel „Delete <name>?" och en meddelanderad som uttryckligen påpekar att posten hamnar i papperskorgen och kan återställas därifrån (tills papperskorgen töms). Två knappar: „Move to Trash" som en destruktiv åtgärd (visas i rött) och „Cancel" med automatisk Esc-bindning. Dialogrutan är icke-modal i den bemärkelsen att den bara blockerar det här fönstret, inte hela appen — det är macOS-standard för reversibla raderingar.

Huvudfönster: Förlustkurva och Gaussian-antal (I39–I41, korsreferens)

Tre av inspector-vyerna i huvudfönstret förtjänar en egen förklaring, eftersom de syns hela tiden under en pågående träning och det finns viktiga tumregler för när kurvan ser hälsosam ut. Vyerna sitter i Inspector under avsnittet Fortskridande, i den utfällbara gruppen Förlustkurva (se kapitel 2 — Inspector), och hjälper dig att tolka träningens förlopp.

När är loss-kurvan hälsosam? En hälsosam loss-kurva visar tre faser: (1) Uppvärmning — under de första 200–500 iterationerna faller losset brant från högt (typiskt 0.15–0.25 för kombinerat L1+SSIM beroende på scen) till ungefär hälften. Om losset INTE faller i denna fas är det oftast fel på indata (trasiga bilder, dåliga SfM-poser, för få initiala Gaussians). (2) Densification — mellan ~500 och densifyUntilIteration (klassiskt 15K, MCMC upp till 20K eller 25K) fortsätter losset att falla, ofta med små hopp nedåt när densify-operationer lägger till nya Gaussians och optimeraren utnyttjar dem. Gaussian-antalet ökar under denna fas. (3) Förfining — därefter övergår losset i en allt plattare svans. Typiska slutvärden som riktmärke: en välbelyst objektscen (till exempel Tanks-&-Temples Truck med P4 Quality) hamnar kring L1 ≈ 0.023, medan vidsträckta utomhusscener som de från Mip-NeRF 360 av naturliga skäl ligger högre (0.04–0.07).

Vad betyder en platå? En platå (loss-kurvan går horisontellt över flera tusen iterationer) har två tolkningar: (a) modellen har konvergerat, ytterligare träning ger inget mer — det är det goda fallet. (b) modellen sitter fast (lokalt minimum, dålig gradient-information, ett tak vid buffertgränsen) — det dåliga fallet. Båda ser identiska ut i diagrammet. Så skiljer du dem åt: titta på Gaussian-antalet. Om det också är platt OCH nära MCMC-taket (t.ex. 150K av 150K vid presetet P8 Quality (MCMC)), är du vid gränsen — antingen höj taket eller acceptera platån. Om Gaussian-antalet fortfarande växer men losset inte faller, är det fastkörning.

När ska du avbryta kontra fortsätta träna? Tumregel: 10K iterationer utan förbättring av min-losset → avbryt, ytterligare iterationer är bortkastade. Innan dess: via Training-menyn → Continue Training → "+5,000 iterations" kan du lägga till en förlängning om du ser gränsfallsförbättring (det finns inget tangentbordskommando för detta). Observera: vid MCMC är platån ofta verklig — taket är den naturliga gränsen.

Platå i Gaussian-antalet är INTE en "klar"-signal. Det betyder bara att MCMC har nått sitt tak eller att Classic Densification är uttömd. Den verkliga "klar"-frågan besvaras först av PSNR/SSIM/LPIPS på en oberoende testuppsättning. Den oberoende testuppsättningen visar också om din kameraserie tillåter en rättvis uppdelning i tränings- och testvinklar.

PSNR/Holdout är sanningen, loss är bara en proxy. Losset är ett relativt mått: det sjunker medan din modell anpassar sig till träningsvyerna. Ett lågt loss betyder dock inte automatiskt en bra modell — om modellen har lärt sig träningsbilderna utantill (overfitting) skulle losset vara litet, men PSNR på osedda vyer (holdout) skulle vara dåligt. Därför: titta alltid på holdout-mätvärdena för den slutliga kvalitetsbedömningen, inte enbart på slut-losset.

Tumregel-lådan

- User Guide och Keyboard Shortcuts är statisk hjälp — snabbt för nyckelordsfrågor, men använd den föreliggande manualen för djupare kunskap. - Öppna Manage Storage så snart hårddisken har mindre än 10% ledigt utrymme kvar. Loggar och Imports-staging är de vanliga bovarna. - Loss-platå och Gaussian-count-platå ska tolkas separat. Cap-gränsen är inte en signal om att man är „klar". Endast holdout-PSNR mäter den verkliga kvaliteten. - 10K iterationer utan förbättring av min-loss → stoppa träningen.