Skip to content

Hand-Eye Result ​

SUMMARY

Write and read a hand_eye.json result file: one tcp_T_camera per camera, plus the intrinsics, reprojection error and consistency it was obtained with. See EyeInHandCalibrator.

UNITS

tcp_T_camera_list holds (4, 4) SE(3) matrices with translation in meters, each the pose of the camera optical frame (x right, y down, z forward) in the TCP (or flange) frame. Reprojection errors are RMS in pixels; consistency values are in meters and degrees.

The Skill ​

python
path = io.save_hand_eye_result(
    output_path,
    reference_index=0,
    tcp_T_camera_list=[tcp_T_camera],
    method=None,
    num_frames_used=None,
    num_frames_total=None,
    intrinsic_matrices=None,
    distortion_coefficients=None,
    reprojection_errors=None,
    consistency_mean_translation_m=None,
    consistency_mean_rotation_deg=None,
)
fields = io.load_hand_eye_result(input_path)
SkillReturnsDescription
save_hand_eye_result(output_path, *, reference_index, tcp_T_camera_list, ...)PathWrite a hand_eye.json result file. If output_path is a directory (or has no extension), writes <output_path>/hand_eye.json. Returns the file written.
load_hand_eye_result(input_path)dictRead a hand_eye.json file (or the one inside a directory).

All parameters after output_path are keyword-only:

ParameterTypeDescription
output_pathstr | PathFile path, or a directory to write hand_eye.json into.
reference_indexintReference camera index.
tcp_T_camera_listlist[(4, 4) ndarray | None]One transform per camera; None for a camera without a result. num_cameras is its length.
methodstr | NoneHand-eye method used, e.g. "TSAI".
num_frames_usedint | NoneFrames used in the solve.
num_frames_totalint | NoneFrames captured.
intrinsic_matriceslist[(3, 3) ndarray | None] | NonePer camera, the camera matrix the transform was solved with.
distortion_coefficientslist[ndarray | None] | NonePer camera, the distortion coefficients.
reprojection_errorslist[float | None] | NonePer camera, intrinsic RMS reprojection error (px).
consistency_mean_translation_mlist[float | None] | NonePer camera, mean TargetConsistencyStats translation deviation.
consistency_mean_rotation_deglist[float | None] | NonePer camera, mean TargetConsistencyStats rotation deviation.

load_hand_eye_result() returns a dict with the same keys (plus num_cameras). Missing entries round-trip as Python None. Files written before the intrinsics and metrics were added still load; those keys then come back as empty lists.

EyeInHandCalibrator.calibrate(..., output_path=...) writes this file for you after a successful solve, filling every field for its single camera.

The Code ​

python
from telekinesis.axon import EyeInHandCalibrator, io

result = calibrator.calibrate(robot_T_tcp_list, image_list)

path = io.save_hand_eye_result(
    "results/",
    reference_index=0,
    tcp_T_camera_list=[result.tcp_T_camera],
    method="TSAI",
    num_frames_used=len(result.camera_T_target_list),
    num_frames_total=len(robot_T_tcp_list),
    intrinsic_matrices=[result.intrinsic_matrix],
    distortion_coefficients=[result.distortion_coefficients],
    reprojection_errors=[result.reprojection_error],
    consistency_mean_translation_m=[result.consistency.mean_translation_m],
    consistency_mean_rotation_deg=[result.consistency.mean_rotation_deg],
)

fields = io.load_hand_eye_result(path)
tcp_T_camera = fields["tcp_T_camera_list"][0]
K = fields["intrinsic_matrices"][0]

Output (results/hand_eye.json):

json
{
  "reference_index": 0,
  "num_cameras": 1,
  "method": "TSAI",
  "num_frames_used": 18,
  "num_frames_total": 20,
  "tcp_T_camera_list": [[[...], [...], [...], [0.0, 0.0, 0.0, 1.0]]],
  "transform_convention": "tcp_T_camera_list[i] is the pose of camera i's optical frame (OpenCV: x right, y down, z forward) in the frame the robot poses referred to (TCP or flange); it maps camera-frame points into that frame. Translations are in meters.",
  "intrinsic_matrices": [[[fx, 0, cx], [0, fy, cy], [0, 0, 1]]],
  "distortion_coefficients": [[k1, k2, p1, p2, k3]],
  "reprojection_errors_px": [0.31],
  "consistency_mean_translation_m": [0.0008],
  "consistency_mean_rotation_deg": [0.05]
}

transform_convention is written for human readers and ignored on load. In the file, the per-camera reprojection errors are stored under reprojection_errors_px; in Python they are the reprojection_errors argument and key. null marks a missing entry.