Capitolo 10 — Modalità principiante

DOVE

Nella barra al bordo superiore della finestra, a sinistra accanto al selettore di modalità. Visibile solo in modalità Principiante.

TECNICO

Mostra le sei fasi della pipeline come catena di pulsanti in sequenza, ciascuno con simbolo e nome, separati da una freccia: Import → Frame Quality → Cameras → Training → Preview → Export. La fase attuale è colorata a pieno, le fasi già completate sono semitrasparenti, le fasi non ancora raggiunte sono grigie. Le fasi già completate sono cliccabili e permettono di tornare indietro; la fase attuale e tutte quelle non ancora raggiunte sono disattivate, così come l'intera catena finché è in corso un'elaborazione. Una barra di avanzamento percentuale continua sull'intera pipeline non esiste più — il progresso della fase in corso è mostrato dal grande cerchio nella schermata di elaborazione (C-19).

DOVE

Lato sinistro del passo Import, grande rettangolo tratteggiato con simbolo. Viene mostrato in modalità Principiante con l'etichetta „Drop photos or a video here".

TECNICO

Area di rilascio che fa saltellare brevemente il simbolo e colora lo sfondo appena elementi trascinati passano sopra il campo. Accetta JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, bundle .radiancescene e directory. Instradamento del rilascio in base al tipo: le immagini vengono raccolte e passate ordinate, i video attivano il percorso di campionamento dei fotogrammi, i file splat aprono direttamente l'anteprima, i bundle scena vengono letti. Le directory vengono enumerate e tutte le immagini contenute importate. I bookmark security-scoped per l'accesso conforme alla sandbox vengono acquisiti e rilasciati correttamente. Le estensioni non supportate vengono mostrate come banner di avviso per 5 secondi.

DOVE

All'interno della zona di rilascio, pulsante prominente.

TECNICO

Pulsante che apre la finestra di dialogo file di macOS con selezione multipla e i tipi di file JPG, PNG, TIFF, MP4, MOV, cartelle e il formato scena proprietario dell'app. Gli URL risultanti sono security-scoped e vengono inoltrati attraverso gli stessi percorsi di import del drag-and-drop. Se l'utente seleziona una cartella, viene enumerata ricorsivamente alla ricerca di immagini.

DOVE

All'interno della zona di rilascio, visibile solo se il bundle dell'app contiene la scena di esempio e non sono ancora state importate immagini/splat.

TECNICO

Compare solo se (a) è presente un file sample-scene.splat, .spz o .ply nel bundle dell'app E (b) non sono ancora state importate immagini/video e non esiste ancora una nuvola di punti. Al clic carica la nuvola di punti già pronta (preferendo il formato più piccolo — .splat ~3 MB, .spz ~1.4 MB, fallback .ply) e dopo 400 ms imposta valori hardcoded della fotocamera provenienti dai metadati originali della scena "flowers" per una prospettiva iniziale esteticamente sensata.

DOVE

All'interno della zona di rilascio, accanto a „Try Sample Scene"; stesse condizioni di visibilità.

TECNICO

Scarica da Internet un set di esempio fornito da RadianceKit: circa 427 MB di 960 fotogrammi a piena risoluzione, che vengono poi decompressi e importati direttamente nell'app. Finché è in corso un'altra elaborazione, il pulsante è disattivato e il download non parte. L'avanzamento del caricamento non viene indicato nell'interfaccia come percentuale; che il download sia terminato lo riconosci dal fatto che l'elenco immagini a destra si riempie con i 960 fotogrammi.

DOVE

Barra degli strumenti flottante inferiore dell'overlay Import, a sinistra accanto al pulsante di avvio.

TECNICO

Selettore a menu con etichetta „Quality", che raggruppa i preset inclusi per categoria in quattro sezioni: „Classic", „MCMC (fewer Gaussians, slower)", „Hybrid (sharp detail, compact)" e „Capture — curated real-world (Drone / 360° / Photo)". Una quinta sezione „Custom" si aggiunge non appena la versione completa è sbloccata ed è stato salvato almeno un preset personalizzato. Stato bloccato: tutti i preset tranne Quick e Preview ricevono un suffisso „🔒" al nome, se l'utente non possiede la versione completa; alla selezione il selettore torna a Preview e apre automaticamente la finestra di acquisto. Alla scelta viene applicato il preset, che sostituisce l'intera configurazione di training.

DOVE

Barra degli strumenti flottante inferiore dell'overlay Import, a destra accanto al selettore preset.

TECNICO

Pulsante che rimane grigio finché non sono state importate né immagini né un video. Al clic avvia la pipeline e commuta la macchina a stadi nella sequenza Frame-Quality → SfM → Training. Il pulsante stesso non ha ulteriori stati; un'elaborazione in corso appare invece come una schermata di elaborazione separata.

DOVE

Elenco immagini a destra, visibile solo se è stato importato un video (invece di immagini).

TECNICO

Cursore da 0.5 fps a 30 fps in passi di 0.5. Al cambiamento viene aggiornata la densità dei fotogrammi e viene inoltre calcolato il numero di fotogrammi target (almeno 10) a partire da densità e durata del video. Il cursore si trova fuori dall'elenco immagini, perché gli elementi dell'elenco bloccherebbero gli eventi del mouse dei cursori. Sotto il cursore sono indicati i fotogrammi target calcolati („247 frames") e la durata del video („1m23s video"). Il tooltip avverte: „Doubling the density doubles the number of frames and increases SfM time by ~100%."

DOVE

Elenco immagini a destra, in basso a destra; visibile solo se sono state importate immagini.

TECNICO

Pulsante rosso. Il clic apre una finestra di dialogo di conferma con titolo „Clear all imported files?" e messaggio „N images will be removed.". La conferma svuota tutte le immagini/video importati, le directory di staging, la nuvola di punti, lo stato di training, il risultato SfM e tutte le cache; la fase torna all'Import. Con Annulla tutto rimane invariato. La finestra di dialogo è configurata con percorso predefinito non distruttivo (il pulsante distruttivo è evidenziato in rosso).

DOVE

Elenco immagini a destra, ogni voce.

TECNICO

Elenco delle immagini importate con swipe-to-delete. Per ogni immagine una riga con icona, nome file, risoluzione („1920 × 1080") e dimensione del file (formattata KB/MB). La risoluzione proviene da una cache di metadati, riempita in modo asincrono dagli header delle immagini, per non bloccare l'interfaccia. La rimozione avviene tramite il tipico swipe-delete di macOS (swipe verso sinistra su una riga con il trackpad); l'elenco non conosce la selezione di righe, quindi qui non esiste un'eliminazione da tastiera. Nota: il percorso avanzato di eliminazione immagini con pulsante meno esplicito, Backspace e Cmd-Z per annullare è stato aggiunto solo in modalità Esperto nel Project Navigator — in modalità Principiante rimane lo swipe-delete.

DOVE

Sotto l'elenco immagini, sopra il pulsante Clear All.

TECNICO

Tre soglie consecutive basate sul numero di immagini importate (attive solo se sono presenti immagini e nessun video): - < 3 immagini: banner rosso (ottagono rosso), testo „At least 3 images are required. Camera alignment cannot be computed from fewer images." - 3–9 immagini: banner rosso, testo „With fewer than 10 images, SfM often fails and the trained scene tends to overfit […]. 15–20 images minimum recommended; 30+ for object captures." - 10–19 immagini: banner arancione (triangolo di avviso), testo „Workable, but quality usually improves with 20+ images and good coverage around the scene."

Da 20 immagini in su il banner scompare. Le soglie sono hardcoded e si basano su oltre 560 esperimenti di training empirici.

DOVE

Al rilascio di una cartella — nessun pulsante visibile, ma logica di rilevamento.

TECNICO

Al rilascio di una directory, viene verificato se al suo interno è presente uno dei tre layout canonici di workspace: sparse/0/cameras.bin, sparse/cameras.bin oppure direttamente cameras.bin nella radice. Se ciò è vero, l'enumerazione standard delle immagini viene interrotta e viene invece aperto un alert modale che chiede all'utente se usare la ricostruzione esistente oppure far ripassare le immagini attraverso Apple Photogrammetry. Stesso percorso anche per workspace in formato testo (cameras.txt) ed export ETH3D. Vedi capitolo 9 Backend Q6 per i dettagli. Funziona in modalità Principiante allo stesso modo che in modalità Esperto.

DOVE

Sfondo a tutto schermo dietro al cerchio di avanzamento, nascosto in caso di annullamento o errore.

TECNICO

Animazione decorativa che, a seconda dell'avanzamento della pipeline (0…1), renderizza un numero crescente di piccole particelle di splat animate. La fonte è un valore di avanzamento calcolato che mappa le fasi SfM su 0–0.2 e il training su 0.2–1.0 (la qualità del frame su 0–0.05). Così gli splat si "costruiscono" visibilmente mentre il training procede. Puramente decorativa — la visualizzazione non mostra risultati intermedi reali del training in corso (questo sarebbe l'anteprima live in modalità Esperto). In caso di annullamento o errore viene nascosta e resta visibile solo il cerchio di stato.

DOVE

Al centro della schermata di elaborazione, 220 × 220 pixel.

TECNICO

Due anelli renderizzati uno sopra l'altro: all'esterno un anello di traccia attenuato, all'interno un anello di avanzamento pieno con tratto in colore accento o rosso (rosso in caso di errore). L'anello segue direttamente l'avanzamento reale dello stadio in corso (con una breve animazione morbida di dissolvenza), in modo che la visualizzazione corrisponda alla riga di avanzamento della modalità Esperto. All'interno del cerchio un'icona di stadio (cervello per il training, fotocamera per SfM, pellicola per l'estrazione dei frame video, scintille per il controllo della qualità dei frame, globo per lo srotolamento di materiale a 360°), il titolo dello stadio e il numero di avanzamento. Questo numero durante il training è il contatore delle iterazioni ("12.500/20.000"), in tutte le altre fasi una percentuale. L'icona pulsa dolcemente finché l'elaborazione è attiva. In caso di errore il titolo passa allo stadio fallito ("Structure from Motion Failed", "Training Failed"), l'anello e il numero diventano rossi. Dopo un annullamento il cerchio mostra invece una croce arancione con "Cancelled!".

DOVE

In alto a sinistra sulla schermata di elaborazione, 32 × 32 pixel.

TECNICO

Pulsante semplice con sfondo materiale. Attiva o disattiva il pannello informativo. L'icona cambia tra cerchio informativo in contorno e cerchio informativo pieno quando attivo. Animazione di dissolvenza morbida. Nel tooltip "Show detailed processing metrics".

DOVE

In basso a sinistra sulla schermata di elaborazione, visibile solo quando i dettagli di elaborazione sono mostrati.

TECNICO

Pannello a due colonne con sfondo materiale ultra-sottile. Colonna sinistra: righe informative specifiche dello stadio — per SfM testo di stato e percentuale; per il training iterazione, loss combinato, loss L1, loss D-SSIM, conteggio Gaussians (colorato in arancione), velocità (it/s), tempo trascorso, ETA calcolata, grado SH e learning rate. Colonna destra: testo di stato, stringa informativa temporale, grafico inline del loss (vedi C-28) e un suggerimento di scopribilità (vedi C-32). Tutti i valori vengono letti dallo stato del training, che viene aggiornato a ogni tick di training.

DOVE

Barra di navigazione inferiore, visibile solo durante lo stadio di training (NON durante SfM) e finché l'elaborazione è in corso.

TECNICO

Pulsante con bordo. Chiama Pausa o Riprendi a seconda dello stato. L'etichetta cambia tra "Pause" (con icona pausa) e "Resume" (icona play). Durante il passaggio SfM il pulsante non viene mostrato, perché Apple Photogrammetry non conosce una semantica di pausa. Lo stato di pausa conserva completamente iterazione, stato dei Gaussians e momentum dell'optimizer — Riprendi continua esattamente da dove era stato interrotto.

DOVE

Barra di navigazione inferiore, visibile mentre l'elaborazione è in corso (SfM o training).

TECNICO

Pulsante con bordo rosso. Apre una finestra di conferma con titolo "Stop and discard progress?", pulsanti "Discard Progress" (distruttivo) e "Keep Running" (annulla). Alla conferma viene impostato il flag di annullamento, il task di training viene terminato, il sottoprocesso SfM viene terminato se necessario e una riga di riepilogo con lo stato di annullamento viene scritta nel log JSONL. A differenza della pausa, i buffer e lo stato del training vengono scartati.

DOVE

Barra di navigazione inferiore, visibile quando la pipeline è fallita (lo stato SfM inizia con "SfM failed" oppure il training è in stato di errore).

TECNICO

Pulsante accento. Riavvia l'intera pipeline. Prima dell'avvio viene verificato se sono ancora presenti immagini/video importati. I log di errore precedenti restano nella directory JSONL; un nuovo run scrive un nuovo file di log con timestamp attuale.

DOVE

Nel pannello info, colonna destra, visibile solo durante il training con una cronologia non vuota.

TECNICO

Area di disegno compatta (40 pixel di altezza), disegna la cronologia del loss come linea di 1 pixel in colore accento. I dati vengono filtrati per valori finiti (protezione NaN per training instabili). Min/max vengono calcolati sull'intera cronologia — il grafico quindi si adatta automaticamente all'intervallo di valori. L'ultimo valore di loss compare in alto a destra sopra il grafico. La cronologia stessa viene costruita nello stato dell'app a ogni tick di training (tipicamente ogni 100 iterazioni).

DOVE

Nel pannello info, colonna destra in basso, visibile solo durante il training E in modalità Principiante.

TECNICO

Piccola riga con icona a forma di occhio e testo didascalia "Switch to Expert Mode (⌘2) for live splat preview", in tonalità discreta e carattere da 10 punti. Nessun elemento interattivo, solo un suggerimento. Non reagisce al clic — l'utente deve effettivamente premere Cmd+2 o cliccare sul menu Modalità → Modalità Esperto.

DOVE

Sfondo a schermo intero del passaggio di anteprima.

TECNICO

Viewport 3D basato su Metal che renderizza la nuvola di punti finita. Il renderer è il rasterizzatore ForwardPass PROPRIO di RadianceKit — lo stesso che renderizza già gli splat durante il training — quindi un vero WYSIWYG (ciò che viene addestrato viene mostrato ed esportato esattamente così). Pipeline di rendering basata su tile con Order-Independent Transparency. Se il renderer non può essere inizializzato (ad es. perché Metal non è disponibile sul sistema), viene invece mostrato uno sfondo nero con il testo „Metal not available". La vista ignora la Safe-Area, quindi il modello arriva fino al bordo della finestra.

DOVE

Sopra il viewport, fluttuante: due pulsanti icona in alto a sinistra, sotto di essi in basso a sinistra il pannello informazioni.

TECNICO

L'overlay è composto esattamente da due pulsanti: „Scene Info" mostra e nasconde il pannello informazioni in basso a sinistra, il secondo commuta la modalità telecamera tra „Orbit" (orbita attorno a un punto target) e „Fly-Through" (volo libero). Il pannello informazioni mostra frame rate, numero di Gaussians, modalità telecamera, angolo di visuale, risoluzione di rendering e campionamento; durante un training in corso si aggiunge una riga di stato del training, dopo il suo completamento una riga di completamento. Caricamenti di scena falliti o in corso vengono mostrati come riga di stato a sé stante, indipendentemente dallo switch informazioni. Rotazione automatica, ripristino telecamera, colore di sfondo e screenshot non sono pulsanti overlay, bensì voci del menu „Viewport".

DOVE

Barra di navigazione inferiore in Z3.

TECNICO

Pulsante in accento con etichetta „Export" e icona di condivisione. Il clic attiva il passaggio a Z4. Prima di ciò, la vista superiore verifica se la versione completa è sbloccata — se non lo è, invece della fase di esportazione viene mostrata la vista di blocco (vedi U-06).

DOVE

Pagina principale sinistra del passaggio di esportazione.

TECNICO

Griglia di schede con due colonne flessibili e 12 punti di spaziatura. Itera sui formati offerti nella modalità per principianti — un sottoinsieme filtrato dell'elenco completo dei formati, che contiene solo i 6 formati più importanti: PLY, SPZ, glTF, .splat, Orbit-Video, Web-Viewer. Gli altri formati vengono offerti solo nella modalità Expert.

DOVE

Ogni scheda nella griglia.

TECNICO

Pulsante semplice con layout a scheda: icona (ad es. zip-documento per PLY, scatola archivio per SPZ, icona video per Orbit-Video) in alto, nome del formato come titolo, didascalia descrittiva (troncata a 2 righe), sotto la dimensione stimata del file (calcolata in tempo reale a partire da formato, numero di Gaussiane e grado SH, formattata in KB/MB). Al clic viene selezionato il formato. La scheda selezionata riceve uno sfondo accentato, un bordo accentato e un'icona a spunta in alto a destra. Il tooltip è la descrizione del formato.

DOVE

Sotto la griglia dei formati, visibile solo quando è selezionato un formato video (Orbit-Video o Social-Video).

TECNICO

Cursore da 3 a 30 secondi con incrementi di 1 secondo, collegato alla durata del video nello stato dell'app. Larghezza massima 300 pixel. Viene mostrato solo se è selezionato un formato video. Con formati non video, il cursore viene rimosso completamente dalla vista — nessuno spazio vuoto.

DOVE

Sotto la griglia dei formati (e sotto lo slider di durata, se è selezionato un video).

TECNICO

Grande pulsante d'accento. Etichetta: "Export {nome formato}", icona di condivisione. Al clic si apre la finestra di dialogo di salvataggio di macOS con l'estensione file corrispondente al formato. Il nome file suggerito proviene dal nome della scena attuale; se non ne è impostato uno (ad es. perché la scena non è mai stata salvata), viene chiamato "scene". Alla conferma l'esportazione viene scritta nel percorso scelto. Disabilitato se non è presente alcun risultato di addestramento o se un'esportazione è già in corso. Sotto il pulsante è indicato l'indice del risultato ("2.991 Gaussians • SH degree 3").

DOVE

Sotto il pulsante di esportazione, visibile solo mentre un'esportazione è in corso.

TECNICO

Indicatore di avanzamento con larghezza massima di 300 pixel, sotto la didascalia "Exporting… N %". Il valore va da 0 a 1 e viene aggiornato durante la scrittura — per PLY in blocchi di 10 000 Gaussiane, per SPZ una sola volta dopo la quantizzazione, per Orbit-Video a intervalli di frame.

DOVE

Sotto la barra di avanzamento, visibile solo se nell'ultima esportazione si è verificato un errore.

TECNICO

Riga rossa con triangolo di avviso e il testo "Export failed: …" insieme a una descrizione dell'errore. Sfondo rosso con 8 % di opacità, angoli arrotondati. Larghezza massima 400 pixel. Cause di errore frequenti: errore di scrittura per disco pieno; errore sandbox per percorsi di destinazione al di fuori dell'area consentita.

DOVE

Lato destro del passaggio di esportazione.

TECNICO

Elenco della cronologia delle esportazioni (salvata in modo permanente nelle impostazioni dell'app, aggiornata dopo ogni esportazione riuscita). Ogni riga mostra un badge del formato (piccolo, colorato con l'accento), timestamp (HH:mm), nome del file (troncato a 1 riga) e dimensione del file formattata. Clic su una riga apre il Finder con il file selezionato. Stato vuoto: "No exports yet".

DOVE

Clic destro su una riga della cronologia.

TECNICO

Menu contestuale su ogni voce dell'elenco con due azioni: "Reveal in Finder" (apre il Finder con il file selezionato, come il clic semplice) e "Copy Path" (copia il percorso completo del file come testo negli appunti). Quest'ultimo è utile per il trascinamento in altre app o per passarlo alla riga di comando.