refactor(franka): load hand-eye calibration from easy_handeye YAMLs by jx-qiu · Pull Request #168 · RLinf/RPent

jx-qiu · 2026-09-10T02:51:04Z

Previously RPent only accepted a json-based camera calibration file with a custom opaque structure, making it hard for users to understand what data are needed and how yaml results from easy_handeye can be converted to the json file.

User: easy_handeye -> yaml files -> somehow copy yaml fields to json -> consumed by RPent

This PR removes the json format, in favor of directly reading native easy_handeye yamls. This also makes robots/{dual_}franka/config/example.yaml the only configuration surface for end users.

User: easy_handeye -> yaml files -> specify yaml locations in example.yaml -> consumed by RPent

Documentation is updated to include more details on the calibration procedure.

…n robot config Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

read-the-docs-community · 2026-09-10T02:52:09Z

Documentation build overview

📚 RPent-cn | 🛠️ Build #34625651 | 📁 Comparing d0f75a2 against latest (24541d6)

🔍 Preview build

24 files changed · + 5 added · ± 18 modified · - 1 deleted

+ Added

± Modified

- Deleted

rst_source/usage/task_card.html

read-the-docs-community · 2026-09-10T02:52:09Z

Documentation build overview

📚 RPent | 🛠️ Build #34625650 | 📁 Comparing d0f75a2 against latest (24541d6)

🔍 Preview build

24 files changed · + 5 added · ± 18 modified · - 1 deleted

+ Added

± Modified

- Deleted

rst_source/usage/task_card.html

Copilot

🟡 Changes recommended

There are a few concrete correctness/quality issues (exception type consistency in robots/franka/perception.py and reStructuredText tab-indentation that can break Sphinx rendering) that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR refactors Franka and Dual-Franka calibration loading to consume native easy_handeye per-camera YAML outputs directly from perception.calibration in the robot config, removing the legacy JSON “bundle” format and the associated CLI/config surfaces.

Changes:

Remove JSON-based calibration bundle support (hand_eye_calibration.json) and the --calibration-path CLI flag; use perception.calibration YAML mapping in the robot config instead.
Add runtime helpers to parse and validate the calibration mapping and load individual easy_handeye YAML files.
Update unit tests, fixtures, example configs, and docs to reflect the YAML-based calibration flow.

File summaries

File	Description
tests/unit_tests/rpent/utils/test_daemon_lifecycle.py	Test-only import adjustments (now includes unused imports that should be removed).
tests/unit_tests/robots/franka/test_tools.py	Update tests to set robot-config path and validate YAML-based calibration loading.
tests/unit_tests/robots/franka/fixtures/hand_eye_calibration.json	Remove legacy JSON calibration bundle fixture.
tests/unit_tests/robots/franka/fixtures/fr3_wrist_apriltag_ee_eye_on_hand.yaml	Add `easy_handeye`-style wrist calibration YAML fixture.
tests/unit_tests/robots/franka/fixtures/fr3_external_apriltag_eye_on_base.yaml	Add `easy_handeye`-style external calibration YAML fixture.
tests/unit_tests/robots/dual_franka/test_dual_franka_tools.py	Update dual-franka tests to load calibration from robot-config YAML mapping and add error-path test.
tests/unit_tests/robots/dual_franka/fixtures/third_to_right_base_calib_eye_on_base.yaml	Add `easy_handeye`-style base camera calibration YAML fixture.
tests/unit_tests/robots/dual_franka/fixtures/hand_eye_calibration.json	Remove legacy dual-franka JSON calibration bundle fixture.
tests/unit_tests/robots/dual_franka/fixtures/d455_to_right_base_eye_on_base.yaml	Add `easy_handeye`-style D455 calibration YAML fixture.
robots/franka/toolkit.py	Remove runtime `calibration_path` plumbing into primitives/toolkit.
robots/franka/runtime_config.py	Add calibration mapping + `easy_handeye` YAML loading helpers; remove JSON bundle path globals.
robots/franka/robot_spec.py	Remove `--calibration-path` CLI arg and primitives kwargs wiring.
robots/franka/perception.py	Load calibration via robot-config mapping and per-YAML normalization instead of JSON bundle.
robots/franka/config/example.yaml	Add `perception.calibration` example mapping for `external` and `wrist`.
robots/dual_franka/runtime_config.py	Stop emitting `enabled` in perception camera config (aligns with env-server iteration).
robots/dual_franka/robot_spec.py	Remove `--calibration-path` CLI arg and primitives kwargs wiring.
robots/dual_franka/perception.py	Load dual-franka calibration bundle from robot-config YAML mapping and update diagnostics field.
robots/dual_franka/env_server.py	Assume perception cameras mapping exists and iterate directly (no `enabled` gate).
robots/dual_franka/config/example.yaml	Add `perception.calibration` example mapping for `base_camera` and `d455_camera`.
docs/source-zh/rst_source/usage/franka.rst	Update calibration docs to describe YAML mapping approach (code block indentation needs fix).
docs/source-zh/rst_source/usage/dual_franka.rst	Update calibration docs to describe YAML mapping approach (code/bullet indentation needs fix).
docs/source-en/rst_source/usage/franka.rst	Update calibration docs to describe YAML mapping approach (code block indentation needs fix).
docs/source-en/rst_source/usage/dual_franka.rst	Update calibration docs to describe YAML mapping approach (code block indentation needs fix).

Review details

Suppressed comments (2)

docs/source-en/rst_source/usage/dual_franka.rst:72

The robot-config mapping snippet under .. code-block:: yaml is tab-indented; Sphinx code blocks should be indented with spaces to avoid formatting issues.

.. code-block:: yaml

	perception:
	  calibration:
		base_camera: ~/.ros/easy_handeye/third_to_right_base_calib_eye_on_base.yaml
		d455_camera: ~/.ros/easy_handeye/d455_to_right_base_eye_on_base.yaml

docs/source-zh/rst_source/usage/dual_franka.rst:76

This bullet list continuation uses tab indentation, which can render incorrectly in reStructuredText; indent continuation lines with spaces.

* ``robots/dual_franka/config/example.yaml`` 包含机器人身份（两台机器人 IP、相机
	序列号/类型、夹爪连接）、工作空间几何（目标位姿、安全边界）、easy_handeye
	YAML 映射（见上方标定说明）和感知定位边界 + base-frame 变换。

Files reviewed: 23/23 changed files
Comments generated: 6
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

…docs Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

Bring upstream main through 43f32aa: dual-Franka real-world deployment, perception, and operator workflows (RLinf#176), shared LLM backend connectivity check (RLinf#152), Codex provider context limits (RLinf#160), CI aggregate gate job, and robotwin/robocasa test updates. Upstream RLinf#176 threads hand-eye calibration through a --calibration-path JSON bundle, which this branch replaced with direct easy_handeye YAML loading from the robot config (perception.calibration). Migrate the new upstream dual-Franka machinery to the config-driven YAML API: - drop --calibration-path / RPENT_CALIBRATION_PATH from the shared franka env server, dual_franka manual-call script, robot spec, and live-env shell scripts; calibration flows via --robot-config - controller no longer carries calibration_path; the Ray worker resolves calibration from controller["robot_config_path"] - dual_franka perception adopts upstream's config-driven projection_views and DualFrankaPerceptionError while loading transforms via the perception.calibration YAML mapping - migrate the new upstream back_project/segment and rlinf-contract tests from the JSON fixture to the YAML fixtures - keep this branch's fail-fast validate_calibration_sources() in _parse_config and add it to the dual-Franka env worker startup Tests: franka + dual_franka unit tests 52 passed; full unit suite 462 passed with 3 pre-existing failures (missing flywheel extra, test ordering) that also fail on the pre-merge tip. ruff check/format clean; sphinx -W builds both EN and ZH docs. Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

refactor(franka): load hand-eye calibration from easy_handeye YAMLs i…

943643d

…n robot config Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

Copilot AI lite review requested due to automatic review settings September 10, 2026 02:51

Copilot started reviewing on behalf of jx-qiu September 10, 2026 02:51 View session

Copilot AI reviewed Sep 10, 2026

View reviewed changes

jx-qiu added 6 commits September 10, 2026 03:16

docs(franka): drop easy_handeye YAML format details from calibration …

feaedc5

…docs Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

docs(franka): replace tabs with spaces in code block indentation

9ac80bf

Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

fix: linting and remove redundant tests

66c84c4

Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

Merge branch 'main' into feat/franka-calibration

93b10fe

Merge branch 'main' into feat/franka-calibration

a82c07e

refactor: remove custom perception error class

a07f102

Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

qurakchin reviewed Sep 11, 2026

View reviewed changes

Comment thread docs/source-zh/rst_source/usage/dual_franka.rst

Comment thread docs/source-zh/rst_source/usage/dual_franka.rst

Sonorous281 reviewed Sep 11, 2026

View reviewed changes

Comment thread robots/franka/runtime_config.py

Sonorous281 reviewed Sep 11, 2026

View reviewed changes

Comment thread robots/franka/runtime_config.py

Sonorous281 reviewed Sep 11, 2026

View reviewed changes

Comment thread robots/franka/perception.py

jx-qiu added 2 commits September 15, 2026 02:56

feat: fail fast when calibration config is non-existent

f69cc1c

Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

jx-qiu force-pushed the feat/franka-calibration branch from bce9704 to 3ef8ac8 Compare September 15, 2026 03:56

jx-qiu and others added 4 commits September 15, 2026 04:00

docs: clarify calibration file resolution

537142e

Signed-off-by: Jiaxing Qiu <jx.qiu@outlook.com>

Merge branch 'main' into feat/franka-calibration

27eb6f2

Merge upstream/main into feat/franka-calibration

8956ad1

Merge branch 'main' into feat/franka-calibration

d0f75a2

Navigation Menu

refactor(franka): load hand-eye calibration from easy_handeye YAMLs - #168

refactor(franka): load hand-eye calibration from easy_handeye YAMLs#168
jx-qiu wants to merge 13 commits into
RLinf:mainfrom
jx-qiu:feat/franka-calibration

jx-qiu commented Sep 10, 2026 •

edited

Loading

Uh oh!

read-the-docs-community Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

read-the-docs-community Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jx-qiu commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

read-the-docs-community Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (2)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jx-qiu commented Sep 10, 2026 •

edited

Loading

read-the-docs-community Bot commented Sep 10, 2026 •

edited

Loading

read-the-docs-community Bot commented Sep 10, 2026 •

edited

Loading