Troubleshooting

MAT Issues

App starts but tracking quality is poor

• Re-check reference_body_size calibration.
• Verify detection mode choice for your scene type.
• Run detection preview on multiple representative frames.

Tracks swap identities at crossings

• Enable backward tracking + merge.
• Reduce assignment gate if false pairings occur.
• Inspect confidence and uncertainty outputs.

Runtime is too slow

• Lower resize_factor.
• Disable non-essential real-time overlays/histograms.
• Verify backend detection (hydra_suite.utils.gpu_utils).

PoseKit Issues

Labeler opens but project behaves inconsistently

• Confirm project keypoint schema matches existing labels.
• Run with --new to force explicit setup when needed.

Model-assisted features fail

• Verify environment has expected ML dependencies.
• Check device selection (auto/cpu/cuda/mps) and memory constraints.

General Diagnostics

• Check session logs generated by GUI components.
• Reduce workflow to smallest reproducible video/frame subset.
• Keep intermediate CSVs and settings snapshots when reporting issues.