Guida utente

Capitolo 4 — Finestre ausiliarie

Oltre alla finestra principale (viewport 3D più Inspector), RadianceKit gestisce altre tre finestre, che si aprono tutte tramite il menu Help. Il menu contiene cinque voci, dall'alto verso il basso: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder… e Manage Storage…. Le due voci "Open …" non aprono una finestra dell'app, ma il Finder; per questo motivo qui non vengono trattate ulteriormente.

Le tre finestre semplici (User Guide, Keyboard Shortcuts, Manage Storage) e le due voci di menu per le cartelle (Open Training Logs / Open Exports Folder) ricevono una breve voce per ogni elemento di controllo.

Alla fine del capitolo si trova una sezione di rimando all'Inspector della finestra principale: cosa puoi ricavare in modo utile dal grafico della loss in tempo reale e dall'indicatore del numero di gaussiane durante un addestramento in corso.

Guida Utente (W1–W4)

Finestra Guida Utente con sidebar a sinistra e contenuto Markdown renderizzato a destra
Finestra Guida Utente con sidebar a sinistra e contenuto Markdown renderizzato a destra

Cos'è: Una finestra di aiuto integrata che renderizza il file guide_<sprache>.md fornito con l'app. La lingua viene dedotta dalle Impostazioni (Tab General → Language) o, se lì è impostato "System", dalle preferenze linguistiche di macOS. Il layout è classico: a sinistra la sidebar con tutte le intestazioni, a destra il testo continuo.

Quando ti serve un rapido promemoria su un singolo punto — quindi come sostituto di appunti veloci. Il riferimento dettagliato è questo manuale; la finestra di aiuto integrata è la versione breve per la consultazione rapida. Viene aggiornata a ogni release dell'app, ma i contenuti restano volutamente più superficiali.

W1NavigationSplitView (Sidebar + Dettaglio)

DOVE

Help → User Guide (⌘?).

TECNICO

Layout a due colonne con una sidebar stretta (larga almeno 180 pt) per l'albero dei contenuti e un'area di dettaglio scorrevole per il vero contenuto Markdown. La finestra ha una dimensione minima di 700 × 500 pt. Alla prima apertura la finestra carica il file guide_<lang>.md appropriato dal bundle dell'app (fallback guide_en.md), lo analizza in record a blocchi (intestazioni H1–H4, paragrafi, liste, tabelle, linee di separazione) ed estrae separatamente la struttura delle intestazioni per la sidebar. La formattazione inline (grassetto, corsivo, span di codice) 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 di locale completi, perché queste varianti si distinguono da zh e pt rispettivamente.

W2List (Sidebar delle intestazioni)

DOVE

Colonna sinistra nella finestra Guida Utente.

TECNICO

Elenco di tutte le intestazioni H2 e H3 del documento Markdown attuale. Le voci H2 appaiono senza rientro con peso di carattere medio, le voci H3 con 16 pt di rientro a sinistra e uno stile in primo piano ridotto. Tutti gli altri livelli — sia H1 che H4 e inferiori — non appaiono nella sidebar, perché altrimenti la renderebbero poco chiara. Gli ID degli ancoraggi vengono generati dal testo dell'intestazione tramite slugificazione (minuscolo + spazi trasformati in trattini + filtro su lettere/numeri/trattini — lo stesso algoritmo usato da GitHub per i suoi ancoraggi Markdown, cosicché anche URL esterni verso la documentazione potrebbero potenzialmente puntare allo stesso ancoraggio). L'elenco usa lo stile nativo di macOS.

W3Button (Salto da intestazione ad ancoraggio)

DOVE

Un pulsante per ogni riga della sidebar.

TECNICO

Ogni voce della sidebar è un pulsante che imposta l'ancoraggio attuale, ma visivamente sembra una voce di elenco. Una variabile osservatore attiva quindi il salto di scorrimento verso l'ancoraggio corrispondente con un'animazione fluida di 0,3 s. Dopo il salto, il valore dell'ancoraggio viene azzerato, in modo che il clic successivo sullo stesso ancoraggio si attivi di nuovo (altrimenti l'osservatore non si attiverebbe di nuovo, perché il valore non è cambiato).

W4ScrollView (Contenuto di dettaglio)

DOVE

Colonna destra.

TECNICO

Area di contenuto scorrevole, impilata verticalmente, con rendering lazy, perché guide più lunghe possono facilmente superare 200 blocchi Markdown — una variante non lazy istanzierebbe tutto contemporaneamente. Ogni blocco riceve un proprio ID, o l'ancoraggio dell'intestazione (che ogni intestazione riceve, indipendentemente dal livello) o un segnaposto di indice. La larghezza massima è 720 pt, il 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 linee di separazione; il codice inline tramite il motore Markdown integrato. I veri blocchi di codice sono attualmente trattati come paragrafi — una limitazione nota della finestra di aiuto.

Scorciatoie da Tastiera (W5–W6)

Keyboard Shortcuts Fenster — fünf Gruppen Navigation/Views/Capture/Editor/Training mit Hotkey-Spalte links und Beschreibung rechts
Finestra Scorciatoie da Tastiera — cinque gruppi Navigation/Views/Capture/Editor/Training con colonna hotkey a sinistra e descrizione a destra

Elenco di riferimento statico 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 (Background-Cycle), 0–9 (salta a Training-Cam 1=10%/5=50%/0=last), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (video turntable), C (Copy Camera Info). Editor: Tab (modalità di modifica), Click/Drag (Paint-Select), Option+Click (deseleziona), X / Delete (elimina selezione), Cmd-Z (annulla ultima eliminazione), [ / ] (dimensione pennello più piccola/più grande), Esc (annulla selezione). Training: Option+Space (metti in pausa/riprendi training), Cmd+E (esporta scena). Non c'è altro qui — Start, Cancel e le estensioni si raggiungono tramite il menu Training (Capitolo 1).

Cos'è: Una semplice panoramica statica di tutte le scorciatoie da tastiera — Navigation, Views, Capture, Editor, Training. Il contenuto è integrato fisso e non viene ricaricato da un file.

Quando cerchi il modo più rapido per fare qualcosa nel viewport. WASD-Fly-Through, R per Camera-Reset, B per il Background-Cycling — sono tutte qui.

W5ScrollView (area contenuti)

DOVE

Help → Keyboard Shortcuts (⌘/).

TECNICO

Una semplice area di scorrimento con una lista verticale al suo interno. Padding di 20 pt tutt'intorno, nessun albero di navigazione laterale (la lista è abbastanza corta). I contenuti sono raggruppati in cinque sezioni (Navigation, Views, Capture, Editor, Training). Per ogni combinazione di tasti una riga con testo traducibile in entrambe le colonne. La colonna sinistra (codice tasto) è fissata a 180 pt di larghezza, così le descrizioni a destra restano allineate verticalmente. Nessuna interazione oltre lo scorrimento — cliccare su una riga non attiva nulla, le scorciatoie sono veri e propri modificatori di tastiera nel menu e nel viewport.

W6VStack (sezioni delle scorciatoie)

DOVE

All'interno della ScrollView.

TECNICO

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

Gestisci Archiviazione (W7–W12)

Finestra Manage Storage — l'intestazione mostra „1,356 items · 55.1 GB total”, tabella con file di export PLY ordinati per data, ciascuno con icona + nome file + dimensione + data
Finestra Manage Storage — l'intestazione mostra „1,356 items · 55.1 GB total", tabella con file di export PLY ordinati per data, ciascuno con icona + nome file + dimensione + data

Vista a tabella di tutti i file gestiti da RadianceKit. L'intestazione conta 1.356 elementi, 55,1 GB di dimensione totale. Toolbar in alto: „Show in Finder" + „Refresh". Ogni riga: icona di export, nome file (es. training_20260718T194416Z.ply), data di export, dimensione (qui varia da 7,8 MB a 2,24 GB), icona lente (Reveal) e icona cestino (Move to Trash). L'ordinamento avviene prima per categoria e all'interno di una categoria per data, il più recente in alto. In questa schermata dominano gli export PLY, perché in questo archivio sono stati salvati soprattutto risultati di training.

Cos'è: Una panoramica dell'uso del disco per tutto ciò che RadianceKit salva in ~/Documents/RadianceKit/ — log, export, scene, capture-bundle (dal companion iOS), import (copie di staging delle immagini in ingresso). Per ogni 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 voce per voce. Questa finestra è tradotta: in italiano si chiama „Gestisci Archiviazione", i due pulsanti dell'intestazione si chiamano „Mostra nel Finder" e „Aggiorna", i pulsanti di riga „Mostra nel Finder" e „Sposta nel cestino". I nomi inglesi nelle voci qui sotto sono le denominazioni della versione inglese.

Quando il disco si riempie. Soprattutto i log si accumulano (un JSONL per ogni tentativo di training, più il _qualityMetrics.json); naturalmente anche gli export (PLY sono dati grezzi al 100%, uno per export). Utile anche dopo un crash, quando la cartella di staging degli import ha ancora vecchie copie delle immagini di ingresso in giro.

W7Pulsante „Show in Finder"

DOVE

Intestazione in alto a destra nella finestra dello storage browser.

TECNICO

Apre la cartella dati di RadianceKit nel Finder — esattamente la directory il cui contenuto viene elencato in questa finestra. Così vedi direttamente la struttura delle cartelle (Logs, Exports, Scenes, Captures, Imports) e puoi spostare o copiare i file anche tu stesso tramite il Finder. L'azione apre una nuova finestra del Finder; la lista nella finestra non cambia di conseguenza — per questo c'è „Refresh" (W8).

W8Pulsante „Refresh"

DOVE

Intestazione, accanto al pulsante Finder.

TECNICO

Avvia una scansione in background eseguita su un task asincrono avviato dall'utente, in modo che la scansione di grandi alberi di directory non blocchi la UI. L'attraversamento vero e proprio passa in rassegna ogni sottocartella nota (Logs, Exports, Scenes, Captures, Imports) e genera una voce di archiviazione per ogni figlio diretto. Per ogni voce viene determinata la dimensione ricorsiva — preferibilmente il consumo effettivo su disco (incluso il sharing degli hardlink APFS) con fallback sulla dimensione logica del file.

W9List (voci di archiviazione)

DOVE

Contenuto principale sotto l'intestazione.

TECNICO

Elenco con per ogni riga questo layout: icona SF Symbol specifica per categoria (documento per Logs, freccia di upload per Exports, cubo per Scenes, iPhone per Capture-Bundle, vassoio per Imports), nome + sottotitolo (etichetta del tipo + data di modifica formattata), contatore byte a destra (allineato a destra, monospaced), pulsante Reveal (icona lente), pulsante Trash (cestino). Ordinamento: primario per tipo (prima Scenes, poi Exports, Logs, Captures, Imports, Other), secondario per data di modifica in ordine decrescente (più recente in alto). Se la scansione è ancora in corso, al posto della lista viene mostrato un progresso „Scanning…". Se non è stato trovato nulla, viene mostrato uno stato vuoto con icona vassoio.

W10Pulsante di riga „Reveal in Finder"

DOVE

Per ogni riga, icona lente a destra.

TECNICO

Apre il Finder e seleziona l'elemento specifico (file o cartella). Differenza rispetto a W7: W7 apre la directory principale; W10 evidenzia esattamente questa singola voce. Flusso di lavoro pratico: identifica una voce grande, clicca sulla lente, poi copiala per esempio su un volume esterno.

W11Pulsante di riga „Move to Trash"

DOVE

Per ogni riga, icona cestino a destra accanto alla lente.

TECNICO

Attiva la finestra di dialogo di conferma (W12). Solo dopo la conferma viene eseguita l'operazione standard di macOS „sposta nel cestino" (quindi reversibile, non un'eliminazione diretta). Dopo il trasferimento riuscito nel cestino, la voce viene rimossa dalla lista e il contatore totale dei byte viene aggiornato. In caso di errori viene mostrata una finestra di dialogo di errore modale.

W12ConfirmationDialog (conferma di eliminazione)

DOVE

Attivata da W11, presentata come sheet di macOS.

TECNICO

Finestra di dialogo di conferma standard con titolo dinamico „Delete <name>?" e una riga di messaggio che indica esplicitamente che la voce finisce nel cestino e da lì può essere ripristinata (finché il cestino non viene svuotato). Due pulsanti: „Move to Trash" come azione distruttiva (mostrata in rosso) e „Cancel" con associazione automatica al tasto Esc. La finestra di dialogo è non modale nel senso che blocca solo questa finestra, non l'intera app — questo è lo standard macOS per le eliminazioni reversibili.

Finestra principale: andamento della loss e conteggio dei Gaussiani (I39–I41, rimando incrociato)

Tre delle visualizzazioni dell'Inspector nella finestra principale meritano una spiegazione a sé, perché sono costantemente visibili durante un training in corso e perché esistono importanti regole pratiche su quando l'andamento appare sano. Le visualizzazioni si trovano nell'Inspector, nella sezione Progresso, nel gruppo espandibile Andamento della Loss (vedi Capitolo 2 — Inspector) e completano la lettura del progresso dell'addestramento.

Quando la curva di Loss è sana? Una curva di Loss sana mostra tre fasi: (1) Warmup — nelle prime 200–500 iterazioni la loss scende ripidamente da un valore alto (tipicamente 0.15–0.25 per L1+SSIM combinati, a seconda della scena) a circa la metà. Se la loss in questa fase NON scende, di solito l'input è sbagliato (immagini danneggiate, pose SfM scadenti, numero di Gaussiani iniziali troppo basso). (2) Densification — tra ~500 e densifyUntilIteration (classicamente 15K, con MCMC fino a 20K o 25K) la loss continua a scendere, spesso con piccoli salti verso il basso quando le operazioni di densificazione inseriscono nuovi Gaussiani e l'optimizer li sfrutta. Il conteggio dei Gaussiani cresce in questa fase. (3) Refinement — successivamente la loss entra in una coda sempre più piatta. Valori finali tipici come orientamento: una scena oggetto ben illuminata (ad esempio Tanks-&-Temples Truck con preset P4 Quality) si assesta su L1 ≈ 0.023, mentre scene esterne ampie come quelle di Mip-NeRF 360 restano naturalmente più alte (0.04–0.07).

Cosa significa un plateau? Un plateau (la curva di Loss procede orizzontale per diverse migliaia di iterazioni) ha due interpretazioni: (a) il modello è convergiuto, ulteriore training non porta più nulla — questo è il caso positivo. (b) il modello è bloccato (stuck: minimo locale, informazione di gradiente scadente, un cap al limite del buffer) — il caso negativo. Entrambi appaiono identici nel grafico. Per distinguerli: osserva il conteggio dei Gaussiani. Se anch'esso è piatto E vicino al cap MCMC (ad es. 150K su 150K con il preset P8 Quality (MCMC)), sei al limite — o aumenti il cap oppure accetti il plateau. Se il conteggio dei Gaussiani sta ancora crescendo ma la loss non scende, allora è stuck.

Quando interrompere e quando continuare il training? Regola pratica: se per 10K iterazioni non c'è miglioramento della Loss minima → interrompi, ulteriori iterazioni sono sprecate. Prima di quel punto: tramite il menu Training → Continue Training → „+5,000 iterations" puoi ancora aggiungere un prolungamento, se noti un miglioramento al limite (non esiste una scorciatoia da tastiera per questo). Attenzione: con MCMC il plateau è spesso reale — il cap è il limite naturale.

Il plateau del conteggio dei Gaussiani NON è un segnale di "finito". Significa solo che MCMC ha raggiunto il cap oppure che la Classic Densification ha esaurito il suo margine. La vera domanda se sia "finito" trova risposta solo in PSNR/SSIM/LPIPS su un test-set indipendente. Il test-set indipendente mostra anche se il tuo set di telecamere consente una suddivisione equa tra punti di vista di training e di test.

PSNR/Holdout è la verità, la Loss è solo un proxy. La loss è una metrica relativa: scende mentre il tuo modello si adatta alle view di training. Una loss bassa però non significa automaticamente un buon modello — se il modello ha imparato a memoria le immagini di training (overfitting), la loss sarebbe piccola, ma la PSNR su view mai viste (Holdout) sarebbe scarsa. Perciò: per la valutazione finale della qualità guarda sempre alle metriche Holdout, non solo alla loss finale.

Regola pratica

- User Guide e Keyboard Shortcuts sono aiuto statico — rapidi per domande puntuali, per gli approfondimenti usa il presente manuale. - Apri Manage Storage non appena il disco scende sotto il 10% di spazio libero. I log e lo staging degli Imports sono i soliti colpevoli. - Il plateau della loss e il plateau del numero di gaussiane vanno interpretati separatamente. Il limite massimo non è un segnale di „completato". La qualità reale si misura solo con il PSNR di holdout. - 10K iterazioni senza miglioramento della loss minima → interrompi il training.