数据加载接口
BOP 加载器读取物体模型及其元数据。用 Tester 处理自己的图片时,准备好模型信息和配套权重即可。需要读取 BOP 场景与标注时再调用 load_folder()。
模型元数据
from HccePose.bop_loader import bop_dataset
bop_dataset(dataset_path, model_name='models', local_rank=0)
dataset_path 是数据集根目录,model_name 指定其中的模型子目录,local_rank 控制提示信息输出。加载器读取 <dataset_path>/<model_name>/models_info.json,并按六位编号构造 obj_000001.ply 形式的模型路径。
| 属性 | 含义 |
|---|---|
dataset_path、model_path |
数据集根路径和选定的模型目录。 |
model_info |
以字符串物体 ID 为键的模型元数据,包括尺寸、最小坐标、直径及可选对称信息。 |
obj_id_list |
按元数据遍历顺序取得的整数物体 ID。 |
obj_model_list |
与 obj_id_list 对齐的 PLY 路径。 |
obj_info_list |
同一顺序的元数据条目。 |
YOLO 类别从 0 开始编号。Tester 将类别索引用作 obj_id_list 的下标来查找物体 ID。更换检测器或整理模型元数据时,务必保留训练时的类别顺序。
数据集根目录或模型目录不存在时,加载器会打印提示并提前返回。缺少 PLY 文件也会打印提示。创建 Tester 或训练数据集前,请检查提示中列出的路径。
Linux 下导入 bop_loader 会设置 PYOPENGL_PLATFORM=egl。即使只做推理,它仍会导入仓库内的 BOP 工具包和增强依赖。从项目根目录运行 python -m zipfile -e bop_toolkit.zip .,解压后应存在 bop_toolkit/bop_toolkit_lib/。
源码:导入与 EGL 设置、模型加载器、检测类别映射。
场景元数据
dataset.load_folder(folder_name, scene_num=200, vis=0.0)
folder_name是相对数据集的目录名,如train_pbr或test。scene_num按连续的六位场景编号扫描,从000000到编号scene_num - 1。vis保留满足visib_fract >= vis的标注实例。
按 BOP 目录结构准备 scene_camera.json、scene_gt.json、scene_gt_info.json,以及 rgb/ 或 gray/、depth/、mask/ 和 mask_visib/。加载器能处理部分标注缺失的情况,但仍会按深度和掩码文件的后缀构造路径。普通 RGB 图片请直接传给 Tester。
{
'img_info': {...}, # 键如 "000000_000001",表示场景号_图像号
'obj_info': {...}, # 键如 "obj_000001",表示物体编号
'scene_path_list': [...], # 已存在的数字编号场景目录
}
img_info 按图像组织路径、相机信息和标注实例,obj_info 按物体组织实例记录。此调用建立元数据索引,图像像素由后续数据集包装器读取。目标文件夹不存在时返回 None。
源码:load_folder。
训练与评测包装器
train_bop_dataset_back_front(
bop_dataset_item, folder_name,
padding_ratio=1.5, crop_size_img=256, aug_op='imgaug',
)
test_bop_dataset_back_front(
bop_dataset_item, folder_name,
bbox_2D=None, test_targets_bop19=None,
bbox_2D_score_threshold=0.0,
padding_ratio=1.5, crop_size_img=256, ratio=1.0,
)
将任一数据集交给 DataLoader 前,先调用 update_obj_id(obj_id, obj_path) 选择物体。两种数据集都按可见比例阈值 0.2 加载场景。初始化时可能创建 <folder_name>_xyz_GT_front/ 和 <folder_name>_xyz_GT_back/ 目录。
训练样本返回 (rgb_c, mask_vis_c, GT_Front_hcce, GT_Back_hcce)。评测样本追加 (Bbox, cam_K, cam_R_m2c, cam_t_m2c);使用外部检测时再追加 (scene_id, image_id, score)。裁剪图为 BGR 归一化张量。现有训练脚本已处理批次、当前物体选择和 checkpoint 元数据。
缺失的正背面标签图会被零填充。训练前请检查生成的标签,并抽查几个样本。
外部 bbox JSON 条目使用 scene_id、image_id、category_id、bbox 和 score,分数筛选条件为严格的 score > bbox_2D_score_threshold。BOP 挑战脚本提供了现成接入示例。
Data loading API
The BOP loader reads object-model metadata. For inference on your own images with Tester, prepare the model metadata and matching weights. Call load_folder() when you also need BOP scenes and annotations.
Model metadata
from HccePose.bop_loader import bop_dataset
bop_dataset(dataset_path, model_name='models', local_rank=0)
dataset_path is the dataset root, model_name selects its model subdirectory, and local_rank controls informational printing. The loader reads <dataset_path>/<model_name>/models_info.json and constructs model filenames as obj_000001.ply, using six-digit IDs.
| Attribute | Meaning |
|---|---|
dataset_path, model_path |
Dataset root and selected model directory. |
model_info |
Model metadata keyed by string object IDs. Contains dimensions, minimum coordinates, diameter and optional symmetry information. |
obj_id_list |
Integer object IDs in metadata iteration order. |
obj_model_list |
PLY paths aligned with obj_id_list. |
obj_info_list |
Metadata entries in the same order. |
YOLO class indices start at zero. Tester uses the class index as a position in obj_id_list to look up the object ID. Preserve the detector's training class order if you replace the detector or reorganize the metadata.
If the dataset root or model directory is missing, the loader prints a message and returns early. It also reports missing PLY files. Check any reported paths before creating a Tester or training dataset.
On Linux, importing bop_loader sets PYOPENGL_PLATFORM=egl. It imports the repository-local BOP toolkit and augmentation dependencies even when used only for inference. Run python -m zipfile -e bop_toolkit.zip . from the project root; the extracted library is at bop_toolkit/bop_toolkit_lib/.
Sources: imports and EGL setting, model loader, detector class mapping.
Scene metadata
dataset.load_folder(folder_name, scene_num=200, vis=0.0)
folder_nameis a dataset-relative directory, such astrain_pbrortest.scene_numscans consecutive six-digit scene IDs, starting at000000and ending at IDscene_num - 1.viskeeps annotated instances withvisib_fract >= vis.
Use the BOP scene layout with scene_camera.json, scene_gt.json, scene_gt_info.json, rgb/ or gray/, depth/, mask/ and mask_visib/. The loader handles some missing annotations but uses the depth and mask file extensions when constructing paths. Pass standalone RGB images directly to Tester.
{
'img_info': {...}, # Keys such as "000000_000001" (scene ID_image ID)
'obj_info': {...}, # Keys such as "obj_000001" (object ID)
'scene_path_list': [...], # Existing numeric scene folders
}
img_info groups paths, camera information and annotated instances by image. obj_info groups instance records by object. The call indexes metadata; image pixels are loaded later by dataset wrappers. If the requested folder does not exist, it returns None.
Source: load_folder.
Training and evaluation wrappers
train_bop_dataset_back_front(
bop_dataset_item, folder_name,
padding_ratio=1.5, crop_size_img=256, aug_op='imgaug',
)
test_bop_dataset_back_front(
bop_dataset_item, folder_name,
bbox_2D=None, test_targets_bop19=None,
bbox_2D_score_threshold=0.0,
padding_ratio=1.5, crop_size_img=256, ratio=1.0,
)
Before passing either dataset to a DataLoader, select the object with update_obj_id(obj_id, obj_path). Both datasets load scenes with a visibility threshold of 0.2. Initialization may create the <folder_name>_xyz_GT_front/ and <folder_name>_xyz_GT_back/ directories.
Training samples return (rgb_c, mask_vis_c, GT_Front_hcce, GT_Back_hcce). Evaluation samples additionally return (Bbox, cam_K, cam_R_m2c, cam_t_m2c); with external detections they append (scene_id, image_id, score). Crops are BGR-normalized tensors. Existing training recipes handle batching, current-object selection and checkpoint metadata.
Missing front or back label images are filled with zeros. Check the generated labels and inspect a few samples before training.
External bbox JSON entries use scene_id, image_id, category_id, bbox, and score; the score filter is strictly score > bbox_2D_score_threshold. The BOP challenge script provides an existing integration example.
Sources: training wrapper, evaluation wrapper, sample return values.
See the refinement API for the three files in an RGB-D frame and how to convert its depth. The utilities guide lists the training and evaluation scripts.