blackbird/docs/reports/actpred_safe_image_augmentation_20260813.md

actpred 训练时安全图像增强

文档类型：特性报告 模块：actpred 日期：2026-08-13

---

1. 背景

pybot dry-run 录制的 episode 数据样本量有限（11 个脚本 → 12 个 episode → ~728 样本），训练容易过拟合。直接增大数据集需要更多 .mt 脚本或更多轮次录制，成本较高。

图像增强（data augmentation）是低成本扩充样本的标准手段，但机器人动作预测场景有特殊约束：空间变换（翻转/旋转/裁剪）会改变图像的语义坐标，而动作标签未随之变换，导致训练对错误。例如水平翻转后，左右舵机角度应互换，但标签不变，形成错误训练信号。

2. 方案

2.1 增强范围

仅启用颜色空间变换（ColorJitter），不涉及任何空间变换：

变换	参数	说明
亮度	±20%（factor ∈ [0.8, 1.2]）	模拟不同光照条件
对比度	±20%（factor ∈ [0.8, 1.2]）	模拟不同摄像头增益
饱和度	±20%（factor ∈ [0.8, 1.2]）	模拟不同色温环境
色调	±5%（factor ∈ [-0.05, 0.05]）	轻微色偏，避免模型过依赖颜色

不使用的变换（因需同步变换动作标签）：

变换	原因
水平/垂直翻转	左右舵机角度需互换，否则标签错误
旋转	重力方向变化，姿态语义改变
裁剪/平移	视野变化导致动作-画面对应关系改变
透视变换	改变空间关系

2.2 同一样本内帧间参数一致性

一个训练样本包含 frame_len 帧连续图像（默认 3 帧，间隔 10ms）。真实场景中连续帧的光照条件不变，因此同一样本内所有帧共享同一组增强参数，而非每帧独立随机：

if self.augment:
    bf = random.uniform(0.8, 1.2)   # 亮度因子，所有帧共用
    cf = random.uniform(0.8, 1.2)   # 对比度因子
    sf = random.uniform(0.8, 1.2)   # 饱和度因子
    hf = random.uniform(-0.05, 0.05) # 色调因子
for p in image_paths:
    image = Image.open(p).convert("RGB")
    if self.augment:
        image = TF.adjust_brightness(image, bf)
        image = TF.adjust_contrast(image, cf)
        image = TF.adjust_saturation(image, sf)
        image = TF.adjust_hue(image, hf)
    frames.append(self.transform(image))

不同样本（不同 __getitem__ 调用）使用独立随机参数，保证整个数据集的增强多样性。

2.3 自适应 frame_len

增强逻辑在 for p in image_paths 循环前生成参数、循环内逐帧施加。image_paths 的长度由 frame_len 决定（image_files[t - frame_len + 1 : t + 1]），循环自动适配。frame_len 为 1、2、3、5、10 等任意值时均无需修改代码。

2.4 训练/验证隔离

数据集	增强	说明
训练集	augment=cfg.train.augment	CLI --augment 控制
验证集	augment=False（默认）	验证 loss 反映真实分布表现

推理端（predict.py / onnx_infer.py / hailo_infer.py）不涉及增强，使用原始图像。

3. CLI 接口

# 训练时启用图像增强
bash _run.sh train --data-dir ./data --epochs 100 --augment

# 显式关闭（默认关闭）
bash _run.sh train --data-dir ./data --epochs 100 --no-augment

--augment 使用 BooleanOptionalAction，支持 --augment / --no-augment 双向开关。

4. 验证

4.1 功能验证

dataset size: 728 samples
augment diff (should be >0): 0.3767        # 增强前后图像有差异
two augment calls diff (should be >0): 0.2626  # 两次增强参数不同（随机性）
action_history diff (should be 0): 0.0     # 动作标签不受影响
target diff (should be 0): 0.0

4.2 端到端训练

--augment --epochs 3（64×64，batch=8）训练正常完成，loss 正常下降。

4.3 回归测试

全量单测 90/90 通过，无回归。

5. 改动文件

文件	改动
actpred/dataset.py	ActionDataset 新增 augment 参数；__getitem__ 在 Resize 前施加 ColorJitter（torchvision.transforms.functional）
actpred/config.py	TrainConfig 新增 augment: bool = False；build_argparser 新增 --augment；apply_overrides 新增映射
actpred/train.py	训练集构造传 augment=cfg.train.augment，验证集默认不增强

6. 后续方向

• 空间增强（需同步标签变换）：水平翻转时自动交换左右舵机角度（s1↔s2, s3↔s4, s5↔s6, s7↔s8），可将训练数据量翻倍。需要了解舵机配对关系后实现。
• 动作噪声增强：pretrain_mt.py 已支持 --noise-std，train.py 可同样引入，对 action_history 和 target 施加高斯扰动。
• 更多 .mt 脚本：从根本上扩大动作多样性，是提升模型泛化能力的最有效手段。