Update README.md

README.md

@@ -1,6 +1,6 @@
-<div align="center">
-  <img src="assets/teaser.png" width="100%">
+![image](https://cdn-uploads.huggingface.co/production/uploads/685631e960baba83d051fe31/D5dZEyHqlNc4kC-qH2IkI.png)
 
+<div align="center">
 <h1>LingBot-Map: Geometric Context Transformer for Streaming 3D Reconstruction</h1>
 
 Robbyant Team
@@ -32,9 +32,63 @@ LingBot-Map has focused on:
 
 ---
 
-# ⚙️ Quick Start
+## 📑 Table of Contents
+
+<details>
+<summary>Click to expand</summary>
+
+- [📰 News](#-news)
+- [📋 TODO](#-todo)
+- [⚙️ Installation](#️-installation)
+- [📦 Model Download](#-model-download)
+- [🚀 Quick Start](#-quick-start)
+- [🎬 Interactive Demo (`demo.py`)](#-interactive-demo-demopy)
+  - [Try the Example Scenes](#try-the-example-scenes)
+  - [Streaming with Keyframe Interval](#streaming-with-keyframe-interval)
+  - [Windowed Inference (for long sequences, >3000 frames)](#windowed-inference-for-long-sequences-3000-frames)
+  - [Sky Masking](#sky-masking)
+  - [Visualization Options](#visualization-options)
+  - [Performance & Memory](#performance--memory)
+- [🎥 Offline Rendering Pipeline (`demo_render/batch_demo.py`)](#-offline-rendering-pipeline-demo_renderbatch_demopy)
+- [📜 License](#-license)
+- [📖 Citation](#-citation)
+- [✨ Acknowledgments](#-acknowledgments)
+
+</details>
+
+---
+
+## 📰 News
+
+- **2026-06-28** — Fixed an SDPA KV cache bug. **The SDPA backend now performs better on long sequences**. We still recommend the FlashInfer backend for the best performance.
+- **2026-05-25** — 📊 **Evaluation benchmark released**. We released the evaluation scripts for KITTI and Oxford Spires — see [benchmark/](benchmark/) for the pipeline, and run [`preprocess/oxford.py`](preprocess/oxford.py) to prepare Oxford Spires data before evaluation.
+- **2026-04-29** — 📹 **Long-video demo released**. We released a very-long-video example (~25 000 frames, 13-minute indoor walkthrough) rendered with the offline pipeline — see [Worked Example](#worked-example--long-indoor-walkthrough-25-000-frames-13-minutes) for the command, flag rationale, and rendered output.
+- **2026-04-27** — 🚀 **LingBot-Map accelerated**. Pull the latest `main` and run `python demo.py --compile ...` or `python gct_profile.py --backend flashinfer --dtype bf16 --compile` to verify on your hardware.
+- **2026-04-24** — Fixed a FlashInfer KV cache bug where `--keyframe_interval > 1` silently cached non-keyframes. **You should now see better pose and reconstruction quality when running with more than 320 frames**.
+
+---
+
+## 📋 TODO
+
+- ✅ Release evaluation benchmark
+  - ✅ Oxford Spires dataset
+  - ✅ KITTI dataset
+  - ✅ VBR dataset
+  - ✅ Droid-W dataset
+  - ✅ TUM-D dataset
+  - ✅ 7-scenes dataset
+  - ✅ ETH3D dataset
+  - ✅ Tanks and Temples dataset
+  - ✅ NRGBD dataset
+- ✅ Release demo scripts
+  - ✅ Indoor long-video demo ([Featured indoor walkthrough](#-featured-indoor-walkthrough-25-000-frames-13-minutes))
+  - ✅ Outdoor long-video demo
+  - ✅ LingBot-World demo ([Worked example](#worked-example--lingbot-world-scenes))
+  - ✅ Aerial long-video demo
+
+---
 
-## Installation
+## ⚙️ Installation
 
 **1. Create conda environment**
 
@@ -46,9 +100,10 @@ conda activate lingbot-map
 **2. Install PyTorch (CUDA 12.8)**
 
 ```bash
-pip install torch==2.9.1 torchvision==0.24.1 --index-url https://download.pytorch.org/whl/cu128
+pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128
 ```
 
+> PyTorch 2.8.0 is the recommended version because NVIDIA Kaolin (required by the batch rendering pipeline) has prebuilt wheels for `torch-2.8.0_cu128`. If you only need `demo.py` you may use a newer PyTorch, but the batch renderer then requires building Kaolin from source.
 > For other CUDA versions, see [PyTorch Get Started](https://pytorch.org/get-started/locally/).
 
 **3. Install lingbot-map**
@@ -59,15 +114,15 @@ pip install -e .
 
 **4. Install FlashInfer (recommended)**
 
-FlashInfer provides paged KV cache attention for efficient streaming inference:
+FlashInfer provides paged KV cache attention for efficient streaming inference. It is a pure-Python package that JIT-compiles CUDA kernels on first use, so a single wheel works across CUDA/PyTorch versions:
 
 ```bash
-# CUDA 12.8 + PyTorch 2.9
-pip install flashinfer-python -i https://flashinfer.ai/whl/cu128/torch2.9/
+pip install --index-url https://pypi.org/simple flashinfer-python
 ```
 
-> For other CUDA/PyTorch combinations, see [FlashInfer installation](https://docs.flashinfer.ai/installation.html).
-> If FlashInfer is not installed, the model falls back to SDPA (PyTorch native attention) via `--use_sdpa`.
+> `--index-url https://pypi.org/simple` is only needed if your default pip index is an internal mirror that doesn't have `flashinfer-python`.
+> (Optional) For faster first-use, you can additionally install a CUDA-specific JIT cache: `pip install flashinfer-jit-cache -f https://flashinfer.ai/whl/cu128/flashinfer-jit-cache/`.
+> See [FlashInfer installation](https://docs.flashinfer.ai/installation.html) for details. If FlashInfer is not installed, the model falls back to SDPA (PyTorch native attention) via `--use_sdpa`.
 
 **5. Visualization dependencies (optional)**
 
@@ -75,43 +130,129 @@ pip install flashinfer-python -i https://flashinfer.ai/whl/cu128/torch2.9/
 pip install -e ".[vis]"
 ```
 
-# 📦 Model Download
+## 📦 Model Download
 
 | Model Name | Huggingface Repository | ModelScope Repository | Description |
 | :--- | :--- | :--- | :--- |
-| lingbot-map | [robbyant/lingbot-map](https://huggingface.co/robbyant/lingbot-map) | [Robbyant/lingbot-map](https://www.modelscope.cn/models/Robbyant/lingbot-map) | Base model checkpoint (4.63 GB) |
+| lingbot-map-long | [robbyant/lingbot-map](https://huggingface.co/robbyant/lingbot-map) | [Robbyant/lingbot-map](https://www.modelscope.cn/models/Robbyant/lingbot-map) | Better suited for long sequences and large scale scenes. |
+| lingbot-map | [robbyant/lingbot-map](https://huggingface.co/robbyant/lingbot-map) | [Robbyant/lingbot-map](https://www.modelscope.cn/models/Robbyant/lingbot-map) | Balanced checkpoint (used in paper, benchmark and offline demo) — trade off all-around performance across short and long sequences. |
+| lingbot-map-stage1 | [robbyant/lingbot-map](https://huggingface.co/robbyant/lingbot-map) | [Robbyant/lingbot-map](https://www.modelscope.cn/models/Robbyant/lingbot-map) | Stage-1 training checkpoint of lingbot-map — can be loaded into the VGGT model for bidirectional inference (c2w). |
 
-# 🎬 Demo
+> 🚧 **Coming soon:** we're training an stronger model that supports longer sequences — stay tuned.
 
-### Streaming Inference from Images
+## 🚀 Quick Start
+
+After installation, run your first scene with one command:
 
 ```bash
-python demo.py --model_path /path/to/checkpoint.pt \
-    --image_folder /path/to/images/
+python demo.py --model_path /path/to/lingbot-map-long.pt \
+    --image_folder example/courthouse --mask_sky
 ```
 
-### Streaming Inference from Video
+This launches an interactive [viser](https://github.com/nerfstudio-project/viser) viewer at `http://localhost:8080`. See [Interactive Demo](#-interactive-demo-demopy) below for the full set of scenes and flags, or jump to [Offline Rendering Pipeline](#-offline-rendering-pipeline-demo_renderbatch_demopy) for long-sequence batch rendering.
+
+## 🎬 Interactive Demo (`demo.py`)
+
+Run `demo.py` for interactive 3D visualization via a browser-based [viser](https://github.com/nerfstudio-project/viser) viewer (default `http://localhost:8080`).
+
+### Try the Example Scenes
 
+We provide four example scenes in `example/` that you can run out of the box:
 ```bash
-python demo.py --model_path /path/to/checkpoint.pt \
-    --video_path video.mp4 --fps 10
+# courthouse scene
+python demo.py --model_path /path/to/lingbot-map-long.pt \
+    --image_folder example/courthouse --mask_sky
+```
+
+
+https://github.com/user-attachments/assets/aa10f7ab-8024-43c7-92f8-d56159ec85c8
+
+
+
+
+
+
+```bash
+# University scene
+python demo.py --model_path /path/to/lingbot-map-long.pt \
+    --image_folder example/university --mask_sky
+```
+
+
+https://github.com/user-attachments/assets/212a1744-6ff5-4ccf-9bd4-728608248b57
+
+
+
+
+
+
+
+```bash
+# Loop scene (loop closure trajectory)
+python demo.py --model_path /path/to/lingbot-map-long.pt \
+    --image_folder example/loop
+```
+
+
+https://github.com/user-attachments/assets/5ae0a292-b081-40c6-838c-b7c1a0538d75
+
+
+
+
+
+```bash
+# Oxford scene with sky masking (outdoor, large scale scene)
+python demo.py --model_path /path/to/lingbot-map-long.pt \
+    --image_folder example/oxford --mask_sky
 ```
 
+
+https://github.com/user-attachments/assets/6b8daa95-9ed4-40b2-9902-7435779b886d
+
+
+
+
+
+
+#### 🎯 Featured: indoor walkthrough (~25 000 frames, 13 minutes)
+
+
+*Sequence is too long for the interactive viser viewer — this clip was rendered with the [Offline Rendering Pipeline](#-offline-rendering-pipeline-demo_renderbatch_demopy). See that section for the full command.*
+
+We will provide more examples in the follow-up.
+
 ### Streaming with Keyframe Interval
 
-Use `--keyframe_interval` to reduce KV cache memory by only keeping every N-th frame as a keyframe. Non-keyframe frames still produce predictions but are not stored in the cache. This is useful for long sequences 
-which excesses 320 frames.
+Use `--keyframe_interval` to reduce KV cache memory by only keeping every N-th frame as a keyframe. Non-keyframe frames still produce predictions but are not stored in the cache. This is useful for long sequences which exceed 320 frames (We train with video RoPE on 320 views, so performance degrades when the KV cache stores more than 320 views. Using a keyframe strategy allows inference over longer sequences.).
+
+
+**Dataset:** Download the demo sequences from [robbyant/lingbot-map-demo](https://huggingface.co/datasets/robbyant/lingbot-map-demo/tree/main) on Hugging Face.
+
+Example run on the `travel` sequence from the dataset above (sky masking on, 4 camera optimization iterations, keyframe every 2 frames):
 
 ```bash
-python demo.py --model_path /path/to/checkpoint.pt \
-    --image_folder /path/to/images/ --keyframe_interval 6
+python demo.py \
+    --image_folder /path/to/lingbot-map-demo/travel/ \
+    --model_path /path/to/lingbot-map-long.pt \
+    --mask_sky \
+    --camera_num_iterations 4 \
+    --keyframe_interval 2
 ```
 
+
+https://github.com/user-attachments/assets/d350b590-d036-4363-af8c-7af3918338ef
+
+
+
+> **Note on inference range.** Our method does not perform state resetting by default, so the maximum inference range is bounded by the longest distance seen during training on the dataset. Beyond that distance, state resetting becomes necessary. If you observe pose collapse, switch to windowed mode (`--mode windowed`) — in most cases tuning `--keyframe_interval` alone is enough and the rest of the windowed parameters can stay at their defaults.
+
+
 ### Windowed Inference (for long sequences, >3000 frames)
+
 ```bash
-python demo.py --model_path /path/to/checkpoint.pt \
+python demo.py --model_path /path/to/lingbot-map-long.pt \
     --video_path video.mp4 --fps 10 \
-    --mode windowed --window_size 64
+    --mode windowed --window_size 128 --overlap_keyframes 16 --keyframe_interval 2 
 ```
 
 
@@ -137,20 +278,282 @@ python demo.py --model_path /path/to/checkpoint.pt \
     --image_folder /path/to/images/ --mask_sky
 ```
 
-Sky masks are cached in `<image_folder>_sky_masks/` so subsequent runs skip regeneration.
+Sky masks are cached in `<image_folder>_sky_masks/` so subsequent runs skip regeneration. You can also specify a custom cache directory with `--sky_mask_dir`, or save side-by-side mask visualizations with `--sky_mask_visualization_dir`:
+
+```bash
+python demo.py --model_path /path/to/checkpoint.pt \
+    --image_folder /path/to/images/ --mask_sky \
+    --sky_mask_dir /path/to/cached_masks/ \
+    --sky_mask_visualization_dir /path/to/mask_viz/
+```
+
+### Visualization Options
+
+| Argument | Default | Description |
+|:---|:---|:---|
+| `--port` | `8080` | Viser viewer port |
+| `--conf_threshold` | `1.5` | Visibility threshold for filtering low-confidence points |
+| `--point_size` | `0.00001` | Point cloud point size |
+| `--downsample_factor` | `10` | Spatial downsampling for point cloud display |
+
+### Performance & Memory
 
-### Without FlashInfer (SDPA fallback)
+#### Without FlashInfer (SDPA fallback)
 
 ```bash
 python demo.py --model_path /path/to/checkpoint.pt \
     --image_folder /path/to/images/ --use_sdpa
 ```
 
-# 📜 License
+#### Running on Limited GPU Memory
+
+If you run into out-of-memory issues, try one (or both) of the following:
+
+- **`--offload_to_cpu`** — offload per-frame predictions to CPU during inference (on by default; use `--no-offload_to_cpu` only if you have memory to spare).
+- **`--num_scale_frames 2`** — reduce the number of bidirectional scale frames from the default 8 down to 2, which shrinks the activation peak of the initial scale phase.
+
+#### Faster Inference
+
+Lower the number of iterative refinement steps in the camera head to trade a small amount of pose accuracy for wall-clock speed:
+
+```bash
+python demo.py --model_path /path/to/checkpoint.pt \
+    --image_folder /path/to/images/ --camera_num_iterations 1
+```
+
+`--camera_num_iterations` defaults to `4`; setting it to `1` skips three refinement passes in the camera head (and shrinks its KV cache by 4×).
+
+## 🎥 Offline Rendering Pipeline (`demo_render/batch_demo.py`)
+
+Use this pipeline when your sequence is too long for the interactive viser viewer — for example, the [indoor walkthrough featured above](#-featured-indoor-walkthrough-25-000-frames-13-minutes). `demo_render/batch_demo.py` is the all-in-one offline entry point: feed it a video or a folder of images and it will run model inference and produce a headless point-cloud flythrough MP4 in a single command. It shares the same PyTorch / FlashInfer / checkpoint stack as `demo.py`.
+
+For those constrained by limited VRAM or GPU usage, you may also refer to the implementation at: https://github.com/ureeey/lingbot-map-rtx4060-8g/commit/eeee84a89cc97c1e39b736b46df4ee315275700b
+
+### Install (extends the main install)
+
+**1. Rendering Python dependencies**
+
+```bash
+pip install -e ".[vis,render]"
+```
+
+`render` pulls in `open3d>=0.19` and `pyyaml` (the core `numpy<2` constraint comes from the base `lingbot-map` install). Sky masking in this pipeline uses `onnxruntime-gpu` for batched segmentation; install it if you don't already have the CPU `onnxruntime`:
+
+```bash
+pip install onnxruntime-gpu
+```
+
+**2. Kaolin** — matches the PyTorch 2.8.0 + CUDA 12.8 recommended above:
+
+```bash
+pip install --index-url https://pypi.org/simple \
+    kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.8.0_cu128.html
+```
+
+> `--index-url https://pypi.org/simple` bypasses any internal mirror that might otherwise serve the PyPI placeholder wheel (which raises `ImportError` on import).
+> NVIDIA Kaolin does not publish prebuilt wheels for PyTorch 2.9.x — if you're on 2.9 for other reasons, build Kaolin from source (`pip install --no-build-isolation git+https://github.com/NVIDIAGameWorks/kaolin.git`, needs local CUDA toolkit). For other torch/CUDA combinations see [NVIDIA Kaolin installation](https://kaolin.readthedocs.io/en/latest/notes/installation.html).
+
+**3. ffmpeg**
+
+```bash
+sudo apt install ffmpeg    # or: brew install ffmpeg
+```
+
+**4. CUDA extensions** (required before first run)
+
+```bash
+cd demo_render/render_cuda_ext && python setup.py build_ext --inplace && cd ../..
+```
+
+This builds `voxel_morton_ext` and `frustum_cull_ext` in place — both are imported by `rgbd_render` for GPU voxelization and frustum culling.
+
+### Worked Example — long indoor walkthrough (~25 000 frames, 13 minutes)
+
+**Dataset:** Download the example video from [robbyant/lingbot-map-demo](https://huggingface.co/datasets/robbyant/lingbot-map-demo/tree/main) on Hugging Face.
+
+```bash
+    python demo_render/batch_demo.py \
+    --video_path /data/demo_videos/indoor_travel.MP4 \
+    --output_folder /data/outputs/indoor_travel/ \
+    --model_path /path/to/lingbot-map.pt \
+    --config demo_render/config/indoor.yaml \
+    --mode windowed --window_size 128 \
+    --keyframe_interval 13 --overlap_keyframes 8 \
+    --sky_mask_dir /data/outputs/sky_masks \
+    --sky_mask_visualization_dir /data/outputs/sky_mask_viz \
+    --camera_vis default --keyframes_only_points \
+    --frame_tag --frame_tag_position top_right \
+    --save_predictions
+```
+
+<img width="1920" height="1080" alt="image" src="https://github.com/user-attachments/assets/f4f5e555-22a8-4cc9-b380-dfde5fe1c809" />
+
+Flag-by-flag rationale:
+
+| Flag | Why it's there |
+|---|---|
+| `--mode windowed --window_size 128` | Sliding-window inference is required once the sequence exceeds the ~320-frame RoPE training range; each window resets the KV cache. **`window_size` counts KV-cache slots, not actual frames** — the first `num_scale_frames` (=8) slots hold the scale frames and the remaining `128 − 8 = 120` slots hold keyframes. With `keyframe_interval = 13`, one window therefore covers `8 + 120 × 13 = 1568` actual frames. |
+| `--keyframe_interval 13` | Cache only every 13th frame as a keyframe. Non-keyframes still emit per-frame predictions but don't grow the KV cache|
+| `--overlap_keyframes 8` | Adjacent windows share 8 keyframes of context, resolved internally to `max(num_scale_frames, 8 × keyframe_interval) = 8 × 13 = 104` actual frames of overlap. Recommended whenever `keyframe_interval > 1`, to keep cross-window pose alignment stable. |
+| `--config demo_render/config/indoor.yaml` | Seed render/scene/camera/overlay defaults from the indoor preset (short depth, tighter follow cam). Any CLI flag the user explicitly passes still overrides the YAML value. |
+| `--sky_mask_dir` / `--sky_mask_visualization_dir` | Persist sky masks and their side-by-side visualizations to disk so subsequent reruns reuse them instead of re-running ONNX segmentation. (The render pipeline only consumes them when sky masking is enabled — by the YAML preset or by `--mask_sky`.) |
+| `--camera_vis default` | Overlay the trajectory trail + recent-frame points on the rendered video. |
+| `--keyframes_only_points` | Only unproject keyframe depth into the point cloud; non-keyframes still contribute their pose to the trajectory/frustum overlay. Keeps the cloud sparse for very long sequences. |
+| `--frame_tag --frame_tag_position top_right` | Stamp a `<i> / <N> Frames` counter in the top-right corner of the MP4. |
+| `--save_predictions` | Persist per-frame NPZs alongside the MP4. Useful for inspection or for re-rendering with different camera/overlay settings later. |
+
+### Worked Example — outdoor drive scene
+
+**Dataset:** Download the example video from [robbyant/lingbot-map-demo](https://huggingface.co/datasets/robbyant/lingbot-map-demo/tree/main) on Hugging Face.
+
+```bash
+    python demo_render/batch_demo.py \
+    --video_path /data/demo_videos/drive_frames.mp4 \
+    --output_folder /data/outputs/drive/ \
+    --model_path /path/to/lingbot-map.pt \
+    --config demo_render/config/outdoor_drive.yaml \
+    --mode windowed --window_size 128 \
+    --max_non_keyframe_gap 100 --overlap_keyframes 8 \
+    --image_stride 1 \
+    --sky_mask_dir /data/outputs/sky_masks \
+    --sky_mask_visualization_dir /data/outputs/sky_mask_viz \
+    --camera_vis default --keyframes_only_points \
+    --frame_tag --frame_tag_position top_right \
+    --save_predictions
+```
+
+<img width="3822" height="1080" alt="image" src="https://github.com/user-attachments/assets/3c26afdb-6bb8-4d20-a7e0-f5a220382662" />
+
+
+What differs from the indoor walkthrough above:
+
+| Flag | Why it's there |
+|---|---|
+| `--config demo_render/config/outdoor_drive.yaml` | Seed defaults from the outdoor preset: sky masking enabled, deeper render range (`max_depth: 250`), and a follow cam tuned for vehicle trajectories with a final birdeye reveal. |
+| `--image_stride 1` | Use every video frame. Increase it to subsample long or high-FPS drive footage. |
+| `--max_non_keyframe_gap 100` | Upper bound on consecutive non-keyframes before a keyframe is forced. Only active with flow-based keyframe selection (`--flow_threshold > 0`); in the default fixed-interval mode it has no effect. |
+
+The remaining flags (`--mode windowed --window_size 128`, `--overlap_keyframes 8`, sky-mask caching, overlays, `--save_predictions`) carry over unchanged from the indoor example — see the flag-by-flag table above.
+
+### Worked Example — LingBot-World scenes
+
+Reconstruct videos generated by LingBot-World, our world model — the same pipeline works on generated footage out of the box.
+
+**Dataset:** Download the example videos (`lingbo_world_frames.mp4`, `lingbo_world2_frames.mp4`) from [robbyant/lingbot-map-demo](https://huggingface.co/datasets/robbyant/lingbot-map-demo/tree/main) on Hugging Face.
+
+```bash
+    python demo_render/batch_demo.py \
+    --video_path /data/demo_videos/lingbo_world_frames.mp4 \
+    --output_folder /data/outputs/lingbo_world/ \
+    --model_path /path/to/lingbot-map.pt \
+    --config demo_render/config/outdoor_drive.yaml \
+    --mode windowed --window_size 128 \
+    --max_non_keyframe_gap 100 --overlap_keyframes 8 \
+    --image_stride 1 \
+    --sky_mask_dir /data/outputs/sky_masks \
+    --sky_mask_visualization_dir /data/outputs/sky_mask_viz \
+    --camera_vis default --keyframes_only_points \
+    --frame_tag --frame_tag_position top_right \
+    --save_predictions
+```
+
+For the second clip, run the same command with `--video_path /data/demo_videos/lingbo_world2_frames.mp4 --output_folder /data/outputs/lingbo_world2/` (and separate `--sky_mask_dir` / `--sky_mask_visualization_dir` folders if you want to keep the cached masks apart).
+
+All flags are identical to the [outdoor drive scene](#worked-example--outdoor-drive-scene) above — only the input video and output folder change. See the drive scene and indoor walkthrough tables for the flag-by-flag rationale.
+
+<img width="3736" height="1080" alt="image" src="https://github.com/user-attachments/assets/1f60d505-1407-482c-9b5d-57c7145c0b7d" />
+
+<img width="1200" height="339" alt="image" src="https://github.com/user-attachments/assets/e62bedaa-1e61-40b3-8fea-01c8a15355f0" />
+
+
+
+### Camera Path (YAML)
+
+The virtual camera path is described by the `camera.segments` list in the YAML preset passed via `--config`. Edit the YAML to design your own shot — no need to touch CLI flags.
+
+Built-in presets live in `demo_render/config/`: `default.yaml`, `indoor.yaml`, `outdoor_drive.yaml`. Copy one and edit the `camera:` block.
+
+#### YAML structure
+
+```yaml
+camera:
+  fov: 60.0          # camera field of view in degrees
+  transition: 30     # frames blended between adjacent segments
+  segments:
+    - mode: follow            # chase cam following the input trajectory
+      frames: [0, 1500]       # rendered-frame range this segment covers (-1 = end)
+      back_offset: 0.3        # how far behind the input camera (fraction of scene scale)
+      up_offset: 0.08         # vertical lift above the input camera
+      look_offset: 0.4        # how far ahead the lookat target points
+      smooth_window: 30       # trajectory smoothing window in frames
+    - mode: birdeye           # rise up for a top-down reveal of the whole scene
+      frames: [1500, 1800]
+      reveal_height_mult: 2.5 # birdeye height = scene scale × this factor
+    - mode: follow            # drop back into chase cam
+      frames: [1800, -1]
+      back_offset: 0.3
+      up_offset: 0.08
+      look_offset: 0.4
+```
+
+`transition` controls how many frames are blended between adjacent segments; `frames: [0, -1]` means "the whole sequence".
+
+#### Available modes
+
+| `mode` | Behavior | Tunable fields |
+|---|---|---|
+| `follow` | Chase cam tracks the input trajectory with smooth offsets. The most cinematic option for walkthroughs. | `back_offset`, `up_offset`, `look_offset`, `smooth_window`, `scale_frames` |
+| `birdeye` | Top-down reveal of the whole scene. Useful for hero / overview shots. | `reveal_height_mult` |
+| `static` | Fixed eye + lookat, auto-derived from the segment's start frame. | — |
+| `pivot` | Fixed eye, lookat sweeps along the trajectory. | — |
+
+#### Single-shot YAML examples
+
+**Pure follow** (most common):
+
+```yaml
+camera:
+  fov: 60.0
+  segments:
+    - mode: follow
+      frames: [0, -1]
+      back_offset: 0.3
+      up_offset: 0.08
+      look_offset: 0.4
+      smooth_window: 30
+```
+
+**Full birdeye** (good for overview / hero shots):
+
+```yaml
+camera:
+  fov: 60.0
+  segments:
+    - mode: birdeye
+      frames: [0, -1]
+      reveal_height_mult: 2.5
+```
+
+**Follow with birdeye inserts**: just list multiple segments in order under `segments:` — adjacent segments are interpolated using `transition` frames.
+
+> Caveat: when `--config` loads a YAML preset, passing **any** segment-shaping CLI flag (`--camera_mode`, `--back_offset`, `--up_offset`, `--look_offset`, `--smooth_window`, `--follow_scale_frames`, `--birdeye_start`, `--birdeye_duration`, `--reveal_height_mult`) discards the YAML's `segments` and rebuilds the camera path from those flags instead. To stay fully YAML-driven, don't pass any of them on the command line.
+
+### Output files
+
+For a given output name (e.g. `<scene>` or `<video_name>`):
+
+| File | Description |
+|------|-------------|
+| `<name>_pointcloud.mp4` | Rendered point-cloud flythrough |
+| `<name>_pointcloud_rgb.mp4` | Original RGB frames encoded as video |
+| `<name>_pointcloud_config.yaml` | Full config snapshot of this run |
+| `batch_results.json` | Per-scene success / duration summary |
+
+## 📜 License
 
 This project is released under the Apache License 2.0. See [LICENSE](LICENSE.txt) file for details.
 
-# 📖 Citation
+## 📖 Citation
 
 ```bibtex
 @article{chen2026geometric,
@@ -161,7 +564,7 @@ This project is released under the Apache License 2.0. See [LICENSE](LICENSE.txt
 }
 ```
 
-# ✨ Acknowledgments
+## ✨ Acknowledgments
 
 We thank Shangzhan Zhang, Jianyuan Wang, Yudong Jin, Christian Rupprecht, and Xun Cao for their helpful discussions and support.