【SLAM】SLAM-Former论文与代码导读

本页概念卡

SLAM-Former · Map Tokens · Pointmap · KV Cache · Cache Sharing · DivPrune · 帧内帧间注意力 · 三训练模式 · 关键帧选择 · 稠密单目SLAM · 未标定SLAM · Pi3 · ATE · Acc · Comp · Chamfer
论文主笔记见 2026-08-10 - SLAM-Former论文与代码导读。本文侧重：方法细节 ↔ 仓库文件映射，方便对照源码读。

0. 仓库地图（先建立目录感）

复制代码

SLAM-Former/
├── slam/
│   ├── demo.py              # 在线 SLAM 主循环（前端/后端调度）
│   ├── utils.py             # 图像缩放、state_dict 清洗
│   ├── visualize_results.py # 静态结果浏览器可视化
│   └── rerun_helper/        # Rerun 实时可视化
└── src/slamformer/
    ├── models/slamformer.py # ★ 核心：KFT / frontendT / backendT / extract / DivPrune
    ├── models/layers/
    │   ├── attention.py     # FlashAttentionRope + KV cache + idx 剪枝
    │   ├── block.py         # BlockRope：帧内/帧间 + branch 1/2/3 mask
    │   ├── camera_head.py   # 9D 旋转 + SVD → 4×4 位姿
    │   ├── transformer_head.py / conv_head.py  # 点/置信度头
    │   └── pos_embed.py     # RoPE2D
    └── models/dinov2/       # 图像编码器

权重协议：代码 BSD-3 ，权重 CC BY-NC 4.0（禁止商用）。

1. 论文概念 → 代码符号

论文	代码	说明
图像特征 / encoder	`self.encoder` = DINOv2 ViT-L/14 reg	`KFT`/`frontendT` 里先 encode
Map tokens FtF_tFt / MMM	`hidden_F`，SLAM 类里 `self.map`	形状约 `[S, P, C]`，CCC 常为 concat 后的 2×dim
Frontend ffnf_{\mathrm{fn}}ffn	`frontendT` → `decode(..., hidden_I, use_cache=True)`	branch≈1，写 `self.fkv`
Backend fbnf_{\mathrm{bn}}fbn	`backendT` → `decode(..., hidden_I=None, hidden_F=...)`	branch≈2，全注意力精炼
关键帧检测	`KFT` + `extract(..., cam_only=True)`	两帧无长 cache
Heads hhh	`extract()` → point/conf/camera	local points 再乘位姿到世界
Retention γ\gammaγ	`retention_ratio`（默认 0.5）	DivPrune 选 token 索引 `idx`
Backend 周期 TTT	`bn_every`（默认 10）	每 N 个关键帧触发

2. 推理主循环（`slam/demo.py`）

SLAM.step(timestamp, image) 每帧：

frontend
- kf_detect：KFT(上一KF, 当前帧) → 相对平移是否 >kfth> kf_th>kfth
- 若是关键帧：frontendT 得 token，map_add 追加到 self.map
- 每 bn_every 个关键帧置 signal_backend=True
backend
- 清掉旧 fkv，backendT(self.map) → self.map_opt
- 后端 KV 写回 self.fkv，供后续前端增量使用（论文「cache sharing」）
terminate
- 尾部不足周期也强制 backend；extract → final.ply / final_traj.txt / final_pc/

初始化特例：

第 1 个关键帧：只登记，几乎不跑完整前端
第 2 个关键帧：frontendT(stack[KF0, KF1]) 联合初始化
之后：单帧 frontendT(frame) + 历史 KV

评测 vs 演示

README：正式评测用 --retention_ratio 1（100% KV）；演示可用 0.5 加速。见上游 issue #15。

3.1 `KFT(img)` --- KeyFrame Test

Encode → decode(..., use_cache=False)（不污染长序列 cache）
返回 hidden_F，只为估相对位姿判关键帧

3.2 `frontendT(img)` --- 前端增量

Encode → decode(..., use_cache=True) → 更新 self.fkv
返回新关键帧的 map tokens（拼进 self.map）

3.3 `backendT(hidden_F)` --- 后端全局

取 hidden_F[:,:,:C//2]（decode 输出是两层特征 concat，后端用一半通道作为输入表示）
decode(hidden_I=None, hidden_F=..., use_cache=True) → 精炼后的 tokens + 新 KV

3.4 `extract(hidden)` --- 解码几何

point_decoder / conf_decoder / camera_decoder（小型 TransformerDecoder）
Camera：CameraHead → 4×44\times44×4
Points：LinearPts3d 或 ConvHead → (xy,z)(xy, z)(xy,z)，z=exp(z)，局部点 [xy*z, z]
世界点：camera_poses @ homogenize(local_points)

ConvHead（checkpoint V1.1）主要修 grid artifact（网格伪影）。

4. 注意力与三种 branch（训练↔推理）

BlockRope.forward：

global_=False（偶数层）：每帧内独立注意力
global_=True（奇数层）：所有帧 tokens 展平做帧间注意力

训练 mask（use_cache=False 时）：

branch	含义	mask
1	Frontend causal	禁止看未来帧（且特殊处理前两帧）
2	Backend full	`attn_mask=None`
3	Mixed	仅后半段新帧遵守因果

推理用 cache 时：历史 K/V 已在 kvcache 里，等价于因果/混合，而不再显式构造大 mask。

FlashAttentionRope：

新帧算 Q/K/V，对 Q、新 K 做 RoPE；past_k/v 不再二次 RoPE
torch.cat([past_k, k], dim=2) 延长序列
若有 idx：k/v.index_select(2, idx) → 只稀疏化 KV

5. DivPrune 实现要点

Pruner / DivPrune：

距离矩阵 d=1−cos⁡d=1-\cosd=1−cos
贪心：先选「最近邻距离最大」的点，再反复选使「到已选集最小距离」最大的点（Max-Min Diversity）
流式：_prune_idx_cache 缓存旧帧索引，只对新 bn_every 帧重算
register tokens 始终保留；只剪 patch tokens

论文强调：丢掉 KV ≠ 丢掉重建------Query 仍全保留，point head 仍可出完整分辨率点云。

6. 运行最小命令

bash 复制代码

cd ./SLAM-Former
# conda env + pip install -r requirements.txt && pip install -e .
python slam/demo.py \
  --ckpt_path .ckpt/checkpoint-10.pth.model \
  --image_folder /path/to/images \
  --output_dir ./output/result \
  --target_size 518 \
  --retention_ratio 0.5

Checkpoint 提示：

v1 / V1.1：--target_size 518
V1.1-long：--target_size 224，更长序列

8. 阅读顺序建议

论文 Fig.1--3 + §3.5 Execution Pipeline（10 分钟建立图像）
slam/demo.py 的 step → frontend → backend（对照流水线）
slamformer.py 的 KFT / frontendT / backendT / decode
block.py branch mask + attention.py KV concat/prune
再回论文 §3.4 训练三模式与 §3.6 剪枝公式

【SLAM】SLAM-Former论文与代码导读

0. 仓库地图（先建立目录感）

1. 论文概念 → 代码符号

2. 推理主循环（slam/demo.py）

3.1 KFT(img) --- KeyFrame Test

3.2 frontendT(img) --- 前端增量

3.3 backendT(hidden_F) --- 后端全局

3.4 extract(hidden) --- 解码几何