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

Tester 接口

HccePose.tester.Tester 处理单张 OpenCV 图像或视频帧。检测器为已知物体产生区域,逐物体网络预测掩码及前后表面坐标,PnP 求解位姿。一个物体类别可以出现多个实例。

构造器

PYTHON
from HccePose.tester import Tester

tester = Tester(
    bop_dataset_item,
    show_op=True,
    hccepose_vis=None,
    CUDA_DEVICE='0',
    top_K=None,
    crop_size=256,
    efficientnet_key=None,
    megapose_model_name_rgb='megapose-1.0-RGB-multi-hypothesis',
    megapose_model_name_rgbd='megapose-1.0-RGBD',
    hccepose_acceleration='pytorch',
    hccepose_acceleration_cache_dir=None,
)
参数 含义
bop_dataset_item BOP 加载器,提供模型、权重根目录及物体顺序。
hccepose_vis 非 None 时覆盖 show_op;控制四个基础可视化字段。
CUDA_DEVICE CUDA 编号字符串,如 '0'。当前推理流程需要 CUDA。
top_K 预留参数,不限制实际检测或位姿数量。
crop_size 默认 256;需与网络及可视化布局匹配,不用于更改原图分辨率。
efficientnet_key None 使用 ResNet 分支,其他值选择 EfficientNet;必须匹配权重。
megapose_model_name_rgb、megapose_model_name_rgbd MegaPose 注册时采用的模型名称。
hccepose_acceleration 'pytorch'、'onnx' 或 'tensorrt',仅选择网络执行后端。
hccepose_acceleration_cache_dir 导出及后端缓存目录;None 时使用各物体的默认目录。

兼容参数 acceleration 和 acceleration_cache_dir 仍可使用,非 None 时覆盖对应的 HccePose 专用参数。加速行为见加速说明。

初始化会加载 models_info.json 中的全部物体,而不只加载之后请求预测的编号。每个物体都需有匹配的位姿权重。YOLO 类别索引通过加载器的 obj_id_list 映射到 BOP 物体编号,因此元数据顺序必须与检测器训练时一致。

即使初始化打印 CPU 回退信息,创建物体边界张量和加载权重仍有 CUDA 路径,不能据此认为支持完整 CPU 推理。损坏或不兼容的 checkpoint 会报告对应物体、路径及原因。

预测

PYTHON
results = tester.predict(
    cam_K, image_bgr, object_ids,
    confidence_threshold=0.75,
    conf=0.75,
    iou=0.50,
    max_det=200,
    pnp_op='ransac+comb',
    depth=None,
    use_megapose=False,
    megapose_vis=False,
    megapose_vis_stages=None,
)
输入 约定
cam_K NumPy 3×3 原图内参,单位为像素,必须对应当前输入尺寸。
image_bgr NumPy H×W×3、uint8,保持 OpenCV BGR 顺序。
object_ids 请求的 BOP 物体编号,不是 YOLO 类别索引;每个编号可返回多个实例。
conf 传给 YOLO 的检测置信度阈值。
confidence_threshold 仅控制 2D 检测图的绘制,不过滤返回的位姿。
iou、max_det 传给 YOLO 的检测去重参数和数量上限。
pnp_op epnp、ransac、ransac+vvs、ransac+comb 或 ransac+vvs+comb。
depth 可选的配准深度,H×W,单位为米;提供后可用于 MegaPose RGB-D。
use_megapose 请求 MegaPose 精修;未注册时在首次使用时注册。
megapose_vis、megapose_vis_stages 请求 MegaPose 调试图及阶段选择。

组合 PnP 模式需要 checkpoint 中的 keypoints_ 先验;缺少时会在检测前报错,不会静默替换求解方式。输出中的 pnp_success 用于逐实例判断初始 PnP 是否成功。

最长边超过 640 像素的输入会先缩小,再按检测器 32 像素步长补边;内参和可选深度同步调整。二维结果字段以处理后画布为准。完整图像掩码须通过还原函数回到输入分辨率。

PYTHON
# 模型只初始化一次;在图片列表或视频循环中重复调用。
results = tester.predict(cam_K, image_bgr, [1])
entry = results.get(1)
if entry is not None:
    valid = entry['pnp_success']
    poses_mm = entry['Rts'][valid]
    print(poses_mm[:, :3, 3])

没有检出的物体不会有对应整数键;字符串键保存计时和图像等信息。完整字段见结果字典。WAPR 通过独立的掩码接入函数调用。

Tester API

HccePose.tester.Tester processes one OpenCV image or video frame. A detector proposes regions for known objects, per-object networks predict masks and front/back coordinates, and PnP estimates poses. Each object category may have multiple instances.

Constructor

PYTHON
from HccePose.tester import Tester

tester = Tester(
    bop_dataset_item,
    show_op=True,
    hccepose_vis=None,
    CUDA_DEVICE='0',
    top_K=None,
    crop_size=256,
    efficientnet_key=None,
    megapose_model_name_rgb='megapose-1.0-RGB-multi-hypothesis',
    megapose_model_name_rgbd='megapose-1.0-RGBD',
    hccepose_acceleration='pytorch',
    hccepose_acceleration_cache_dir=None,
)
Argument Meaning
bop_dataset_item BOP loader containing models, the asset root and object ordering.
hccepose_vis Overrides show_op when not None; controls the four base visualization fields.
CUDA_DEVICE CUDA index as a string, such as '0'. The current inference pipeline requires CUDA.
top_K Reserved; does not limit detections or poses.
crop_size Defaults to 256; must match the network and visualization layout, rather than the original image size.
efficientnet_key None selects ResNet; other values select EfficientNet. Must match the checkpoint.
megapose_model_name_rgb, megapose_model_name_rgbd Model names used when registering MegaPose.
hccepose_acceleration 'pytorch', 'onnx' or 'tensorrt'; selects the network execution backend.
hccepose_acceleration_cache_dir Export/backend cache location, or None for per-object defaults.

The compatibility arguments acceleration and acceleration_cache_dir remain available. Non-None values override the corresponding HccePose-specific settings. See acceleration.

Initialization loads every object listed in models_info.json, rather than only the IDs later requested for prediction. Each needs a matching checkpoint. YOLO category indices map through the loader’s obj_id_list, whose order must match detector training.

A CPU fallback message during initialization does not imply full CPU support: object-bound tensors and checkpoint loading still use CUDA paths. Invalid or incompatible checkpoints report the object, path and cause.

Prediction

PYTHON
results = tester.predict(
    cam_K, image_bgr, object_ids,
    confidence_threshold=0.75,
    conf=0.75,
    iou=0.50,
    max_det=200,
    pnp_op='ransac+comb',
    depth=None,
    use_megapose=False,
    megapose_vis=False,
    megapose_vis_stages=None,
)
Input Contract
cam_K NumPy 3×3 original-image intrinsics in pixels, matching the input dimensions.
image_bgr NumPy H×W×3, uint8, in OpenCV BGR order.
object_ids BOP object IDs, not YOLO category indices; each may return multiple instances.
conf Detection confidence threshold passed to YOLO.
confidence_threshold Controls only drawing in the 2D detection image; does not filter returned poses.
iou, max_det Detector suppression setting and maximum number of detections passed to YOLO.
pnp_op epnp, ransac, ransac+vvs, ransac+comb or ransac+vvs+comb.
depth Optional registered H×W depth in meters; enables the MegaPose RGB-D model.
use_megapose Requests refinement; registers MegaPose on first use if needed.
megapose_vis, megapose_vis_stages Request MegaPose debug images and select stages.

Combined PnP modes require keypoints_ in the checkpoint. Missing priors raise before detection rather than silently changing the solver. Inspect pnp_success for each instance’s initial PnP status.

Inputs whose longest side exceeds 640 pixels are resized and then padded to the detector’s 32-pixel stride. Intrinsics and optional depth are adjusted together. Pixel-valued result fields use this processed canvas. Use the mask restoration helper to return to input resolution.

PYTHON
# Initialize the models once; repeat prediction for images or video frames.
results = tester.predict(cam_K, image_bgr, [1])
entry = results.get(1)
if entry is not None:
    valid = entry['pnp_success']
    poses_mm = entry['Rts'][valid]
    print(poses_mm[:, :3, 3])

Undetected objects have no corresponding integer key. String keys contain timings and images. See the results dictionary. Call WAPR through the separate mask integration function.

打开原图 ↗Open original ↗