Gen6D 技术故障排查指南

Gen6D 作为 ECCV2022 开源项目，提供了从 RGB 图像中实现通用化无模型 6-DoF 对象姿态估计的核心能力，帮助开发者无需特定模型训练即可对未知对象进行精准姿态估计。

【环境配置失败：依赖包安装冲突】

问题场景

执行 pip install -r requirements.txt 时出现 ERROR: Could not find a version that satisfies the requirement torch==1.7.1 报错，或安装后运行 train_model.py 提示 ImportError: cannot import name 'xxx' from 'torch'。

原因分析

1. Python 版本与依赖包不兼容（如 Python 3.10 与 PyTorch 1.7.1 存在兼容性问题）
2. pip 版本过低导致依赖解析失败
3. 未正确配置 CUDA 环境导致 GPU 版本 PyTorch 安装失败

分步解决方案

🔧 方案 A：使用 pip 安装

1. 检查 Python 版本：

   python --version
   

   注意：确保版本为 3.7-3.9，3.10+ 可能存在兼容性问题

2. 升级 pip 并安装依赖：

   python -m pip install --upgrade pip
   pip install -r requirements.txt
   

🔧 方案 B：使用 conda 环境（推荐新手）

1. 创建并激活环境：

   conda create -n gen6d python=3.8 -y
   conda activate gen6d
   

2. 安装 PyTorch（以 CUDA 10.2 为例）：

   conda install pytorch==1.7.1 torchvision==0.8.2 cudatoolkit=10.2 -c pytorch
   

3. 安装剩余依赖：

   pip install -r requirements.txt
   

预防建议

• 在项目根目录创建 environment.yml 保存环境配置
• 使用 pip freeze > requirements.txt 更新依赖版本
• 定期检查 PyTorch 官方文档 确认 CUDA 兼容性

💡 经验总结：环境问题80%源于版本不匹配，建议严格按照 requirements.txt 指定版本安装，GPU 用户需特别注意 CUDA 版本与 PyTorch 版本的对应关系。

【数据集加载错误：文件路径找不到】

问题场景

运行 python eval.py --cfg configs/gen6d_pretrain.yaml --object_name genmop/tformer 时，终端提示 FileNotFoundError: [Errno 2] No such file or directory: 'data/GenMOP/tformer/texture.png'。

原因分析

1. 数据集未按要求放置在指定目录
2. 配置文件中的路径参数与实际文件位置不匹配
3. 数据集下载不完整或解压失败

分步解决方案

🔧 确认数据集结构

1. 检查项目根目录是否存在以下结构：

   Gen6D
   ├── data
   │   ├── GenMOP
   │   │   └── tformer
   │   └── LINEMOD
   

   注意：data 目录需手动创建，不会随代码仓库自动下载

2. 下载并放置数据集：

   • 从项目提供的数据源获取 GenMOP 和 LINEMOD 数据集
   • 确保 genmop/tformer 目录下包含 texture.png 和 model.ply 等必要文件

🔧 验证配置文件路径

1. 打开 configs/gen6d_pretrain.yaml，检查以下参数：

   DATASET:
     ROOT: 'data'
     OBJECT: 'genmop/tformer'
   

2. 确保配置中的路径与实际文件位置一致

预防建议

• 使用 tree data 命令检查数据集目录结构
• 修改配置文件后使用 grep -r "data/" configs/ 验证所有路径引用
• 下载大型数据集时使用校验和验证文件完整性

💡 经验总结：数据集问题通常是路径或文件缺失导致，建议遵循项目标准目录结构，对于自定义对象，可参考 custom_object.md 文档进行配置。

【模型训练失败：CUDA 内存不足】

问题场景

启动训练命令 python train_model.py --cfg configs/gen6d_train.yaml 后，训练开始不久即报错 RuntimeError: CUDA out of memory. Tried to allocate 2048.00 MiB (GPU 0; 11.76 GiB total capacity; 9.87 GiB already allocated; 1.52 GiB free; 10.05 GiB reserved in total by PyTorch)。

原因分析

1. 批处理大小（batch size）设置过大
2. 输入图像分辨率超出 GPU 处理能力
3. 模型参数过多或中间特征图尺寸过大

分步解决方案

🔧 降低批处理大小

1. 打开训练配置文件：

   vim configs/gen6d_train.yaml
   

2. 修改 batch size 参数：

   TRAIN:
     BATCH_SIZE: 4  # 从 8 降至 4
   

🔧 调整输入分辨率

1. 在配置文件中找到数据预处理部分：

   DATA_TRANSFORM:
     RESIZE: [480, 640]  # 从 [640, 800] 降低分辨率
   

🔧 使用混合精度训练

1. 安装 apex 库：

   git clone https://github.com/NVIDIA/apex
   cd apex
   pip install -v --disable-pip-version-check --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./
   

2. 在训练脚本中启用混合精度：

   from apex import amp
   model, optimizer = amp.initialize(model, optimizer, opt_level="O1")
   

预防建议

• 训练前使用 nvidia-smi 检查 GPU 内存使用情况
• 对于 12GB 以下显存的 GPU，建议从 batch size=2 开始尝试
• 优先使用 --cfg configs/gen6d_pretrain.yaml 进行预训练，再加载权重进行微调

💡 经验总结：CUDA 内存问题是训练中的常见挑战，通过降低 batch size、分辨率和启用混合精度这三个步骤，可解决大多数内存不足问题。

【姿态估计结果异常：边界框偏移或模型错位】

问题场景

运行预测命令后生成的结果图像中，3D 边界框与实际物体位置偏差明显，或模型姿态出现明显倾斜、翻转等错误。

原因分析

1. 检测阶段未正确定位物体（边界框不准确）
2. 相机内参 calibration 文件缺失或错误
3. 特征匹配过程中出现误匹配

分步解决方案

🔧 检查物体检测结果

1. 查看检测阶段输出：

   python predict.py --cfg configs/gen6d_pretrain.yaml --input_image test.jpg --show_detection
   

   注意：确保绿色检测框准确包围物体，如下所示：

2. 如果检测框不准确，尝试：

   python train_model.py --cfg configs/detector/detector_train.yaml
   

🔧 验证相机内参

1. 检查 data/[dataset]/camera.txt 文件是否存在
2. 若无相机参数，使用 colmap 生成：

   python colmap_script.py --image_dir data/test_images --output_dir data/colmap_output
   

🔧 启用姿态优化

1. 在配置文件中开启 refinement 模块：

   MODEL:
     REFINE: True
   

2. 查看优化过程对比：

预防建议

• 确保输入图像光照均匀，避免强反光或遮挡
• 对于纹理较少的物体，增加多角度图像进行训练
• 使用 compute_align_poses.py 工具评估姿态精度

💡 经验总结：姿态估计结果异常通常需要从检测、相机参数和优化三个环节排查，逐步定位问题根源。

常见问题速查表

问题现象	可能原因	解决方案
依赖包安装失败	Python版本不兼容	降级至Python 3.8并使用pip安装
数据集路径错误	目录结构不正确	按要求创建data目录并放置数据集
CUDA内存不足	batch size过大	调整为2-4并降低输入分辨率
检测框偏移	检测器权重问题	重新训练detector模型
姿态估计错误	相机参数缺失	运行colmap_script.py生成内参
训练中断	数据加载错误	检查数据集完整性和路径配置
预测无输出	模型路径错误	确认配置文件中MODEL.PATH正确
评估指标异常	物体名称错误	检查--object_name参数与数据集匹配