Capitolo 8 — Formati di esportazione

DOVE

Barra dei menu → Export → 3D Formats → Export PLY… (⌘E). Modalità Simple: passaggio guidato Export → scheda formato „PLY". Dimensione: tipicamente 100 % (valore di riferimento). Compatibile con: SuperSplat, PolyCam, tutti i viewer 3DGS.

TECNICO

PLY è il formato di archiviazione canonico per 3D Gaussian Splatting. RadianceKit scrive un file binario little-endian con il layout di proprietà 3DGS standardizzato: per ogni Gaussiana una posizione a tre componenti, tre normali sempre impostate a zero, tre coefficienti SH DC (f_dc_0..2) per il colore RGB di base, seguiti da fino a 45 ulteriori coefficienti SH (f_rest_0..44) nella disposizione channel-major trasposta definita dal paper Kerbl 2023 (prima tutti i coefficienti del canale R, poi tutti quelli G, poi tutti quelli B), seguiti da opacità in logit (valori grezzi pre-sigmoid), tre scale in log-space e una rotazione quaternione wxyz. Il grado SH massimo esportato viene limitato al minimo tra il desiderio dell'utente e il grado effettivamente appreso; il default è 3 (45 coefficienti residui). Prima della scrittura la dimensione del payload viene calcolata in interi a 64 bit per intercettare eventuali overflow su cloud estremamente grandi. Il file viene scritto in modo atomico, il che con cloud grandi occupa temporaneamente il doppio dello spazio su disco.

DOVE

Barra dei menu → Export → 3D Formats → Export Compressed PLY…. Modalità Simple: scheda formato „Compressed PLY". Dimensione: circa 10–20 % rispetto a PLY (compressione da 5 a 10 volte). Compatibile con: SuperSplat, motore PlayCanvas, viewer basati su web.

TECNICO

La variante PlayCanvas del formato PLY con quantizzazione a chunk. Le Gaussiane vengono raggruppate in chunk da 256. Per ogni chunk vengono salvati nell'header i limiti min/max separati per posizione, scala e colore; le singole Gaussiane fanno riferimento ai propri valori relativamente a questi limiti e vengono compresse a 32 bit ciascuna: posizione e scala con packing 11-10-11 bit, rotazione come quaternione „Smallest-Three" a 2-10-10-10 bit, colore come RGBA 8-8-8-8. I coefficienti SH più alti vengono quantizzati con soli 8 bit per componente (tre byte per coefficiente e Gaussiana). Il formato stesso rimane comunque un PLY con header ASCII e quindi fondamentalmente validabile con strumenti PLY, ma le proprietà dei vertici sono dichiarate come campi uint. Il grado SH è per default 0 (nessun coefficiente residuo), per massimizzare la compressione — gradi SH più alti possono essere scelti esplicitamente.

DOVE

Barra dei menu → Export → 3D Formats → Export SPZ…. Modalità Simple: scheda formato „SPZ". Dimensione: circa 10 % rispetto a PLY (90 % più piccolo). Compatibile con: Niantic Scaniverse, Niantic Spatial Fields, MetalSplatter.

TECNICO

Il formato SPZ v2 di Niantic. Le posizioni vengono impacchettate come fixed-point a 24 bit (il che dà circa 0,25 mm di risoluzione), le scale come quantizzazione a 8 bit nello spazio logaritmico, le rotazioni come Smallest-Three a 8 bit (nella v2 vengono salvati solo xyz, w viene derivato nel decoder dalla norma del quaternione), le opacità come valori sigmoidizzati a 8 bit. Il DC-SH viene salvato con una formula di packing specifica di SPZ (dc_raw * 0.15 * 255 + 0.5 * 255), le bande SH più alte con 5 bit (banda 1) o 4 bit (banda 2-3) per coefficiente. L'intero blob binario impacchettato viene poi compresso con gzip standard (RFC 1952), il che produce un formato contenitore gzippato con byte magici 1f 8b. RadianceKit chiama a questo scopo il gzip di sistema, perché l'API zlib integrata di Apple genera un framing proprietario Apple, che non sarebbe compatibile con i reader SPZ in Spatial Fields o MetalSplatter. Il gzip di sistema rimane avviabile anche all'interno della sandbox macOS.

DOVE

Barra dei menu → Export → 3D Formats → Export SOG…. Modalità Simple: scheda formato „SOG". Dimensione: circa 5–6 % rispetto a PLY (compressione da 15 a 20 volte — l'opzione più piccola). Compatibile con: motore PlayCanvas, editor SuperSplat.

TECNICO

„Spatially Ordered Gaussians" — un formato PlayCanvas che salva la cloud pronta per la GPU in diverse immagini WebP lossless. Prima tutte le Gaussiane vengono ordinate spazialmente tramite codice Morton 3D (Z-order a 30 bit, 10 bit per asse), il che garantisce alle immagini una successiva località di cache nel renderer. Poi le posizioni vengono quantizzate a valori a 16 bit con trasformazione logaritmica simmetrica (per un migliore range dinamico) e divise in due immagini RGBA (means_l.webp per gli 8 bit inferiori, means_u.webp per gli 8 bit superiori). Le rotazioni vengono codificate come Smallest-Three con 3×8 bit più 2 bit di modo in un'immagine RGBA (il modo finisce nell'alpha come 252 + largest). Scale e DC-SH vengono quantizzati con un codebook di 256 voci ciascuno (distribuito su base percentile su tutti i valori), gli indici finiscono in scales.webp e sh0.webp. Le cinque immagini più un meta.json con codebook e limiti vengono impacchettate in un file ZIP (encoder personalizzato, perché la sandbox blocca lo zip di sistema) e salvate con l'estensione .sog.

Attenzione sandbox: SOG è l'unica opzione di formato che richiede un binario esterno. La fase di codifica WebP chiama cwebp da /usr/local/bin/cwebp o /opt/homebrew/bin/cwebp. Se non viene trovato alcun binario cwebp, il codice ricade sulla codifica PNG grezza — ma attenzione: il fallback PNG non funziona in SuperSplat. Nella versione App Store valuta la disponibilità in base alla variante di build; nella variante Developer cwebp deve essere installato via Homebrew (brew install webp).

DOVE

Barra dei menu → Export → 3D Formats → Export glTF…. Modalità Simple: scheda formato „glTF". Dimensione: paragonabile a PLY. Compatibile con: viewer glTF con estensione KHR_gaussian_splatting (standard bozza Khronos).

TECNICO

Scrive un file binario .glb autonomo (nessun file bin separato allegato) secondo la specifica dell'estensione KHR_gaussian_splatting. Le posizioni vengono salvate come normali dati vertice glTF POSITION (float3), tutti gli altri attributi (rotazione come float4, scala come float3, opacità come float, coefficienti SH come float3 × shCoeffCount) risiedono in attributi vertice aggiuntivi e vengono referenziati tramite l'estensione. Importante: glTF usa un sistema di coordinate destrorso Y-up, COLMAP/3DGS lavora Y-down/Z-forward. L'esportatore applica quindi una rotazione di 180 gradi attorno all'asse X — le posizioni vengono riscritte con (x, -y, -z), i quaternioni vengono adattati a (w, x, -y, -z). Il risultato è una rappresentazione geometricamente corretta, con orientamento giusto (non speculare) nei viewer glTF. I chunk JSON e binari vengono paddati ad allineamento a 4 byte, come richiesto dallo standard GLB.

DOVE

Barra dei menu → Export → 3D Formats → Export .splat…. Modalità Simple: scheda formato „.splat". Dimensione: esattamente 32 byte per Gaussiana. Compatibile con: gsplat.js, viewer basati su web (riferimento antimatter15), la maggior parte delle demo 3DGS da browser.

TECNICO

Il formato .splat di antimatter15 — 32 byte per Gaussiana, nessun header, nessuna indirezione. Layout per voce: 3 × float32 posizione (coordinate mondo), 3 × float32 scala (trasformata con exp dallo spazio logaritmico del buffer interno), 4 × uint8 colore RGBA (coefficiente DC-SH scalato con SH_C0 = 0.282... e limitato a [0,255]), 4 × uint8 quaternione (w,x,y,z, normalizzato e codificato nell'intervallo byte come 128 + 128*q). Viene salvato solo il DC-SH — le bande SH più alte vengono scartate. Ciò rende il formato estremamente compatto, ma costa i cambiamenti di colore dipendenti dal punto di vista, che si presentano con riflessi o highlight speculari. L'ordine di scrittura è esattamente l'ordine degli indici della cloud (nessun ordinamento spaziale), i viewer web come gsplat.js fanno il rendering partendo da questo presupposto.

DOVE

Barra dei menu → Export → Media → Export Web Viewer…. Modalità Simple: scheda formato „Web Viewer". Dimensione: dati splat codificati in base64 (≈ overhead 4/3) + circa 5 KB di shell HTML/JS. Compatibile con: ogni browser moderno con WebGL2 (tutti i desktop, iOS 15+, Android 5+).

TECNICO

Raggruppa la Gaussian Cloud insieme a un renderer WebGL2 scritto completamente inline in un unico file .html. Non ci sono dipendenze CDN, nessun WASM, nessun secondo file. La cloud viene prima codificata internamente come binario .splat (stessa logica a 32 byte di E6), poi incorporata in base64, poi decodificata con atob nel browser. Il renderer integrato esegue una propria ordinazione WebGL2, un controllo mouse-orbit e ordinazione lato CPU per frame; l'intero codice JS (shader, matematica, loop) è visibile nell'HTML di output. La convenzione degli assi al confine tra memorizzazione e renderer è esattamente la stessa di E5: posizione (x, -y, -z), quaternione (w, x, -y, -z). Opzionalmente si può visualizzare un overlay di branding (interruttore per il livello free). Poiché tutto è inline, il file funziona anche direttamente dal protocollo file:// — non serve un webserver locale per testare.

DOVE

Barra dei menu → Viewport → Record Turntable Video OPPURE Barra dei menu → Export → Media → Export Orbit Video…. Modalità Simple: scheda formato „Orbit Video" con cursore durata 3–30 s. Dimensione: dipende da durata, risoluzione, bitrate. Compatibile con: tutte le piattaforme (H.264 e HEVC sono lo standard Apple).

TECNICO

Renderizza la Gaussian Cloud lungo una ripresa camera in orbita parametrica e codifica ogni frame tramite AVAssetWriter in un file MP4 o MOV. La configurazione dell'orbita controlla velocità di rotazione (giri), distanza, elevazione, FOV, durata e fattore di ease-in/out. L'esportazione Orbit Video passa per la FASE di rendering PROPRIA di RadianceKit con valutazione SH completa — pixel-per-pixel identica al viewport in-app (WYSIWYG). Per ogni frame la matrice di adattamento del mondo (calcolata dal renderer per ruotare le coordinate interne nel mondo orbita Y-up) viene moltiplicata per la camera, poi viene applicata una speculazione di conversione della camera (Orbit Y-up → COLMAP Y-down). Il target di rendering offscreen viene trasferito tramite IOSurface in un CVPixelBuffer per l'encoder. L'encoder supporta H.264 e HEVC, bitrate e risoluzione configurabili da 480p a 8K. Prima del primo frame il renderer attende 200 ms, affinché l'ordinamento iniziale dello splat sia completato. Questa esportazione è vincolata dalla GPU — a 8K e con milioni di Gaussiane il tempo di rendering per frame è di diversi secondi, quindi sono possibili tempi totali di rendering di 10–30 minuti per 6 s di video.

DOVE

Barra dei menu → Export → Photogrammetry → Export SfM (transforms.json)…. Dimensione: tipicamente 1–10 KB (solo pose + intrinseci, nessuna immagine, nessuna Gaussiana). Compatibile con: nerfstudio, Brush, gsplat, OpenSplat, Meshroom, tutti i moderni trainer 3DGS feed-forward.

TECNICO

Scrive il formato transforms.json di nerfstudio con un elenco di pose camera più intrinseci condivisi. Per ogni camera viene invertita la matrice di vista (interna a RadianceKit: World-to-Camera in convenzione COLMAP), poi vengono riflessi i vettori base locali alla camera Y e Z, per convertire nella convenzione nerfstudio (stile OpenGL, la camera guarda lungo -Z, +Y è verso l'alto). La matrice 4×4 finale finisce come array annidato row-major di double nel campo transform_matrix di ogni frame. Gli intrinseci vengono salvati a livello superiore (lunghezza focale x/y, punto principale x/y, larghezza/altezza immagine, camera_model = "OPENCV", più i coefficienti di distorsione k1, k2, p1, p2) — tranne quando l'esportatore rileva più set di intrinseci diversi, nel qual caso vengono scritti per frame. I percorsi delle immagini vengono scritti come images/<filename> relativi al file JSON; l'utente deve creare una cartella images/ gemella con le foto di training.

DOVE

Barra dei menu → Export → Photogrammetry → Export SfM (COLMAP Workspace)…. Dimensione: tre file binari insieme tipicamente 4–8 MB — points3D.bin domina (una riga per punto 3D della sparse cloud), images.bin e cameras.bin sono entrambi ben sotto i 100 KB. Compatibile con: COLMAP stesso, Nerfstudio, Postshot, Meshroom, tutti gli strumenti che si aspettano una directory sparse/ di COLMAP.

TECNICO

Scrive il layout standard COLMAP sparse/0/ con tre file binari: cameras.bin, images.bin, points3D.bin. Il riferimento di formato è la documentazione ufficiale COLMAP. cameras.bin contiene l'elenco deduplicato degli intrinseci (camere con intrinseci identici + dimensione immagine identica vengono unite in un'unica voce); il modello camera utilizzato è OPENCV (modello 4), con fx/fy/cx/cy più i quattro coefficienti di distorsione k1/k2/p1/p2. images.bin elenca per ogni immagine la posa come quaternione wxyz più traslazione, seguiti dall'ID camera e dal nome file; non vengono salvate corrispondenze 2D-3D. points3D.bin contiene la nuvola di punti SfM con posizione, colore (RGB 0-255) e valori predefiniti per riproiezione e lunghezza track. Tutto viene scritto in little-endian. La re-importazione in RadianceKit funziona tramite il menu File → „Import COLMAP/Metashape Workspace…" (vedi Q3 nel capitolo sul backend SfM).