From 443edbfa25cdbe3d99c1325edbe5eb46df57304d Mon Sep 17 00:00:00 2001
From: SikongJueluo <selfconfusion@gmail.com>
Date: Wed, 13 May 2026 20:02:11 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20add=20experiments=20feasibility=20surve?=
 =?UTF-8?q?y=20for=20paper=20sections=206.2=E2=80=936.8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/experiments.md | 392 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 392 insertions(+)
 create mode 100644 docs/experiments.md

diff --git a/docs/experiments.md b/docs/experiments.md
new file mode 100644
index 0000000..b3886fb
--- /dev/null
+++ b/docs/experiments.md
@@ -0,0 +1,392 @@
+# Mini-Nav 实验可行性调研报告
+
+本文档调研当前 Mini-Nav 项目对论文/报告第 6.2–6.8 节实验的支持程度，判断哪些实验可以直接开展，哪些实验只能部分开展，以及还需要补齐哪些代码、脚本或评估流程。
+
+> 调研范围：当前仓库中的 Python 代码、CAM RTL、Cocotb 仿真、benchmark 框架、Scene Graph 原型、Habitat simulator 辅助代码与现有配置。
+
+## 总体结论
+
+| 实验章节 | 当前状态 | 结论 |
+|---|---:|---|
+| 6.2 CAM 硬件功能正确性验证 | 较完整 | 可以做 |
+| 6.3 CAM 硬件性能基准测试 | 有参数化仿真基础 | 部分可做，性能/资源脚本缺失 |
+| 6.4 Hash Compressor 检索性能实验 | 有模型和训练代码 | 部分可做，缺系统化评估脚本 |
+| 6.5 对象级 Top-K 检索实验 | 有雏形 | 部分可做，但集成问题较多 |
+| 6.6 Scene Graph 构建与路径推理实验 | 很弱 | 大多还不能做 |
+| 6.7 CAM 加速后的整体框架实验 | 缺软件-硬件桥接与端到端闭环 | 只能做局部模拟 |
+| 6.8 消融实验与误差分析 | 依赖前面模块 | 只能做少量离线消融 |
+
+简短判断：**6.2 最成熟；6.3、6.4 可较快补齐；6.5 有雏形但需要修集成；6.6、6.7、6.8 中涉及 Scene Graph 和端到端导航的部分目前还不具备完整实验条件。**
+
+## 项目中已有的关键能力
+
+### CAM 硬件与仿真
+
+相关路径：
+
+- `hw/rtl/cam_top.sv`
+- `hw/rtl/cam_noisy.sv`
+- `hw/rtl/cam_core_banked.sv`
+- `hw/rtl/match_engine_pipeline.sv`
+- `hw/rtl/popcount_pipeline.sv`
+- `hw/rtl/cam_write_noise.sv`
+- `hw/rtl/cam_read_noise.sv`
+- `hw/rtl/noise_mask_grouped.sv`
+- `hw/rtl/cam_params.svh`
+- `hw/sim/model/ref_model.py`
+- `hw/sim/sweep_noise.py`
+- `hw/sim/tests/*.py`
+- `hw/sim/Makefile`
+- `.justfile`
+
+已有能力：
+
+- CAM 顶层模块支持写入、查询、匹配输出。
+- 参数支持 `NUM_ROWS`、`HASH_BITS`、`LANES`。
+- 有写噪声和读噪声模块。
+- 有 Python 参考模型用于验证噪声和匹配行为。
+- 有 Cocotb/Verilator 测试命令：
+  - `just cam-test-py`
+  - `just cam-test-all`
+  - `just cam-test-module MODULE=...`
+
+### Hash Compressor 与检索
+
+相关路径：
+
+- `mini-nav/compressors/hash_compressor.py`
+- `mini-nav/compressors/common.py`
+- `mini-nav/compressors/train.py`
+- `mini-nav/compressors/pipeline.py`
+- `mini-nav/commands/benchmark.py`
+- `mini-nav/benchmarks/tasks/retrieval.py`
+
+已有能力：
+
+- `HashCompressor` 支持 DINO token 到二值 hash bits 的映射。
+- 默认目标是 512-bit CAM-compatible hash code。
+- `HashLoss` 包含 contrastive、distillation、quantization 三类损失。
+- `train.py` 可以在 CIFAR-10 上训练 HashCompressor。
+- `common.py` 有 Hamming distance / similarity 工具。
+
+### 对象级检索雏形
+
+相关路径：
+
+- `mini-nav/benchmarks/tasks/multi_object_retrieval.py`
+- `mini-nav/data_loading/insdet_scenes.py`
+- `mini-nav/data_loading/loader.py`
+- `mini-nav/compressors/pipeline.py`
+
+已有能力：
+
+- 有多对象检索 benchmark task 雏形。
+- 有 object-level vector 建库、query、scene-level aggregation 的基本逻辑。
+- `HashPipeline` 支持 OWLv2 文本检测、SAM 分割、DINO 特征、Hash 压缩的流水线设计。
+
+主要问题：
+
+- `multi_object_retrieval.py` 引入 `utils.sam`，但源码中没有 `mini-nav/utils/sam.py`，只有历史 `__pycache__`。
+- 普通 benchmark 使用字段 `img`，多对象检索使用字段 `image`，存在数据接口不一致。
+- 当前多对象检索主要走 LanceDB 连续向量检索，不是真正的 CAM/hash 检索。
+
+### Scene Graph 与 Habitat 辅助代码
+
+相关路径：
+
+- `mini-nav/scenegraph/objectnode.py`
+- `mini-nav/scenegraph/roomnode.py`
+- `mini-nav/scenegraph/scenegraph.py`
+- `mini-nav/simulator/habitat.py`
+- `mini-nav/simulator/views.py`
+- `mini-nav/simulator/topdown.py`
+
+已有能力：
+
+- `ObjectNode` 数据结构中已有 `visual_hash`、`semantic_hash` 字段。
+- `SimpleSceneGraph` 目前仅保存 `rooms` 和 `objects` 两个字典。
+- Habitat 侧有 simulator 创建、随机 navigable point 采图、topdown map 可视化辅助函数。
+
+主要问题：
+
+- 没有 Scene Graph 构建器。
+- 没有 room-waypoint-object 拓扑关系。
+- 没有检索结果到导航目标点的转换。
+- 没有 episode、policy、SPL/success 等导航评估指标。
+
+## 6.2 CAM 硬件功能正确性验证
+
+结论：**可以做。**
+
+| 小节 | 状态 | 说明 |
+|---|---:|---|
+| 6.2.1 写入与读取功能验证 | 可以做 | `cam_core_banked`、`cam_top` 有 Cocotb 测试 |
+| 6.2.2 汉明距离计算验证 | 可以做 | `match_engine_pipeline` 和 ref model 覆盖 bit match / popcount |
+| 6.2.3 Top-K 输出正确性验证 | 部分可做 | 当前硬件更接近 Top-1 输出，不是完整 Top-K 列表 |
+| 6.2.4 噪声注入功能验证 | 可以做 | 写噪声、读噪声、组合噪声都有测试和参考模型 |
+
+### 已具备内容
+
+- 写入/读取：`hw/rtl/cam_core_banked.sv`、`hw/sim/tests/test_cam_core_banked.py`
+- 匹配与 popcount：`hw/rtl/match_engine_pipeline.sv`、`hw/rtl/popcount_pipeline.sv`
+- 噪声模块：`hw/rtl/cam_write_noise.sv`、`hw/rtl/cam_read_noise.sv`
+- 参考模型：`hw/sim/model/ref_model.py`
+- 集成测试：`hw/sim/tests/test_cam_basic.py`
+
+### 还需补齐
+
+1. 如果论文中写的是严格的 **Top-K 硬件输出**，当前 RTL 需要补 Top-K 选择/排序模块，或者明确实验是 Top-1 / Top-K 由软件侧重排实现。
+2. 需要统一整理仿真日志、表格和截图，形成可放入论文的实验结果。
+3. 建议补一个 `scripts/run_cam_correctness.py` 或类似脚本，一键跑 6.2 所需配置。
+
+## 6.3 CAM 硬件性能基准测试
+
+结论：**部分可做。**
+
+| 小节 | 状态 | 说明 |
+|---|---:|---|
+| 6.3.1 不同行数 `NUM_ROWS` 下的延迟 | 部分可做 | Makefile 支持参数化，但缺自动 latency 统计 |
+| 6.3.2 不同 `HASH_BITS` 下的资源占用 | 暂不能充分做 | 缺 Yosys/Vivado/Quartus 综合脚本 |
+| 6.3.3 不同 `LANES` 下的吞吐率 | 部分可做 | RTL 参数支持，但缺吞吐率测量脚本 |
+| 6.3.4 与软件检索方法的性能对比 | 还不能完整做 | 缺统一的硬件/软件 benchmark 脚本 |
+
+### 已具备内容
+
+- `hw/sim/Makefile` 支持：
+  - `NUM_ROWS`
+  - `HASH_BITS`
+  - `LANES`
+  - `WRITE_NOISE_*`
+  - `READ_NOISE_*`
+- `.justfile` 已封装远程 Verilator/Cocotb 执行命令。
+
+### 还需补齐
+
+1. CAM 性能 sweep 脚本：
+   - 输入：`NUM_ROWS`、`HASH_BITS`、`LANES`
+   - 输出：latency cycles、throughput、仿真耗时
+2. Cocotb latency 统计：
+   - 记录 `query_valid` 到 `result_valid` 的周期数。
+3. 综合/资源统计流程：
+   - Yosys 或 Vivado TCL。
+   - 输出 LUT、FF、BRAM、频率估计。
+4. 软件 baseline：
+   - Python/NumPy Hamming scan。
+   - PyTorch vectorized Hamming。
+   - LanceDB/DINO continuous vector retrieval。
+
+## 6.4 Hash Compressor 检索性能实验
+
+结论：**部分可做。**
+
+| 小节 | 状态 | 说明 |
+|---|---:|---|
+| 6.4.1 原始 DINOv2 特征与二值哈希特征对比 | 可补后做 | DINO 和 Hash 都有，但缺统一评估脚本 |
+| 6.4.2 不同哈希长度消融实验 | 可补后做 | `HashCompressor(hash_bits=...)` 支持，但训练脚本固定 512 |
+| 6.4.3 不同压缩方法对比实验 | 暂不能做 | 目前只有一种 MLP HashCompressor，无 PCA/随机投影/ITQ/LSH baseline |
+| 6.4.4 相似度保持能力分析 | 可补后做 | 有 DINO embedding 和 hash similarity，缺相关性分析脚本 |
+
+### 已具备内容
+
+- `HashCompressor.encode()` 可以生成 binary bits。
+- `HashCompressor.compute_similarity()` 可以计算 Hamming similarity。
+- `HashLoss` 支持相似度蒸馏，有利于做 similarity preservation 分析。
+- `train.py` 可训练基础 512-bit compressor。
+
+### 还需补齐
+
+建议新增 `scripts/eval_hash_retrieval.py`，支持：
+
+- DINO baseline vs Hash baseline。
+- `hash_bits = 64 / 128 / 256 / 512`。
+- Recall@K、mAP、query latency。
+- DINO cosine similarity 与 Hash Hamming similarity 的 Spearman/Pearson 相关性。
+- storage compression ratio。
+
+如果要做 6.4.3，需要新增压缩 baseline：
+
+- random projection + sign。
+- PCA + sign。
+- LSH。
+- ITQ 或简化二值量化方法。
+
+## 6.5 对象级 Top-K 检索实验
+
+结论：**部分可做，但当前不能顺畅跑完整实验。**
+
+| 小节 | 状态 | 说明 |
+|---|---:|---|
+| 6.5.1 图像查询实验 | 部分可做 | 有 object retrieval 框架，但需修 `utils.sam` 和字段兼容 |
+| 6.5.2 文本类别查询实验 | 部分可做 | `HashPipeline` 支持 OWLv2 text labels，但 benchmark 未集成 |
+| 6.5.3 多视角对象特征融合实验 | 暂不能做 | 没有 object tracking / multi-view merge / feature aggregation |
+| 6.5.4 类别过滤与重排序实验 | 只有基础 | 有 mask filtering；类别级过滤和重排序逻辑还需补 |
+
+### 已具备内容
+
+- `multi_object_retrieval.py` 有对象级检索任务结构。
+- `data_loading/loader.py` 能加载带 bbox/category 的 InsDet scene 数据。
+- `HashPipeline` 支持文本标签驱动的 OWLv2 检测。
+
+### 主要问题
+
+1. `utils.sam` 缺失。
+2. `img` / `image` 字段不一致。
+3. 数据库 schema 与 object-level retrieval 的 schema 需要和 runner 对齐。
+4. 当前 object retrieval 不是 hash/CAM 检索。
+5. 缺类别过滤、重排序、多视角融合的正式评估接口。
+
+### 还需补齐
+
+1. 补 `mini-nav/utils/sam.py`，或改为复用 `compressors/model_loader.py` 与 `compressors/proposal`。
+2. 统一 benchmark dataset item 字段。
+3. 给 object retrieval 增加三种模式：
+   - DINO continuous vector。
+   - Hash/Hamming。
+   - CAM/ref_model Hamming。
+4. 增加 category filter 与 rerank 开关。
+5. 多视角融合需要新增 object association 和 feature aggregation。
+
+## 6.6 Scene Graph 构建与路径推理实验
+
+结论：**大部分还不能做。**
+
+| 小节 | 状态 | 说明 |
+|---|---:|---|
+| 6.6.1 ObjectNode 构建质量验证 | 只能做静态/伪数据 | 有数据结构，无自动构建流程 |
+| 6.6.2 房间层与 waypoint 层关系验证 | 不能做 | 没有 waypoint node / room-waypoint graph |
+| 6.6.3 检索结果到导航目标点转换实验 | 不能做 | 没有 object → navigable point / goal pose 映射 |
+| 6.6.4 基于 Scene Graph 的路径生成实验 | 不能做 | 没有 graph search / Habitat path planner 封装 |
+
+### 已具备内容
+
+- `ObjectNode` 能存储 object id、room id、position、visual hash、semantic hash。
+- `RoomNode` 和 `SimpleSceneGraph` 是极简数据结构。
+- Habitat simulator helper 可以采集场景图像和 topdown map。
+
+### 还需补齐
+
+1. SceneGraph builder：
+   - 输入多视角图像、检测结果、相机位姿。
+   - 输出 ObjectNode、RoomNode、WaypointNode。
+2. 多视角 object association：
+   - 判断不同视角中同一物体。
+   - 合并位置和 hash 特征。
+3. Waypoint graph：
+   - 房间节点、waypoint 节点、object 节点关系。
+4. Path planning：
+   - 检索结果转 target pose。
+   - target pose 转 Habitat shortest path 或自定义 graph path。
+
+## 6.7 CAM 加速后的整体框架实验
+
+结论：**端到端还不能做；局部对比可以做。**
+
+| 小节 | 状态 | 说明 |
+|---|---:|---|
+| 6.7.1 无 CAM 与加入 CAM 的检索延迟对比 | 可补脚本后做局部实验 | 可用 Python CAM ref model 模拟，但无硬件级整体接入 |
+| 6.7.2 无 Scene Graph 与加入 Scene Graph 的目标选择对比 | 不能做 | Scene Graph 目标选择逻辑不足 |
+| 6.7.3 Top-K 候选切换与失败恢复实验 | 不能做 | 没有导航策略/失败恢复机制 |
+| 6.7.4 端到端离线闭环实验 | 不能做 | 缺 query → retrieve → goal → plan → evaluate 闭环 |
+
+### 可以先做的局部实验
+
+- DINO/LanceDB 检索延迟 vs Hash/Hamming 检索延迟。
+- Python CAM ref model 检索延迟 vs PyTorch Hamming scan。
+- 噪声 CAM 对 Top-1 / Top-K 稳定性的影响。
+
+### 还需补齐
+
+1. Hash output 到 CAM/ref_model 的桥接脚本。
+2. CAM 检索 API：给定 query hash 和 database hash，返回 Top-K candidate。
+3. 整体 pipeline：
+   - image/text query
+   - object retrieval
+   - scene graph rerank
+   - target waypoint selection
+   - path planning
+   - offline evaluation
+
+## 6.8 消融实验与误差分析
+
+结论：**只能做部分离线消融。**
+
+| 小节 | 状态 | 说明 |
+|---|---:|---|
+| 6.8.1 去除类别过滤 | 可补后做 | 类别过滤还没有完整 pipeline |
+| 6.8.2 去除多视角融合 | 不能做 | 多视角融合本身未实现 |
+| 6.8.3 去除 Scene Graph 重排序 | 不能做 | Scene Graph rerank 未实现 |
+| 6.8.4 CAM 噪声对最终结果的影响 | 可做局部 | 可测对检索结果影响，不能测完整导航最终结果 |
+| 6.8.5 失败案例分析 | 可做检索失败分析 | 导航失败案例暂不可做 |
+
+### 可先做的误差分析
+
+- Hash 检索失败案例：query 与 top candidates 可视化。
+- CAM 噪声导致 Top-1 改变的案例。
+- DINO 与 Hash 排序不一致的案例。
+- SAM/OWLv2 分割或检测失败案例。
+
+### 暂不能做的误差分析
+
+- 多视角融合失败原因。
+- Scene Graph 重排序失败原因。
+- 端到端导航失败恢复分析。
+
+## 推荐实施顺序
+
+### 阶段 1：快速产出可用实验结果
+
+优先完成：
+
+1. 6.2 CAM correctness。
+2. 6.3 CAM 仿真性能 sweep。
+3. 6.4 DINO vs Hash 检索性能对比。
+
+建议新增脚本：
+
+- `scripts/run_cam_correctness.py`
+- `scripts/sweep_cam_perf.py`
+- `scripts/eval_hash_retrieval.py`
+
+### 阶段 2：解锁对象级实验
+
+优先修复：
+
+1. `mini-nav/utils/sam.py` 缺失问题。
+2. benchmark dataset 字段不一致问题。
+3. object-level schema 与 runner 对齐问题。
+4. object retrieval 的 hash/CAM 模式。
+
+然后开展：
+
+- 6.5.1 图像查询实验。
+- 6.5.2 文本类别查询实验。
+- 6.5.4 类别过滤与重排序实验。
+
+### 阶段 3：实现 Scene Graph 与端到端闭环
+
+需要新增核心模块：
+
+1. SceneGraph builder。
+2. Waypoint graph。
+3. Object-to-goal mapping。
+4. Navigation evaluator。
+5. Candidate switching / failure recovery。
+
+完成后才能正式开展：
+
+- 6.6 Scene Graph 构建与路径推理。
+- 6.7 CAM 加速后的整体框架实验。
+- 6.8 中涉及 Scene Graph、导航闭环、多视角融合的消融实验。
+
+## 最小可行实验组合
+
+如果目标是尽快形成一组完整、可信的实验章节，建议先采用以下组合：
+
+1. **CAM 功能正确性**：覆盖 6.2。
+2. **CAM 参数化仿真性能**：覆盖 6.3 的一部分。
+3. **DINO vs Hash 检索性能**：覆盖 6.4.1。
+4. **Hash length ablation**：覆盖 6.4.2。
+5. **CAM noise 对检索稳定性的影响**：覆盖 6.2.4、6.8.4 的离线部分。
+6. **对象级检索 demo**：修复 `utils.sam` 后覆盖 6.5.1 的基础版本。
+
+这组实验避开了目前尚未实现的 Scene Graph 端到端导航闭环，同时能充分利用当前仓库中已经完成度较高的 CAM 和 HashCompressor 模块。