Log del rendering 3DGS e strumenti di debug

Questo documento descrive come ottenere le informazioni di diagnostica e come leggere ogni strumento. Per individuare un problema per sintomo, vedere Risoluzione dei problemi.

Visualizzare il log del plugin

Il log del plugin ha due categorie:

Categoria	Origine
`LogLCC`	Pipeline LCC e funzionalità comuni (caricamento, collisioni, licenze, funzioni di utilità)
`LogLCC2`	Specifica della pipeline LCC2

Visualizzarlo nell'editor

Aprire Window > Output Log. Durante l'analisi, digitare LogLCC nella casella del filtro per trovare rapidamente i messaggi del plugin, oppure eseguire i comandi seguenti nella console per aumentare il livello di log:

log LogLCC Verbose
log LogLCC2 Verbose

Il file di log dell'editor si trova in:

<directory del progetto>/Saved/Logs/<nome del progetto>.log

Visualizzarlo in una build pacchettizzata

Avviare una build Development con il parametro -log per far comparire una finestra di console. Il file di log si trova in:

<directory del pacchetto>/<nome del progetto>/Saved/Logs/<nome del progetto>.log

Le build Shipping non stampano log per impostazione predefinita, quindi usare una build Development per l'analisi.

Quando si segnala un problema, allegare il file di log completo dell'esecuzione in cui il problema si è verificato, non solo alcune righe filtrate del plugin. Individuare un problema richiede spesso il contesto esterno al plugin.

Statistiche di rendering: stat XGrids

Eseguire stat XGrids nella console, oppure usare il pulsante Stats nella categoria Actions del pannello Details dell'Actor.

Leggerlo insieme a stat unit per valutare prima se il collo di bottiglia venga dal 3DGS.

Voci di conteggio

Le voci consultate più spesso:

Metrica	Significato
`Total Splats`	Numero totale di splat del dataset
`Level0 Splats`	Numero di splat del Level 0 (la precisione più alta)
`Current Render Splats`	Numero di splat effettivamente renderizzati nel fotogramma corrente, la voce principale per valutare il carico di rendering
`Current Render Main Splats`	Quantità di dati principali renderizzati nel fotogramma corrente
`Current Render Environment Splats`	Quantità di dati dell'ambiente renderizzati nel fotogramma corrente
`Total Nodes`	Numero totale di nodi
`Current Render Nodes`	Numero di nodi renderizzati nel fotogramma corrente
`Visible Node Num`	Numero di nodi visibili
`LCC Draw Call`	Numero di draw call prodotte dal plugin
`LCC Sort Num`	Numero di ordinamenti
`Camera Num`	Numero di camere che partecipano al rendering

Come usarlo: quando Current Render Splats resta costantemente vicino al limite di Max Splat Num, il limite di conteggio sta già tagliando i dati e il dettaglio dell'immagine risulta ridotto. Aumentare il limite (prestazioni in cambio di qualità), oppure regolare Level Factor per ridurre i nodi all'origine.

La dimensione totale dei dati è leggibile anche da codice, vedere GetSplatNumber.

Voci di tempo

Costi suddivisi per fase, usati per individuare quale passo è lento:

Metrica	Fase corrispondente
`Render LCC`	Costo totale di rendering del plugin
`Traversal Time`	Traversal dei nodi, che decide i nodi renderizzati in questo fotogramma
`Determine Nodes Level`	Calcolo del Level di precisione di ogni nodo
`Load Data To CPU`	Lettura dei dati in memoria
`Upload To GPU`	Upload dei dati nella memoria video
`Splat Sort`	Ordinamento degli splat (necessario per il rendering traslucido)
`Node Sort`	Ordinamento dei nodi
`Build Mesh Batch`	Costruzione dei batch di disegno
`Wait Node Ready`	Attesa che i dati dei nodi siano pronti
`Component Update`	Aggiornamenti del Component
`Update Camera Info`	Aggiornamenti delle informazioni della camera
`Load Meta File`	Caricamento del file delle metainformazioni
`Load Index Data`	Caricamento dei dati di indice (pipeline LCC)
`Load Collision Data`	Caricamento dei dati di collisione
`Load Environment Data`	Caricamento dei dati dell'ambiente
`Update Collision`	Aggiornamenti delle collisioni
`Get Physics Trimesh Data`	Generazione della mesh di collisione fisica
`Release Memory`	Rilascio della memoria
`Preload Node`	Precaricamento dei nodi
`Get From Cache`	Recupero dei dati dalla cache
`Create Thread`	Creazione dei thread
`Draw Node Box`	Disegno dei bound dei nodi (solo con la visualizzazione di debug abilitata)

Come usarlo:

Quando Splat Sort è alto, la pipeline LCC può aumentare Sort Factor per ordinare meno spesso
Quando Wait Node Ready è alto, il caricamento dei dati non tiene il passo, forse per un disco lento o thread insufficienti
Quando Upload To GPU è alto, la quantità caricata per fotogramma è elevata, quindi regolare Level Factor o Max Splat Num
Quando Update Collision e Get Physics Trimesh Data sono alti, ridurre Max Load Collision Distance

Per il flusso di lavoro completo di regolazione, vedere Guida alle prestazioni.

Voci di memoria e memoria video

Metrica	Significato
`CPU Usage`	Memoria usata dal plugin
`GPU Usage`	Memoria video usata dal plugin
`Position Data(For Raycast) Usage`	Uso dei dati di posizione per i test dei raggi
`Collision Data Usage`	Uso dei dati di collisione
`CPU Occupy Percentage`	Percentuale di memoria usata
`GPU Occupy Percentage`	Percentuale di memoria video usata

Le voci percentuali corrispondono alle soglie di rilascio nelle impostazioni del progetto. Un uso che resta a lungo vicino a Max GPU Usage Percetage For Free significa che il recupero delle risorse si attiva frequentemente, cosa che può causare scatti.

Per le regole di allocazione della memoria video e i limiti di budget, vedere Rendering.

Voci sui thread

Metrica	Significato
`Collision Loader Thread Num`	Numero di thread di caricamento delle collisioni
`Exporter Thread Num`	Numero di thread dell'exporter

Visualizzazione dei bound dei nodi

Attivarla con il pulsante Debug Node Bound nella categoria Actions del pannello Details dell'Actor, oppure eseguire nella console:

r.Xgrids.DrawNodeBox 1

Disegna i nodi attualmente caricati come scatole wireframe. Il colore della scatola corrisponde al Level del nodo: rosso, arancione, giallo, verde, blu e viola si susseguono in ordine, dove il rosso è il Level più basso (la precisione più alta) e il bianco è il Level più alto (la precisione più bassa).

Per i concetti di nodo e Level, vedere Rendering.

Come leggerlo:

Scatole rosse ancora renderizzate in lontananza indicano una precisione troppo alta e prestazioni sprecate. Aumentare Level Factor
Scatole di colori freddi da vicino indicano che la precisione è stata abbassata troppo e l'immagine appare sfocata. Ridurre Level Factor o verificare Start Level
Un numero di scatole molto superiore alle attese indica che Max Distance può essere impostato su un valore troppo grande

Funziona solo nell'editor e nelle build Development. L'interfaccia di codice corrispondente è DebugNodeBound.

Visualizzazione delle collisioni

Attivarla con il pulsante Show Collision nella categoria Actions del pannello Details dell'Actor, oppure eseguire nella console:

r.xgrids.DrawCollision 1

Disegna il wireframe dei corpi di collisione caricati.

Come leggerlo:

Nessun wireframe: i dati non contengono un file di collisione, oppure bEnableCollision è disattivato, vedere Prerequisiti delle collisioni
Wireframe solo nelle vicinanze: comportamento normale, perché le collisioni vengono caricate in streaming in base alla distanza e sono limitate da Max Load Collision Distance
Il wireframe è spostato rispetto al contenuto dell'immagine: i dati di collisione non corrispondono ai dati di rendering, contattare il supporto tecnico

Abilitarla come prima cosa quando si analizzano test dei raggi che non colpiscono nulla o personaggi che attraversano il terreno, per confermare se le collisioni sono state effettivamente caricate. Per il meccanismo di caricamento, vedere Collisioni; l'interfaccia di codice è ShowCollision.

Messaggio di log	Significato e azione
`LCC file :<path> does not exist.`	Il percorso non esiste. Verificare il percorso; i percorsi relativi si basano su `Content`
`meta.lcc file :<path> load error,Please check.`	L'analisi del file delle metainformazioni LCC1 è fallita, il file può essere danneggiato
`Load Meta.lcc error,Please check your file!`	Come sopra
`Read index.bin error,path:<path>.`	La lettura del file di indice è fallita. Verificare che `index.bin` esista e non sia danneggiato
`LCC4Unreal do not support this file format!`	Il formato non è supportato, verificare che l'estensione sia nell'intervallo supportato
`The data file:<path> does not exist,Please check your file!`	Manca un file di chunk dei dati, la directory dei dati può essere incompleta

Collisioni

Messaggio di log	Significato e azione
`There is neither collision.bin nor collision.lci in the folder:<path>, please check.`	Nella directory dei dati non c'è alcun file di collisione, quindi le collisioni non possono essere abilitate per questi dati
`Failed to open file <path>`	L'apertura del file di collisione è fallita, verificare permessi e integrità del file
`Read collision data error,path:<path>.`	La lettura dei dati di collisione è fallita, il file può essere danneggiato
`Invalid indices in collision data!`	Il contenuto dei dati di collisione è anomalo, contattare il supporto tecnico

Rendering

Messaggio di log	Significato e azione
`r.PostProcessing.PropagateAlpha is 0. LCC4Unreal requires this to be enabled for correct rendering.`	Questa opzione deve essere abilitata, altrimenti il blending dell'alpha è scorretto. Il plugin mostra anche un avviso
`Unlicensed: enabled clipping volumes limited to <N> ...`	Il numero di volumi di taglio dell'edizione gratuita supera la quota e l'eccesso non viene renderizzato. Vedere Edizioni e licenze
`Unlicensed: enabled section planes limited to <N> ...`	Come sopra, per il numero di piani di sezione

GIS

Messaggio di log	Significato e azione
`This lcc does not have RTK information!`	I dati non contengono informazioni geografiche RTK, quindi il posizionamento geografico non può essere usato
`MetaInfo's Offset has no 3 elements!`	Il campo di offset nelle metainformazioni è anomalo, i dati possono avere un problema

Licenze

Messaggio di log	Significato e azione
`ProjectID is invalid; generate one in Project Settings (Project/Description). Refusing authentication.`	Il progetto non ha un Project ID, generarne uno nelle impostazioni del progetto
`Failed to decode AppKey, please check.`	Il contenuto dell'AppKey è incompleto, copiarlo di nuovo
`Invalid AppKey, please check.`	Il formato dell'AppKey è errato
`Authorization has expired, please check.`	La licenza è scaduta, rigenerarla
`AppKey has expired. Please generate a new one.`	Come sopra
`Authentication Failed: <message>`	Il motivo del fallimento restituito dal server, agire in base al contenuto del messaggio
`HTTP request failed`	Il server delle licenze non è raggiungibile, verificare la rete
`HTTP error! Status: <code>`	Il server ha restituito un codice di stato di errore
`Signature Verification Failed`	La verifica della firma è fallita, contattare il supporto tecnico

Proxy Mesh

Messaggio di log	Significato e azione
`has a null StaticMesh`	All'Actor della mesh proxy non è assegnata alcuna StaticMesh e non ha effetto. Segnalato una volta per istanza

Cosa allegare quando si segnala un problema

Raccogliere le voci di questo elenco velocizza notevolmente la diagnosi.

Versione del plugin e versione del motore. La versione del plugin è visibile nell'angolo in basso a destra del pannello del plugin e si può trovare anche cercando LCC4Unreal nella finestra Edit > Plugins del motore.
Il file di log completo del momento in cui il problema si è verificato. Fornire il file .log stesso, non filtrato e non solo la singola riga di errore. Il contesto attorno al log contiene spesso le informazioni chiave necessarie alla diagnosi, e il filtraggio fa perdere questi indizi. Per la posizione del log, vedere Visualizzare il log del plugin.
Informazioni sui dati. Formato, dimensione approssimativa (Total Splats) e presenza di collisioni.
Passi per riprodurre il problema. Un percorso di riproduzione minimo a partire da un progetto nuovo è il più utile.
Ambiente hardware. Modello della scheda grafica, versione del driver e dimensione della memoria video.
Project ID. Necessario per i problemi di licenza; è visibile in Project Settings > Project > Description.

Per i contatti, vedere Contattaci.