Capitolo 4 — Finestre ausiliarie

Oltre alla finestra principale (viewport 3D più Inspector), RadianceKit gestisce altre sette finestre, tutte aperte tramite il menu Help. La lista da cima a fondo: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (non apre una finestra dell'app ma il Finder; quindi qui non trattata oltre), Manage Storage…, Pareto Dashboard… (⇧⌘D), Holdout Analysis… (⇧⌘H), BayesOpt Console… (⇧⌘B). Tre di esse — Dashboard, Holdout, BayesOpt — sono strumenti di analisi autonomi. Hanno ciascuno un proprio stack di view model, leggono o scrivono file JSON su disco e per ognuna c'è un argomento CLI con cui far puntare la finestra direttamente a un determinato file all'avvio dell'app (–dashboard-dir, –holdout-file, –bayesopt-autorun).

Le quattro finestre semplici (User Guide, Keyboard Shortcuts, Manage Storage, più le voci di sottomenu Open Training Logs / Open Exports Folder) ricevono una breve voce per controllo. Le tre finestre di analisi sono documentate in modo più approfondito — ciascuna con un'introduzione che spiega cosa vedi nella finestra, quando dovresti aprirla e come interpretare l'immagine visualizzata.

Alla fine del capitolo c'è una sezione di rimandi all'Inspector della finestra principale: cosa puoi leggere in modo sensato dal grafico Loss live e dal display Gaussian Count durante un training in corso.

User Guide (W1–W4)

Cos'è: Una finestra di aiuto integrata che renderizza la guide_<lingua>.md fornita con l'app. La lingua viene derivata dalle Impostazioni (tab General → Language) o, se lì c'è "System", dalle preferenze di lingua di macOS. Il layout è classico: a sinistra la sidebar con tutte le intestazioni, a destra il testo corrente.

Quando hai bisogno di un rapido promemoria su un singolo punto — come sostituto di una parola chiave. Il riferimento esaustivo è questo manuale; la finestra di aiuto integrata è piuttosto ciò che sarebbe un –help sulla riga di comando. Viene aggiornata ad ogni release dell'app, ma mantenuta contenutisticamente più superficiale.

W1NavigationSplitView (Sidebar + Detail)

DOVE

Help → User Guide (⌘?)..

TECNICO

Layout a due colonne con sidebar stretta (almeno 180 pt di larghezza) per l'albero dei contenuti e un'area di dettaglio scrollabile per il contenuto Markdown vero e proprio. La finestra ha una dimensione minima di 700 × 500 pt. Alla prima apertura la finestra carica la guide_<lang>.md corrispondente dal bundle dell'app (fallback guide_en.md), la parsifica in blocchi (intestazioni H1–H4, paragrafi, liste, tabelle, divisori) ed estrae separatamente la struttura delle intestazioni per la sidebar. La formattazione inline (bold, italic, code-span) viene renderizzata tramite il motore Markdown integrato. La lingua viene letta dalle impostazioni dell'app, con il caso speciale del cinese (zh-Hans) e del portoghese brasiliano (pt-BR), che vengono mantenuti come tag locale completi perché queste varianti si distinguono da zh risp. pt.

W2List (sidebar delle intestazioni)

DOVE

Colonna sinistra nella finestra User Guide..

TECNICO

Lista su tutte le intestazioni H2 e H3 del documento Markdown attuale. Le voci H2 appaiono senza rientro con peso font medium, le voci H3 con rientro a sinistra di 16 pt e stile foreground ridotto. H4 e profondità superiori vengono ignorate, perché la profondità altrimenti rende la sidebar disordinata. Gli ID di ancoraggio vengono generati dal testo dell'intestazione tramite slugificazione (lowercase + spazi a dash + filtraggio su lettere/numeri/dash — stesso algoritmo che GitHub usa per i suoi ancoraggi Markdown, in modo che anche URL esterni alla documentazione potenzialmente finirebbero sullo stesso ancoraggio). La lista utilizza lo stile macOS nativo.

W3Button (intestazione → salto all'ancoraggio)

DOVE

Un pulsante per riga della sidebar..

TECNICO

Ogni voce della sidebar è un pulsante che imposta l'ancoraggio attuale, otticamente però appare come voce di lista. Una variabile osservatore attiva poi il salto di scroll all'ancoraggio corrispondente con un'animazione morbida di 0,3 s. Dopo il salto il valore dell'ancoraggio viene resettato, in modo che il prossimo clic sullo stesso ancoraggio si attivi di nuovo (altrimenti l'osservatore non scatterebbe di nuovo, perché il valore non è cambiato).

W4ScrollView (contenuto di dettaglio)

DOVE

Colonna destra..

TECNICO

Area di contenuto scrollabile e impilata verticalmente con lazy rendering, perché guide più lunghe possono facilmente avere oltre 200 blocchi Markdown — una variante non lazy le istanzierebbe tutte contemporaneamente. Ogni blocco riceve un proprio ID, o l'ancoraggio dell'intestazione (per H1–H3 saltabili) o un placeholder di indice. La larghezza massima è 720 pt, padding 32 orizzontale / 24 verticale, in modo che le righe lunghe mantengano un layout ben leggibile. Le tabelle vengono renderizzate cella per cella con stack orizzontali e divisori; il codice inline tramite il motore Markdown integrato. I veri blocchi di codice vengono attualmente trattati come paragrafo — una limitazione nota della finestra di aiuto.

Keyboard Shortcuts (W5–W6)

Lista di riferimento statica in cinque sezioni. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (movimento fly-through), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (regolazione FoV). Views: R (Reset Camera), T (Auto-Rotation), P (Camera Playback), B (ciclo sfondo), 0–9 (salta a training cam 1=10%/5=50%/0=ultima), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (Turntable Video), C (Copy Camera Info). Editor: Tab (modalità modifica), Click/Drag (paint-select), Option+Click (deselect), X / Delete (elimina selezione), Cmd-Z (annulla ultima eliminazione), [ / ] (dimensione pennello più piccola/più grande), Esc (deseleziona). Training: Start, Pause/Resume, Cancel, Continue +5K/+10K/+20K tramite scorciatoie di menu in M9–M14.

Cos'è: Una semplice panoramica statica di tutte le scorciatoie da tastiera — Navigation, Views, Capture, Editor, Training. Il contenuto è hard-coded, nessun caricamento Markdown.

Quando cerchi il modo più rapido per fare qualcosa nel viewport. WASD fly-through, R per reset fotocamera, B per il ciclo dello sfondo — tutti sono qui.

W5ScrollView (area di contenuto)

DOVE

Help → Keyboard Shortcuts (⌘/)..

TECNICO

Una semplice area di scorrimento con una lista verticale all'interno. Padding 20 tutt'intorno, nessuna sidebar di navigazione (la lista è abbastanza corta). I contenuti sono raggruppati in cinque sezioni (Navigation, Views, Capture, Editor, Training). Per combinazione di tasti una riga con testo traducibile in entrambe le colonne. Colonna sinistra (codice tasto) fissata a 180 pt di larghezza, in modo che le descrizioni a destra rimangano allineate verticalmente. Nessuna interazione oltre allo scorrimento — cliccare su una riga non attiva nulla, le scorciatoie sono veri modificatori di tastiera nel menu e nel viewport.

W6VStack (sezioni delle scorciatoie)

DOVE

All'interno dello ScrollView..

TECNICO

Sezioni impilate allineate a sinistra con distanza di 16 pt. All'interno delle cinque sezioni rispettivamente intestazione + sequenza di righe. Le intestazioni usano uno stile subheadline secondario — deliberatamente nessun formato title, perché le sezioni non devono essere navigabili. Il contenuto è deliberatamente piatto (nessuna disclosure, nessuna ricerca, nessun filtro), affinché il componente funzioni invariato su ogni versione macOS e il file rimanga leggibile.

Manage Storage (W7–W12)

Vista a tabella di tutti i file gestiti da RadianceKit. L'header conta 693 voci, dimensione totale 16.74 GB. Toolbar in alto: "Show in Finder" + "Refresh". Ogni riga: icona PLY, nome file (ad es. training_20260527T211321Z.ply), data esportazione, dimensione (varia da 7 KB a 218 MB), icona lente (Reveal) e icona cestino (Move to Trash). I file sono ordinati per data, più recenti in alto. In questa registrazione demo dominano le esportazioni PLY, perché si è lavorato molto con –benchmark.

Cos'è: Una panoramica dell'uso del disco per tutto ciò che RadianceKit deposita sotto ~/Documents/RadianceKit/ — log, esportazioni, scene, bundle di capture (dal companion iOS), importazioni (copie di staging delle immagini di input). Per voce una dimensione in byte e due pulsanti: "Mostra nel Finder" e "Sposta nel Cestino". NON è una pulizia automatica — l'app non elimina nulla da sola; decidi tu per voce.

Quando il disco si riempie. Soprattutto i log si accumulano (un JSONL per tentativo di training, più il _qualityMetrics.json); le esportazioni naturalmente anche (PLY 100% dati grezzi, una per esportazione). Utile anche dopo un crash, quando la directory di staging Imports ha ancora vecchie copie delle immagini di input (vedi "Disk-pressure incident" in dev_v549f-needle-reduction.md).

W7Pulsante "Show in Finder"

DOVE

Header in alto a destra nella finestra Storage Browser..

TECNICO

Apre l'intera directory RadianceKit (~/Documents/RadianceKit/) nel Finder, in modo che tu possa vedere direttamente la struttura delle cartelle e manipolarla anche con il Finder stesso. L'azione apre una nuova finestra del Finder e non passa al container sandbox dell'app — ~/Documents/RadianceKit/ è il dominio Documents regolarmente accessibile alle app, non un percorso di container sandboxed.

W8Pulsante "Refresh"

DOVE

Header, accanto al pulsante Finder..

TECNICO

Attiva una scansione in background, che gira su un task asincrono iniziato dall'utente, in modo che la scansione di grandi alberi di directory non blocchi l'UI. Il walk vero e proprio attraversa ogni sottocartella nota (Logs, Exports, Scenes, Captures, Imports) e crea una voce di archiviazione per ogni figlio diretto. Per voce viene determinata la dimensione ricorsiva — preferibilmente il consumo reale del disco (incluso APFS hardlinks sharing) con fallback sulla dimensione logica del file.

W9List (voci di archiviazione)

DOVE

Contenuto principale sotto l'header..

TECNICO

Lista con per riga questo layout: icona SF Symbol specifica per categoria (documento per Logs, freccia upload per Exports, cubo per Scenes, vassoio per Imports), nome + sottotitolo (etichetta tipo + data di modifica formattata), contatore byte a destra (allineato a destra, monospaziato), pulsante Reveal (simbolo lente), pulsante Trash (cestino). Ordinamento: primario per tipo (Scenes prima, poi Exports, Logs, Captures, Imports, Other), secondario per data di modifica decrescente (più recenti in alto). Se la scansione è ancora in corso, in quella posizione viene mostrato invece un progresso "Scanning…". Se non è stato trovato nulla, una visualizzazione empty state con icona vassoio.

W10Pulsante riga "Reveal in Finder"

DOVE

Per riga, simbolo lente a destra..

TECNICO

Apre il Finder e seleziona la voce specifica (file o cartella). Differenza rispetto a W7: W7 apre la directory root; W10 contrassegna esattamente questa singola voce. Flusso di lavoro pratico: identifica una voce grande, clicca sulla lente, poi copiala ad esempio su un volume esterno.

W11Pulsante riga "Move to Trash"

DOVE

Per riga, simbolo cestino a destra accanto alla lente..

TECNICO

Attiva la finestra di conferma (W12). Solo dopo conferma viene eseguita l'operazione standard di macOS "sposta nel cestino" (quindi reversibile, nessuna eliminazione diretta). Dopo il successo del trash la voce viene rimossa dalla lista e il contatore byte totale aggiornato. In caso di errori viene visualizzata una finestra di errore modale.

W12ConfirmationDialog (conferma di eliminazione)

DOVE

Viene attivata da W11, visualizzata come sheet macOS..

TECNICO

Finestra di conferma standard con titolo dinamico "Delete <name>?" e una riga di messaggio che indica esplicitamente che la voce finisce nel cestino ed è da lì ripristinabile (finché il cestino non viene svuotato). Due pulsanti: "Move to Trash" come azione distruttiva (rappresentata in rosso) e "Cancel" con binding automatico di Esc. La finestra è non modale nel senso che blocca solo questa finestra, non l'intera app — è standard macOS per eliminazioni reversibili.

Pareto Dashboard (W13–W22)

Stato vuoto (dopo la prima apertura) — empty state con call-to-action "Open Reports Folder…". I punti dati appaiono non appena i report di training sono caricati, vedi il prossimo scatto.

La toolbar dell'header mostra "129 reports of 129" (tutti i report nella cartella scelta sono stati parsati con successo — 21 file aggiuntivi non sono stati parsati per formato più vecchio, vedi lista di note a destra). Assi: picker X su Gaussians, picker Y su PSNR (dB). Scatter plot: punti verdi = strategia Classic, punti blu = MCMC. La linea tratteggiata della frontiera di Pareto corre lungo i valori PSNR migliori raggiunti e si appiattisce attorno a PSNR≈30 dB da circa 500K gaussiane. Chip filtro a destra: 7 scene (bicycle, bonsai, family, flowers, kitchen, stump, truck), 2 strategie (classic, mcmc), 3 opzioni Mip-Splatting (All, On, Off). Attualmente tutti i filtri sono aperti, da qui il denso cluster di punti.

Cos'è: Uno strumento di confronto multi-run. Hai addestrato in passato più scene o la stessa scena con preset diversi — ognuna di queste esecuzioni di training produce (se hai passato –benchmark o chiamato tramite la funzione benchmark) un file di report JSON che contiene tra l'altro PSNR, SSIM, LPIPS, gaussian count e tempo wallclock finali. Il dashboard legge un'intera cartella di tali report contemporaneamente e li traccia come scatter 2D con assi selezionabili. Inoltre la frontiera di Pareto (l'insieme dei punti non dominati) viene tracciata come linea tratteggiata.

Dopo aver creato almeno tre o quattro report di training. Con meno punti la linea della frontiera non è significativa. Caso d'uso tipico: hai provato a ricostruire una scena outdoor e hai eseguito in sequenza P3 Balanced (Classic), P4 Quality (Classic), P7 MCMC Quality e P9 Outdoor (tuned) — ora vuoi sapere quale configurazione fornisce il miglior PSNR per secondo di tempo di training o quale ha bisogno di meno gaussiane per un dato PSNR.

Entrambi gli assi sono liberamente selezionabili (asse X:,, psnr, ssim, lpips, …; asse Y allo stesso modo). La logica della frontiera di Pareto in ParetoFront2D.indices sa per ogni metrica se "più piccolo = meglio" (ad es. LPIPS, Loss, Time) o "più grande = meglio" (PSNR, SSIM) — la linea corre quindi a seconda della scelta degli assi da basso sinistra ad alto destra o da alto sinistra a basso destra, sempre lungo la migliore combinazione raggiunta. Un punto è ottimale di Pareto se NESSUN altro punto è almeno altrettanto buono in ENTRAMBE le dimensioni (cioè nessun altro lo domina). I punti ottimali di Pareto si trovano sulla linea, gli altri punti a destra/sopra (a seconda dell'orientamento degli assi). I punti SULLA linea sono i veri candidati per "miglior preset"; i punti LONTANI dalla linea sono tempo di training sprecato.

Puoi restringere la selezione a una scena specifica (se vuoi confrontare ad es. solo le esecuzioni outdoor), a una strategia specifica (Classic o MCMC) o a Mip-Splatting on/off (rilevante dopo la Fase Q1.5, dove Mip rimane come opt-in advanced flag).

Hai tre report per la scena "truck" sotto ~/Documents/RadianceKit/Reports/: Run A (P4 Quality, 40K iter, 524K Gs, 105 s, PSNR 23.4), Run B (P7 MCMC, 200K iter, 150K Gs, 693 s, PSNR 24.6), Run C (P9 Outdoor, 100K iter, 1.25M Gs, 312 s, PSNR 25.8). Imposta asse X su trainingTime, asse Y su PSNR. Run B sta in alto a destra, Run C ancora più in alto a destra, Run A in basso a sinistra. La frontiera di Pareto collega A e C — entrambi non dominati. Run B è "perso" (C è migliore in Time E PSNR). Conclusione: per "truck" non vale la pena il default MCMC; o veloce+ok (A) o lungo+molto buono (C). Salva la configurazione di C come preset proprio (Inspector → I1 Save Preset).

Prossima azione: Salvare la migliore configurazione come preset. In concreto: guarda i punti di Pareto (l'hover mostra PSNR/SSIM/LPIPS/Gs/Time nel tooltip), decidi quale si adatta meglio al trade-off tempo-vs-qualità, apri il report corrispondente (il nome file contiene il timestamp del run), copia la sua configurazione di training in un nuovo run o salvala come preset dopo la prossima sessione di training tramite l'Inspector.

W13Pulsante "Open Reports Folder…"

DOVE

Toolbar in alto a sinistra..

TECNICO

Apre una finestra di selezione cartella con la richiesta "Select a folder containing benchmark .json reports". Dopo la conferma viene eseguito un task in background che parsifica sequenzialmente tutti i file .json nella cartella. I report errati (JSON danneggiato, schema sbagliato) vengono raccolti e visualizzati in fondo alla sidebar come "N file failed to parse" — nessun crash. Se avviene un secondo clic mentre un primo load è ancora in corso, il task precedente viene interrotto, in modo che due risultati non scrivano contemporaneamente nello stato.

Anche via CLI: –dashboard-dir /path/to/reports carica la cartella direttamente all'avvio dell'app.

W14Picker "X-Axis"

DOVE

Sopra il grafico, a sinistra..

TECNICO

Picker di menu con tutti gli assi metrici disponibili del modulo dashboard (PSNR, SSIM, LPIPS, gaussian count, tempo di training e così via). Il default è gaussian count. Al cambio il punto in hover viene resettato, perché una posizione finora evidenziata nel vecchio sistema di coordinate degli assi non ha più senso dopo il cambio di asse. Il picker è limitato alla larghezza del contenuto, in modo che non si estenda su tutta la larghezza.

W15Picker "Y-Axis"

DOVE

Sopra il grafico, accanto a X-Axis..

TECNICO

Identico a W14, solo che il default è PSNR. La scelta dell'asse viene salvata in modo indipendente, quindi l'utente può anche scegliere combinazioni senza senso (X=PSNR, Y=PSNR — porterebbe tutti i punti su una diagonale). Tali combinazioni non vengono però intercettate; decisione consapevole, perché un confronto "SSIM vs PSNR" è ben interessante per vedere quanto coerentemente si comportano le metriche.

W16Toggle "Show Pareto Front"

DOVE

A destra accanto ai picker degli assi..

TECNICO

Toggle macOS standard. Se attivo, nel grafico Pareto viene tracciata, oltre alla nuvola di punti, una linea con la frontiera di Pareto 2D calcolata. Stile: tratteggiata (pattern tratti 4–4), grigia semitrasparente, spessore linea 1,5 pt. Il calcolo Pareto avviene nel main thread — con il numero tipico di report (≤ ~50) è senza problemi veloce. Se il toggle è spento, la linea viene omessa, in modo che ci siano solo i punti nudi.

W17Chip filtro "Scene"

DOVE

Sidebar destra nella finestra del dashboard..

TECNICO

Chip filtro per ogni scena presente nei report caricati. Layout flow proprio che riimpacchetta automaticamente i chip su più righe non appena la larghezza è esaurita. I chip attivi ricevono lo sfondo di accento, quelli inattivi uno sfondo materiale standard neutro. La selezione multipla è possibile (semantica di set); se nessun chip è selezionato, valgono tutte le scene come "fatte passare" — ovvero la logica di set è "selezione vuota = tutto", non "selezione vuota = nulla".

W18Chip filtro "Strategy"

DOVE

Sotto il filtro Scene nella sidebar..

TECNICO

Esattamente come W17, ma per le strategie di training — tipicamente i due valori "classic" e "mcmc", derivati dal campo strategy dei JSON dei report di benchmark. Utile se hai mescolato report di entrambe le strategie e vuoi vedere solo una sorta (ad es. "mostra solo run MCMC, perché Classic l'ho già escluso").

W19Chip filtro "Mip-Splatting"

DOVE

Sotto il filtro Strategy nella sidebar..

TECNICO

Filtro a tre valori (invece di set come W17/W18): "All" / "On" / "Off". Sfondo: Mip-Splatting è stato valutato nella Fase Q1.5 come miglioramento multi-scala sperimentale e il verdetto finale è stato "nessun vantaggio piacevole in modo continuativo; mantenuto come opt-in flag". Quando fai confronti Mip on/off, spesso vuoi poter separare nettamente. Da qui il filtro ternario dedicato con gli stati "lascia passare tutto", "solo Mip on", "solo Mip off". La sezione della sidebar viene mostrata solo se ci sono almeno un report Mip E almeno un report non Mip nel set di dati (altrimenti il filtraggio non ha senso).

W20ChipButton (toggle filtro, all/on/off)

DOVE

Componente helper, viene usato in W17/W18/W19..

TECNICO

Wrapper minimalista per pulsante. Contenuto: testo etichetta con grado font caption e padding 10 orizzontale / 5 verticale. Sfondo condizionale: se attivo → colore di accento dell'app con testo bianco; altrimenti sfondo materiale standard neutro con testo nero. La forma è una capsule (a forma di pillola). Stile pulsante plain, in modo che il materiale capsule non sia sovrapposto a un bordo di sistema.

W21Chart (scatter Pareto)

DOVE

Area centrale del dashboard..

TECNICO

Grafico Swift Charts con due layer: 1. un punto per report — posizione dalle metriche X e Y scelte, colore per strategia, simbolo per stato Mip. Dimensione simbolo normale 80, evidenziato 200 (se l'ID corrisponde al report attualmente in hover). 2. una linea per la frontiera di Pareto, solo se il toggle è attivo.

Overlay del grafico: un rettangolo trasparente registra il movimento del mouse; per frame viene determinata la posizione del punto più vicina euclideamente nel frame del grafico e il report in hover aggiornato, se la distanza è sotto 24 px (altrimenti resettato). Così ottieni il tooltip senza cliccare — basta l'hover.

W22Tooltip (dettaglio hover)

DOVE

Sotto il grafico, mostrato in hover..

TECNICO

Stack orizzontale: nome scena (headline), tag strategia (caption), divisore, poi metriche PSNR/SSIM/LPIPS/Gs/Time ciascuna in un piccolo gruppo verticale (etichetta + valore monospaziato). Se Mip era attivato, in più un tag capsule "Mip" in colore di accento. Sfondo blur semitrasparente, rettangolo arrotondato con raggio 8 pt. Viene mostrato solo se il mouse è effettivamente su un punto. Scompare automaticamente all'uscita.

Holdout Analysis (W23–W29)

Stato vuoto con empty state e call-to-action "Open transforms.json…". Accetta i formati NeRF Studio e Instant NGP.

Stato vuoto (dopo la prima apertura) — i marker delle fotocamere appaiono non appena un transforms.json è caricato, vedi il prossimo scatto.

L'header mostra il file caricato (transforms_train.json) e il conteggio cam ("100 cameras"). Sidebar sinistra: picker della strategia con due opzioni — Angular (longitudinal) attivo (allinea i fold per settori di longitudine/latitudine sulla sfera, in modo che ogni test fold sia geometricamente denso) vs Linear (round-robin) (basato sull'ordine, ogni k-esimo frame come test set). Lo slider k-Folds è su 5, il picker Test Fold su Fold 1. Il pulsante Export genera un fold-assignment.json per Nerfstudio/Instant-NGP. Pannello centrale: proiezione su globo 3D di tutte le 100 fotocamere — punti verdi = Train, punti rossi = test fold attuale (Fold 1 con 20 fotocamere). Sidebar destra (Angular Correlation): per fold 20 cam + Mean Nearest Angle (Fold 1: 7.9°, Fold 2: 7.8°, Fold 3: 7.7°, Fold 4: 7.0°, Fold 5: 6.3°) — un valore più piccolo significa che le fotocamere all'interno di questo fold sono strettamente vicine, quindi lo split holdout è spazialmente coerente.

Cos'è: Un visualizzatore 3D per la disposizione delle tue fotocamere con logica di cross-validation. Carichi un transforms.json (il formato standard di Nerfstudio / Instant-NGP per le pose delle fotocamere), l'app legge tutte le fotocamere, proietta le loro direzioni di vista su una sfera unitaria e le mostra come piccoli marker sferici su un globo virtuale. Poi divide le fotocamere in k fold (secondo la strategia scelta: angolare o lineare), contrassegna in verde la quota di training e in rosso la quota di test (holdout), e calcola per fold un punteggio Angular Correlation, che ti dice quanto lontano il test fold è dal training fold nello spazio degli angoli di visualizzazione.

Quando vuoi fare valutazione holdout — ovvero: quanto bene generalizza il tuo modello su angoli di visualizzazione mai visti? Lo standard nel training è "every-8th view come holdout" (convenzione Mip-NeRF360), ma è una divisione molto lineare. Se le tue immagini sono ad esempio raggruppate temporalmente (prima un lato dell'oggetto, poi l'altro), allora "every-8th" non è rappresentativo — una posizione casuale della sequenza finisce nel test, ma tutti i suoi vicini sono nel training, è troppo facile. Con "angular" si stratifica invece sullo spazio degli angoli di visualizzazione: ogni fold contiene fotocamere da tutte le aree dell'orbit, in modo che il test testi davvero le lacune di generalizzazione.

Angular vs Linear: - Angular (standard): divide le fotocamere per angolo longitudinale (coordinata φ attorno all'asse Y) in k settori uguali. Fold 0 sono fotocamere con φ ∈ [0°, 360/k°), Fold 1 i successivi, e così via. Vantaggio: ogni fold copre una sezione dell'orbit; il test fold è spazialmente compatto ma ampiamente distribuito sul dataset mondiale. Buono per riprese orbit classiche. - Linear (round-robin): indice di fold = (image_index modulo k). È la semplice divisione "every-k-th". Funziona se l'ordine dell'immagine NON ha bias spaziale (ad es. riprese di drone ordinate casualmente). Funziona male se le immagini si raggruppano temporalmente.

Nel globo 3D vedi subito: punti verdi (training) e punti rossi (test). Se i punti rossi si raggruppano tutti in un angolo, l'holdout è cattivo (nessun buon test di generalizzazione). Se sono distribuiti uniformemente tra i verdi, è buono. Il punteggio Angular Correlation per fold (sidebar destra, in gradi) dice in più: valore più piccolo = il test è vicino al training (ogni fotocamera di test ha una fotocamera di training vicina, test facile); valore più grande = il test è lontano dal training (generalizzazione più dura).

Hai registrato la tua scena Truck con 251 immagini, esporti tramite la voce di menu M33 (Export SfM transforms.json) un file nerfstudio. Apri la finestra Holdout (⇧⌘H), carica il JSON tramite "Open transforms.json…", guarda il globo. k=5 (default) ti dà 5 fold. Clicca su "Fold 3" — vedi se i marker rossi sono ragionevolmente uniformi. Se sì: "Export fold-assignment.json", metti il file esportato nella cartella Reports, e alla prossima esecuzione di training con –benchmark (o le corrispondenti impostazioni dell'Inspector) viene usata esattamente questa divisione di fold come holdout di test — al posto dello standard "every-8th".

W23Pulsante "Open transforms.json…"

DOVE

Toolbar in alto a sinistra..

TECNICO

Apre una finestra di selezione file limitata ai file JSON. Dopo la conferma il modulo Holdout carica il file. Il loader parsifica sia il formato nerfstudio (intrinseci della fotocamera più lista di frame con percorso immagine e matrice trasformazione) sia il formato instant-ngp (stessa struttura). Per frame, la direzione di vista viene estratta dalla matrice trasformazione (asse z della base locale della fotocamera) e salvata. Se il parsing fallisce, viene mostrato un messaggio di errore nell'area di stato.

Anche via CLI: –holdout-file /percorso/a/transforms.json avvia la finestra direttamente con il file caricato.

W24Picker "Strategy" (angular/linear)

DOVE

Sidebar sinistra, in alto..

TECNICO

Picker radio con due opzioni: Angular e Linear. Il cambio di strategia attiva automaticamente un ricalcolo dei fold. Le direzioni di vista sono una lista di vettori unitari 3D sulla sfera; la strategia angolare li proietta sull'angolo longitudinale φ e ordina, la strategia lineare fa semplicemente una divisione modulo sull'indice del frame.

W25Slider "k Folds"

DOVE

Sidebar sinistra, al centro..

TECNICO

Slider da 3 a 10, passo 1. Alla modifica il calcolo dei fold viene riavviato automaticamente, in modo che la lista dei fold, gli indici di training/test e il punteggio per fold vengano ricalcolati immediatamente. Il valore scelto viene visualizzato come testo monospaziato a destra accanto all'etichetta.

Regola pratica: k=5 è standard (ti dà il 20% di test per fold, è comune per cross-validation). k=10 quando hai molti dati e hai bisogno di più fold per significatività statistica. k=3 quando hai pochi dati.

W26Picker "Test Fold"

DOVE

Sidebar sinistra, sotto lo slider k..

TECNICO

Picker di menu. Le opzioni sono dinamicamente 0..<k, etichetta "Fold 1" a "Fold N" (quindi 1-indexed nell'UI, 0-indexed internamente). Se l'indice scelto in precedenza è ≥ k (ad es. perché hai ridotto k da 10 a 5), viene resettato automaticamente a 0. Il test fold scelto viene rappresentato in rosso nel globo, tutti gli altri in verde.

W27Pulsante "Export fold-assignment.json"

DOVE

Sidebar sinistra, in basso..

TECNICO

Apre una finestra di salvataggio con nome file predefinito fold-assignment.json. Dopo la conferma il modulo Holdout codifica la divisione attuale in uno schema JSON (assegnazione fold per frame più meta blocco strategia). Questo file può poi essere passato al prossimo training con –benchmark, in modo che lo stesso holdout venga usato per la valutazione finale delle metriche. Gli errori di scrittura vengono mostrati come testo di errore; il successo in testo verde come "Saved to (filename)".

W28SCNView (globo 3D delle fotocamere)

DOVE

Pannello centrale nella finestra Holdout..

TECNICO

Vista globo SceneKit. La scena è composta da: una sfera wireframe (raggio 1.0, 36 segmenti, grigio scuro), tre moncherini di assi colorati (rosso/verde/blu per X/Y/Z, ciascuno lunghi 1.2), e per fotocamera una piccola sfera marker (raggio 0.03) nella posizione di direzione di vista corrispondente sulla sfera unitaria (leggermente all'esterno, in modo che non scompaia NELLA sfera wireframe). I marker NON vengono ricostruiti ad ogni cambio di fold — il rebuild è necessario solo se cambia la lista dei frame (cioè quando viene caricato un nuovo JSON). Invece per aggiornamento avviene un aggiornamento in place dei colori del materiale: rosso per indici di test, verde per training, grigio chiaro se né né. Così i tick dello slider rimangono performanti anche con N > 1000 fotocamere.

Il controllo della fotocamera è attivato — puoi ruotare con il mouse il globo, zoomare, panare. L'illuminazione assicura che i marker non appaiano piatti. Lo sfondo è grigio scuro.

W29FoldCard (tocca per selezionare il fold)

DOVE

Sidebar destra, sezione "Angular Correlation"..

TECNICO

Per fold una vista carta — rettangolo arrotondato con raggio 6 pt, padding 10, layout verticale con due righe (in alto "Fold N" + numero fotocamere, in basso "Mean nearest angle:" + valore in gradi). Colore di sfondo condizionale: fold attivo = colore di accento semitrasparente, inattivo = materiale standard neutro. Toccando seleziona il fold, e il globo si ricolora dal vivo.

Il punteggio "Mean nearest angle" è l'angolo medio più piccolo per fotocamera di test alla fotocamera di training più vicina (calcolato internamente in radianti, visualizzato in gradi nell'UI).

BayesOpt Console (W30–W39)

Stato vuoto con picker Search Space (RadianceKit defaults (6-dim)), slider Trial Budget (default 40), Random Seed (42) e tre pannelli vuoti per Convergence Chart, Trial Log e lista di parametri dello spazio di ricerca.

Stato vuoto (dopo la prima apertura) — Convergence Chart e tabella dei trial si riempiono non appena viene avviato un run, vedi il prossimo scatto.

Stato in alto a destra "Finished — best 0.9943 after 40 trials". Sidebar sinistra: picker Search Space su RadianceKit defaults (6-dim), Trial Budget 40, Random Seed 42. La lista dei parametri mostra i sei iperparametri da tunare con i loro intervalli di valori: mipSmoothing3DScale [0.05, 0.5], mipFilter2DVariance [0.1, 0.6], densifyGradThreshold [5e-07, 5e-06], ssimWeight [0.05, 0.5], mcmcNoiseScale [1e-05, 0.0001], mcmcRelocationInterval [50, 200]. Al centro: Convergence Chart (X = indice trial 1–40, Y = valore objective 0–1) — punti grigi = sample iniziali (LHS), punti blu = acquisizione BayesOpt, punti arancioni = trial di restart (#22 e #31). La linea del valore migliore sale ripida fino al trial ~7, poi solo miglioramento marginale fino al trial 15, da lì plateau piatto a 0.99+. Sidebar destra: log trial #1–#34 con score + tag (init/bo/restart). Il pulsante Save Best Config in alto a destra scrive bayesopt-best.json.

Cos'è: Una console di ottimizzazione bayesiana per la ricerca di iperparametri. L'ottimizzazione bayesiana è una procedura automatica che cerca di trovare il punto ottimale di una funzione sconosciuta con il minor numero possibile di esperimenti — tipicamente: "quale combinazione di mcmcMaxGaussians, capMultiplier, ssimWeight e gradThreshold fornisce il miglior PSNR per la mia classe di scena?" Invece di una griglia di 6^4 = 1296 trial, BayesOpt prova circa 40–100 trial informati e si avvicina così all'ottimo.

Importante: La versione attualmente fornita nell'app non esegue l'ottimizzazione contro esecuzioni di training reali (durerebbe giorni), ma contro un obiettivo demo sintetico — un paesaggio multi-modale con carattere di hill climbing più rumore leggero. È deliberatamente così: la finestra dovrebbe mostrarti il comportamento dell'ottimizzatore (andamento di convergenza, sample point, best so far) e farti capire le definizioni dello spazio di ricerca. Per veri run BayesOpt guidati da training (come eseguiti nella Fase Q7 per i preset Scene-Class) viene usato un workflow CLI offline separato; la finestra è la variante UI dal vivo.

Tre casi d'uso: 1. Vuoi capire come lavora BayesOpt — allora avvia un run demo e osserva il Convergence Chart. 2. Pianifichi una nuova classe di scena (ad esempio "acquari" o "mobili antichi") per la quale i 10 preset integrati non si adattano perfettamente. Definisci mentalmente uno spazio di ricerca, verificalo qui con la "Bowl demo" o il preset "Densify", esporta poi la best config come JSON e usala come punto di partenza per un vero run di training. 3. Vuoi ispezionare gli spazi di ricerca di default definiti nel pacchetto RKBayesOpt (Mip subset, RadianceKit Defaults) — vengono elencati nel pannello dei parametri della sidebar sinistra.

- Convergence Chart (colonna centrale): Y = miglior valore della funzione obiettivo finora raggiunto. X = indice del trial. Inizialmente in salita ripida (BayesOpt prova casualmente i sample iniziali, alcuni sono fortunati), poi sempre più piatto, perché la regione vicino all'ottimo è esaurita. Se la linea rimane piatta per 20+ trial, puoi fermare il run — altri trial non portano più nulla. I singoli punti nel chart sono i valori individuali del trial (quindi non "best so far"), colorati per fase: grigio = sample iniziale, blu = acquisizione bayesopt, arancione = restart. - Tabella trial (colonna destra): #1, #2, #3, … con rispettivamente valore e tag fase. Il miglior trial finora è contrassegnato con una stella gialla. Dalla tabella puoi identificare il best trial e visualizzare in seguito i suoi valori dei parametri all'esportazione. - Ispettore Search Space (sidebar sinistra): mostra per il preset selezionato tutti i nomi dei parametri e i loro intervalli di ricerca [lo, hi]. Se sei sul preset "RadianceKit defaults (6-dim)", vedi ad es. "densifyGradThreshold [5e-7, 5e-6]" — quindi log uniforme tra questi due valori.

Seleziona il preset "RadianceKit defaults (6-dim)", Trial Budget 40, seed 42. Clicca "Start". Osserva: i primi 8 trial sono grigi (sample iniziali, LHS Latin Hypercube), i seguenti blu (acquisiti da BayesOpt). Il Convergence Chart sale ripido fino al trial ~15, poi si appiattisce. Al trial ~30–40 si stabilizza il valore migliore. Clicca "Save Best Config" — viene salvato un bayesopt-best.json con nome preset, indice trial, valore e valori dei parametri decodificati. Questo JSON puoi poi trasferire manualmente nella tua definizione di preset.

W30Pulsante "Start"

DOVE

Toolbar a sinistra, nello stato Idle/Finished..

TECNICO

Resetta la lista dei trial, passa allo stato Running, genera un nuovo run ID (per il rilevamento stale di clic Start multipli) e crea un fresco pause gate. Poi avvia un task in background che esegue l'ottimizzatore come stream asincrono. La dimensione dei sample iniziali risulta da min(8, budget / 4 + 1) — quindi tipicamente 8 sample Latin Hypercube con budget ≥ 28, meno con budget piccolo. Gli aggiornamenti dei trial vengono ricevuti in modo incrementale e aggiunti alla lista. Protezione da run stale: se nel frattempo un secondo clic Start imposta di nuovo il run ID, gli aggiornamenti dal vecchio run vengono scartati.

Stile primary action per il look prominente del pulsante.

W31Pulsante "Pause"

DOVE

Toolbar a sinistra, nello stato Running..

TECNICO

Imposta il pause gate attivo e passa allo stato Paused. L'effetto effettivo: il runner attende in un polling loop di 50 ms prima di valutare la prossima funzione obiettivo. Ciò significa che un trial attualmente in esecuzione viene portato a termine (è sintetico e dura solo microsecondi), ma nessun altro trial viene avviato. Non appena Resume gira, prosegue da dove si era fermato.

W32Pulsante "Stop"

DOVE

Toolbar a sinistra, negli stati Running e Paused..

TECNICO

Interrompe il task del runner, azzera il riferimento, rilascia il pause gate (se ancora in pausa) e passa allo stato Finished (se esistono trial) o Idle (se nessuno). I trial già calcolati rimangono visibili nella lista — Stop non li elimina. Il ruolo distruttivo del pulsante mostra il pulsante in rosso, perché interrompe il run.

W33Pulsante "Resume"

DOVE

Toolbar a sinistra, nello stato Paused..

TECNICO

Rilascia il pause gate e torna allo stato Running. Il task del runner è già in esecuzione (aspetta nel polling loop); non appena il loop si accorge che la pausa è stata rilasciata, prosegue e avvia il prossimo trial.

W34Pulsante "Save Best Config"

DOVE

Toolbar a destra, sempre visibile (ma disabilitato se non c'è bestTrial)..

TECNICO

Apre una finestra di salvataggio con nome file predefinito bayesopt-best.json, limitato a JSON. Dopo la conferma viene costruito un payload dictionary: nome preset, indice trial, valore (objective score), parametri (dictionary dei nomi dei parametri decodificati → valori). La decodifica proietta le coordinate dello spazio di ricerca normalizzato in [0,1]^d indietro nell'intervallo di valori originale (con scale log-uniform/lineare/intera di conseguenza). L'output JSON è pretty-printed e con chiavi ordinate. In caso di errore di scrittura (nella versione demo attuale) viene silenziosamente ignorato — nessuna UI di errore, perché è un percorso demo.

Il pulsante rimane in grigio finché nessun trial è stato eseguito.

W35Picker "Search Space" preset

DOVE

Sidebar sinistra, in alto..

TECNICO

Picker di menu con quattro opzioni preset: - "RadianceKit defaults (6-dim)" — lo spazio di ricerca standard completo con tutti gli iperparametri Q7. - "Mip subset (2-dim)" — solo mipSmoothing3DScale [0.05, 0.5] log uniforme e mipFilter2DVariance [0.1, 0.6] lineare. Utile se vuoi sintonizzare Mip-Splatting per una classe di scena. - "densify-until + ssim-weight + grad-thresh" — tre parametri rilevanti per la densify (densifyGradThreshold log uniforme, ssimWeight lineare, densifyUntilIter intero). - "Bowl demo (1-dim)" — spazio di ricerca pedagogico a parametro singolo per demo "così funziona BayesOpt".

Mentre un run è attivo, lo spazio di ricerca non può essere cambiato (confonderebbe l'ottimizzatore).

W36Slider "Trial Budget"

DOVE

Sidebar sinistra, sotto il picker Search Space..

TECNICO

Slider da 10 a 200, passo 5. Default 40. Significa: BayesOpt può fare al massimo N trial. Di questi i primi sono sample iniziali (Latin Hypercube), il resto sono veri trial BayesOpt. Regole pratiche per la pratica: uno spazio di ricerca con d dimensioni ha bisogno di circa 10d a 20d trial per un buon ottimo. Con default 6-dim quindi 60–120, con sottoinsieme Mip 2-dim 20–40, con Bowl Demo 1-dim 10–20.

Durante l'esecuzione lo slider è disabilitato.

W37Slider "Random Seed"

DOVE

Sidebar sinistra, sotto lo slider budget..

TECNICO

Slider da 1 a 100, passo 1. Default 42. Il seed viene passato sia ai sample iniziali Latin Hypercube sia al componente rumore dell'obiettivo demo. Riproducibilità: stesso seed + stesso spazio di ricerca + stesso budget produce esattamente la stessa sequenza di trial. Utile per "tutti i tuoi colleghi ottengono lo stesso run se ricostruiscono la demo?". Durante il run disabilitato.

W38Chart (Convergence)

DOVE

Colonna centrale della finestra..

TECNICO

Grafico Swift Charts con due layer: 1. una linea per "best value so far" per trial — una curva monotonamente crescente o invariata in colore di accento. 2. un punto per trial con il valore objective individuale, colorato per fase. Dimensione simbolo 40. Tre etichette fase: "init" (grigio), "bo" (blu), "restart" (arancione).

Una piccola legenda mostra i colori delle fasi in alto a sinistra. Se la lista dei trial è vuota (prima del primo start), viene mostrata invece una visualizzazione empty state con icona chart e nota "Press Start to begin a BayesOpt run.".

W39Table (Trial Log)

DOVE

Colonna destra della finestra..

TECNICO

Area di scorrimento con righe di trial impilate lazy. Per riga uno stack orizzontale: numero trial (3 cifre monospaziato, a sinistra), valore (monospaziato, allineato a destra, larghezza 70 pt), tag fase (capsule, riempito con colore fase al 25% di opacità), opzionalmente una stella gialla se questo trial è quello attualmente migliore. Un meccanismo di auto-scroll salta automaticamente alla fine non appena un nuovo trial si aggiunge — in modo che tu possa leggere l'andamento dal vivo in fondo allo schermo, senza dover scrollare tu stesso.

Finestra principale: andamento della perdita e Gaussian Count (I39–I41, rimando)

Tre delle visualizzazioni dell'Inspector nella finestra principale meritano una propria spiegazione, perché sono costantemente visibili durante un training in corso e ci sono regole pratiche importanti su quando l'andamento appare sano. Le visualizzazioni sono nell'Inspector sotto la sezione "Loss Chart" (vedi Capitolo 2 — Inspector) e completano l'analisi Holdout dalla finestra ausiliaria sopra.

Quando la curva Loss è sana? Una curva Loss sana mostra tre fasi: (1) Warmup — nelle prime 200–500 iterazioni il loss scende ripido dall'alto (tipicamente 0.15–0.25 per L1+SSIM combinato a seconda della scena) a circa la metà. Se il loss in questa fase NON scende, di solito l'input è sbagliato (immagini danneggiate, pose SfM scadenti, numero di gaussiane iniziali troppo piccolo). (2) Densification — tra ~500 e densifyUntilIteration (classicamente 15K, MCMC fino a 20K o 25K) il loss continua a scendere, spesso con piccoli salti in giù quando le operazioni di densify inseriscono nuove gaussiane e l'optimizer le sfrutta. Il gaussian count sale in questa fase. (3) Refinement — dopo il loss entra in una coda che si appiattisce. Valori finali tipici: Tanks-&-Temples Truck con P4 Quality si attesta a L1 ≈ 0.023, Horse con Full Classic V546 a L1 ≈ 0.0230, scene outdoor Mip-NeRF360 spesso peggio (0.04–0.07).

Cosa significa un plateau? Un plateau (la curva Loss corre orizzontale per diverse migliaia di iterazioni) ha due interpretazioni: (a) il modello è convergente, altro training non porta più nulla — è il caso buono. (b) il modello è bloccato (minimo locale, informazione di gradiente scadente, un cap al limite del buffer) — il caso cattivo. Entrambi appaiono identici nel chart. Distinzione: guarda il gaussian count. Se anche è piatto E vicino al cap MCMC (ad es. 150K su 150K con .fullMCMC), sei al limite — o aumenta il cap o accetta il plateau. Se il gaussian count cresce ancora, ma il loss non scende, è bloccato.

Quando interrompere vs continuare il training? Regola pratica: 10K iterazioni senza miglioramento del Min Loss → interrompere, ulteriori iterazioni sono sprecate. Prima: puoi tramite Cmd+T (menu Training → Continue Training → +5K iterations) aggiungere ancora un'estensione, se vedi miglioramento borderline. Attenzione: con MCMC il plateau è spesso vero — il cap è il limite naturale.

Il plateau del Gaussian Count NON è un segnale di "finito". Significa solo che MCMC ha raggiunto il cap o che la densification Classic è esaurita. La vera domanda "finito" la pone solo l'analisi Holdout — PSNR/SSIM/LPIPS su un set di test indipendente, valutato nella finestra Holdout (W23–W29) o tramite il flag –benchmark.

PSNR/Holdout è la verità, il Loss solo proxy. Il loss è una metrica relativa: scende mentre il tuo modello si adatta alle viste di training. Un loss basso non significa però automaticamente buon modello — se il modello ha imparato a memoria le immagini di training (overfitting), il loss sarebbe piccolo, ma il PSNR su viste mai viste (holdout) sarebbe scadente. Quindi: per la valutazione finale della qualità guarda sempre le metriche holdout, non il loss finale da solo.

Box delle regole pratiche

- User Guide e Keyboard Shortcuts sono aiuto statico — per domande veloci, per la profondità usare il manuale presente. - Aprire Manage Storage non appena il disco scende sotto il 10% di spazio libero. Log e staging Imports sono i soliti colpevoli. - Pareto Dashboard sensato solo dopo almeno tre o quattro report di training. Asse X = costo (Time / Gs), asse Y = qualità (PSNR / SSIM). La frontiera di Pareto mostra le combinazioni efficienti. - Usare Holdout Analysis prima di pubblicare benchmark PSNR con altri — ti assicura che il tuo set di test sia davvero rappresentativo. - BayesOpt Console è primariamente uno strumento di apprendimento e ispezione per definizioni di spazio di ricerca. Per veri tuning di iperparametri guidati da training usare il workflow CLI offline. - Loss-plateau e Gaussian-Count-plateau sono da interpretare separatamente. Il limite del cap non è un segnale di "finito". La vera qualità la misura solo il PSNR holdout. - 10K iterazioni senza miglioramento del Min Loss → fermare il training.