docs(readme): restructure into MODNet (§1) and RVM (§2) chapters; drop frontmatter

README.md

@@ -1,25 +1,6 @@
----
-language:
-  - en
-  - zh
-tags:
-  - image-matting
-  - portrait-segmentation
-  - modnet
-  - onnx
-  - rknn
-  - rk3588
-  - video-matting
-  - robust-video-matting
-license: mit
-library_name: pytorch
-base_model: ZHKKKe/MODNet
-pipeline_tag: image-segmentation
----
+# MODNet 与 RVM 模型制品仓库 (Model Artifact Registry)
 
-# MODNet 模型制品仓库 (Model Artifact Registry)
-
-> **用途**：集中管理 MODNet 检查点（Checkpoint）、ONNX 模型及训练制品（Training Artifacts）
+> **用途**：集中管理 MODNet 与 RVM 的检查点（Checkpoint）、ONNX/RKNN 模型及训练制品（Training Artifacts）
 >
 > **维护者**：PotterWhite
 > **最后更新**：2026-07-03
@@ -29,21 +10,29 @@ pipeline_tag: image-segmentation
 
 ## 目录（Table of Contents）
 
-1. [官方预训练模型（Official Pretrained Models）](#1-官方预训练模型official-pretrained-models)
-2. [微调模型（Fine-tuned Models）—— 摄影数据集](#2-微调模型fine-tuned-models-摄影数据集)
-3. [ONNX 模型变体（ONNX Model Variants）](#3-onnx-模型变体onnx-model-variants)
-4. [目录结构（Directory Structure）](#4-目录结构directory-structure)
-5. [生成与部署指南（Generation & Deployment Guide）](#5-生成与部署指南generation--deployment-guide)
-6. [速查表（Quick Reference）](#6-速查表quick-reference)
-7. [RobustVideoMatting（RVM）模型](#7-robustvideoMattingrvm模型)
-    - [7.5 Graph Surgery：移除最终的 Resize 及以后的算子](#75-graph-surgery移除最终的-resize-及以后的算子)
-8. [相关文档（Related Documentation）](#8-相关文档related-documentation)
+1. [MODNet 模型](#1-modnet-模型)
+   - [1.1 官方预训练模型](#11-官方预训练模型)
+   - [1.2 微调模型 — 摄影数据集](#12-微调模型--摄影数据集)
+   - [1.3 ONNX 模型变体](#13-onnx-模型变体)
+   - [1.4 目录结构](#14-目录结构)
+   - [1.5 生成与部署指南](#15-生成与部署指南)
+   - [1.6 速查表](#16-速查表)
+2. [RVM 模型](#2-rvm-模型)
+   - [2.1 ONNX 模型](#21-onnx-模型)
+   - [2.2 RKNN 模型](#22-rknn-模型)
+   - [2.3 质量总结](#23-质量总结)
+   - [2.4 推荐模型选择](#24-推荐模型选择)
+   - [2.5 Graph Surgery：移除最终的 Resize 及以后的算子](#25-graph-surgery移除最终的-resize-及以后的算子)
+3. [相关文档](#3-相关文档)
+4. [附录：训练日志摘要](#附录训练日志摘要)
 
 ---
 
-## 1. 官方预训练模型（Official Pretrained Models）
+## 1. MODNet 模型
+
+### 1.1 官方预训练模型
 
-### 1.1 摄影人像抠图（Photographic Portrait Matting）
+#### 摄影人像抠图（Photographic Portrait Matting）
 
 **文件**：`photographic/modnet_photographic_portrait_matting.ckpt`
 
@@ -57,7 +46,7 @@ pipeline_tag: image-segmentation
 - 状态：✓ 生产基线
 ```
 
-### 1.2 摄像头人像抠图（Webcam Portrait Matting）
+#### 摄像头人像抠图（Webcam Portrait Matting）
 
 **文件**：`modnet_webcam_portrait_matting.ckpt`
 
@@ -71,7 +60,7 @@ pipeline_tag: image-segmentation
 - 状态：✓ 可用，当前管线未使用
 ```
 
-### 1.3 MobileNetV2 人体分割（Human Segmentation）
+#### MobileNetV2 人体分割（Human Segmentation）
 
 **文件**：`mobilenetv2_human_seg.ckpt`
 
@@ -85,13 +74,13 @@ pipeline_tag: image-segmentation
 
 ---
 
-## 2. 微调模型（Fine-tuned Models）—— 摄影数据集
+### 1.2 微调模型 — 摄影数据集
 
-### 2.1 纯批归一化变体（Pure Batch Normalization Variant）
+#### 纯批归一化变体（Pure Batch Normalization Variant）
 
 **训练轮次**：Block 1.2 微调（2026-03-19 ~ 2026-03-19）
 
-#### 概要
+##### 概要
 
 ```
 在 P3M-10k 摄影数据集上微调 MODNet-BN
@@ -100,7 +89,7 @@ pipeline_tag: image-segmentation
 - 最佳模型：验证集 L1 Loss 0.0062
 ```
 
-#### 训练配置
+##### 训练配置
 
 | 参数 | 值 |
 |------|-----|
@@ -118,7 +107,7 @@ pipeline_tag: image-segmentation
 | 训练时长 | ~4 小时 |
 | 时间戳 | 2026-03-19 15:40:18 |
 
-#### 生成的制品（Artifacts）
+##### 生成的制品（Artifacts）
 
 ```
 photographic/finetune/
@@ -131,7 +120,7 @@ photographic/finetune/
 ├── logs/
 │   └── block1_2_training_20260319_154018.log  # 训练日志（详细）
 ├── onnx/
-│   └── modnet_bn_best_pureBN.onnx             # ★ ONNX 导出（见 §3.3）
+│   └── modnet_bn_best_pureBN.onnx             # ★ ONNX 导出（见 §1.3.3）
 └── output/
     ├── epoch_01_val.png                       # 验证预览（第 1 轮）
     ├── epoch_02_val.png
@@ -139,7 +128,7 @@ photographic/finetune/
     └── epoch_15_val.png                       # 最终验证可视化
 ```
 
-#### 验证损失曲线（Validation Loss Curve）
+##### 验证损失曲线（Validation Loss Curve）
 
 ```
 Epoch | Val L1 Loss | 改进幅度
@@ -163,7 +152,7 @@ Epoch | Val L1 Loss | 改进幅度
 → 第 5 轮后收敛（学习率调度生效），持续稳步改进
 ```
 
-#### 使用方法
+##### 使用方法
 
 ```python
 # PyTorch 推理
@@ -182,9 +171,9 @@ sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_p
 
 ---
 
-## 3. ONNX 模型变体（ONNX Model Variants）
+### 1.3 ONNX 模型变体
 
-### 3.1 官方原始版本（Photographic）
+#### 官方原始版本（Photographic）
 
 **文件**：`photographic/modnet_photographic_portrait_matting.onnx`
 
@@ -199,7 +188,7 @@ sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_p
 - 注意：InstanceNormalization 在 NPU 上会回退到 CPU，**不推荐用于边缘部署**
 ```
 
-### 3.2 折叠变体（Folded Variant，Anti-fusion）
+#### 折叠变体（Folded Variant，Anti-fusion）
 
 **文件**：`photographic/modnet_photographic_portrait_matting_in_folded.onnx`
 
@@ -215,7 +204,7 @@ sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_p
 - 分析：违背了优化初衷
 ```
 
-### 3.3 纯批归一化版本（ONNX 导出）
+#### 纯批归一化版本（ONNX 导出）
 
 **文件**：`photographic/finetune/onnx/modnet_bn_best_pureBN.onnx`
 
@@ -245,7 +234,7 @@ sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_p
   - RKNN 工具链 v2.3.2（编译阶段验证）
 ```
 
-#### 验证结果（对比参考）
+##### 验证结果（对比参考）
 
 ```
 黄金测试向量（Golden Test Vector）：green-fall-girl-point-to.png (1803×1019)
@@ -256,7 +245,7 @@ sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_p
 
 ---
 
-## 4. 目录结构（Directory Structure）
+### 1.4 目录结构
 
 ```
 MODNet/
@@ -300,9 +289,9 @@ MODNet/
 
 ---
 
-## 5. 生成与部署指南（Generation & Deployment Guide）
+### 1.5 生成与部署指南
 
-### 5.1 ONNX 生成方法
+#### ONNX 生成方法
 
 ```python
 # 第 1 步：训练微调检查点
@@ -344,7 +333,7 @@ onnx.checker.check_model(onnx_model)
 print("✓ ONNX 模型验证通过")
 ```
 
-### 5.2 C++ 推理部署
+#### C++ 推理部署
 
 ```bash
 # 构建 C++ 推理引擎
@@ -362,7 +351,7 @@ cd helmsman.git/
 python3 tools/MODNet/verify_golden_tensor.py
 ```
 
-### 5.3 部署清单（Deployment Checklist）
+#### 部署清单
 
 - [ ] ONNX 模型通过 `onnx.checker.check_model()` 验证
 - [ ] C++ 构建通过黄金张量验证（Golden Tensor Verification）
@@ -372,7 +361,7 @@ python3 tools/MODNet/verify_golden_tensor.py
 
 ---
 
-## 6. 速查表（Quick Reference）
+### 1.6 速查表
 
 | 模型 | 文件 | 大小 | 用途 | 状态 |
 |------|------|------|------|------|
@@ -384,9 +373,9 @@ python3 tools/MODNet/verify_golden_tensor.py
 
 ---
 
-## 7. RobustVideoMatting（RVM）模型
+## 2. RVM 模型
 
-### 7.1 ONNX 模型
+### 2.1 ONNX 模型
 
 位于 `RobustVideoMatting/onnx/`。
 
@@ -405,7 +394,7 @@ python3 tools/MODNet/verify_golden_tensor.py
 - 6 个输入：`src [1,3,H,W]`、`r1i~r4i`（ConvGRU 状态）、`downsample_ratio [1]`
 - 经 ArcFoundry `fold_constant_inputs` 处理后：5 个输入（downsample_ratio 烘焙为常量）
 
-### 7.2 RKNN 模型
+### 2.2 RKNN 模型
 
 位于 `RobustVideoMatting/rknn/`。
 
@@ -426,7 +415,7 @@ python3 tools/MODNet/verify_golden_tensor.py
 - 目标平台：RK3588
 - 归一化：`mean=[0,0,0], std=[255,255,255]`（RKNN 运行时执行 `/255.0`）
 
-### 7.3 质量总结（s14/s20/s21 板端实验）
+### 2.3 质量总结
 
 | 模型 | dsr | 与 PyTorch 的 mean_diff | bg_ratio | 速度（推理+合成） | 备注 |
 |------|-----|------------------------|----------|------------------|------|
@@ -438,7 +427,7 @@ python3 tools/MODNet/verify_golden_tensor.py
 - 所有模型在 `dance.mp4` 上测试（363 帧，1920×1080）
 - 板端：RK3588S，NPU0=40%，NPU1&2=10%
 
-### 7.4 推荐模型选择
+### 2.4 推荐模型选择
 
 | 使用场景 | 推荐模型 | 理由 |
 |----------|---------|------|
@@ -446,14 +435,16 @@ python3 tools/MODNet/verify_golden_tensor.py
 | **速度优先** | `rvm_mobilenetv3_fp16_1080x1920_rk3588_fp16.rknn` | 比 dsr=0.5 快 1.43 倍 |
 | **低内存** | `rvm_mobilenetv3_fp16_288x512_rk3588_fp16_v20260416.rknn` | 最小 r-state 占用 |
 
-### 7.5 Graph Surgery：移除最终的 Resize 及以后的算子
+### 2.5 Graph Surgery：移除最终的 Resize 及以后的算子
 
 > 最终调试版 RKNN 模型（文件名包含 `no-resize`）通过 ArcFoundry `graph_surgery`
 > 把原始 RVM ONNX 中 refiner 末尾的 2 个 Resize + 后续 element-wise 链裁掉，
 > 由 C++ 后处理端自行完成 guided-filter 组合 + 上采样。
 >
-> 详情见仓库内 `log-MR2-P5-s5_8_22-bottleneck-investigation.md`
-> 的 §s5_8_22_12（独立脚本版）和 §s5_8_22_14（ArcFoundry 集成版）。
+> 详情见 `primary-folder/log/log-MR2-P5-s5_8_22-bottleneck-investigation.md`
+> 的 §s5_8_22_12（独立脚本版）和 §s5_8_22_14（ArcFoundry 集成版）；
+> 算子实测对比结果（脚本 + 输出）已嵌入该 PKB 的 §s5_8_22_12 / `### After - 执行` /
+> `2026-07-03 算子数对比验证` 章节。
 
 #### 裁剪点
 
@@ -465,7 +456,7 @@ python3 tools/MODNet/verify_golden_tensor.py
 | **图清理后净减少的节点（实测）** | **36 个**（353 → 317） |
 | 裁剪版图输出 tensor | `777`（Conv_316 输出，refiner A，4ch，272×480）、`779`（Sub_318 输出，refiner b，4ch，272×480），外加 `r1o~r4o` |
 
-#### 实测算子分类对比（脚本：`scripts/compare_rvm_op_counts.py`）
+#### 实测算子分类对比（脚本与实测：见 PKB §s5_8_22_12 / `2026-07-03 算子数对比验证` 章节）
 
 | op_type | 原版 | 裁剪版 | Δ（原版 − 裁剪版） |
 |---------|----:|-----:|------------------:|
@@ -481,8 +472,8 @@ python3 tools/MODNet/verify_golden_tensor.py
 | Split    | 10  |  9   |  +1 |
 | **合计** |    |     | **+36** |
 
-> 上表只列出发生变化的 `op_type`（未变的不列出）。所有数值均由
-> `scripts/compare_rvm_op_counts.py` 在 2026-07-03 实测得出，无估算。
+> 上表只列出发生变化的 `op_type`（未变的不列出）。所有数值由 PKB §s5_8_22_12
+> `2026-07-03 算子数对比验证` 章节中嵌入的脚本在 2026-07-03 实测得出，无估算。
 
 **为什么 `Constant` 减少了 16 个？** 因为 `graph.cleanup()` 会同时清理那些原本只为
 被删节点提供常量输入的 Constant 节点；而 `Shape`/`Slice`/`Concat` 的减少则来自
@@ -494,14 +485,14 @@ A(4ch,272×480) + b(4ch,272×480) 是 C++ 后处理 guided-filter 组合的输
 
 ---
 
-## 8. 相关文档（Related Documentation）
+## 3. 相关文档
 
 - **训练脚本**：`helmsman.git/third-party/scripts/modnet/train_modnet_block1_2.py`
 - **ONNX 导出脚本**：`helmsman.git/third-party/scripts/modnet/onnx/export_onnx_pureBN.py`
 - **C++ 推理**：`helmsman.git/runtime/cpp/apps/matting/client/`
 - **Python 黄金参考**：`helmsman.git/third-party/scripts/modnet/onnx/generate_golden_files.py`
 - **验证工具**：`helmsman.git/tools/MODNet/verify_golden_tensor.py`
-- **RVM PKB**：`/volumes_pkb_helmsman/model/round2-rvm/log-MR2-P5-rknn-inference.md`
+- **RVM 瓶颈 PKB（含算子对比脚本 + 实测结果）**：`primary-folder/log/log-MR2-P5-s5_8_22-bottleneck-investigation.md`
 - **RVM ArcFoundry 配置**：`ArcFoundry.git/configs/rvm/`
 
 ---
@@ -528,6 +519,6 @@ Overfitting: ✓ No significant degradation, clean convergence
 
 ---
 
-**文档版本**：1.2
+**文档版本**：1.3
 **最后更新**：2026-07-03 by PotterWhite
 **提交历史**：通过 Git commit message 追踪