docs: add DISCOVERSE 3DGS scene tutorial + AndroidTwin 4-cam rollout demo

- scripts/data_collection/download_discoverse_scenes.sh: pull packed PLY
  from tatp/DISCOVERSE-models on HF, decompress SuperSplat -> standard
  3DGS layout consumed by GaussianSensor. Default lab3, --all for the
  four indoor scenes (lab3, flower_table, discover_operation_studio,
  tsimf_library_0). Assets remain gitignored - this script is the only
  source of truth.
- scripts/data_collection/decompress_supersplat.py: PlayCanvas packed
  PLY -> x/y/z + f_dc_* + scale_* + rot_* + opacity. Required by the
  download script (sibling lookup).
- docs/discoverse_scenes.md: scene catalog, why-unpack rationale, render
  example, four non-obvious gotchas (don't render packed, floor 5th-pct,
  GS != MuJoCo intrinsics, GS coverage limited to training-cam hull).
- README.md: new showcase "DISCOVERSE 3DGS rooms x AndroidTwin multi-cam
  rollout" right after the kitchen demo. Documents the single shared
  world_T_gs alignment + the OpenGL->OpenCV Y-flip required for
  level-horizon world cams.
- docs/media/discoverse_lab3/{4cam_composite,head_cam,world_cam,
  world_back_cam,world_side_cam}.mp4: 920 KB total demo clips.

Author: dukaijie

README.md

@@ -95,6 +95,59 @@ uv run at-eval \
 (`MuGSRecorder`) lives at `androidtwin/envs/mugs_recorder.py` in the
 AndroidTwin repo and uses MuGS's standalone `GaussianSensor` API.
 
+### DISCOVERSE 3DGS rooms × AndroidTwin multi-cam rollout
+
+Four cameras, one rollout, one shared `world_T_gs` rigid alignment. The
+G1 + Inspire FTP stands via AMO inside the DISCOVERSE `lab3` 3DGS room;
+each frame is captured from the robot's first-person `head_cam` plus
+three world cams (front-diagonal, over-the-shoulder, low side hero).
+The composite below stitches all four panes — every panel is a hybrid
+MuGS render (3DGS bg + MuJoCo fg, alpha-blended per camera).
+
+[![4-cam DISCOVERSE lab3 composite](docs/media/discoverse_lab3/4cam_composite.mp4)](docs/media/discoverse_lab3/4cam_composite.mp4)
+
+| Camera | View |
+|---|---|
+| `robot/head_cam` (first-person, D435 mount, 47° down, 42° vfov) | [head_cam.mp4](docs/media/discoverse_lab3/head_cam.mp4) |
+| `world_cam` (front-diagonal) | [world_cam.mp4](docs/media/discoverse_lab3/world_cam.mp4) |
+| `world_back_cam` (over-the-shoulder back) | [world_back_cam.mp4](docs/media/discoverse_lab3/world_back_cam.mp4) |
+| `world_side_cam` (low hero shot) | [world_side_cam.mp4](docs/media/discoverse_lab3/world_side_cam.mp4) |
+
+Two pieces of plumbing make this work compared to the kitchen demo
+above:
+
+- **One alignment for all cams.** `MuGSRecorder` accepts a `world_T_gs`
+  4×4 transform that maps MJ-world → GS-world. Every simultaneous camera
+  applies the same transform to its live MJ pose, so the four views see
+  the same room from coherent perspectives without per-cam initial-pose
+  snapping.
+- **OpenGL → OpenCV Y-flip.** gsplat is OpenCV (+Y down). MuGS internally
+  negates column 2 of the cam rotation (Z forward), so the recorder
+  pre-negates column 1 in the `world_T_gs` branch. Without this, every
+  level-horizon world cam renders upside-down; the first-person head cam
+  survives unflipped only because its 47° pitch coincidentally lines up.
+
+Get the scene:
+
+```bash
+bash scripts/data_collection/download_discoverse_scenes.sh   # default: lab3
+```
+
+Render the demo (from the AndroidTwin repo, scene path adjusted):
+
+```bash
+.venv/bin/python examples/discoverse_room_rollout.py \
+  --bg-ply /path/to/MuGS/assets/scenes/discoverse_unpacked/lab3/point_cloud.ply \
+  --out-dir outputs/discoverse_lab3 \
+  --num-steps 120 --width 480 --height 360 \
+  --gs-fx 380 --gs-fy 380 --yaw-deg 180
+```
+
+See [`docs/discoverse_scenes.md`](docs/discoverse_scenes.md) for the
+scene catalog, alignment knobs (`yaw_deg`, GS focal, floor 5%-percentile,
+bbox-center vs median), and the training-cam convex-hull caveat that
+makes some camera placements render dim/noisy.
+
 ## Features
 
 ### Core Rendering

docs/discoverse_scenes.md

@@ -0,0 +1,97 @@
+# DISCOVERSE 3DGS scenes
+
+How to fetch and render the DISCOVERSE indoor 3DGS captures used by the
+multi-camera AndroidTwin demo (see [the showcase
+section](../README.md#discoverse-3dgs-rooms--androidtwin-multi-cam-rollout)
+of the top-level README).
+
+No scenes are tracked in this repo — `assets/scenes/*.ply` is `.gitignore`d.
+The download script is the only path.
+
+## What you get
+
+Four indoor 3DGS captures from the DISCOVERSE project:
+
+| Scene                       | Description                          | Packed (HF) | Unpacked |
+|-----------------------------|--------------------------------------|------------:|---------:|
+| `lab3`                      | Robotics lab corner (cabinet, desk)  |    ~5.5 MB |   ~23 MB |
+| `flower_table`              | Indoor scene with a flower table     |    ~7.9 MB |   ~33 MB |
+| `discover_operation_studio` | Operation studio room                |    ~8.4 MB |   ~36 MB |
+| `tsimf_library_0`           | Library reading area                 |     ~22 MB |   ~92 MB |
+
+Source: [`tatp/DISCOVERSE-models`](https://huggingface.co/tatp/DISCOVERSE-models)
+on Hugging Face, paths under `3dgs/scene/<name>/point_cloud.ply`.
+
+## Why the unpack step
+
+DISCOVERSE ships scenes in PlayCanvas **SuperSplat compressed** PLY format
+(chunked uint32 packed fields), not the official 3DGS schema. MuGS's
+`GaussianSensor` only consumes the unpacked layout (`x/y/z`, `f_dc_*`,
+`scale_*`, `rot_*`, `opacity`), so the script runs
+`decompress_supersplat.py` once per scene right after download.
+
+## Quick start
+
+```bash
+# default: lab3 only
+bash scripts/data_collection/download_discoverse_scenes.sh
+
+# everything
+bash scripts/data_collection/download_discoverse_scenes.sh --all
+
+# pick a subset
+bash scripts/data_collection/download_discoverse_scenes.sh lab3 flower_table
+```
+
+Outputs land in:
+
+```
+assets/scenes/discoverse/<scene>/point_cloud.ply          # packed (archival)
+assets/scenes/discoverse_unpacked/<scene>/point_cloud.ply # unpacked (renderable)
+```
+
+Override with `--dst-root <dir>` or env `DISCOVERSE_SCENE_ROOT=…`. The
+unpacked directory always appends `_unpacked` to the chosen root.
+
+## Dependencies
+
+- `curl` (or `wget`) for download.
+- `python3` with `numpy` and `plyfile` for the decompressor.
+
+## Render with MuGS
+
+```python
+from mugs.sensors import GaussianSensor, GaussianSensorConfig
+
+cfg = GaussianSensorConfig(
+    width=480,
+    height=360,
+    background_ply_path="assets/scenes/discoverse_unpacked/lab3/point_cloud.ply",
+    render_mode="3dgs_only",   # or "hybrid" with a MuJoCo foreground
+)
+sensor = GaussianSensor(cfg)
+```
+
+Pair with `MuGSRecorder` (in the AndroidTwin repo) for a full
+hybrid 3DGS + MuJoCo + MuJoCo-cam-tracking pipeline.
+
+## Gotchas worth knowing once
+
+1. **Don't render the packed PLY directly.** `GaussianSensor` will load it
+   and silently render noise. Always go through the unpack step.
+2. **Use `bbox.center` for xy, `percentile(z, 5)` for floor.** COLMAP
+   leaves a small number of sub-floor splats that drag `bbox.min[2]` ~1 m
+   below the actual floor; the 5th-percentile reading is robust. The
+   median xy is biased toward the densest splat cluster (e.g. lab3
+   `median_y=+0.72` vs `bbox_center_y=+0.20`) which can push virtual
+   cameras outside the training-cam convex hull — use the bbox center.
+3. **`gs_intrinsics ≠ MuJoCo intrinsics`.** Feed the GS scene's training
+   focal length (lab3 ≈ 380 px at 480×360) to the renderer, not the
+   MuJoCo camera's own `fx/fy`. A mismatch shows up as squashed or
+   stretched backgrounds.
+4. **GS coverage ≠ scene bbox.** Each capture only renders cleanly
+   *inside the convex hull of the training cameras*. lab3's training
+   cams are biased toward the GS `-X` half — virtual cameras placed in
+   the `+X` half will render dim/blurry noise. Use AndroidTwin's
+   `examples/dump_cam_params.py` to isolate a single camera's GS-only
+   render before composing a full multi-cam rollout.

docs/media/discoverse_lab3/4cam_composite.mp4

@@ -0,0 +1,196 @@
+"""Decompress SuperSplat / PlayCanvas packed 3DGS PLY → official 3DGS PLY.
+
+DISCOVERSE assets are stored in the PlayCanvas compressed format
+(`element chunk` + `element vertex` with uint32 packed_* fields).
+This script converts a single file or directory of such PLYs into
+the standard 3DGS layout (`x/y/z`, `f_dc_*`, `scale_*`, `rot_*`,
+`opacity`) that `mugs.sensors.GaussianSensor._load_official_ply`
+already understands.
+
+Bit layout (per playcanvas engine `gsplat-compressed-data.js`):
+  packed_position : uint32   11/10/11 bits  → lerp(chunk min,max)
+  packed_scale    : uint32   11/10/11 bits  → lerp(chunk min,max)  (log-space)
+  packed_rotation : uint32   2/10/10/10     → smallest-three quat
+  packed_color    : uint32   8/8/8/8        → R,G,B,A in [0,1]
+"""
+
+from __future__ import annotations
+
+import argparse
+import math
+from pathlib import Path
+
+import numpy as np
+from plyfile import PlyData, PlyElement
+
+
+SH_C0 = 0.28209479177387814
+
+
+def _unpack_unorm(values: np.ndarray, shift: int, bits: int) -> np.ndarray:
+    mask = (1 << bits) - 1
+    return ((values >> shift) & mask).astype(np.float64) / float(mask)
+
+
+def _smallest_three_quat(packed: np.ndarray) -> np.ndarray:
+    sel = (packed >> 30) & 0x3
+    a = _unpack_unorm(packed, 20, 10) - 0.5
+    b = _unpack_unorm(packed, 10, 10) - 0.5
+    c = _unpack_unorm(packed, 0, 10) - 0.5
+    s = math.sqrt(2.0)
+    a *= s
+    b *= s
+    c *= s
+    d2 = 1.0 - (a * a + b * b + c * c)
+    d = np.sqrt(np.clip(d2, 0.0, None))
+
+    quats = np.zeros((packed.shape[0], 4), dtype=np.float64)
+    # Convention used by playcanvas engine: ordering [x, y, z, w], the
+    # selector indexes the *largest* magnitude component. Official 3DGS
+    # PLYs store rot_0..rot_3 as [w, x, y, z], so map accordingly.
+    # playcanvas index 0->x, 1->y, 2->z, 3->w  -->  official wxyz idx
+    pc_to_wxyz = np.array([1, 2, 3, 0])
+    for pc_i in range(4):
+        mask = sel == pc_i
+        if not mask.any():
+            continue
+        out_idx = pc_to_wxyz[pc_i]
+        quats[mask, out_idx] = d[mask]
+        remaining_pc = [j for j in range(4) if j != pc_i]
+        remaining_out = pc_to_wxyz[remaining_pc]
+        quats[mask, remaining_out[0]] = a[mask]
+        quats[mask, remaining_out[1]] = b[mask]
+        quats[mask, remaining_out[2]] = c[mask]
+
+    quats /= np.linalg.norm(quats, axis=1, keepdims=True) + 1e-12
+    return quats
+
+
+def decompress_supersplat(plydata: PlyData) -> dict[str, np.ndarray]:
+    if "chunk" not in {e.name for e in plydata.elements}:
+        raise ValueError("not a compressed SuperSplat PLY (missing 'chunk' element)")
+
+    chunks = plydata["chunk"]
+    verts = plydata["vertex"]
+    n = len(verts)
+    chunk_size = 256
+    chunk_idx = np.minimum(np.arange(n) // chunk_size, len(chunks) - 1)
+
+    def per_vertex(field: str) -> np.ndarray:
+        return chunks[field][chunk_idx]
+
+    pmin = np.stack([per_vertex("min_x"), per_vertex("min_y"), per_vertex("min_z")], 1)
+    pmax = np.stack([per_vertex("max_x"), per_vertex("max_y"), per_vertex("max_z")], 1)
+    smin = np.stack(
+        [per_vertex("min_scale_x"), per_vertex("min_scale_y"), per_vertex("min_scale_z")],
+        1,
+    )
+    smax = np.stack(
+        [per_vertex("max_scale_x"), per_vertex("max_scale_y"), per_vertex("max_scale_z")],
+        1,
+    )
+
+    pp = verts["packed_position"].astype(np.uint32)
+    pn = np.stack(
+        [_unpack_unorm(pp, 21, 11), _unpack_unorm(pp, 11, 10), _unpack_unorm(pp, 0, 11)],
+        1,
+    )
+    positions = pmin + pn * (pmax - pmin)
+
+    ps = verts["packed_scale"].astype(np.uint32)
+    sn = np.stack(
+        [_unpack_unorm(ps, 21, 11), _unpack_unorm(ps, 11, 10), _unpack_unorm(ps, 0, 11)],
+        1,
+    )
+    log_scales = smin + sn * (smax - smin)
+
+    quats_wxyz = _smallest_three_quat(verts["packed_rotation"].astype(np.uint32))
+
+    pc = verts["packed_color"].astype(np.uint32)
+    r = _unpack_unorm(pc, 24, 8)
+    g = _unpack_unorm(pc, 16, 8)
+    b = _unpack_unorm(pc, 8, 8)
+    alpha = _unpack_unorm(pc, 0, 8)
+    color_bound_fields = chunks.data.dtype.names
+    if "min_r" in color_bound_fields:
+        rmin = per_vertex("min_r")
+        rmax = per_vertex("max_r")
+        gmin = per_vertex("min_g")
+        gmax = per_vertex("max_g")
+        bmin = per_vertex("min_b")
+        bmax = per_vertex("max_b")
+        r = rmin + r * (rmax - rmin)
+        g = gmin + g * (gmax - gmin)
+        b = bmin + b * (bmax - bmin)
+    colors_rgb = np.stack([r, g, b], 1)
+    colors_rgb = np.clip(colors_rgb, 1e-6, 1.0 - 1e-6)
+    alpha = np.clip(alpha, 1e-6, 1.0 - 1e-6)
+
+    # Convert color back to SH DC (the official format stores SH DC,
+    # then renderer does 0.5 + SH_C0 * dc). Inverse:
+    f_dc = (colors_rgb - 0.5) / SH_C0
+    # Opacity is stored pre-sigmoid in official format; renderer does sigmoid.
+    opacity_pre = np.log(alpha / (1.0 - alpha))
+
+    return {
+        "xyz": positions.astype(np.float32),
+        "f_dc": f_dc.astype(np.float32),
+        "scales_log": log_scales.astype(np.float32),
+        "rot_wxyz": quats_wxyz.astype(np.float32),
+        "opacity_pre": opacity_pre.astype(np.float32),
+    }
+
+
+def write_official_ply(out_path: Path, gaussians: dict[str, np.ndarray]) -> None:
+    n = gaussians["xyz"].shape[0]
+    dtype = [
+        ("x", "f4"), ("y", "f4"), ("z", "f4"),
+        ("nx", "f4"), ("ny", "f4"), ("nz", "f4"),
+        ("f_dc_0", "f4"), ("f_dc_1", "f4"), ("f_dc_2", "f4"),
+        ("opacity", "f4"),
+        ("scale_0", "f4"), ("scale_1", "f4"), ("scale_2", "f4"),
+        ("rot_0", "f4"), ("rot_1", "f4"), ("rot_2", "f4"), ("rot_3", "f4"),
+    ]
+    arr = np.zeros(n, dtype=dtype)
+    arr["x"], arr["y"], arr["z"] = gaussians["xyz"].T
+    arr["f_dc_0"], arr["f_dc_1"], arr["f_dc_2"] = gaussians["f_dc"].T
+    arr["opacity"] = gaussians["opacity_pre"]
+    arr["scale_0"], arr["scale_1"], arr["scale_2"] = gaussians["scales_log"].T
+    arr["rot_0"], arr["rot_1"], arr["rot_2"], arr["rot_3"] = gaussians["rot_wxyz"].T
+    el = PlyElement.describe(arr, "vertex")
+    PlyData([el], byte_order="<").write(str(out_path))
+
+
+def convert_file(src: Path, dst: Path) -> dict:
+    src = src.resolve()
+    plydata = PlyData.read(src)
+    g = decompress_supersplat(plydata)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    write_official_ply(dst, g)
+    bbox = g["xyz"].max(0) - g["xyz"].min(0)
+    return {
+        "src": str(src),
+        "dst": str(dst),
+        "n": g["xyz"].shape[0],
+        "bbox_m": tuple(round(float(x), 3) for x in bbox),
+        "center_m": tuple(round(float(x), 3) for x in g["xyz"].mean(0)),
+    }
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("src", type=Path, help="Compressed ply file or directory")
+    ap.add_argument("dst", type=Path, help="Output ply file or directory")
+    args = ap.parse_args()
+
+    if args.src.is_dir():
+        for ply in sorted(args.src.glob("*.ply")):
+            info = convert_file(ply, args.dst / ply.name)
+            print(info)
+    else:
+        info = convert_file(args.src, args.dst)
+        print(info)
+
+
+if __name__ == "__main__":
+    main()