docs: real-image hero GIF (real footage -> V-JEPA 2 -> surprise)

Replace the synthetic occupancy hero with one built from REAL photographs: a
panned real-video clip fed to the real V-JEPA 2 model; surprise stays low while
the camera pans and spikes when the scene cuts. The old imagination GIF moves
into the RViz section where it belongs.

- tools/gif: gen_data `hero` (downloads picsum/Unsplash real photos, picks the
  3 most-different scenes, primes the clip buffer, runs V-JEPA 2) +
  render_hero.html + build.sh target.
- tools/pages: hero.gif becomes the landing hero; imagination joins the gallery.

Author: rsasaki0109

README.md

@@ -12,10 +12,11 @@ using *existing* World Models in robotics and autonomous driving.**
 > score trajectories, visualize imagination in RViz, and export rosbag2 data to
 > robot-learning datasets.
 
-![imagined future occupancy + risk](docs/imagination.gif)
+![real video through V-JEPA 2, surprise spikes on scene changes](docs/hero.gif)
 
-<sub>Imagined `FutureOccupancy` (green = near, red = far) and action-conditioned
-`RiskScore` from one ROS 2 call — here the GPU-free `dummy` adapter.</sub>
+<sub>Real footage → the real **V-JEPA 2** video model on a GPU → **surprise**:
+the latent stays calm while the camera pans and spikes the instant the scene
+cuts. Actual model output on real photographs.</sub>
 
 ## Highlights
 
@@ -113,7 +114,11 @@ risk readout on top — all from the GPU-free dummy model.
 ros2 launch world_model_viz imagination_demo.launch.py     # rviz:=false on headless
 ```
 
-The viewer republishes `MarkerArray` on `/world_model_viz/imagination`.
+![imagined future occupancy + risk](docs/imagination.gif)
+
+<sub>Top-down: a robot and an obstacle whose future occupancy the model predicts
+(green = soon → red = later), with the risk of the planned action. The viewer
+republishes `MarkerArray` on `/world_model_viz/imagination`.</sub>
 
 ### 4. See the imagination (Foxglove)
 

docs/hero.gif

@@ -16,10 +16,12 @@ FPS_imagination=12 ; FRAMES_imagination=32
 FPS_nav2=11        ; FRAMES_nav2=43
 FPS_ijepa=6        ; FRAMES_ijepa=18
 FPS_compare=6      ; FRAMES_compare=18
+FPS_hero=6         ; FRAMES_hero=24
 OUT_imagination=imagination.gif
 OUT_nav2=nav2_scoring.gif
 OUT_ijepa=ijepa_surprise.gif
 OUT_compare=jepa_compare.gif
+OUT_hero=hero.gif
 
 build_one() {
   local kind="$1" work; work="$(mktemp -d)"
@@ -37,7 +39,7 @@ build_one() {
 }
 
 case "${1:-all}" in
-  all) build_one imagination; build_one nav2; build_one ijepa; build_one compare ;;
-  imagination|nav2|ijepa|compare) build_one "$1" ;;
-  *) echo "usage: $0 [imagination|nav2|ijepa|compare|all]"; exit 2 ;;
+  all) build_one imagination; build_one nav2; build_one ijepa; build_one compare; build_one hero ;;
+  imagination|nav2|ijepa|compare|hero) build_one "$1" ;;
+  *) echo "usage: $0 [imagination|nav2|ijepa|compare|hero|all]"; exit 2 ;;
 esac

tools/gif/build.sh

@@ -146,11 +146,67 @@ def gen_compare():
     return {"frames": out}
 
 
+def gen_hero():
+    """Hero GIF: REAL photographs panned into a video, fed to the real V-JEPA 2
+    encoder; surprise spikes at scene cuts. Needs network (picsum.photos, fixed
+    seeds, Unsplash-licensed) + a GPU. Output is the derived GIF, not the photos.
+    """
+    import base64
+    import io
+    import urllib.request
+    from PIL import Image
+
+    W, Hh, CROP, PAN = 512, 384, 384, 8
+    candidates = ["forest", "ocean", "city", "desert", "snow", "market"]
+
+    def fetch(seed):
+        url = f"https://picsum.photos/seed/{seed}/{W}/{Hh}"
+        data = urllib.request.urlopen(url, timeout=30).read()
+        return Image.open(io.BytesIO(data)).convert("RGB")
+
+    imgs = [fetch(s) for s in candidates]
+    means = [np.asarray(im.resize((32, 32)), np.float32).reshape(-1, 3).mean(0) for im in imgs]
+    # greedily pick the 3 most mutually-different scenes -> punchier cuts
+    chosen = [0]
+    while len(chosen) < 3:
+        best, bestd = None, -1
+        for i in range(len(imgs)):
+            if i in chosen:
+                continue
+            d = min(float(np.linalg.norm(means[i] - means[c])) for c in chosen)
+            if d > bestd:
+                best, bestd = i, d
+        chosen.append(best)
+
+    def crop(im, k):
+        x = int((W - CROP) * k / (PAN - 1))
+        return np.asarray(im.crop((x, 0, x + CROP, CROP)).resize((256, 256), Image.BILINEAR)).astype(np.uint8)
+
+    frames = [crop(imgs[c], k) for c in chosen for k in range(PAN)]
+
+    wm = load_model("vjepa2", entry="vjepa2_vit_large", device="cuda", dtype="float16", clip_len=16)
+    for _ in range(16):                       # prime the clip buffer (no warmup blip)
+        wm.predict_future(Observation(image=frames[0]), horizon=1)
+    wm.reset()
+
+    out = []
+    for f in frames:
+        r = float(wm.predict_future(Observation(image=f), horizon=1).risk)
+        thumb = Image.fromarray(f).resize((150, 150), Image.BILINEAR)
+        buf = io.BytesIO()
+        thumb.save(buf, "JPEG", quality=82)
+        out.append({"img": "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode(),
+                    "surprise": round(r, 4)})
+    cuts = [PAN, 2 * PAN]
+    return {"frames": out, "cuts": cuts}
+
+
 GENERATORS = {
     "imagination": gen_imagination,
     "nav2": gen_nav2,
     "ijepa": gen_ijepa,
     "compare": gen_compare,
+    "hero": gen_hero,
 }
 
 

tools/gif/gen_data.py

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<style>html,body{margin:0;background:#1b1b20}#c{display:block}</style></head>
+<body>
+<canvas id="c" width="760" height="420"></canvas>
+<script>
+const ctx=document.getElementById('c').getContext('2d');
+const PX0=392,PX1=734,PY0=110,PY1=300,THR=0.05;
+function text(s,x,y,sz,col,al){ctx.fillStyle=col;ctx.font=`${sz}px system-ui,sans-serif`;ctx.textAlign=al||'left';ctx.fillText(s,x,y);}
+function xmap(k,N){return PX0+(N<2?0:k/(N-1))*(PX1-PX0);}
+
+window.setData=(D)=>{
+  window.DATA=D;
+  window.SMAX=Math.max(0.1, Math.max(...D.frames.map(f=>f.surprise))*1.15);
+  window.IMGS=D.frames.map(f=>{const im=new Image();im.src=f.img;return im;});
+  Promise.all(window.IMGS.map(im=>im.decode().catch(()=>{}))).then(()=>{window.imagesReady=true;});
+};
+function ymap(s){return PY1-Math.max(0,Math.min(1,s/window.SMAX))*(PY1-PY0);}
+
+function renderFrame(i){
+  const D=window.DATA,F=D.frames,N=F.length,s=F[i].surprise,anom=s>THR;
+  ctx.fillStyle='#1b1b20';ctx.fillRect(0,0,760,420);
+  text('A World Model watches real video',28,32,21,'#f0f0f3');
+  text('real footage → V-JEPA 2 → surprise · the latent jumps when the scene changes',28,54,13,'#9aa0ad');
+  text('real photographs (picsum/Unsplash) · V-JEPA 2 ViT-L · GPU',28,408,12,'#6a6a74');
+
+  // real camera frame
+  const IX=28,IY=72,IS=300;
+  ctx.fillStyle='#000';ctx.fillRect(IX,IY,IS,IS);
+  if(window.IMGS&&window.IMGS[i])ctx.drawImage(window.IMGS[i],IX,IY,IS,IS);
+  ctx.strokeStyle=anom?'#ff5a4a':'#33333c';ctx.lineWidth=anom?5:1;ctx.strokeRect(IX-0.5,IY-0.5,IS+1,IS+1);
+  text('camera',IX+10,IY+24,15,'#fff');
+  if(anom){text('● scene change',IX+IS-12,IY+24,15,'#ff5a4a','right');}
+
+  // surprise sparkline
+  text('surprise (latent novelty)',PX0,PY0-14,14,'#9a9aa6');
+  ctx.strokeStyle='#33333c';ctx.lineWidth=1;ctx.strokeRect(PX0-0.5,PY0-0.5,PX1-PX0+1,PY1-PY0+1);
+  ctx.setLineDash([5,4]);ctx.strokeStyle='rgba(255,90,74,0.5)';
+  ctx.beginPath();ctx.moveTo(PX0,ymap(THR));ctx.lineTo(PX1,ymap(THR));ctx.stroke();ctx.setLineDash([]);
+  text('alert',PX1,ymap(THR)-5,11,'rgba(255,120,108,0.85)','right');
+  // faint full + bright up-to-i
+  ctx.strokeStyle='rgba(140,140,152,0.28)';ctx.lineWidth=2;ctx.beginPath();
+  F.forEach((f,k)=>{const x=xmap(k,N),y=ymap(f.surprise);k?ctx.lineTo(x,y):ctx.moveTo(x,y);});ctx.stroke();
+  ctx.strokeStyle='#5ad1ff';ctx.lineWidth=3;ctx.beginPath();
+  for(let k=0;k<=i;k++){const x=xmap(k,N),y=ymap(F[k].surprise);k?ctx.lineTo(x,y):ctx.moveTo(x,y);}ctx.stroke();
+  const cx=xmap(i,N),cy=ymap(s);
+  ctx.fillStyle=anom?'#ff5a4a':'#5ad1ff';if(anom){ctx.shadowColor='#ff5a4a';ctx.shadowBlur=14;}
+  ctx.beginPath();ctx.arc(cx,cy,6,0,7);ctx.fill();ctx.shadowBlur=0;
+
+  text('surprise',PX0,PY1+34,13,'#9a9aa6');
+  text(s.toFixed(3),PX0,PY1+64,26,anom?'#ff5a4a':'#5ad1ff');
+  text('low while the camera pans,',PX1,PY1+28,13,'#8b8b96','right');
+  text('high the instant the scene cuts',PX1,PY1+48,13,'#8b8b96','right');
+}
+window.renderFrame=renderFrame;window.__ready=true;
+</script>
+</body></html>

tools/gif/render_hero.html

@@ -17,13 +17,14 @@
 REPO_URL = "https://github.com/rsasaki0109/worldmodels_ros2"
 
 CAPTIONS = {
-    "imagination.gif": "Imagined future occupancy + risk from one ROS 2 call (dummy).",
+    "hero.gif": "Real footage → V-JEPA 2 → surprise; the latent spikes when the scene cuts.",
+    "imagination.gif": "Top-down: predicted future occupancy of an obstacle (green→red) + risk.",
     "jepa_compare.gif": "Same camera stream, two real World Models: I-JEPA vs V-JEPA 2 surprise.",
     "nav2_scoring.gif": "Nav2 candidate paths ranked by model-based risk; safest highlighted.",
     "ijepa_surprise.gif": "Real I-JEPA surprise spiking on scene changes (GPU).",
 }
-HERO = "imagination.gif"
-ORDER = ["jepa_compare.gif", "nav2_scoring.gif", "ijepa_surprise.gif"]
+HERO = "hero.gif"
+ORDER = ["jepa_compare.gif", "imagination.gif", "nav2_scoring.gif", "ijepa_surprise.gif"]
 
 
 def _card(gif: str) -> str: