项目首页Project home
接口文档API reference
本页目录On this page

工具与进阶接口

用 Tester 完成推理后,可以用这里的工具保存图像、打印分阶段耗时。需要直接调用网络或读取 checkpoint 时,参见下方接口。推理输出的形状和单位见结果字典。

保存可视化

PYTHON
from HccePose.test_script_utils import save_visual_artifacts

save_visual_artifacts(artifacts, enabled=True)

artifacts 是 (path, image) 二元组的可迭代对象,图像采用 OpenCV BGR H × W × 3;保存测试器输出时使用 uint8 图像。enabled=False 时不写文件、返回 []。函数跳过路径或图像为 None 的条目,创建父目录,再调用 cv2.imwrite()。

PYTHON
# output_dir 是选定的本地输出目录。
import os

saved_paths = save_visual_artifacts([
    (os.path.join(output_dir, 'pose.jpg'), results.get('show_6D_vis2')),
    (os.path.join(output_dir, 'detection.jpg'), results.get('show_2D_results')),
])

函数允许覆盖同名文件,并会记录每个尝试写入的路径。它不检查 cv2.imwrite() 的返回值;需要确认写入成功时,请检查目标文件。

源码:save_visual_artifacts。

打印阶段耗时

PYTHON
from HccePose.test_script_utils import print_stage_time_breakdown

print_stage_time_breakdown(results_dict, enabled=False, prefix='')

设置 enabled=True 后打印 time、各阶段秒数和占比,返回 None。耗时字典缺失或格式不符时打印 unavailable 提示。百分比以 results_dict['time'] 为分母,但可视化可能位于这一计时区间之外,所以不保证加总为 100%。见计时定义。

源码:print_stage_time_breakdown。

底层可视化

PYTHON
vis_rgb_mask_Coord(
    rgb_c, pred_mask, pred_front_code, pred_back_code, img_path=None,
)

vis_rgb_mask_Coord_origin(
    cam_K, obj_ids_l, obj_ids_all, BBox_3d_l, Rts_l, conf_s,
    rgb_c, pred_mask, pred_front_code, pred_back_code, img_path=None,
)

函数位于 HccePose.visualization。第一个返回裁剪及编码展示图,第二个返回 (combined_canvas, compact_canvas),并投影模型包围盒。输入是归一化 BGR 张量和编码、掩码张量。第二个函数要求掩码与编码已映射到图像画布,位姿与 BBox_3d_l 使用相同模型坐标约定。

vis_rgb_mask_Coord 返回可视化图像,传入 img_path 时还会把图像保存到该路径。vis_rgb_mask_Coord_origin 返回两幅图像,保留了 img_path 参数,但不使用它写文件。常规推理可让 Tester 准备输入,再用上面的工具保存 show_* 图像。

源码:裁剪图可视化、完整画布可视化。

网络与 checkpoint

PYTHON
from HccePose.network_model import HccePose_BF_Net

HccePose_BF_Net(
    efficientnet_key=None,
    input_channels=3,
    min_xyz=None,
    size_xyz=None,
)

network.inference_batch(inputs, Bbox, thershold=0.5)

inputs 是归一化 BGR 裁剪张量,通常为 N × 3 × 256 × 256。Bbox 为 N × 4 张量,内容是对应图像画布中的 [x, y, width, height]。min_xyz 和 size_xyz 应描述物体轴对齐模型边界,并与运算张量的设备匹配。

调用时按接口的拼写传入 thershold,用于对 sigmoid 后的掩码和编码设阈值。该接口返回稠密预测、解码后的模型坐标及 logits。要获得最终 Rts,还需要检测和 PnP,见结果字段。efficientnet_key=None 选择 ResNet,其余值选择 EfficientNet。

Checkpoint 工具也位于 HccePose.network_model:

PYTHON
get_checkpoint(path)
load_checkpoint(
    check_point_path, net, optimizer=None, local_rank=0, CUDA_DEVICE='0',
)

两处路径都指向 checkpoint 目录。get_checkpoint() 解析文件名 step 前面的分数,返回最高分文件路径。load_checkpoint() 加载 CUDA 权重及可选优化器状态,返回 best_score、iteration_step、keypoints_。当前加载器对无法加载的权重抛出明确异常,并提供物体编号、文件及原因。使用架构兼容的 checkpoint;不要将说明文件或旧权重混放在 best_score/ 中。

源码:网络构造、批推理、checkpoint 选择、checkpoint 加载。

训练与评测边界

训练和评测各有独立的 Python 脚本,参数在脚本内设置。仓库没有统一的 train() 或 evaluate() 接口。下表脚本位于公开上游源码根目录,并非当前项目的本地入口。

脚本 用途
s4_p2_train_bf_pbr.py 逐物体训练;ide_debug=True 为单卡,False 启用 DDP。数据集路径仍为占位值,需编辑。
s4_p2_test_bf_pbr.py 在已裁剪的 PBR 图像上验证网络预测和 PnP。
s4_p2_test_bf_pbr_bop_challenge.py 默认 LM-O 示例,使用外部 GDRNPP 检测,写入分割 JSON 和位姿 CSV,不调用官方评分器、不上传结果。

训练脚本使用 total_iteration=50001、batch_size=24。训练时从同一 train_pbr 目录抽取 ratio=0.01 的样本监控进度。评测独立测试集时请使用相应的评测脚本。

BOP 脚本使用 efficientnet_key=1、脚本列出的 LM-O 物体 ID 及该数据集的检测 JSON。它输出 seg2d_<dataset>.json 和 det6d_<dataset>.csv 供后续评分。两份文件的 time=-1 均为占位值;运行耗时需单独测量。

源码:训练设置、PBR 验证、挑战设置、挑战输出。

Utilities and advanced interfaces

After running inference with Tester, use these helpers to save images and print stage timings. The lower-level interfaces below provide access to the network and checkpoints. See the results API for output shapes and units.

Save visualization artifacts

PYTHON
from HccePose.test_script_utils import save_visual_artifacts

save_visual_artifacts(artifacts, enabled=True)

artifacts is an iterable of (path, image) pairs. Images use OpenCV BGR H × W × 3; use uint8 images when saving the tester outputs. With enabled=False, the helper returns [] without writing. It skips None paths/images, creates parent directories and calls cv2.imwrite().

PYTHON
# output_dir is the chosen local output folder.
import os

saved_paths = save_visual_artifacts([
    (os.path.join(output_dir, 'pose.jpg'), results.get('show_6D_vis2')),
    (os.path.join(output_dir, 'detection.jpg'), results.get('show_2D_results')),
])

Existing files at the same path may be overwritten. The helper records each attempted path without checking the return value of cv2.imwrite(). Check the destination files when you need to confirm that writing succeeded.

Source: save_visual_artifacts.

Print stage times

PYTHON
from HccePose.test_script_utils import print_stage_time_breakdown

print_stage_time_breakdown(results_dict, enabled=False, prefix='')

Set enabled=True to print time, stage seconds and percentages. It returns None. Missing or malformed timing dictionaries print an unavailable message. Percentages use results_dict['time']; visualization can fall outside that interval, so percentages need not sum to 100%. See timing definitions.

Source: print_stage_time_breakdown.

Lower-level visualization

PYTHON
vis_rgb_mask_Coord(
    rgb_c, pred_mask, pred_front_code, pred_back_code, img_path=None,
)

vis_rgb_mask_Coord_origin(
    cam_K, obj_ids_l, obj_ids_all, BBox_3d_l, Rts_l, conf_s,
    rgb_c, pred_mask, pred_front_code, pred_back_code, img_path=None,
)

These functions live in HccePose.visualization. The first returns a crop/code canvas; the second returns (combined_canvas, compact_canvas) with model box projections. The inputs are normalized BGR tensors plus code/mask tensors. The second function requires masks and codes already warped into the image canvas and poses in the same model coordinate convention as BBox_3d_l.

vis_rgb_mask_Coord returns the visualization and also writes it to disk when you supply img_path. vis_rgb_mask_Coord_origin returns two images and does not use its img_path argument. For normal inference, let Tester prepare the inputs and pass its show_* images to the saving helper above.

Sources: crop visualization, full-canvas visualization.

Network and checkpoints

PYTHON
from HccePose.network_model import HccePose_BF_Net

HccePose_BF_Net(
    efficientnet_key=None,
    input_channels=3,
    min_xyz=None,
    size_xyz=None,
)

network.inference_batch(inputs, Bbox, thershold=0.5)

inputs is a normalized BGR crop tensor, typically N × 3 × 256 × 256. Bbox is a tensor N × 4 containing [x, y, width, height] in the associated image canvas. min_xyz and size_xyz must describe the object's axis-aligned model bounds and be compatible with the tensor device.

Use the API spelling thershold to threshold the sigmoid mask and code values. The call returns dense predictions, decoded model coordinates and logits. Detection and PnP are separate steps for computing the final Rts. See result field shapes. efficientnet_key=None selects ResNet. Other values select EfficientNet.

Checkpoint helpers are also in HccePose.network_model:

PYTHON
get_checkpoint(path)
load_checkpoint(
    check_point_path, net, optimizer=None, local_rank=0, CUDA_DEVICE='0',
)

Both paths refer to a checkpoint directory. get_checkpoint() parses score prefixes before step and returns the highest-scoring file path. load_checkpoint() loads CUDA weights and optional optimizer state, returning best_score, iteration_step, and keypoints_. The current loader raises clear errors for invalid checkpoints, including object, file and cause. Use architecture-compatible weights; keep notes and obsolete checkpoints out of best_score/.

Sources: network constructor, batch inference, checkpoint selection, checkpoint loading.

Training and evaluation boundaries

Training and evaluation have separate Python scripts. Set the parameters in the relevant script. There is no shared train() or evaluate() entry point. The scripts below live in the public upstream root, rather than the current project.

Script Purpose
s4_p2_train_bf_pbr.py Per-object training. ide_debug=True selects single-GPU mode; False enables DDP. The dataset path is a placeholder requiring editing.
s4_p2_test_bf_pbr.py Evaluates the loaded network and PnP on cropped PBR images.
s4_p2_test_bf_pbr_bop_challenge.py Default LM-O example with external GDRNPP detections; writes segmentation JSON and pose CSV. It does not invoke the official scorer or upload results.

The training script sets total_iteration=50001 and batch_size=24. To monitor training, it samples ratio=0.01 from the same train_pbr directory. Use the appropriate evaluation script for a held-out test set.

The BOP script uses efficientnet_key=1, the listed LM-O object IDs and the dataset's detection JSON. It writes seg2d_<dataset>.json and det6d_<dataset>.csv for subsequent scoring. Both files use a time=-1 placeholder. Measure runtime separately.

Sources: training settings, PBR validation, challenge setup, challenge output.

打开原图 ↗Open original ↗