VIEWER_DEBUG.md

Viewer Debugging Guide

The viewer now has extensive console logging to help diagnose issues.

How to Debug

1. Run the app:

   python app.py
   

2. Open the browser console:

   • Chrome/Edge: Press F12 or Ctrl+Shift+J (Windows) / Cmd+Option+J (Mac)
   • Firefox: Press F12 or Ctrl+Shift+K (Windows) / Cmd+Option+K (Mac)
   • Safari: Enable Developer menu in Preferences, then press Cmd+Option+C

3. Check the Console tab and look for these key messages:

Expected Console Messages

On Page Load:

DOM already loaded, initializing viewer in 100ms
initViewer called, isInitialized: false
Container found: <div...>
Canvas created and added
WebGL2 context created
Worker created
Starting render loop
✓ Viewer initialized successfully
Rendering black screen, waiting for data...  (repeats every 60 frames)

After Generating a Model:

=== Starting PLY load ===
URL: /gradio_api/file=outputs/splats/xxxxx/xxxxx.ply?v=xxxxx
Initialized? true
Worker? true
Fetching: /gradio_api/file=...
Response status: 200
ArrayBuffer size: XXXXX bytes
Magic bytes: Uint8Array(4) [112, 108, 121, 10]  (this is correct for PLY files)
PLY file sent to worker

[Worker] Message received: {ply: ArrayBuffer}
[Worker] Processing PLY buffer...
[Worker] Buffer processed, vertex count: XXXXX
[Worker] Generating texture...
[Worker] Texture generated and sent

Worker message received: {texdata: Uint32Array, ...}
Texture data: {texwidth: 2048, texheight: XXX, vertexCount: XXXXX}
✓ Successfully loaded XXXXX gaussians

First render with XXXXX vertices

Common Issues and Solutions

Issue 1: "Container #splat-container not found"

Problem: The viewer container isn't in the DOM yet Solution: This should auto-retry, but if it persists, check that the Gradio interface loaded correctly

Issue 2: "Failed to load: 404"

Problem: The PLY file URL is incorrect or the file doesn't exist Solution: Check that the generation completed successfully and the file was saved

Issue 3: Worker doesn't receive message

Problem: The fetch failed or the ArrayBuffer is empty Solution: Check the ArrayBuffer size in the console - it should be > 0

Issue 4: Worker error during processing

Problem: The PLY file format might be incompatible Solution: Check the magic bytes - should be [112, 108, 121, 10] which is "ply\n"

Issue 5: Black screen but no errors

Problem: vertexCount might be 0 or rendering issue Solution: Check that "Successfully loaded X gaussians" appears with X > 0

Quick Test

Run this in the browser console after the page loads:

console.log('Testing viewer state:');
console.log('Window function:', typeof window.__load_splat__);  // should be "function"
console.log('Container exists:', !!document.getElementById('splat-container'));  // should be true

Next Steps

Copy the console output and we can diagnose the exact issue!