Logs und Debug-Werkzeuge für das 3DGS-Rendering

Diese Seite behandelt, wie Diagnoseinformationen erhoben und die einzelnen Werkzeuge gelesen werden. Zum Eingrenzen eines Problems nach Symptom siehe Fehlerbehebung.

Das Plugin-Log ansehen

Das Plugin-Log hat zwei Kategorien:

Kategorie	Quelle
`LogLCC`	LCC-Pipeline und gemeinsame Funktionen (Laden, Kollision, Lizenzierung, Hilfsfunktionen)
`LogLCC2`	Spezifisch für die LCC2-Pipeline

Window > Output Log öffnen. Bei der Untersuchung LogLCC in das Filterfeld eingeben, um die Plugin-Meldungen schnell zu finden, oder die folgenden Befehle in der Konsole ausführen, um den Log-Level zu erhöhen:

log LogLCC Verbose
log LogLCC2 Verbose

Die Log-Datei des Editors liegt unter:

<Projektverzeichnis>/Saved/Logs/<Projektname>.log

In einer Paketausgabe ansehen

Einen Development-Build mit dem Parameter -log starten, um ein Konsolenfenster zu öffnen. Die Log-Datei liegt unter:

<Paketverzeichnis>/<Projektname>/Saved/Logs/<Projektname>.log

Shipping-Builds geben standardmäßig kein Log aus, zur Untersuchung daher einen Development-Build verwenden.

Bei einer Problemmeldung die vollständige Log-Datei des Durchlaufs beifügen, in dem das Problem auftrat, nicht nur einige gefilterte Plugin-Zeilen. Das Eingrenzen eines Problems erfordert häufig den Kontext außerhalb des Plugins.

Render-Statistiken: stat XGrids

stat XGrids in der Konsole ausführen oder die Schaltfläche Stats unter der Kategorie Actions im Details-Panel des Actors verwenden.

Zusammen mit stat unit lesen, um zuerst zu beurteilen, ob der Engpass das 3DGS ist.

Zähleinträge

Die am häufigsten gelesenen Einträge:

Metrik	Bedeutung
`Total Splats`	Gesamte Splat-Anzahl des Datensatzes
`Level0 Splats`	Splat-Anzahl auf Level 0 (der höchsten Genauigkeit)
`Current Render Splats`	Im aktuellen Bild tatsächlich gerenderte Splat-Anzahl, der zentrale Eintrag zur Beurteilung der Render-Last
`Current Render Main Splats`	Im aktuellen Bild gerenderte Menge der Hauptdaten
`Current Render Environment Splats`	Im aktuellen Bild gerenderte Menge der Umgebungsdaten
`Total Nodes`	Gesamte Anzahl der Nodes
`Current Render Nodes`	Im aktuellen Bild gerenderte Anzahl der Nodes
`Visible Node Num`	Anzahl der sichtbaren Nodes
`LCC Draw Call`	Anzahl der vom Plugin erzeugten Draw Calls
`LCC Sort Num`	Anzahl der Sortierungen
`Camera Num`	Anzahl der am Rendering teilnehmenden Kameras

Wie damit umzugehen ist: Bleibt Current Render Splats dauerhaft nahe an der Grenze von Max Splat Num, greift die Anzahlbegrenzung bereits und die Bilddetails sind reduziert. Entweder die Grenze erhöhen (Leistung gegen Qualität) oder Level Factor anpassen, um Nodes an der Quelle zu reduzieren.

Die Gesamtgröße der Daten lässt sich auch aus Code lesen, siehe GetSplatNumber.

Zeiteinträge

Nach Stufe aufgeschlüsselte Kosten, um zu erkennen, welcher Schritt langsam ist:

Metrik	Zugehörige Stufe
`Render LCC`	Gesamte Render-Kosten des Plugins
`Traversal Time`	Node-Traversierung, die die in diesem Bild gerenderten Nodes bestimmt
`Determine Nodes Level`	Berechnung des Genauigkeits-Levels jedes Nodes
`Load Data To CPU`	Lesen der Daten in den Arbeitsspeicher
`Upload To GPU`	Upload der Daten in den Grafikspeicher
`Splat Sort`	Splat-Sortierung (für transluzentes Rendering erforderlich)
`Node Sort`	Node-Sortierung
`Build Mesh Batch`	Aufbau der Draw-Batches
`Wait Node Ready`	Warten darauf, dass Node-Daten bereit sind
`Component Update`	Aktualisierungen der Komponente
`Update Camera Info`	Aktualisierungen der Kamerainformationen
`Load Meta File`	Laden der Meta-Informationsdatei
`Load Index Data`	Laden der Index-Daten (LCC-Pipeline)
`Load Collision Data`	Laden der Kollisionsdaten
`Load Environment Data`	Laden der Umgebungsdaten
`Update Collision`	Aktualisierungen der Kollision
`Get Physics Trimesh Data`	Erzeugen des Kollisions-Mesh für die Physik
`Release Memory`	Freigabe von Arbeitsspeicher
`Preload Node`	Vorladen von Nodes
`Get From Cache`	Abrufen von Daten aus dem Cache
`Create Thread`	Erzeugen von Threads
`Draw Node Box`	Zeichnen der Node Bounds (nur bei aktivierter Debug-Visualisierung)

Wie damit umzugehen ist:

Ist Splat Sort hoch, kann die LCC-Pipeline Sort Factor erhöhen, um seltener zu sortieren
Ist Wait Node Ready hoch, kommt das Laden der Daten nicht mit, möglicherweise ein langsamer Datenträger oder zu wenige Threads
Ist Upload To GPU hoch, ist die pro Bild hochgeladene Menge groß, daher Level Factor oder Max Splat Num anpassen
Sind Update Collision und Get Physics Trimesh Data hoch, Max Load Collision Distance senken

Zum vollständigen Optimierungsablauf siehe Leitfaden zur Leistung.

Einträge zu Arbeits- und Grafikspeicher

Metrik	Bedeutung
`CPU Usage`	Vom Plugin belegter Arbeitsspeicher
`GPU Usage`	Vom Plugin belegter Grafikspeicher
`Position Data(For Raycast) Usage`	Bedarf der Positionsdaten für Strahlentests
`Collision Data Usage`	Bedarf der Kollisionsdaten
`CPU Occupy Percentage`	Prozentanteil des belegten Arbeitsspeichers
`GPU Occupy Percentage`	Prozentanteil des belegten Grafikspeichers

Die Prozenteinträge entsprechen den Freigabeschwellwerten in den Projekteinstellungen. Liegt der Bedarf längere Zeit nahe an Max GPU Usage Percetage For Free, löst die Ressourcenfreigabe häufig aus, was Ruckeln verursachen kann.

Zu den Zuweisungsregeln des Grafikspeichers und den Budget-Grenzen siehe Rendering.

Thread-Einträge

Metrik	Bedeutung
`Collision Loader Thread Num`	Anzahl der Threads zum Laden von Kollisionen
`Exporter Thread Num`	Anzahl der Exporter-Threads

Visualisierung der Node Bounds

Über die Schaltfläche Debug Node Bound unter der Kategorie Actions im Details-Panel des Actors umschalten oder in der Konsole ausführen:

r.Xgrids.DrawNodeBox 1

Das zeichnet die aktuell geladenen Nodes als Drahtgitter-Boxen. Die Farbe der Box entspricht dem Level des Nodes: rot, orange, gelb, grün, blau und violett folgen in dieser Reihenfolge, wobei rot das niedrigste Level (die höchste Genauigkeit) und weiß das höchste Level (die niedrigste Genauigkeit) ist.

Zu den Begriffen Node und Level siehe Rendering.

Wie es zu lesen ist:

In der Ferne weiterhin gerenderte rote Boxen bedeuten, dass die Genauigkeit zu hoch ist und Leistung verschwendet wird. Level Factor erhöhen
Überall in der Nähe kalt gefärbte Boxen bedeuten, dass die Genauigkeit zu stark heruntergedrückt wird und das Bild unscharf wirkt. Level Factor senken oder Start Level prüfen
Eine weit über der Erwartung liegende Anzahl an Boxen bedeutet, dass Max Distance möglicherweise zu groß gesetzt ist

Es funktioniert nur im Editor und in Development-Builds. Die zugehörige Code-Schnittstelle ist DebugNodeBound.

Visualisierung der Kollision

Über die Schaltfläche Show Collision unter der Kategorie Actions im Details-Panel des Actors umschalten oder in der Konsole ausführen:

r.xgrids.DrawCollision 1

Das zeichnet das Drahtgitter der geladenen Kollisionskörper.

Wie es zu lesen ist:

Überhaupt kein Drahtgitter: Die Daten enthalten keine Kollisionsdatei, oder bEnableCollision ist aus, siehe Voraussetzungen für Kollision
Drahtgitter nur in der Nähe: normales Verhalten, da Kollision nach Distanz nachgeladen wird und durch Max Load Collision Distance begrenzt ist
Das Drahtgitter ist gegenüber dem Bildinhalt versetzt: Die Kollisionsdaten passen nicht zu den Renderdaten, den technischen Support kontaktieren

Bei der Untersuchung nicht treffender Line Traces oder durch Geometrie fallender Charaktere dies zuerst aktivieren, um zu prüfen, ob die Kollision tatsächlich geladen wurde. Zum Lademechanismus siehe Kollision; die Code-Schnittstelle ist ShowCollision.

Log-Meldung	Bedeutung und Maßnahme
`LCC file :<path> does not exist.`	Der Pfad existiert nicht. Den Pfad prüfen; relative Pfade beziehen sich auf `Content`
`meta.lcc file :<path> load error,Please check.`	Das Auswerten der LCC1-Meta-Informationsdatei ist fehlgeschlagen, die Datei kann beschädigt sein
`Load Meta.lcc error,Please check your file!`	Wie oben
`Read index.bin error,path:<path>.`	Das Lesen der Index-Datei ist fehlgeschlagen. Prüfen, dass `index.bin` existiert und nicht beschädigt ist
`LCC4Unreal do not support this file format!`	Das Format wird nicht unterstützt, prüfen, dass die Erweiterung im unterstützten Bereich liegt
`The data file:<path> does not exist,Please check your file!`	Eine Datenchunk-Datei fehlt, das Datenverzeichnis kann unvollständig sein

Kollision

Log-Meldung	Bedeutung und Maßnahme
`There is neither collision.bin nor collision.lci in the folder:<path>, please check.`	Im Datenverzeichnis gibt es keine Kollisionsdatei, für diese Daten lässt sich Kollision daher nicht aktivieren
`Failed to open file <path>`	Das Öffnen der Kollisionsdatei ist fehlgeschlagen, Dateiberechtigungen und Integrität prüfen
`Read collision data error,path:<path>.`	Das Lesen der Kollisionsdaten ist fehlgeschlagen, die Datei kann beschädigt sein
`Invalid indices in collision data!`	Der Inhalt der Kollisionsdaten ist fehlerhaft, den technischen Support kontaktieren

Rendering

Log-Meldung	Bedeutung und Maßnahme
`r.PostProcessing.PropagateAlpha is 0. LCC4Unreal requires this to be enabled for correct rendering.`	Diese Option muss aktiviert sein, sonst ist das Alpha-Blending fehlerhaft. Das Plugin zeigt zusätzlich einen Hinweis
`Unlicensed: enabled clipping volumes limited to <N> ...`	Die Anzahl der Clipping-Volumen der kostenlosen Edition übersteigt das Kontingent und der Überschuss wird nicht gerendert. Siehe Editionen und Lizenzierung
`Unlicensed: enabled section planes limited to <N> ...`	Wie oben, für die Anzahl der Schnittebenen

GIS

Log-Meldung	Bedeutung und Maßnahme
`This lcc does not have RTK information!`	Die Daten enthalten keine geografischen RTK-Informationen, die geografische Platzierung lässt sich daher nicht nutzen
`MetaInfo's Offset has no 3 elements!`	Das Feld offset in den Meta-Informationen ist fehlerhaft, die Daten können ein Problem haben

Lizenzierung

Log-Meldung	Bedeutung und Maßnahme
`ProjectID is invalid; generate one in Project Settings (Project/Description). Refusing authentication.`	Das Projekt hat keine Project ID, eine in den Projekteinstellungen erzeugen
`Failed to decode AppKey, please check.`	Der Inhalt des AppKey ist unvollständig, ihn erneut kopieren
`Invalid AppKey, please check.`	Das Format des AppKey ist falsch
`Authorization has expired, please check.`	Die Lizenz ist abgelaufen, sie neu erzeugen
`AppKey has expired. Please generate a new one.`	Wie oben
`Authentication Failed: <message>`	Die vom Server zurückgegebene Fehlerursache, nach dem Meldungsinhalt handeln
`HTTP request failed`	Der Lizenzserver ist nicht erreichbar, das Netzwerk prüfen
`HTTP error! Status: <code>`	Der Server hat einen Fehlerstatuscode zurückgegeben
`Signature Verification Failed`	Die Signaturprüfung ist fehlgeschlagen, den technischen Support kontaktieren

Proxy Mesh

Log-Meldung	Bedeutung und Maßnahme
`has a null StaticMesh`	Dem Proxy-Mesh-Actor ist kein StaticMesh zugewiesen und er hat keine Wirkung. Wird einmal pro Instanz gemeldet

Was einer Problemmeldung beizufügen ist

Das Zusammenstellen der Punkte dieser Checkliste beschleunigt die Diagnose deutlich.

Plugin-Version und Engine-Version. Die Plugin-Version steht unten rechts im Plugin-Panel und findet sich außerdem über die Suche nach LCC4Unreal im Fenster Edit > Plugins der Engine.
Die vollständige Log-Datei aus dem Zeitpunkt des Problems. Die .log-Datei selbst bereitstellen, ungefiltert und nicht nur die einzelne Fehlerzeile. Der Kontext um das Log enthält häufig die für die Diagnose entscheidenden Informationen, und Filtern verliert diese Hinweise. Zum Speicherort des Logs siehe Das Plugin-Log ansehen.
Informationen zu den Daten. Format, ungefähre Größe (Total Splats) und ob Kollision enthalten ist.
Schritte zur Reproduktion. Ein minimaler Reproduktionsweg ausgehend von einem neuen Projekt ist am wertvollsten.
Hardware-Umgebung. Grafikkartenmodell, Treiberversion und Größe des Grafikspeichers.
Project ID. Bei Lizenzproblemen erforderlich; sie steht unter Project Settings > Project > Description.

Zu den Kontaktdaten siehe Kontakt.