Analyze Rotation Variety

SUMMARY

Hand-eye calibration is only well-determined when the captured motions span SO(3), pure planar sweeps under-constrain the solve. analyze_rotation_variety checks this on a captured dataset before you commit to a full EyeInHandCalibrator.calibrate() run, see EyeInHandCalibrator for the class this powers.

SUPPORTED TARGETS

Target-independent. It reads only the camera_T_target_list transforms, so it works with poses from any source, though in practice those come from a CharucoTarget eye-in-hand run.

UNITS

camera_T_target_list holds (4, 4) SE(3) matrices with translation in meters. min_rotation_deg, angle_mean_deg, and angle_max_deg are in degrees; axis_span_ratio is a unitless ratio in [0, 1].

The Skill

stats = diagnostics.analyze_rotation_variety(camera_T_target_list, min_rotation_deg=0.5)
print(diagnostics.format_rotation_variety(stats))

Skill	Returns	Description
analyze_rotation_variety(camera_T_target_list, min_rotation_deg=0.5)	RotationVarietyStats | None	Analyzes rotation variety across consecutive camera_T_target frames. min_rotation_deg sets the minimum inter-frame rotation to count as a motion (near-zero motions add no SO(3) information). Returns None if fewer than 3 usable motions are available.
format_rotation_variety(stats)	str	Human-readable report of the result above.

Parameter	Type	Description
camera_T_target_list	list[(4, 4) ndarray]	Per-frame target poses to analyze.
min_rotation_deg	float	Minimum inter-frame rotation counted as a motion, in degrees. Default 0.5.
stats	RotationVarietyStats	Result of analyze_rotation_variety(), for format_rotation_variety().

The Code

from telekinesis.axon import diagnostics

RotationVarietyStats

Field	Type	Description
num_motions	int	Number of inter-frame motions used.
singular_values	list[float]	Singular values of the stacked relative-rotation vectors.
axis_span_ratio	float	sv_min / sv_max, 1.0 is perfect 3D spread, near 0 means coplanar motions.
angle_mean_deg, angle_max_deg	float	Mean / max inter-frame rotation angle.

Best Practices

• axis_span_ratio near 1.0 is good, near 0 is a warning. Below roughly 0.3-0.4, treat the hand-eye result as unreliable regardless of how low its reprojection_error looks, the rotation coverage, not the per-frame detection quality, is the bottleneck at that point (see EyeInHandCalibrator Best Practices).