Capitolo 3 — Impostazioni

DOVE

Settings → General → Interface → picker Default Mode. Bound:. Default: .simple.

TECNICO

Controlla in quale delle due modalità UI l'app si apre dopo il prossimo avvio. "Simple Mode" è il flusso di lavoro guidato a wizard in 4 passaggi (Importazione → Elaborazione → Anteprima → Esportazione, documentato nel Capitolo 10 sotto Z1–Z4), "Expert Mode" il layout classico a tre pannelli con Navigator, Viewport 3D ed Expert Inspector del Capitolo 2. Il valore viene memorizzato tra i riavvii. Effetto identico al menu Mode → Simple Mode (⌘1) / Mode → Expert Mode (⌘2), tranne che il menu cambia la sessione in corso mentre questo picker imposta il default per le sessioni future. Entrambe le modalità accedono allo stesso stato del progetto — progetti, fotocamere e configurazione del training vengono preservati al cambio di modalità. I pulsanti della toolbar specifici della modalità vengono rigenerati immediatamente.

DOVE

Settings → General → Interface → picker Language. Bound:. Default: .system (segue la lingua di macOS).

TECNICO

Seleziona la lingua di visualizzazione dell'intera UI dell'app, indipendentemente dalla lingua di sistema macOS. RadianceKit è localizzato in 17 lingue (de, en, pl, en-AU, ar-SA, più altre 12). Con "System" l'app segue la lingua macOS. Con una scelta esplicita l'impostazione della lingua viene memorizzata tra i riavvii; l'effetto completo richiede di solito un riavvio dell'app, perché i bundle di localizzazione vengono caricati solo all'avvio. Le 298 chiavi di localizzazione documentate nel progetto sono tutte considerate, comprese le voci nelle sub-view e nei tooltip della guida.

DOVE

Settings → General → Viewport → picker Background. Bound:. Default: .darkGray (RGB 0.1, 0.1, 0.1).

TECNICO

Imposta il colore di sfondo predefinito per il viewport 3D. Tre opzioni: "Dark Gray" (RGB 0.1, 0.1, 0.1 — default), "Black" (0, 0, 0) e "White" (1, 1, 1). L'impostazione persiste il default per nuovi progetti e sessioni tra i riavvii e contemporaneamente aggiorna immediatamente il renderer Metal in esecuzione. Opzioni identiche si trovano nel menu Viewport → Background (M21, M22, M23), ma il picker Settings imposta il default mentre il menu cambia la visualizzazione in corso. Importante per screenshot e video demo: gli sfondi bianchi evidenziano più fortemente i floater verdi/blu, gli sfondi scuri sono migliori per cattura di rendering pulite.

DOVE

Settings → General → Viewport → Toggle "Auto-Rotate After Training". Bound:. Default: false.

TECNICO

Avvia una rotazione continua a piatto rotante della fotocamera del viewport attorno al centroide della scena immediatamente dopo la fine del training (velocità di rotazione predefinita ~0.3 rad/s). Praticamente utile per sessioni demo, confronti A/B e per valutare immediatamente da una vista a 360° se si sono formati "floater" ai bordi della scena. L'effetto è visivamente identico al menu Viewport → Toggle Auto-Rotation (M16, ⌘⌥T), tranne che questo toggle attiva il comportamento automaticamente dopo la fine del training invece che manualmente. Può essere interrotto in qualsiasi momento tramite il menu o cliccando nel viewport (cosa che mette in pausa la rotazione). Non ha alcuna influenza sulle prestazioni del training — la rotazione parte solo quando il training è terminato.

DOVE

Settings → General → Training → picker Live Preview. Bound: AppState.trainingConfig.livePreviewInterval. Default: 0 (Off).

TECNICO

Determina l'intervallo di iterazione con cui lo snapshot del training in corso viene renderizzato nel viewport 3D. Quattro valori discreti: 0 ("Off"), 50, 250, 1000 iterazioni. Con Live Preview attivo, il trainer copia il buffer Gaussian dalla GPU in un buffer di rendering separato e attiva un redraw del viewport. Con "Off", il viewport viene aggiornato solo dopo il completamento del training. Costo prestazionale: ogni 50 iterazioni ~5–10% più lento su M3 Ultra, ogni 250 iterazioni ~1–2% più lento, ogni 1000 iterazioni non misurabile. Overhead di memoria costante ~2 GB per il buffer dello snapshot, indipendentemente dall'intervallo. Il valore serve come default per i nuovi training; dopo l'inizio del training, il Training Inspector mostra il valore live effettivo del training in corso. Con intervallo 50 l'impressione visiva è una "crescita" fluida della nuvola di punti, con 1000 risulta a scatti.

DOVE

Settings → General → Training → picker Throttle. Bound: AppState.trainingConfig.throttleDelayMs. Default: 0 (Off).

TECNICO

Inserisce un ritardo artificiale in millisecondi tra le iterazioni del training. Quattro valori discreti: 0 ("Off"), 2 ("Light"), 5 ("Moderate"), 10 ("Eco"). Scopo: durante training più lunghi (diverse ore) la GPU verrebbe altrimenti utilizzata al 100%, il che porta a una UI di sistema notevolmente più lenta (cursore del mouse che salta, altre app diventano lente). Il ritardo throttle dà alla GPU pause durante le quali possono essere eseguiti altri compiti. Il costo prestazionale è considerevole: con 5 ms di throttle un tipico training 40K dura circa 50–80% più a lungo che senza throttle. In modalità prestazione "Eco" (10 ms) il ritardo per iterazione è più lungo dell'iterazione stessa — fattore 2–3× più lento. Con throttle attivo appare sotto il picker una nota: "Throttle is on. Training will be slower than usual." L'app stessa non reagisce in modo notevolmente migliore — solo le altre app ne traggono beneficio.

DOVE

Settings → General → Experimental — Outdoor Floater Reduction → Toggle "Sky Masking". Bound: AppState.trainingConfig.skyMaskingEnabled. Default: false.

TECNICO

Attiva la segmentazione pre-training dei pixel del cielo basata su Apple Vision. Prima dell'inizio del training, per ogni fotocamera di input viene estratta la regione del cielo tramite la maschera di foreground di Apple Vision (Sky = Background) e assegnata come maschera per-pixel alla rispettiva fotocamera. Durante il training, il contributo del loss per pixel viene moltiplicato per il complemento della maschera del cielo — i pixel del cielo contribuiscono 0 al gradiente, così che le gaussiane che si proiettano nel cielo non ricevono segnali di ottimizzazione e quindi non diventano "più dense" o "più luminose". Riduce significativamente i floater (grumi scuri nel cielo) in scene outdoor/drone. Costa ~3% di regressione L1 nel training classico 40K (vedi memory/dev_outdoor-floater-reduction.md). Utile solo per scene outdoor con cielo chiaramente riconoscibile; per scene interne o sfondi bianchi la segmentazione del cielo identifica aree sbagliate e blocca segnali di loss validi. A differenza degli altri toggle sperimentali, il valore non viene memorizzato tra i riavvii dell'app — al prossimo avvio dell'app è di nuovo spento.

DOVE

Settings → General → Experimental — Outdoor Floater Reduction → Toggle "Mid-Training Floater Cleanup". Bound:. Default: false.

TECNICO

Abilita due passaggi aggiuntivi di density control durante il training Classic 40K (preset "P4 Quality"): all'iterazione 20,000 e all'iterazione 30,000. Entrambi i passaggi scansionano tutte le gaussiane secondo tre criteri: (a) opacità molto bassa (default 0.005), (b) dimensione minuscola in screen-space, (c) nessun contributo al loss nelle ultime 1000 iterazioni. Le gaussiane che soddisfano tutte e tre le condizioni vengono purgate. Effetto: ~5–15% di gaussiane in meno alla fine del training, visibilmente meno grumi scuri nel cielo per scene drone/outdoor. Costa ~1–3% di regressione L1 su scene indoor close-up, quindi non abilitato come default. Il valore viene memorizzato tra i riavvii (a differenza di S7). Le due iterazioni di cleanup (20K, 30K) sono hard-coded e attualmente non possono essere modificate tramite UI; per training più brevi (ad es. P2 Preview 5K) il toggle non ha effetto, perché non raggiunge mai i marker di iterazione. Dettagli: memory/dev_outdoor-floater-reduction.md.

DOVE

Settings → General → Experimental — Outdoor Floater Reduction → Toggle "Reduce Elongated Gaussians". Bound:. Default: false.

TECNICO

Attiva un'ulteriore regolarizzazione dell'anisotropia nel termine di loss. Durante l'ottimizzazione, per ogni gaussiana viene calcolata l'anisotropia come rapporto tra l'asse di scala massimo e minimo. Se il rapporto supera una soglia (, default 10.0), viene aggiunto al loss un termine di penalità, scalato proporzionalmente all'eccesso. Effetto: le gaussiane a forma di ago, tipiche di artefatti cross-hatch e a strisce in erba e fogliame denso, durante il training vengono forzate a forme più rotonde o purgate. In cambio ~6 % di regressione L1 su scene indoor standard, nessun effetto su catture rigorose di oggetti. Il sweet spot è per riprese in volo di drone sopra la vegetazione. Scrive su, persiste tramite. Implementazione in optimizer.metal come penalità aggiuntiva nel calcolo del gradiente. Vedi la nota nella memoria del progetto: V549d era la versione distribuita; una successiva V549f con regolarizzazione di scala più aggressiva è stata revertita per regressione catastrofica. Dettagli: memory/dev_outdoor-floater-reduction.md e memory/dev_v549f-needle-reduction.md.

DOVE

Settings → General → Experimental — Outdoor Floater Reduction → Toggle "Reconstruct Sky Dome". Bound:. Default: false.

TECNICO

Attiva la proiezione pre-training del Sky Dome (V549e MVP). Dopo l'SfM e prima dell'inizio del training, per ogni fotocamera di input viene estratta dall'immagine la maschera del cielo Apple Vision condivisa con S7, i pixel del cielo vengono de-proiettati utilizzando gli intrinseci della fotocamera su una superficie sferica virtuale (raggio predefinito 8× il raggio della scena). Su questa sfera vengono inizializzate ~5000 nuove gaussiane con valori medi di colore dai pixel del cielo proiettati, scala molto grande (1.0 in unità di scena) e opacità iniziale 0.95. Queste 5000 gaussiane non sono una maschera del cielo in senso classico — vengono addestrate come tutte le altre, ma l'opacità iniziale alta le mantiene in un guscio sottile. Risultato: per viste novel a 360° in scene outdoor/drone, appaiono il colore reale del cielo e strutture nuvolose invece di grumi di coriandoli scuri. Il valore viene memorizzato tra i riavvii. Utile solo per scene outdoor con almeno copertura della fotocamera a 360°; per catture oggetti puri senza vista del cielo non ha alcun effetto. Stato: sperimentale, validazione A/B più ampia su più set outdoor ancora in sospeso.

DOVE

Settings → AI Helpers → prima sezione → Toggle "AI Helpers enabled". Bound:. Default: true.

TECNICO

Master switch su tutte le funzionalità AI Helpers nella pipeline. Quando spento, la pipeline di importazione e SfM salta completamente tutti gli stadi di preprocessing basati su ML — nessuna chiamata Apple Vision, nessun caricamento di modello CoreML, nessun risveglio della NPU. Quando acceso, vengono consultati i singoli sub-toggle (S12–S14). Il valore viene memorizzato tra i riavvii. Si applica ai seguenti stadi: (a) pre-check di qualità dei frame prima di SfM (S12), (b) rilevamento di loop closure (S13), (c) auto sky masking come valore predefinito per nuovi training (S14). Importante: quando spento, i tre sub-toggle sono disabilitati e visivamente in grigio. La nota a piè di pagina sottolinea che tutti gli AI Helpers vengono eseguiti rigorosamente on-device — nessun upload di immagini, nessuna elaborazione cloud. La garanzia di privacy deriva dall'uso esclusivo del framework Apple Vision (localmente sulla Neural Engine) e dai modelli CoreML che vengono distribuiti direttamente nel bundle dell'app.

DOVE

Settings → AI Helpers → sezione Available → Toggle "Frame quality check". Bound:. Default: true.

TECNICO

Attiva lo screener di qualità dei frame (Fase 3.11), che analizza ogni frame importato prima della chiamata SfM. Passi della pipeline per frame: (a) filtro di varianza laplaciana da Apple Vision (rilevamento sfocatura — soglia ~150), (b) controllo di sovra/sotto-esposizione basato su istogramma (soglia: >5% pixel a 0 o 255), (c) rilevamento frame vuoti (deviazione standard < 5 su tutti i pixel). I frame che superano tutti e tre i controlli passano direttamente. I frame che falliscono almeno un controllo attivano un dialogo modale di conferma che elenca ogni frame problematico con miniatura e motivo e chiede se debba essere rimosso. Importante: nessuna eliminazione automatica — il dialogo è sempre richiesto, l'utente mantiene la decisione finale. Prestazioni: ~50 ms per frame su M3 Ultra, eseguito in parallelo. Quando spento, tutti i frame vengono inoltrati all'SfM senza controllo. Con il master (S11) disabilitato, questo toggle è visivamente in grigio e senza effetto. Stato distribuito secondo la memoria: SHIPPED 2026-05-23.

DOVE

Settings → AI Helpers → sezione Available → Toggle "Loop closure detection". Bound:. Default: true.

TECNICO

Attiva il rilevamento di loop closure basato sul feature print di Apple Vision. Per ogni frame importato viene calcolato un vettore di feature di ~768 dimensioni, che rappresenta un embedding neurale del contenuto dell'immagine. Tutti i feature print vengono poi confrontati a coppie tramite similarità coseno. Le coppie con similarità > 0.85 e distanza nell'indice dei frame > 50 (ossia frame non adiacenti) vengono identificate come "candidate di loop closure" e scritte in un file sidecar JSONL nella cartella del progetto. Solo informativo — la sequenza di immagini importate non viene modificata. Scopo: dà al risolutore SfM (in particolare COLMAP) un suggerimento che questi frame si raggruppano insieme nello spazio 3D. Per l'SfM nativo le informazioni sidecar sono attualmente solo documentative; COLMAP utilizza i suggerimenti internamente tramite file di match personalizzato (integrazione manuale possibile, non collegata automaticamente). Prestazioni: ~200 ms per frame su M3 Ultra, eseguito in parallelo. Quando spento, non vengono generati feature print. Con il master (S11) disabilitato, visivamente in grigio.

DOVE

Settings → AI Helpers → sezione Available → Toggle "Auto sky masking". Bound: UserDefaults.standard.bool(forKey: "aiHelpersSkyMaskingDefault") (tramite custom binding). Default: false.

TECNICO

Imposta il valore predefinito per l'impostazione Sky Masking di S7 in nuove configurazioni di training. A differenza di S11–S13, l'impostazione Sky Masking effettiva vive per sessione di training e non viene memorizzata tra i riavvii dell'app (vedi S7). Affinché l'UI degli AI Helpers possa comunque offrire un default persistente per "nuovi training", esiste questo valore ombra: viene memorizzato tra i riavvii e viene preso come default iniziale per Sky Masking quando si imposta un nuovo training (ad es. nuova importazione di progetto). Con il master (S11) disabilitato, visivamente in grigio.