Capitolo 2 — Inspector (Vista Esperto)

Inspector vuoto prima dell'importazione: La sidebar a sinistra mostra il contatore Images 0 e il suggerimento "Drop images here / or tap + to import". L'Inspector a destra è completamente funzionale, ma i preset sono solo informativi (nessun training attivo). Il preset predefinito "Preview" (5K iter) è contrassegnato. Camera Alignment su Apple Photogrammetry, Densification Classic, SSIM Weight 0.20, Render Scale 50 %. Stati vuoti in Training Metrics ("Start training to see live metrics") e Loss History ("Loss curve will appear during training").

Inspector dopo l'importazione: Stato dell'header "60 images ready". La sidebar Image elenca tutti i 60 frame importati (frame_0001.jpg fino a frame_0945.jpg, ogni 16° frame del dataset di 960 cam come sottoinsieme per iterazioni rapide). La logica auto-render-scale verifica la risoluzione dell'immagine (1536×2048 = 3.1 MP) e adatta Render Scale di conseguenza. Il pulsante play (verde, in basso a sinistra) è ora attivo e avvia il training con il preset attivo.

Inspector durante il training: La title bar mostra il progresso globale "RadianceKit — Training NN %". Il viewport renderizza la ricostruzione gaussiana in corso in tempo reale (aggiornato ogni 50 iterazioni — intervallo live preview impostabile in Settings → General → Training → Live Preview). Barra delle metriche sotto il viewport: loss attuale, learning rate, gaussian count e contatore di iterazioni (ad es. 1,600/5,000 con preset Preview). La scheda preset "Preview" dell'Inspector mostra il badge "Modified" non appena qualsiasi parametro si discosta dal default integrato. La sidebar "Log" raccoglie gli eventi degli stadi SfM e training.

Inspector dopo il training: La title bar mostra il numero finale di gaussiane (qui 2 991 — molto compatto, perché la scena sintetica del bouquet su sfondo chiaro ha geometria semplice). Il viewport mostra la nuvola di punti finita — navigazione drag orbitale attiva (ruota attorno al centro della scena). La sezione delle metriche di training è ora riempita con i valori finali, il grafico Loss History mostra l'andamento di tutte le 5 000 iterazioni. La sezione di esportazione in basso è ora attiva (tutti i pulsanti di formato abilitati).
L'Inspector è la sidebar di destra in Modalità esperto (⌘2). Raggruppa tutti i parametri rilevanti per il training in cinque sezioni richiudibili: Preset, Configurazione del training, Enhancements, Metriche e grafico di perdita. Ogni sezione può essere richiusa cliccando sull'header, l'ordine può essere riorganizzato tramite drag-and-drop (InspectorView.swift:81-97). Per default tutte le sezioni sono visibili, lo stato dell'app salva le preferenze di richiusura e ordine attraverso gli avvii dell'app.
Una serie di controlli dell'Inspector compare in forma quasi identica anche nelle Impostazioni (Capitolo 3) — tipicamente backend SfM, Sky Masking e default simili. La separazione è intenzionale: le Impostazioni forniscono il template a livello di app per i progetti appena creati, l'Inspector sovrascrive questi valori per il progetto attualmente aperto. Chi conosce la logica di una pagina può usare l'altra ad occhi chiusi.
La colonna di sinistra in Modalità esperto — il Project Navigator — non appartiene all'Inspector, ma è il suo vicino diretto. Lì le immagini importate possono essere selezionate con un clic, viste in Quick Look con la barra spaziatrice ed eliminate tramite il pulsante meno o il tasto Backspace (con Cmd-Z per l'annullamento). L'Inspector segue la selezione attuale della sidebar con informazioni di dettaglio specifiche del contesto, le cinque sezioni principali rimangono però sempre visibili.
Sezione Preset (I1–I11)
La sezione Preset è il modo più rapido per applicare una configurazione testata. I preset integrati (Classic, MCMC, Scene-Class) forniscono punti di partenza riproducibili da 560+ esperimenti documentati; i preset propri possono essere salvati, esportati, importati e condivisi. La lista è raggruppata per categorie (Classic, MCMC, SceneClass, Custom) e più di una categoria può essere espansa contemporaneamente. Tramite il meccanismo del menu contestuale (clic destro su una riga) sono raggiungibili Export, Duplicate e — per preset propri — Delete.
I1Pulsante Save…
DOVE
Inspector → sezione Preset → pulsante Save… (barra azioni in basso).
TECNICO
Apre un popover con campo di testo e pulsanti Save/Cancel. Lo stato attuale di TrainingConfig viene persistito come nuovo preset personalizzato (codificato JSON, salvato a livello di app). L'operazione di salvataggio copia tutti gli 81 parametri di training più la strategia di densification attuale. Il preset finisce automaticamente nella categoria Custom, indipendentemente da quale preset integrato sia stato derivato. Nomi vuoti e input di solo whitespace vengono scartati. I nomi già esistenti non vengono rifiutati — ogni preset ha un proprio ID interno, i nomi duplicati sono tecnicamente consentiti ma in pratica confusi.
I2Campo di testo Preset Name
DOVE
Popover Save → campo di testo "Preset Name".
TECNICO
Semplice campo di testo con bordo arrotondato, forma larga. Il valore viene assunto come nome del preset al clic sul pulsante Save. Nessun limite di lunghezza nell'UI, ma il nome salvato deve essere codificabile in JSON e rappresentabile nelle liste UI — emoji e caratteri accentati funzionano. Il contenuto viene automaticamente resettato a stringa vuota all'apertura del popover. Il pulsante Save rimane disabilitato finché il campo dopo trim è vuoto. Non c'è auto-suggest né preimpostazione con il nome del preset attualmente attivo.
I3Pulsante Cancel (dialogo Save)
DOVE
Popover Save → pulsante Cancel (a sinistra).
TECNICO
Chiude il popover senza salvare. Scarta il contenuto del campo di testo — alla prossima apertura viene di nuovo resettato a vuoto dalla logica del pulsante Save… (I1). Stile di pulsante standard, nessuna finestra di conferma, nessuna hotkey. La TrainingConfig attuale rimane invariata, poiché il percorso di salvataggio non è stato eseguito.
I4Pulsante Save (dialogo Save)
DOVE
Popover Save → pulsante Save (a destra, stile prominente).
TECNICO
Attiva la persistenza effettiva. Valida nuovamente il nome non vuoto (controllo difensivo) e scrive poi la TrainingConfig attuale come JSON nella memoria dell'app. Successivamente chiude il popover. Evidenziato in blu, in grigio finché il campo di testo è vuoto. Se il salvataggio fallisce (ad es. perché la memoria dell'app è piena — molto improbabile), al momento non c'è una finestra di errore visibile; il preset semplicemente non apparirebbe al prossimo avvio dell'app.
I5Pulsante Export…
DOVE
Inspector → sezione Preset → barra azioni → pulsante Export….
TECNICO
Esporta il preset attualmente selezionato come file .radiancepreset (internamente JSON). Disabilitato se non è selezionato alcun preset. Al clic l'app apre una finestra di salvataggio con nome file predefinito (nome preset + estensione .radiancepreset). Il formato salvato contiene l'intera TrainingConfig più metadati (nome, categoria, ID, flag built-in). Il doppio clic nel Finder apre l'app — ma non automaticamente l'importazione; l'utente deve usare il pulsante Import (I6).
I6Pulsante Import…
DOVE
Inspector → sezione Preset → barra azioni → pulsante Import….
TECNICO
Apre una finestra di dialogo dei file che consente solo file .radiancepreset (selezione multipla disabilitata). Alla selezione il file JSON viene caricato, validato e inserito nella categoria Custom — con un nuovo ID interno per evitare collisioni con i built-in. L'importazione imposta automaticamente la categoria su Custom, anche se il preset esportato era originariamente ad es. un built-in. File danneggiati o incompatibili con uno schema di versione precedente vengono silenziosamente rifiutati, senza finestra di errore (il log della console fornisce però informazioni).
I7Riga preset (attivazione con clic)
DOVE
Inspector → sezione Preset → ogni riga preset in ogni categoria.
TECNICO
Il clic su una riga preset sostituisce tutti i campi della TrainingConfig con i valori dal preset, memorizza l'ID del preset attivo e resetta lo stato modificato. Il segno di spunta attivo davanti alla riga appare solo se il preset è selezionato E non modificato. Non appena un valore viene modificato nella TrainingConfig (slider, stepper, toggle nelle altre sezioni dell'Inspector), appare un badge arancione "Modified" dopo il nome. I preset integrati non possono essere sovrascritti — in caso di modifica deve essere creata una copia propria tramite il pulsante Save (I1).
I8Menu contestuale "Export…"
DOVE
Clic destro su ogni riga preset → prima voce "Export…".
TECNICO
Funzionalità identica a I5 (pulsante Export…), ma raggiungibile più comodamente — senza che il preset debba essere prima selezionato. Esporta direttamente il preset cliccato nella riga. Funziona allo stesso modo per tutte le categorie di preset (built-in o Custom), nessuna restrizione. L'esportazione contiene il flag built-in e la categoria originale, ma al re-import la categoria viene mappata su Custom come descritto in I6.
I9Menu contestuale "Duplicate"
DOVE
Clic destro su ogni riga preset → seconda voce "Duplicate".
TECNICO
Clona il preset nella categoria Custom. Genera un nuovo ID interno, appende " Copy" al nome e salva la copia. Funziona anche per i preset integrati — il clone è poi editabile. L'originale rimane intatto. La TrainingConfig viene copiata valore per valore (roundtrip JSON), in modo che non esistano collegamenti di riferimento tra originale e copia.
I10Menu contestuale "Delete"
DOVE
Clic destro sulle righe preset proprie → ultima voce "Delete" (rosso, distruttivo).
TECNICO
Visibile solo per preset Custom. I built-in non possono essere eliminati. La voce è contrassegnata come distruttiva, appare in rosso nel menu contestuale e viene separata da un divisore in modo da non cliccarla per errore. Non c'è alcun dialogo di conferma — un clic elimina immediatamente il preset. Il preset eliminato non è ripristinabile (Cmd-Z non funziona qui — l'annullamento esiste nella build attuale solo per la lista delle immagini, non per le operazioni sui preset). Se il preset eliminato era attualmente attivo, la TrainingConfig attuale rimane invariata, solo la selezione preset attiva viene azzerata.
I11Header di categoria (espandi/comprimi)
DOVE
Inspector → sezione Preset → ogni header di categoria (Classic, MCMC, SceneClass, Custom).
TECNICO
Stato di richiusura per categoria con default diverso: Classic parte espanso, MCMC, SceneClass e Custom partono chiusi. Lo stato non viene persistito — al riavvio dell'app tutte le categorie sono di nuovo nello stato predefinito. La freccia chevron ruota animata. Il numero a destra nell'header mostra il numero di preset in questa categoria. L'area di hit del clic copre l'intera area dell'header.
Sezione Configurazione del Training (I12–I22)

Qui si trovano le leve centrali: quale backend SfM deve calcolare, come lavora la densification, quante iterazioni, quanto grande è il peso SSIM. Con la strategia MCMC compaiono due toggle aggiuntivi ("MCMC Quality" e "Auto-scale by scene") che vengono nascosti in modalità Classic. Con il backend Native SfM si aggiunge il campo FOV Override, che serve solo per frame video senza lunghezza focale EXIF.
I12Picker Camera Alignment
DOVE
Inspector → Configurazione del training → Camera Alignment (picker segmentato in alto).
TECNICO
Picker segmentato con due opzioni: Apple Photogrammetry e Native (Beta). La selezione determina il backend SfM utilizzato alla prossima ricostruzione delle fotocamere. Influenza contemporaneamente quali altri elementi dell'Inspector sono visibili: Native mostra in più il FOV Override (I13), che serve solo con frame video privi di EXIF. Nota: per riprese outdoor molto grandi puoi caricare il risultato di uno strumento esterno (Metashape o COLMAP) tramite Workspace Import — vedi Capitolo 1 (M5) e Capitolo 9 (Q3, Q6).
I13Campo FOV Override (SfM Native)
DOVE
Inspector → Configurazione del training → FOV Override (visibile solo con Camera Alignment = Native).
TECNICO
Campo di testo numerico (range 0-170°), default 0 = determinazione automatica da EXIF o euristica. L'input manuale è necessario se le immagini di input sono state estratte da un video che non contiene metadati di lunghezza focale. Valori tipici: iPhone Wide ≈ 73°, DJI Mavic Wide-Crop ≈ 70°, drone con sensore full-frame ≈ 84°. Il valore viene limitato a [0, 170] — valori fuori vengono riportati direttamente al limite. Ha effetto solo sulla pipeline SfM nativa (Q4/Q5); Apple Photogrammetry ignora completamente questo valore.
I15Picker Densification
DOVE
Inspector → Configurazione del training → Densification (picker segmentato, sempre visibile).
TECNICO
Commuta tra le due strategie di densification: Classic (metodo 3DGS originale con clone/split/prune e soglia di gradiente) e MCMC (Stochastic Gradient Langevin Dynamics con rilocazione, NeurIPS 2024). Al passaggio da Classic a MCMC l'app imposta automaticamente i campi specifici MCMC su valori di default collaudati (reg-weight = 0, MCMC cap-multiplier 3.0, sample/noise schedule). Senza questa inizializzazione automatica le sessioni con preset vecchi soffrivano del bug MCMC collapse 1.4.4 (460K→5 gaussiane, kill del watchdog). La selezione del picker determina inoltre quali elementi dell'Inspector sono visibili — con MCMC compaiono I16/I17. Effetto dettagliato dei campi nel Capitolo 6, T11–T16 (Classic) e T61–T73 (MCMC).
I16Toggle MCMC Quality
DOVE
Inspector → Configurazione del training → MCMC Quality (solo con Densification = MCMC).
TECNICO
Commuta l'accumulo del gradiente su 2 passi (attivo) o 1 passo (inattivo). Accumula i gradienti da due viste di fotocamera consecutive prima dell'esecuzione dello step dell'optimizer. Empiricamente (sessione 33, V544a) ciò riduce l'errore L1 finale di circa il 6% (0.0246 con Quality vs 0.0261 senza, in media su 3 trial su Horse-Full-MCMC). Il prezzo: tempo di training raddoppiato. Su training molto lunghi (200K iterazioni) ciò porta a oltre 10 minuti di attesa aggiuntiva — quindi vale la pena solo se gli ultimi punti percentuali di qualità sono davvero necessari. Ha effetto solo sul training, non sul formato di esportazione o sulla visualizzazione del viewport.
I17Toggle Auto-scale by scene
DOVE
Inspector → Configurazione del training → Auto-scale by scene (solo con MCMC).
TECNICO
Se attivo, scala il limite superiore effettivo di Max-Gaussians con SfM-init-point-count × MCMC-cap-multiplier (default 3.0). Esempio: SfM fornisce 250K initpoint, base cap = 150K, multiplier 3.0 → limite superiore effettivo = max(150K, 750K) = 750K. Se disattivato, vale rigorosamente solo la base. Introdotto per v1.4.5, perché grandi riprese outdoor con oltre 1000 frame e corrispondente alta densità di punti SfM facevano morire di fame la densification con il default rigido di 150K cap — i punti superflui rimanevano, quelli nuovi non potevano nascere. Default OFF nei preset Custom, ON nei built-in MCMC. Ha effetto solo durante il training, non nell'esportazione.
I18Stepper Max Iterations
DOVE
Inspector → Configurazione del training → GroupBox → Max Iterations.
TECNICO
Stepper con range 1 000–100 000, passo 1 000. Determina il numero totale di iterazioni dell'optimizer. Correlato linearmente al tempo di training (dimezzamento = circa 50% del tempo). Sweet spot empirici: 20K (Classic Balanced, L1≈0.028), 40K (Classic Quality, L1≈0.023), 200K (MCMC Full, L1≈0.0246). Oltre 40K con Classic in media non porta quasi alcun miglioramento — diminishing returns. Alla modifica, se la funzione di link (I19) è attiva, Densify Until viene tirato proporzionalmente (rapporto di default: 0.5, ossia Densify Until = Max/2).
I19Pulsante Link/Unlink (Densify ↔ Iterations)
DOVE
Inspector → Configurazione del training → GroupBox → piccolo pulsante Link tra Max Iterations e Densify Until.
TECNICO
Pulsante toggle che congela il rapporto tra Densify Until e Max Iterations. Con attivo (icona link evidenziata) a ogni modifica di Max Iterations Densify Until viene tirato proporzionalmente. Con unlink (icona link-plus) i valori rimangono indipendenti. Default è linked, perché ciò riflette la correlazione tipica — se tiri il training su iterazioni doppie, di solito vuoi anche far girare la densification proporzionalmente più a lungo. Il rapporto viene calcolato all'impostazione del pulsante link dal valore attuale; un rapporto tipico è 0.5 (Densify Until = metà del numero di iter).
I20Stepper Densify Until
DOVE
Inspector → Configurazione del training → GroupBox → Densify Until.
TECNICO
Stepper con range 500–50 000, passo 500. Determina l'indice di iterazione a partire dal quale non vengono più aggiunte nuove gaussiane tramite clone/split (Classic) o rilocazione (MCMC). Al raggiungimento vengono raffinate solo posizione e colore. Valori più alti = più gaussiane = file più grande, tempo per iterazione più lungo (+30-60% di tempo GPU per passo). Valori tipici: 15K (per 30K Max Iter), 20K (per 40K), 100K (per 200K MCMC). Con link attivo (I19) automaticamente scalato. Ha effetto diverso con Classic vs MCMC: Classic ferma completamente la crescita, MCMC ferma la logica di rilocazione, ma l'adattamento di sample/noise prosegue.
I21Slider SSIM Weight
DOVE
Inspector → Configurazione del training → GroupBox → SSIM Weight.
TECNICO
Slider 0.0–1.0 in passi di 0.05, visualizzazione come "0.20". Mescola loss L1 (0.0) e loss SSIM (1.0). L1 stringe la luminosità per pixel, SSIM la somiglianza strutturale (bordi, statistiche locali). Il default 0.2 è il valore del paper 3DGS originale (Kerbl 2023) e reverse-engineered come compromesso robusto in numerose sessioni. Valori più alti (0.5+) preferiscono la conservazione del dettaglio, ma possono ignorare errori locali di luminosità. Valori più bassi (< 0.1) portano alla perdita di dettaglio sui bordi netti. Il calcolo SSIM avviene nello shader con una finestra Gaussian 11×11. Prestazioni: a 0.0 (solo L1) il training è circa 8-12% più veloce, perché il calcolo SSIM viene saltato nello shader.
I22Slider Render Scale
DOVE
Inspector → Configurazione del training → GroupBox → Render Scale.
TECNICO
Slider 0.25–1.0 in passi di 0.25, visualizzazione come "100%". Scala la risoluzione di rendering di training relativa alla dimensione dell'immagine sorgente. La più grande leva sulle prestazioni: 50% riduce il tempo GPU di circa il 75% (perché 4× meno pixel), 25% di circa il 94%. La soglia del gradiente viene scalata automaticamente. Sotto lo slider appare una visualizzazione live della risoluzione in MP (ad es. "2304×1296 (3.0 MP)"). Se il valore attuale si discosta da quello raccomandato, viene mostrato in arancione "— recommended: 50%". La raccomandazione mira a ~3 MP di risoluzione effettiva — l'intervallo elaborato più efficientemente dalle GPU Apple Silicon. Le immagini sorgente 4K ricevono ad es. automaticamente 25% raccomandato, le immagini FullHD 100%. Una modifica attiva inoltre la riallocazione del buffer.
Sezione Enhancements (I26–I29)

La sezione Enhancements raggruppa quattro funzionalità che migliorano la qualità dell'immagine senza modificare il loop di training core. Le prime tre (I26-I28) sono stadi post-training o viewport: la compactification fa pulizia dopo la fine del training, MetalFX e MPS Lanczos sono puri renderer del viewport che non influenzano il training in corso. La Perceptual Loss (I29) è nonostante l'appartenenza alla sezione una componente del training — viene attivata durante il training come termine di loss aggiuntivo, da qui la separazione dai toggle del viewport tramite un divisore.
I26Toggle Post-Training Compactification
DOVE
Inspector → Enhancements → Post-Training Compactification.
TECNICO
Attiva il post-processing V443: dopo la conclusione delle iterazioni di training vengono eliminate le gaussiane con opacità sotto 0.01 (1% di visibilità). Empiricamente ciò riduce la dimensione del file di ~55-58% senza perdita di qualità visibile — perché queste gaussiane non contribuiscono comunque visivamente. La compactification viene eseguita come pass compatto GPU e dura a seconda del gaussian count frazioni di secondo a pochi secondi. Non influenza le prestazioni del training. Quando questo toggle è spento, vengono esportate anche le gaussiane invisibili — rilevante solo se vuoi usare il formato per un ulteriore stadio di training (Continue Training), altrimenti spreco di memoria.
I27Toggle MetalFX Spatial Upscaling
DOVE
Inspector → Enhancements → MetalFX Spatial Upscaling.
TECNICO
Attiva l'upscaler spaziale MetalFX di Apple nel renderer del viewport. Se la risoluzione di training (tramite I22 Render Scale) è inferiore alla dimensione del viewport, MetalFX scala il frame renderizzato basato su ML alla dimensione di visualizzazione. Fornisce i risultati più nitidi di tutte le opzioni di scaling, perché il modello upscaler ML è ottimizzato per bordi netti. La pipeline del renderer viene riconfigurata in diretta al cambio — visibile immediatamente, senza riavvio. Ha la precedenza su MPS Lanczos (I28): se entrambi sono attivi vince MetalFX. Overhead di prestazioni nel viewport circa 1-2ms per frame su GPU M3. Ha effetto solo sul live viewport, non sulle esportazioni renderizzate (video orbit, screenshot) — che vengono renderizzate a piena risoluzione sorgente.
I28Toggle MPS Lanczos Scaling
DOVE
Inspector → Enhancements → MPS Lanczos Scaling.
TECNICO
Attiva i Metal Performance Shaders di Apple con ricampionamento Lanczos come upscaler del viewport. Lanczos è il ricampionamento classico con filtro 8-tap sinc — più nitido del bilineare, algoritmo classico senza ML. La pipeline del renderer viene riconfigurata in diretta al cambio. Viene ignorato se MetalFX (I27) è anch'esso attivo. Overhead minimo (<0.5ms per frame), ma la qualità è inferiore a MetalFX. Applicazione: fallback per scene in cui MetalFX produce artefatti (ad es. strutture lineari forti che l'upscaler ML occasionalmente "appiana"). Ha effetto come I27 solo nel live viewport, non nelle esportazioni.
I29Slider Perceptual Loss
DOVE
Inspector → Enhancements → Perceptual Loss.
TECNICO
Slider 0.0–0.2 in passi di 0.01, visualizzazione a 0.0 come "Off", altrimenti come "0.05" ecc. Attiva un termine di loss aggiuntivo che confronta il Gaussian blur multi-scala del rendering con l'immagine ground truth (3 scale di blur). Cattura differenze strutturali che L1+SSIM da soli non riconoscono. Implementazione V460. Empiricamente un valore di 0.05-0.1 migliora lo score L1 nelle sessioni di qualche punto percentuale, ma costa ~5% di tempo di training (forward pass aggiuntivo attraverso i blur kernel). Sopra 0.15 il training diventa instabile e L1 peggiora di nuovo (il termine di loss domina l'ottimizzazione). Ha effetto durante il training, non nel post-processing — nonostante la posizione nella sezione "Enhancements" non è dunque un puro miglioramento successivo.
Sezione Metriche (I30–I38)

Mentre un training è in esecuzione, la sezione Metriche mostra nove valori live dal loop di training. Prima dell'avvio di un training la sezione è vuota ("Start training to see live metrics"). Tutti i valori vengono aggiornati ogni ~30 iterazioni (frequenza di aggiornamento dello stream). La sezione è in sola lettura — nessun elemento è cliccabile o modificabile. Per un'analisi più approfondita consulta i log JSONL di training sotto ~/Documents/RadianceKit/Logs/ (script python3 scripts/analyze_logs.py best 5).
I30Iteration
DOVE
Inspector → Metriche → Iteration. Sola lettura.
TECNICO
Visualizzazione nel formato "4523 / 40000" — iterazione attuale su iterazioni totali pianificate. Conta sincrono con il loop di training, che spinge i valori ogni ~30 iter. Il secondo numero corrisponde al valore Max Iterations al momento dell'avvio; non cambia più anche se l'utente regola lo stepper dopo — l'esecuzione in corso usa la sua copia snapshot. Se l'app aggiunge iterazioni tramite il menu Training (Continue Training +5K/+10K/+20K), il denominatore aumenta.
I31Loss
DOVE
Inspector → Metriche → Loss. Sola lettura.
TECNICO
Valore float con sei decimali (ad es. "0.024385"). Misura il loss combinato L1+SSIM (mix controllato tramite I21 SSIM Weight) più opzionalmente Perceptual Loss (I29) e altri regolarizzatori. La scala non è assoluta, ma dipende dalla scena — richiede lo stesso dataset per la maggior parte dei confronti. Valori finali tipici con buone configurazioni: - Classic Quality 40K iter: 0.022–0.025 (Horse, Truck, Garden) - MCMC Full 200K iter: 0.024–0.028 - Outdoor drone 30K: 0.030–0.060 (peggiore per motivi di geometria) - Indoor appartamenti: 0.018–0.025
Valori sopra 0.10 dopo 5K iterazioni indicano problemi SfM (pose della fotocamera scadenti) — interrompi e ricalcola l'SfM.
I32Learning Rate
DOVE
Inspector → Metriche → Learning Rate. Sola lettura.
TECNICO
Visualizzazione in notazione scientifica (ad es. "1.60e-04"). Learning rate attuale per i parametri di posizione (3DGS ha sei LR indipendenti per posizione, SH-DC, SH-Rest, opacità, scala, rotazione — qui viene mostrata la posizione LR come dimensione rappresentativa). Valore iniziale predefinito 1.6e-4, che attraverso un decadimento esponenziale scende a ~1.6e-6 alla fine del training. Il decadimento è regolabile tramite il campo LR-schedule nella configurazione del training (campo T nel Cap. 6). Se la LR rimane insolitamente alta (ad es. 1e-3 o più dopo 10K iterazioni), potrebbe indicare una configurazione caricata in modo errato.
I33SH Degree
DOVE
Inspector → Metriche → SH Degree. Sola lettura.
TECNICO
Intero 0-3. Grado di spherical harmonics per la rappresentazione del colore. Parte da 0 (solo la componente DC, ossia colore indipendente dalla direzione per gaussiana — quindi solo una costante RGB) e cresce progressivamente fino a 3 nel corso del training. Lo schedule standard solleva il grado di 1 a 1000/2000/3000 iterazioni. SH-3 corrisponde a 48 coefficienti di colore per gaussiana (3 canali RGB × 16 funzioni base SH). Grado SH più alto = più riflessione dipendente dalla direzione (le superfici lucide appaiono correttamente diverse da angoli di visualizzazione differenti), ma anche più memoria e training più lento.
I34Gaussians
DOVE
Inspector → Metriche → Gaussians. Sola lettura.
TECNICO
Numero attuale di gaussiane nel modello, formattato con separatore di locale (ad es. "524.318"). Crescita: - Classic: parte dagli initpoint SfM (tipico 50K-300K), cresce tramite clone/split fino a poco prima di Densify Until, poi statico fino alla fine del training (modulo pruning) - MCMC: i sample point vengono aggiunti fino al cap MCMC, poi solo rilocazione
Valori finali sani: - Classic Quality: 400K-700K (Horse 524K, Garden 800K) - MCMC Full: esattamente al cap (default 150K, con auto-scale multiplier × SfM count a seconda della scena 500K-1.5M)
Con MCMC il numero scende al < 60% del cap → anomalia (indicatore di collapse, indica regolarizzatori troppo aggressivi).
I35GPU Memory
DOVE
Inspector → Metriche → GPU Memory. Sola lettura.
TECNICO
Stima del consumo di memoria del buffer gaussiano come gaussian count × 616 byte (formattato in stile memoria). 616 byte è la dimensione empirica di una gaussiana completamente equipaggiata (posizione, scala, rotazione, opacità, coefficienti SH grado 3, accumulatore di gradiente). La visualizzazione non cattura l'overhead del renderer (tile buffer, sort buffer, backward buffer) — il consumo reale di memoria GPU è tipicamente 2-3× sopra questo valore. A 500K gaussiane: visualizzato ~290 MB, reale ~700 MB. A 1.5M gaussiane: visualizzato ~880 MB, reale ~2.5 GB. Su M3 Max con 64+ GB di memoria unificata non critico, su M3 Pro con 18 GB già un limite.
I36Speed
DOVE
Inspector → Metriche → Speed. Sola lettura.
TECNICO
Iterazioni al secondo con una cifra decimale ("24.3 it/s"). Calcolato dal trainer come media mobile sulle ultime ~100 iterazioni. Valori tipici: - Preset Quick (1K iter): 80-120 it/s (breve, nessuno steady state) - Classic 20K @ 1.0 Render Scale (scena Truck, M3 Max): 25-35 it/s - Classic 20K @ 0.5 Render Scale: 80-120 it/s - MCMC 200K @ 0.5 Render Scale: 25-50 it/s (più lento per la rilocazione) - Con 1M+ gaussiane e risoluzione piena: < 10 it/s
Speed in calo nel corso del training è normale — più gaussiane = più compute per iterazione. Crolli improvvisi (ad es. da 30 → 5 it/s) indicano thermal throttling della GPU o app concorrenti.
I37Elapsed
DOVE
Inspector → Metriche → Elapsed. Sola lettura.
TECNICO
Tempo già trascorso come "4:23" (m:ss) o "1:23:45" (h:mm:ss). Cambio di formato a partire da 1 ora. Misura solo il puro tempo di training, non le fasi precedenti (calcolo SfM, importazione immagini). Con pausa/resume il cronometro continua — è quindi wall clock, non tempo CPU.
I38ETA
DOVE
Inspector → Metriche → ETA. Sola lettura.
TECNICO
Tempo residuo stimato come "17:42" o "1:12:35". Calcolo: (Max Iterations − iterazione attuale) / iterazioni-al-secondo. Mostra "–" se la velocità è attualmente zero (proprio all'inizio o in pausa). La stima non viene adattata al tipico rallentamento verso la fine del training — soprattutto con MCMC e Classic con grandi valori di Densify Until il training tende a diventare più lento, perché entrano sempre più gaussiane nell'immagine. In realtà rimane tipicamente 10-20% sopra l'ETA iniziale.
Sezione Grafico di perdita (I39–I41)

La sezione Grafico di perdita visualizza l'andamento del training nel tempo. È costituita da due grafici: un grafico Loss-Curve (grande, in alto, blu) e un grafico Gaussian Count (più piccolo, in basso, arancione). Entrambi vengono costruiti in tempo reale durante il training e persistono fino al prossimo avvio del training. Prima del primo training l'area è vuota ("Loss curve will appear during training"). I grafici sono puri disegni di SwiftUI Path (nessun framework Swift Charts), in modo che renderizzino fluidamente anche con 100K+ punti.
I39Current Loss (visualizzazione)
DOVE
Inspector → Grafico di perdita → area etichetta sinistra "Current: 0.0287". Sola lettura.
TECNICO
Valore float dell'ultimo loss sample point, formattato con quattro decimali. Identico a I31 (Loss nella sezione Metriche), solo qui formattato in modo più compatto. La fonte è la Loss History — una lista che riceve una voce ogni ~30 iterazioni. Solo valori finiti vengono inseriti nella lista — NaN/Infinity (molto raro, in caso di un bug di gradient explosion) vengono filtrati.
I40Min Loss (visualizzazione)
DOVE
Inspector → Grafico di perdita → area etichetta destra "Min: 0.0245" (verde). Sola lettura.
TECNICO
Minimo di tutti i valori loss mai visti dell'esecuzione di training attuale. Viene ricalcolato dal vivo dalla Loss History — nessuna persistenza separata. Viene rappresentato in verde, perché "Min" = "Best so far". La linea verde tratteggiata sul bordo inferiore del grafico segna visivamente questa posizione Y. In sessioni di Continue Training il tracking del minimo riparte — la vecchia history nell'UI viene sostituita da quella nuova (non appesa). Se il training attuale procede peggio del precedente, la visualizzazione Min può quindi essere più grande del risultato finale precedente.
I41Grafico Gaussian Count
DOVE
Inspector → Grafico di perdita → secondo grafico sotto (arancione). Sola lettura.
TECNICO
Grafico a linee del numero di gaussiane sulle iterazioni di training. Fonte: la Gaussian Count History (lista di coppie (iter, count), riempita dal trainer ogni ~30 iter). Scala Y dinamica tra minimo e massimo della history. Con strategia Classic la curva appare tipicamente così: in costante aumento fino a Densify Until, poi piatta (con piccole oscillazioni di pruning). Con MCMC: salita ripida fino al cap, poi linea orizzontale (la rilocazione mantiene il numero costante). Se la curva scende nonostante il training attivo, la densification fa pruning troppo aggressivo — indizio di default sbagliati o di un noto bug MCMC collapse (tema dell'hotfix 1.4.4).
Come si legge la curva di perdita?
Il grafico Loss è lo strumento diagnostico più importante nell'Inspector — nessun altro indicatore mostra in modo così diretto se il training procede utilmente o si è bloccato. La forma sana tipica è una rapida discesa nelle prime 1000-3000 iterazioni (da ~0.15 a ~0.05), seguita da una discesa lenta e uniforme fino alla fine del training (a 0.020-0.030). Logaritmicamente la curva appare in tal caso come una diagonale liscia.
Cosa significa un plateau nel Loss? Se la curva rimane piatta per diverse migliaia di iterazioni, ci sono due possibili letture: (a) Il training è "convergente" — il loss non può più scendere significativamente, perché il modello è buono quanto può essere con i dati e le impostazioni date. Ciò è desiderato; è "finito". (b) Il training si "blocca" — il loss potrebbe in realtà ancora scendere, ma l'ottimizzazione ristagna (minimo locale, learning rate troppo piccolo, densification spenta). Distinguere: se il valore loss si trova in un intervallo tipicamente buono (0.020-0.030 con indoor/oggetto, 0.040-0.060 con outdoor) e la curva è piatta da 5K iterazioni, è convergente. Se il valore è nettamente più alto rispetto a scene paragonabili (ad es. 0.08), si blocca.
Attenzione: plateau gaussiane ≠ plateau loss. Un plateau nel numero di gaussiane non significa "il training è finito". Significa solo che la densification ha smesso di aggiungere nuovi punti — o perché è stato raggiunto (Classic) o perché il cap MCMC è pieno. Il training prosegue dopo e raffina solo i punti esistenti. Il vero segnale di "finito" lo leggi nella curva Loss e nella visualizzazione di iterazione (I30), non qui.
Regola pratica per interrompere: Se la curva Loss dopo 5000+ iterazioni è sopra 0.08 e scende a malapena, è molto probabile che la ricostruzione SfM sia storta. Interrompi il training, consulta il Capitolo 9 se il backend SfM scelto si adatta alla scena, eventualmente passa a COLMAP/Native, poi riavvia. Meglio investire 10 minuti in un SfM migliore che 2 ore di training con allineamento delle fotocamere scadente.
Quando ricorrere all'Inspector?
Riferimento rapido: quale sezione + quali controlli per quale caso d'uso tipico?
| Compito comune | Sezione | ID controllo |
|---|---|---|
| Caricare setup preconfezionato | Preset | I7 (cliccare riga) |
| Salvare setup proprio | Preset | I1 → I2 → I4 |
| Condividere setup con colleghi | Preset | I5 (Export) risp. I6 (Import) |
| Cambiare backend SfM (ad es. perché Apple PG troppo instabile) | Configurazione del training | I12 (vedi Cap. 9) |
| Elaborare frame video senza lunghezza focale EXIF | Configurazione del training | I13 (FOV Override) |
| Prestazioni COLMAP: GLOMAP invece di classico | Configurazione del training | I14 |
| Passare da Classic a MCMC | Configurazione del training | I15 |
| Far girare il training più a lungo | Configurazione del training | I18 (Max Iter) + I20 (Densify Until) — accoppiati tramite I19 |
| Dimezzare il tempo GPU | Configurazione del training | I22 (Render Scale al 50%) |
| +6% qualità training (MCMC) | Configurazione del training | I16 (MCMC Quality) |
| Scena outdoor con molti punti SfM | Configurazione del training | I17 (Auto-scale by scene) |
| Impostare/cambiare percorso COLMAP | Configurazione del training | I23 / I24 / I25 |
| Rimpicciolire i file di esportazione | Enhancements | I26 (lasciare sempre acceso) |
| Viewport più nitido senza più tempo di training | Enhancements | I27 (MetalFX) |
| MetalFX leviga troppo → alternativa | Enhancements | I28 (MPS Lanczos) |
| Ultimo briciolo di dettaglio con strutture fini | Enhancements | I29 (Perceptual Loss 0.05-0.1) |
| Monitorare il training | Metriche | I30 (progresso), I36 (tempo), I38 (tempo residuo) |
| Valutare presto la qualità | Metriche | I31 (Loss < 0.05 dopo 5K = buono) |
| Sospetto di problema SfM | Metriche + grafico Loss | I31 + I39 (Loss > 0.08 dopo 5K → SfM nuovo) |
| Distinguere convergence vs stuck | Grafico di perdita | I39 + I40 (leggere il plateau loss) |
| Riconoscere problema di densification | Grafico di perdita | I41 (curva gaussiane scende → bug) |