Capitolo 10 — Modalità principiante

DOVE

In alto sopra il workflow, sempre visibile.

TECNICO

Mostra una barra di progresso orizzontale su tutta la pipeline (frame quality → SfM → training) con stage allocation: frame quality occupa 0–5% (fase 3.11, molto breve), SfM occupa 0–30% della barra, training 30–100%. Accanto testo di stato e visualizzazione percentuale nominata per fase ("SfM 41%", "Training 12 500/20 000"), in modo che gli utenti non leggano come errore il passo indietro apparente "41% SfM → 25% training" — la barra mostra il progresso dell'intera pipeline, non la sub-stage. Il calcolo ETA inizia non appena è misurato abbastanza training tempo (tipicamente dopo le prime 100 iterazioni). La stessa visualizzazione è anche usata in Modalità esperto sopra l'Inspector.

DOVE

Lato sinistro del passaggio di import, grande rettangolo tratteggiato con simbolo. Mostrato in Modalità principiante con l'etichetta "Drop photos or a video here".

TECNICO

Area di drop che fa saltare brevemente il simbolo e colora lo sfondo, non appena gli elementi di drag si librano sopra il campo. Accetta JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, bundle .radiancescene e directory. Drop routing per tipo: le immagini vengono raccolte e passate ordinate, i video attivano il percorso di frame sampling, i file splat aprono direttamente l'anteprima, i bundle di scena vengono caricati. Le directory vengono enumerate e tutte le immagini contenute importate. I bookmark security-scoped per l'accesso sandbox-compatibile vengono correttamente ripresi e rilasciati. Le estensioni non supportate vengono mostrate come banner di avviso per 5 secondi.

DOVE

All'interno della drop zone, pulsante prominente.

TECNICO

Pulsante che apre il dialogo file macOS con selezione multipla e i tipi di file JPG, PNG, TIFF, MP4, MOV, cartelle e il formato scena proprio dell'app. Gli URL risultato sono security-scoped e vengono inoltrati attraverso gli stessi percorsi di import del trascinamento. Se l'utente seleziona una cartella, viene enumerata ricorsivamente per immagini.

DOVE

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

TECNICO

Appare solo se (a) una sample-scene.splat, .spz o .ply è presente nel bundle dell'app E (b) nessuna immagine o video è ancora importato e nessuna nuvola di punti è presente. Al clic carica la nuvola di punti finita (preferibilmente il formato più piccolo — .splat ~3 MB, .spz ~1.4 MB, fallback .ply) e imposta dopo 400 ms valori di fotocamera hard-coded dai metadati originali della scena di fiori per una prospettiva di ingresso esteticamente sensata.

DOVE

All'interno della drop zone, accanto a "Try Sample Scene"; stesse condizioni di visibilità.

TECNICO

Attiva un download (repo github.com/bkindler/radiancekit-sample-photos), che carica circa 427 MB di 960 frame a piena risoluzione e li alimenta nell'app. Durante il download il pulsante è disabilitato. Il progresso appare nella barra di progresso superiore come "Downloading X%" in uno stadio proprio, perché questo stadio mantiene la propria scala 0–100% e non si sovrappone allo stadio SfM successivo.

DOVE

Barra strumenti fluttuante inferiore dell'overlay di import, a sinistra del pulsante Start.

TECNICO

Controllo con etichetta "Quality" raggruppa i preset disponibili per categoria (Classic / MCMC / Custom). I preset integrati vengono raggruppati per categoria; gli header di sezione sono hard-coded. I preset Custom visibili solo se ne esistono. Stato bloccato: i preset non presenti nella lista free (Quick + Preview) ricevono un suffisso "🔒" al nome se l'utente non ha acquistato; alla selezione il picker torna a Preview e apre automaticamente il purchase sheet. Alla scelta il preset viene applicato, il che sostituisce l'intera configurazione di training.

DOVE

Barra strumenti fluttuante inferiore dell'overlay di import, a destra del picker preset.

TECNICO

Pulsante che rimane grigio finché non sono importate né immagini né un video. Al clic avvia la pipeline e passa la macchina a stadi all'ordine frame quality → SfM → training. Il pulsante stesso non ha ulteriore stato; un'elaborazione in corso appare invece come schermo di elaborazione separato.

DOVE

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

TECNICO

Slider da 0.5 fps a 30 fps in passi di 0.5. Alla modifica viene aggiornata la densità di frame e in più calcolato il numero di frame target (almeno 10) da densità e lunghezza video. Lo slider si trova al di fuori della lista delle immagini, perché gli elementi della lista bloccherebbero gli eventi del mouse degli slider. Sotto lo slider stanno i frame target calcolati ("247 frames") e la lunghezza del video ("1m23s video"). Il tooltip avverte: "Doubling the density doubles the number of frames and increases SfM time by ~100%."

DOVE

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

TECNICO

Pulsante rosso. Il clic apre una finestra 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 del training, il risultato SfM e tutte le cache; lo stadio torna a Import. Su Cancel rimane tutto. La finestra è configurata come percorso default non distruttivo (pulsante distruttivo marcato in rosso).

DOVE

Lista immagini destra, ogni voce.

TECNICO

Lista sulle immagini importate con swipe per eliminare. Per immagine una riga con icona, nome file, risoluzione ("1920 × 1080") e dimensione file (formattata KB/MB). La risoluzione proviene da una cache di metadati che viene riempita in modo asincrono dagli header delle immagini, in modo che l'interfaccia non si blocchi. L'azione di eliminazione offre swipe delete tipico macOS (swipe trackpad a sinistra su una riga) così come delete da tastiera con riga selezionata. Nota: il percorso esteso di eliminazione immagine con pulsante meno esplicito, Backspace e Cmd-Z per annullare è stato aggiunto solo in Modalità esperto nel Project Navigator — in Modalità principiante rimane swipe delete.

DOVE

Sotto la lista delle 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 (octagon 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 warning), testo "Workable, but quality usually improves with 20+ images and good coverage around the scene."

Da 20 immagini il banner sparisce. Le soglie sono hard-coded e basate su 560+ esperimenti empirici di training.

DOVE

Al drop di una cartella — nessun pulsante visibile, ma logica di riconoscimento.

TECNICO

Al drop di una directory viene controllato se al suo interno si trova uno dei tre layout di workspace canonici: sparse/0/cameras.bin, sparse/cameras.bin o direttamente cameras.bin nella root. Se sì, l'enumerazione standard delle immagini viene interrotta e viene invece aperto un alert modale che chiede all'utente se usare la ricostruzione esistente o rimandare le immagini attraverso Apple Photogrammetry. Stesso percorso anche per workspace in formato testo (cameras.txt) ed export ETH3D. Vedi Capitolo 9 Backend Q6 per dettagli. Funziona in Modalità principiante esattamente come in Modalità esperto.

DOVE

Sfondo a tutta pagina dietro il cerchio di progresso, nascosto in caso di interruzione o errore.

TECNICO

Animazione decorativa che a seconda del progresso della pipeline (0…1) renderizza un numero crescente di piccole particelle splat animate. La fonte è un valore di progresso calcolato che mappa le fasi SfM su 0–0.2 e il training su 0.2–1.0 (frame quality su 0–0.05). Così gli splat si "costruiscono" visibilmente mentre il training gira. Esclusivamente decorativo — la visualizzazione non mostra risultati intermedi reali del training attuale (sarebbe live preview in Modalità esperto). In caso di cancel o failure viene nascosta e rimane visibile solo il cerchio di stato.

DOVE

Al centro dello schermo di elaborazione, 220 × 220 pixel.

TECNICO

Due anelli renderizzati sovrapposti: all'esterno un anello traccia attenuato, all'interno un anello di progresso pieno con stroke di accento o rosso (rosso in caso di errore). All'interno del cerchio uno stage icon (cervello per training, fotocamera per SfM, film per estrazione frame video, sparkles per frame quality), titolo dello stadio e la cifra percentuale animata live in font rounded da 32 pt. L'icona pulsa delicatamente finché l'elaborazione è attiva. La visualizzazione interpola su un timer 30 Hz dolcemente verso il vero progresso attuale — con constant creep (0.0003/frame) più una quota proporzionale (4% del gap) e un soft ceiling che si imposta all'80% del prossimo milestone atteso (per SfM da una tabella hard-coded di milestone). Così il progresso appare fluido, anche se gli update SfM reali arrivano solo ogni pochi secondi.

DOVE

In alto a sinistra sullo schermo di elaborazione, 32 × 32 pixel.

TECNICO

Pulsante semplice con sfondo materiale. Attiva o disattiva il pannello di info. L'icona cambia tra info-cerchio outline e info-cerchio pieno quando attivo. Animazione di ingresso delicata. Nel tooltip "Show detailed processing metrics".

DOVE

In basso a sinistra sullo schermo di elaborazione, visibile solo se showProcessingInfo == true.

TECNICO

Pannello a due colonne con sfondo ultra-thin material. Colonna sinistra: righe info specifiche per stadio — per SfM testo di stato e percentuale; per training iterazione, loss combinato, loss L1, loss D-SSIM, gaussian count (colorato arancione), speed (it/s), elapsed time, ETA calcolato, SH degree e learning rate. Colonna destra: testo di stato, stringa time info, chart di loss inline (vedi C-28) e un nudge di discoverability (vedi C-32). Tutti i valori vengono letti dallo stato del training, aggiornato ad ogni tick di training.

DOVE

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

TECNICO

Bordered button. A seconda dello stato chiama Pause o Resume. L'etichetta cambia tra "Pause" (con icona pause) e "Resume" (icona play). Durante il passo SfM il pulsante non viene mostrato, perché Apple Photogrammetry non conosce semantica di pausa. Lo stato di pausa preserva completamente iterazione, stato gaussian e momentum optimizer — Resume prosegue dove ci si è fermati.

DOVE

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

TECNICO

Pulsante bordered rosso. Apre una finestra di conferma con titolo "Stop and discard progress?", pulsanti "Discard Progress" (distruttivo) e "Keep Running" (cancel). Alla conferma viene impostato il flag cancel, il task di training terminato, il sottoprocesso SfM se necessario terminato e una riga di summary con status di interruzione scritta nel log JSONL. A differenza di Pause i buffer di training e lo stato vengono scartati.

DOVE

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

TECNICO

Pulsante accent. Avvia di nuovo l'intera pipeline. Prima dell'avvio viene controllato se sono ancora presenti immagini/video importati. I log degli errori precedenti rimangono nella directory JSONL; un nuovo run scrive un nuovo file di log con timestamp attuale.

DOVE

Nel pannello info, colonna destra, visibile solo durante training con storia di andamento non vuota.

TECNICO

Area di disegno compatta (40 pixel di altezza), disegna la loss history come linea da 1 pixel in colore accent. I dati vengono filtrati su valori finiti (protezione NaN per training instabili). Min/max vengono calcolati sull'intera history — il chart fa quindi auto-zoom sull'intervallo dei valori. L'ultimo valore loss sta in alto a destra sopra il chart. La history stessa viene costruita nello stato dell'app ad ogni tick di training (tipicamente ogni 100 iterazioni).

DOVE

Nel pannello info, colonna destra in basso, visibile solo durante training E in Modalità principiante.

TECNICO

Piccola riga con icona occhio e testo caption "Switch to Expert Mode (⌘2) for live splat preview", in tonalità sobria e font 10 pt. Nessun elemento interattivo, solo nota. Non reagisce al clic — l'utente deve effettivamente premere Cmd+2 o cliccare il menu Mode → Expert Mode.

DOVE

Sfondo a schermo intero del passaggio anteprima.

TECNICO

Viewport 3D basato su Metal che renderizza la nuvola di punti finita. Il renderer è il fork vendored di MetalSplatter con fix RadianceKit per popping/flickering. 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), appare invece uno sfondo nero con testo "Metal not available". La vista ignora la safe area, in modo che il modello arrivi fino al bordo della finestra.

DOVE

Sopra il viewport, fluttuante.

TECNICO

Overlay UI compatto con pulsanti per auto-rotation (turntable), reset-camera, scelta dello sfondo (Gray/Black/White), save screenshot, toggle info panel. Si lega ai parametri della fotocamera (distanza, azimut, elevazione, target, FOV) e controlla l'auto turntable. Durante il training (quando l'utente vuole vedere girare con sé il viewport in Modalità esperto) l'overlay mostra in più una compatta riga di stato del training.

DOVE

Barra di navigazione inferiore in Z3.

TECNICO

Pulsante accent con etichetta "Export" e icona share. Il clic attiva il passaggio a Z4. Prima la vista superiore controlla se la versione completa è sbloccata — se no, viene mostrata la vista di blocco invece dello stadio di export (vedi U-06).

DOVE

Lato principale sinistro del passaggio di esportazione.

TECNICO

Griglia di schede con due colonne flessibili e 12 punti di spaziatura. Itera sui formati offerti in Modalità principiante — un sottoinsieme filtrato della lista completa dei formati che contiene solo i 6 formati più importanti: PLY, SPZ, glTF, .splat, orbit video, web viewer. Compressed PLY e SOG vengono offerti SOLO in Modalità esperto.

DOVE

Ogni scheda nella griglia.

TECNICO

Pulsante semplice con layout a scheda: icona (ad es. zipper documento per PLY, scatola di archivio per SPZ, icona video per orbit video) in alto, nome del formato come headline, caption di descrizione (accorciata su 2 righe), sotto la dimensione del file stimata (calcolata live da formato, gaussian count e SH degree e formattata come KB/MB). Al clic il formato viene selezionato. La scheda selezionata riceve sfondo accent, bordo accent e un'icona di spunta in alto a destra. Tooltip è la descrizione del formato.

DOVE

Sotto la griglia formato, visibile solo se è selezionato un formato video (orbit video o social video).

TECNICO

Slider 3–30 secondi in passi di 1 secondo, lega alla durata video nello stato dell'app. Larghezza massima 300 pixel. Viene mostrato solo se è selezionato un formato video. Con formati non video lo slider viene completamente rimosso dalla vista — nessun spazio morto.

DOVE

Sotto la griglia formato (e sotto lo slider duration se video selezionato).

TECNICO

Grande pulsante accent. Etichetta: "Export {nome-formato}", icona share. Al clic viene aperto il dialogo di salvataggio macOS con estensione adatta al formato e nome file predefinito "scene.{ext}"; alla conferma l'export viene scritto nell'URL scelto. Disabilitato se non è presente alcun risultato di training o se un export è già in corso.

DOVE

Sotto il pulsante export, visibile solo mentre un export è in corso.

TECNICO

Indicatore di progresso con larghezza max 300 pixel, sotto caption "Exporting… N%". Il valore va da 0 a 1 e viene aggiornato durante la scrittura — con PLY in chunk di 10 000 gaussiane, con SPZ una volta dopo la quantizzazione, con orbit video in intervalli di frame.

DOVE

Sotto la progress bar, visibile solo se nell'ultimo export è avvenuto un errore.

TECNICO

Riga rossa con icona warning e testo errore. Sfondo rosso all'8% di opacità, angoli arrotondati. Larghezza max 400 pixel. Cause di errore frequenti: SOG si aspetta cwebp nel PATH di sistema (non conforme App Store); errore di scrittura con disco pieno; errore sandbox con destinazioni di salvataggio fuori dall'area consentita.

DOVE

Lato destro del passaggio di esportazione.

TECNICO

Lista sulla cronologia di esportazione (salvata in modo persistente come JSON in UserDefaults, gestita dopo ogni export riuscito). Ogni riga mostra badge formato (piccolo, colorato accent), timestamp (HH:mm), nome file (1 riga accorciata) e dimensione file formattata. Il clic su una riga apre il Finder con il file selezionato. Empty state: "No exports yet".

DOVE

Clic destro su una riga history.

TECNICO

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