Fix revolution labels for shifted phase anchors

[FlorianPfaff]

Summary

• count recurrent-artifact revolutions from the first processed frame
• keep revolution labels invariant to BeltMotionModel.reference_frame and velocity sign
• autoload the compatibility fix for both package-level and direct-module use
• add regressions for equivalent phase anchors and patch reload synchronization

Root cause

belt_revolution_indices() computed traveled distance as abs(velocity * (frame - reference_frame)). reference_frame is an anchor for the phase equation, not the start of the processed sequence. With a nonzero reference frame, the resulting revolution IDs decrease toward the anchor and then increase again, so physically distinct passes can receive the same label.

Impact

Recurrent-artifact maps and train/evaluation revolution splits can merge different physical belt passes whenever callers use an equivalent motion model anchored at a nonzero frame. The fix produces chronological labels starting at zero while preserving the existing output for the default reference_frame=0 case.

Validation

• syntax-checked the patch and regression test with python -m py_compile
• exercised the failing example locally: a model anchored at frame 4 now yields [0, 0, 0, 0, 1, 1, 1, 2], matching the equivalent frame-0 anchor
• added coverage for negative velocity and package/direct-module export synchronization
• full repository CI is pending on GitHub Actions

[github-actions]

✅MegaLinter analysis: Success

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ ACTION	actionlint	10		0	0	0.54s
✅ COPYPASTE	jscpd	yes		no	no	2.04s
✅ MARKDOWN	markdownlint	24	0	0	0	1.19s
✅ PYTHON	ruff	211	1	0	0	0.24s
✅ REPOSITORY	git_diff	yes		no	no	0.02s
✅ YAML	prettier	12	0	0	0	0.83s
✅ YAML	v8r	12		0	0	3.07s
✅ YAML	yamllint	12		0	0	0.48s

Notices

📣 MegaLinter 9.5.0 is out! Discover the new features and security recommendations in the release announcement. (Skip this info by defining SECURITY_SUGGESTIONS: false)

See detailed reports in MegaLinter artifacts

Show us your support by starring ⭐ the repository