Viewer: preload all frames in a client-side three.js player (smooth playback)

Replace gradio Model3D + Timer with a custom three.js point-cloud player
embedded via gr.HTML(head=..., js_on_load=...). All per-frame .glb point
clouds are loaded once into the scene; playback animates by toggling frame
visibility, so the points stay on screen the whole time (no per-frame
network/parse → no white flashes) and the full, un-subsampled cloud is kept.
Play/Pause, Speed (fps) and a scrub slider run entirely client-side; a hidden
file list bridges the served .glb URLs to the viewer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app.py

@@ -526,29 +526,21 @@ def run(
 
         _say(1.0, "Done.")
 
-        model3d = view_glbs[0] if view_glbs else None
         if not has_canon:
             log.append("WARNING: model produced no canonical output — canonical "
                        "video and point tracks were skipped (check the checkpoint).")
 
         status = "\n".join(f"• {m}" for m in log)
-        slider_update = gr.Slider(
-            minimum=0, maximum=max(1, N - 1), step=1, value=0,
-            label="Track point-cloud frame",
-            visible=bool(view_glbs) and N > 1,
-            interactive=N > 1,
-        )
-        play_row_update = gr.update(visible=bool(view_glbs) and N > 1)
+        # view_glbs is the per-frame track point cloud (.glb), glTF-aligned and
+        # track-colored. They go to the hidden file list, whose URLs the
+        # client-side three.js player preloads and animates (see VIEWER_JS).
         return (
-            model3d,
+            view_glbs or None,
             canonical_vid,
             depth_vid,
             normals_vid,
             tracks2d_vid,
             tracks_zip,
-            view_glbs,
-            slider_update,
-            play_row_update,
             status,
         )
     except gr.Error:
@@ -558,15 +550,6 @@ def run(
         raise gr.Error(f"Inference failed: {e}\n\n{tb[-1500:]}")
 
 
-def pick_frame(idx, view_glbs):
-    """Swap the 3D viewer to a different frame's track point cloud."""
-    if not view_glbs:
-        return None
-    idx = int(idx)
-    idx = max(0, min(idx, len(view_glbs) - 1))
-    return view_glbs[idx]
-
-
 # --------------------------------------------------------------------------- #
 # UI
 # --------------------------------------------------------------------------- #
@@ -583,11 +566,220 @@ temporally-consistent **3D point tracks**.
 [Code](https://github.com/kocasariumut/FaceAnything)
 """
 
+# --------------------------------------------------------------------------- #
+# Custom 3D viewer (client-side three.js).
+#
+# gradio's Model3D re-fetches and re-parses a .glb from the server on every
+# frame, so animating it flashes white (the next cloud isn't on the client yet).
+# Instead we load *every* frame's .glb once into a three.js scene and animate by
+# toggling which frame is visible — no per-frame network/parse, the points stay
+# on screen the whole time, and the full (un-subsampled) cloud is kept.
+# --------------------------------------------------------------------------- #
+THREE_HEAD = """
+<script src="https://cdn.jsdelivr.net/npm/three@0.137.0/build/three.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.137.0/examples/js/loaders/GLTFLoader.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.137.0/examples/js/controls/OrbitControls.js"></script>
+"""
+
+VIEWER_MARKUP = """
+<div class="fa-viewer-root" style="width:100%;">
+  <div class="fa-canvas-wrap" style="position:relative;width:100%;height:420px;background:#ffffff;border:1px solid #e5e7eb;border-radius:8px;overflow:hidden;">
+    <div class="fa-overlay" style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;color:#6b7280;font-family:sans-serif;font-size:14px;text-align:center;padding:0 16px;">Run a reconstruction to view the 3D point tracks here.</div>
+  </div>
+  <div class="fa-controls" style="display:none;gap:10px;align-items:center;padding:8px 4px 2px;font-family:sans-serif;font-size:13px;flex-wrap:wrap;">
+    <button class="fa-play" type="button" style="cursor:pointer;padding:4px 12px;border:1px solid #d1d5db;border-radius:6px;background:#f9fafb;">&#9654; Play</button>
+    <span style="display:inline-flex;align-items:center;gap:6px;">Speed <input class="fa-speed" type="range" min="1" max="30" step="1" value="12" style="width:90px;vertical-align:middle;"><span class="fa-fps">12 fps</span></span>
+    <input class="fa-scrub" type="range" min="0" max="0" step="1" value="0" style="flex:1;min-width:120px;vertical-align:middle;">
+    <span class="fa-frame" style="min-width:64px;text-align:right;color:#374151;">&ndash; / &ndash;</span>
+  </div>
+</div>
+"""
+
+# Runs once when the HTML component mounts; sets up the three.js scene and
+# exposes window.faViewer.load(urls) for the file bridge below to call.
+VIEWER_JS = """
+(function(){
+  if (element.__faInit) return;
+  element.__faInit = true;
+  var wrap = element.querySelector('.fa-canvas-wrap');
+  var overlay = element.querySelector('.fa-overlay');
+  var controls = element.querySelector('.fa-controls');
+  var playBtn = element.querySelector('.fa-play');
+  var speedEl = element.querySelector('.fa-speed');
+  var fpsEl = element.querySelector('.fa-fps');
+  var scrubEl = element.querySelector('.fa-scrub');
+  var frameEl = element.querySelector('.fa-frame');
+  if (!wrap) return;
+  var renderer, scene, camera, orbit, group;
+  var frames = [], cur = 0, playing = false, fps = 12, acc = 0, last = 0, loadToken = 0;
+
+  function waitThree(cb, tries){
+    tries = tries || 0;
+    if (window.THREE && THREE.GLTFLoader && THREE.OrbitControls) { cb(); }
+    else if (tries > 200) { setOverlay('Could not load the 3D viewer (three.js) \\u2014 check your network / ad-blocker.'); }
+    else { setTimeout(function(){ waitThree(cb, tries + 1); }, 60); }
+  }
+  function setOverlay(msg){
+    if (!overlay) return;
+    if (msg) { overlay.textContent = msg; overlay.style.display = 'flex'; }
+    else { overlay.style.display = 'none'; }
+  }
+  function resize(){
+    if (!renderer) return;
+    var w = wrap.clientWidth || 1, h = wrap.clientHeight || 1;
+    renderer.setSize(w, h, false);
+    camera.aspect = w / h; camera.updateProjectionMatrix();
+  }
+  function applyStyle(root){
+    root.traverse(function(o){
+      if (o.isPoints && o.material){
+        o.material.size = 2.5;
+        o.material.sizeAttenuation = false;
+        o.material.vertexColors = true;
+        o.material.needsUpdate = true;
+      }
+    });
+  }
+  function firstPoints(root){
+    var found = null;
+    root.traverse(function(o){ if (!found && o.isPoints) found = o; });
+    return found;
+  }
+  function showFrame(i){
+    if (!frames.length) return;
+    if (i < 0) i = 0;
+    if (i > frames.length - 1) i = frames.length - 1;
+    for (var k = 0; k < frames.length; k++){ frames[k].visible = (k === i); }
+    cur = i;
+    if (scrubEl) scrubEl.value = String(i);
+    if (frameEl) frameEl.textContent = (i + 1) + ' / ' + frames.length;
+  }
+  function fitCamera(){
+    if (!frames.length) return;
+    var box = new THREE.Box3().setFromObject(frames[0]);
+    if (box.isEmpty()) return;
+    var c = box.getCenter(new THREE.Vector3());
+    var s = box.getSize(new THREE.Vector3());
+    var r = Math.max(s.x, s.y, s.z) * 0.5 || 0.5;
+    var d = (r / Math.tan(camera.fov * Math.PI / 360)) * 1.7;
+    orbit.target.copy(c);
+    camera.near = Math.max(d / 200, 0.0005);
+    camera.far = d * 50 + r * 20;
+    camera.position.set(c.x, c.y, c.z + d);
+    camera.updateProjectionMatrix();
+    orbit.update();
+  }
+  function clearFrames(){
+    for (var k = 0; k < frames.length; k++){
+      group.remove(frames[k]);
+      if (frames[k].geometry) frames[k].geometry.dispose();
+      if (frames[k].material) frames[k].material.dispose();
+    }
+    frames = []; cur = 0;
+  }
+  function play(){ if (frames.length < 2) return; playing = true; last = 0; acc = 0; if (playBtn) playBtn.innerHTML = '\\u23F8 Pause'; }
+  function pause(){ playing = false; if (playBtn) playBtn.innerHTML = '\\u25B6 Play'; }
+  function toggle(){ if (playing) pause(); else play(); }
+  function animate(ts){
+    requestAnimationFrame(animate);
+    if (orbit) orbit.update();
+    if (playing && frames.length > 1){
+      if (!last) last = ts;
+      acc += (ts - last); last = ts;
+      var interval = 1000 / Math.max(1, fps);
+      if (acc >= interval){
+        var steps = Math.floor(acc / interval);
+        acc -= steps * interval;
+        showFrame((cur + steps) % frames.length);
+      }
+    } else { last = ts; }
+    if (renderer && scene && camera) renderer.render(scene, camera);
+  }
+  function initThree(){
+    if (renderer) return;
+    renderer = new THREE.WebGLRenderer({ antialias: true, alpha: false });
+    renderer.setPixelRatio(1);
+    renderer.setClearColor(0xffffff, 1);
+    if (THREE.sRGBEncoding) renderer.outputEncoding = THREE.sRGBEncoding;
+    renderer.domElement.style.display = 'block';
+    renderer.domElement.style.width = '100%';
+    renderer.domElement.style.height = '100%';
+    wrap.appendChild(renderer.domElement);
+    scene = new THREE.Scene();
+    scene.background = new THREE.Color(0xffffff);
+    camera = new THREE.PerspectiveCamera(50, 1, 0.001, 1000);
+    camera.position.set(0, 0, 2);
+    orbit = new THREE.OrbitControls(camera, renderer.domElement);
+    orbit.enableDamping = true; orbit.dampingFactor = 0.1;
+    group = new THREE.Group();
+    scene.add(group);
+    resize();
+    if (window.ResizeObserver) { new ResizeObserver(resize).observe(wrap); }
+    else { window.addEventListener('resize', resize); }
+    requestAnimationFrame(animate);
+  }
+  function finishLoad(token, loaded){
+    if (token !== loadToken) return;
+    frames = loaded.filter(function(p){ return p; });
+    if (!frames.length){ setOverlay('Failed to load the 3D point clouds.'); return; }
+    for (var k = 0; k < frames.length; k++){ frames[k].visible = false; group.add(frames[k]); }
+    setOverlay('');
+    if (controls) controls.style.display = 'flex';
+    if (scrubEl){ scrubEl.min = '0'; scrubEl.max = String(frames.length - 1); scrubEl.value = '0'; }
+    fitCamera();
+    showFrame(0);
+    if (frames.length > 1) play();
+  }
+  function load(urls){
+    waitThree(function(){
+      initThree();
+      var token = ++loadToken;
+      pause();
+      clearFrames();
+      if (controls) controls.style.display = 'none';
+      if (!urls || !urls.length){ setOverlay('No 3D point tracks for this run.'); return; }
+      setOverlay('Loading 3D sequence\\u2026 0 / ' + urls.length);
+      var loader = new THREE.GLTFLoader();
+      var loaded = new Array(urls.length);
+      var done = 0;
+      function tick(){
+        done++;
+        setOverlay('Loading 3D sequence\\u2026 ' + done + ' / ' + urls.length);
+        if (done === urls.length) finishLoad(token, loaded);
+      }
+      urls.forEach(function(url, idx){
+        loader.load(url, function(gltf){
+          if (token !== loadToken) return;
+          var pts = firstPoints(gltf.scene);
+          if (pts){ applyStyle(pts); loaded[idx] = pts; }
+          tick();
+        }, undefined, function(){ if (token === loadToken){ loaded[idx] = null; tick(); } });
+      });
+    });
+  }
+  if (playBtn) playBtn.addEventListener('click', toggle);
+  if (speedEl) speedEl.addEventListener('input', function(){ fps = parseInt(speedEl.value, 10) || 12; if (fpsEl) fpsEl.textContent = fps + ' fps'; });
+  if (scrubEl) scrubEl.addEventListener('input', function(){ pause(); showFrame(parseInt(scrubEl.value, 10) || 0); });
+  window.faViewer = { load: load, play: play, pause: pause, setFrame: showFrame };
+  waitThree(function(){ initThree(); });
+})();
+"""
+
+# Bridge: when the hidden file list (served .glb URLs) changes, hand the URLs to
+# the three.js viewer. Runs purely client-side (no server round-trip).
+ANIM_BRIDGE_JS = """
+(files) => {
+  try {
+    var list = (files || []).map(function(f){ return f && (f.url || f.path); }).filter(Boolean);
+    if (window.faViewer) { window.faViewer.load(list); }
+  } catch (e) { console.error('faViewer load error', e); }
+}
+"""
+
 
 def build_demo():
     with gr.Blocks(title="Face Anything") as demo:
         gr.Markdown(DESCRIPTION)
-        view_state = gr.State([])
 
         with gr.Row():
             # ---------------- inputs ----------------
@@ -645,24 +837,18 @@ def build_demo():
 
             # ---------------- outputs ----------------
             with gr.Column(scale=1):
-                model3d = gr.Model3D(
-                    label="3D point cloud with colorful tracks",
-                    clear_color=[1.0, 1.0, 1.0, 1.0],
-                    height=420,
+                gr.Markdown("**3D point cloud with colorful tracks**  ·  "
+                            "loads the whole sequence, then plays smoothly")
+                # client-side three.js player: all frames preloaded once, then
+                # animated by visibility toggle (no per-frame reload → no white
+                # flashes; full, un-subsampled cloud). See VIEWER_JS above.
+                viewer = gr.HTML(
+                    value=VIEWER_MARKUP, head=THREE_HEAD, js_on_load=VIEWER_JS,
+                    show_label=False,
                 )
-                frame_slider = gr.Slider(
-                    0, 1, value=0, step=1, visible=False,
-                    label="Track point-cloud frame")
-                # play / pause / speed — animate the point cloud over time
-                with gr.Row(visible=False) as play_row:
-                    play_btn = gr.Button("▶ Play", size="sm")
-                    pause_btn = gr.Button("⏸ Pause", size="sm")
-                    play_speed = gr.Slider(
-                        1, 20, value=8, step=1, label="Speed (fps)",
-                        info="Frames/second. Smoothness depends on point-cloud "
-                             "size (each frame is reloaded); pause to orbit freely.")
-                play_timer = gr.Timer(1.0 / 8, active=False)
-                playing = gr.State(False)
+                # hidden: run() puts the per-frame .glb files here so gradio
+                # serves them; ANIM_BRIDGE_JS hands their URLs to the viewer.
+                anim_files = gr.File(file_count="multiple", visible=False)
                 tracks_zip = gr.File(
                     label="Download point clouds (.zip: tracks/ + points/)")
                 with gr.Tab("Canonical (2D)"):
@@ -683,34 +869,12 @@ def build_demo():
             inputs=[files, video, mode, process_res, remove_bg,
                     conf_percentile, n_tracks, track_k, track_threshold,
                     fps, max_frames],
-            outputs=[model3d, canonical_vid, depth_vid, normals_vid, tracks2d_vid,
-                     tracks_zip, view_state, frame_slider, play_row, status],
+            outputs=[anim_files, canonical_vid, depth_vid, normals_vid,
+                     tracks2d_vid, tracks_zip, status],
             concurrency_limit=1,
         )
-        # .release (not .change) so the viewer reloads only when you let go of the
-        # slider — smoother than reloading a glb on every drag tick.
-        frame_slider.release(pick_frame, inputs=[frame_slider, view_state],
-                             outputs=model3d)
-
-        # ---------------- playback (dynamic point cloud over time) ----------------
-        def _advance(idx, view_glbs):
-            """Timer tick: hop to the next frame's point cloud, looping at the end."""
-            if not view_glbs:
-                return gr.update(), gr.update()
-            nxt = (int(idx) + 1) % len(view_glbs)
-            return view_glbs[nxt], nxt
-
-        play_timer.tick(_advance, inputs=[frame_slider, view_state],
-                        outputs=[model3d, frame_slider], show_progress="hidden")
-        play_btn.click(
-            lambda f: (gr.Timer(value=1.0 / float(f), active=True), True),
-            inputs=[play_speed], outputs=[play_timer, playing])
-        pause_btn.click(
-            lambda: (gr.Timer(active=False), False),
-            outputs=[play_timer, playing])
-        play_speed.change(
-            lambda f, p: gr.Timer(value=1.0 / float(f), active=bool(p)),
-            inputs=[play_speed, playing], outputs=[play_timer])
+        # when the served .glb list changes, push the URLs to the three.js player
+        anim_files.change(None, inputs=anim_files, outputs=None, js=ANIM_BRIDGE_JS)
 
         # ---------------- examples (thumbnail shown, click to load + run) ----------------
         ex40 = sorted(glob.glob(os.path.join(APP_DIR, "examples", "seq40", "*.png")))[:MAX_IMAGES]
@@ -718,9 +882,8 @@ def build_demo():
             run_inputs = [files, video, mode, process_res, remove_bg,
                           conf_percentile, n_tracks, track_k, track_threshold,
                           fps, max_frames]
-            run_outputs = [model3d, canonical_vid, depth_vid, normals_vid,
-                           tracks2d_vid, tracks_zip, view_state, frame_slider,
-                           play_row, status]
+            run_outputs = [anim_files, canonical_vid, depth_vid, normals_vid,
+                           tracks2d_vid, tracks_zip, status]
 
             def _thumb():
                 return gr.Image(value=ex40[0], height=150, show_label=False,