From dfd5e1de20d8c101a67ec563414f41c796aa2d61 Mon Sep 17 00:00:00 2001 From: eust-w Date: Wed, 24 Jun 2026 11:47:18 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Add=20simulation=20and=20transform?= =?UTF-8?q?=20validation=20operators?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/operator-runner/main.py | 9 + backend/operator-runner/test_main.py | 125 ++++++ .../mjcf_actuator_validate/__init__.py | 1 + .../mjcf_actuator_validate/operator.json | 16 + .../mjcf_actuator_validate/operator.py | 226 +++++++++++ .../mjcf_actuator_validate/repository.json | 31 ++ .../robomimic_hdf5_validate/__init__.py | 1 + .../robomimic_hdf5_validate/operator.json | 16 + .../robomimic_hdf5_validate/operator.py | 372 ++++++++++++++++++ .../robomimic_hdf5_validate/repository.json | 32 ++ .../tf_transform_tree_validate/__init__.py | 1 + .../tf_transform_tree_validate/operator.json | 16 + .../tf_transform_tree_validate/operator.py | 294 ++++++++++++++ .../repository.json | 31 ++ docs/operators/MJCF-执行器校验.md | 109 +++++ docs/operators/README.md | 5 +- docs/operators/TF-坐标树校验.md | 113 ++++++ docs/operators/robomimic-HDF5-示教校验.md | 121 ++++++ internal/api/builtin_operators_catalog.json | 174 ++++++++ .../generate_operator_repository_manifests.py | 3 + 20 files changed, 1695 insertions(+), 1 deletion(-) create mode 100644 backend/operators/builtin/mjcf_actuator_validate/__init__.py create mode 100644 backend/operators/builtin/mjcf_actuator_validate/operator.json create mode 100644 backend/operators/builtin/mjcf_actuator_validate/operator.py create mode 100644 backend/operators/builtin/mjcf_actuator_validate/repository.json create mode 100644 backend/operators/builtin/robomimic_hdf5_validate/__init__.py create mode 100644 backend/operators/builtin/robomimic_hdf5_validate/operator.json create mode 100644 backend/operators/builtin/robomimic_hdf5_validate/operator.py create mode 100644 backend/operators/builtin/robomimic_hdf5_validate/repository.json create mode 100644 backend/operators/builtin/tf_transform_tree_validate/__init__.py create mode 100644 backend/operators/builtin/tf_transform_tree_validate/operator.json create mode 100644 backend/operators/builtin/tf_transform_tree_validate/operator.py create mode 100644 backend/operators/builtin/tf_transform_tree_validate/repository.json create mode 100644 docs/operators/MJCF-执行器校验.md create mode 100644 docs/operators/TF-坐标树校验.md create mode 100644 docs/operators/robomimic-HDF5-示教校验.md diff --git a/backend/operator-runner/main.py b/backend/operator-runner/main.py index e7828701..f5c3a663 100644 --- a/backend/operator-runner/main.py +++ b/backend/operator-runner/main.py @@ -57,6 +57,7 @@ from backend.operators.builtin.lerobot_metadata_consistency_validate import oper from backend.operators.builtin.language_instruction_validate import operator as language_instruction_validate_operator from backend.operators.builtin.mcap_topic_summary import operator as mcap_topic_summary_operator from backend.operators.builtin.merge import operator as merge_operator +from backend.operators.builtin.mjcf_actuator_validate import operator as mjcf_actuator_validate_operator from backend.operators.builtin.model_inference import operator as model_inference_operator from backend.operators.builtin.mongodb_write import operator as mongodb_write_operator from backend.operators.builtin.package import operator as package_operator @@ -64,6 +65,7 @@ from backend.operators.builtin.parquet_table_summary import operator as parquet_ from backend.operators.builtin.pointcloud_summary import operator as pointcloud_summary_operator from backend.operators.builtin.real_source import operator as real_source_operator from backend.operators.builtin.rlds_episode_summary import operator as rlds_episode_summary_operator +from backend.operators.builtin.robomimic_hdf5_validate import operator as robomimic_hdf5_validate_operator from backend.operators.builtin.robot_model_asset_validate import operator as robot_model_asset_validate_operator from backend.operators.builtin.rosbag_summary import operator as rosbag_summary_operator from backend.operators.builtin.rgbd_frame_pair_validate import operator as rgbd_frame_pair_validate_operator @@ -72,6 +74,7 @@ from backend.operators.builtin.sensor_timestamp_sync_validate import operator as from backend.operators.builtin.shell_command import operator as shell_command_operator from backend.operators.builtin.template_render import operator as template_render_operator from backend.operators.builtin.tfrecord_structural_validate import operator as tfrecord_structural_validate_operator +from backend.operators.builtin.tf_transform_tree_validate import operator as tf_transform_tree_validate_operator from backend.operators.builtin.trajectory_integrity_validate import operator as trajectory_integrity_validate_operator from backend.operators.builtin.upload import operator as upload_operator from backend.operators.builtin.video_annotate import operator as video_annotate_operator @@ -4944,6 +4947,7 @@ BUILTIN_HANDLER_RULES: tuple[tuple[str, tuple[str, ...]], ...] = ( ("hf_dataset_probe", ("hf 数据集探测", "huggingface dataset", "hf dataset", "dataset viewer")), ("rlds_episode_summary", ("rlds", "tfds", "open x-embodiment", "轨迹概览")), ("aloha_hdf5_validate", ("aloha hdf5", "aloha 示教", "act hdf5", "aloha 数据校验")), + ("robomimic_hdf5_validate", ("robomimic hdf5", "robomimic 示教", "robomimic 数据校验", "robomimic dataset")), ("hdf5_demonstration_summary", ("hdf5 示教", "hdf5 demo", "robomimic", "droid hdf5")), ("vla_sample_manifest_validate", ("vla 样本", "vla manifest", "openvla", "视觉语言动作", "droid manifest")), ("lerobot_dataset_validate", ("lerobot 数据集校验", "lerobot validate", "lerobot validation")), @@ -4959,6 +4963,8 @@ BUILTIN_HANDLER_RULES: tuple[tuple[str, tuple[str, ...]], ...] = ( ("webdataset_shard_summary", ("webdataset 分片", "webdataset shard", "tar shard", "分片概览")), ("zarr_trajectory_summary", ("zarr 轨迹", "zarr trajectory", "zarr array", "数组轨迹")), ("camera_calibration_validate", ("相机标定校验", "camera calibration", "intrinsics", "extrinsics")), + ("tf_transform_tree_validate", ("tf 坐标树", "transform tree", "tf tree", "坐标树校验", "frametree")), + ("mjcf_actuator_validate", ("mjcf 执行器", "mjcf actuator", "mujoco actuator", "执行器校验", "ctrlrange")), ("robot_model_asset_validate", ("机器人模型资产校验", "robot model asset", "urdf", "mjcf")), ("pointcloud_summary", ("点云数据概览", "point cloud", "pointcloud", "pcd", "ply")), ("sensor_timestamp_sync_validate", ("多传感器时间同步", "timestamp sync", "sensor sync", "时间同步")), @@ -5016,6 +5022,7 @@ BUILTIN_HANDLERS: dict[str, BuiltinHandler] = { "rlds_episode_summary": operator_handler(rlds_episode_summary_operator), "hdf5_demonstration_summary": operator_handler(hdf5_demonstration_summary_operator), "aloha_hdf5_validate": operator_handler(aloha_hdf5_validate_operator), + "robomimic_hdf5_validate": operator_handler(robomimic_hdf5_validate_operator), "vla_sample_manifest_validate": operator_handler(vla_sample_manifest_validate_operator), "lerobot_dataset_validate": operator_handler(lerobot_dataset_validate_operator), "lerobot_metadata_consistency_validate": operator_handler(lerobot_metadata_consistency_validate_operator), @@ -5030,6 +5037,8 @@ BUILTIN_HANDLERS: dict[str, BuiltinHandler] = { "webdataset_shard_summary": operator_handler(webdataset_shard_summary_operator), "zarr_trajectory_summary": operator_handler(zarr_trajectory_summary_operator), "camera_calibration_validate": operator_handler(camera_calibration_validate_operator), + "tf_transform_tree_validate": operator_handler(tf_transform_tree_validate_operator), + "mjcf_actuator_validate": operator_handler(mjcf_actuator_validate_operator), "robot_model_asset_validate": operator_handler(robot_model_asset_validate_operator), "pointcloud_summary": operator_handler(pointcloud_summary_operator), "sensor_timestamp_sync_validate": operator_handler(sensor_timestamp_sync_validate_operator), diff --git a/backend/operator-runner/test_main.py b/backend/operator-runner/test_main.py index aefbbbb8..6a76821c 100644 --- a/backend/operator-runner/test_main.py +++ b/backend/operator-runner/test_main.py @@ -259,8 +259,11 @@ class RuntimeFileContractTests(unittest.TestCase): self.assertEqual(MODULE.select_handler("BOS 增量扫描"), "bos_incremental_scan") self.assertEqual(MODULE.select_handler("人工审核"), "human_review") self.assertEqual(MODULE.select_handler("ALOHA HDF5 示教校验"), "aloha_hdf5_validate") + self.assertEqual(MODULE.select_handler("robomimic HDF5 示教校验"), "robomimic_hdf5_validate") self.assertEqual(MODULE.select_handler("VLA 样本清单校验"), "vla_sample_manifest_validate") self.assertEqual(MODULE.select_handler("URDF 关节限位校验"), "joint_limit_validate") + self.assertEqual(MODULE.select_handler("MJCF 执行器校验"), "mjcf_actuator_validate") + self.assertEqual(MODULE.select_handler("TF 坐标树校验"), "tf_transform_tree_validate") def test_operator_helpers_do_not_expose_legacy_builtin_handlers(self): legacy_keys = sorted(key for key in MODULE.OPERATOR_HELPERS if key.startswith("builtin_")) @@ -2905,6 +2908,55 @@ class EmbodiedDatasetOperatorTests(unittest.TestCase): self.assertEqual(payload["qposDimensions"], [14]) self.assertEqual(payload["files"][0]["cameraNames"], ["cam_high", "cam_wrist"]) + def test_robomimic_hdf5_validate_reads_real_demo_groups(self): + try: + import h5py # type: ignore + import numpy as np # type: ignore + except Exception as exc: + self.skipTest(f"h5py/numpy not available: {exc}") + with tempfile.TemporaryDirectory() as temp_dir: + path = pathlib.Path(temp_dir) / "robomimic.hdf5" + with h5py.File(path, "w") as handle: + data = handle.create_group("data") + data.attrs["total"] = 3 + data.attrs["env_args"] = json.dumps({"env_name": "Lift"}) + demo_1 = data.create_group("demo_1") + demo_1.attrs["num_samples"] = 2 + demo_1.create_dataset("actions", data=np.array([[0.1, 0.2], [0.3, 0.4]], dtype="float32")) + demo_1.create_dataset("rewards", data=np.array([0.0, 1.0], dtype="float32")) + demo_1.create_dataset("dones", data=np.array([False, True], dtype="bool")) + demo_1.create_dataset("states", data=np.array([[1.0], [2.0]], dtype="float32")) + obs = demo_1.create_group("obs") + obs.create_dataset("robot0_eef_pos", data=np.array([[0.0, 0.1, 0.2], [0.2, 0.3, 0.4]], dtype="float32")) + next_obs = demo_1.create_group("next_obs") + next_obs.create_dataset("robot0_eef_pos", data=np.array([[0.1, 0.2, 0.3], [0.3, 0.4, 0.5]], dtype="float32")) + demo_2 = data.create_group("demo_2") + demo_2.attrs["num_samples"] = 1 + demo_2.create_dataset("actions", data=np.array([[0.5, 0.6]], dtype="float32")) + demo_2.create_dataset("rewards", data=np.array([0.5], dtype="float32")) + demo_2.create_dataset("dones", data=np.array([True], dtype="bool")) + obs = demo_2.create_group("obs") + obs.create_dataset("robot0_eef_pos", data=np.array([[0.4, 0.5, 0.6]], dtype="float32")) + next_obs = demo_2.create_group("next_obs") + next_obs.create_dataset("robot0_eef_pos", data=np.array([[0.5, 0.6, 0.7]], dtype="float32")) + mask = handle.create_group("mask") + mask.create_dataset("train", data=np.array([b"demo_1"])) + mask.create_dataset("valid", data=np.array([b"demo_2"])) + node_data = {"label": "robomimic HDF5 示教校验", "hyperparams": [{"key": "SOURCE_PATH", "value": str(path)}]} + + artifacts = MODULE.BUILTIN_HANDLERS["robomimic_hdf5_validate"]( + "run-1", "robomimic", pathlib.Path(temp_dir) / "out", node_data, [] + ) + + payload = MODULE.load_artifact_payload(artifacts[0]) + self.assertEqual(payload["datasetType"], "robomimic-hdf5-validation") + self.assertTrue(payload["valid"]) + self.assertEqual(payload["demoCount"], 2) + self.assertEqual(payload["totalSamples"], 3) + self.assertEqual(payload["maskKeys"], ["train", "valid"]) + self.assertEqual(payload["actionDimensions"], [2]) + self.assertEqual(payload["files"][0]["observationKeyCounts"], {"robot0_eef_pos": 2}) + def test_lerobot_dataset_validate_reads_real_parquet_and_metadata(self): try: import pyarrow as pa # type: ignore @@ -3484,6 +3536,79 @@ class EmbodiedDatasetOperatorTests(unittest.TestCase): self.assertEqual(payload["meshReferenceCount"], 1) self.assertEqual(payload["missingMeshCount"], 0) + def test_mjcf_actuator_validate_reads_real_ctrlrange(self): + with tempfile.TemporaryDirectory() as temp_dir: + root = pathlib.Path(temp_dir) / "mjcf" + root.mkdir() + (root / "scene.xml").write_text( + "" + " " + " " + " " + " " + " " + " " + " " + " " + " " + " " + "", + encoding="utf-8", + ) + node_data = {"label": "MJCF 执行器校验", "hyperparams": [{"key": "SOURCE_PATH", "value": str(root)}]} + + artifacts = MODULE.BUILTIN_HANDLERS["mjcf_actuator_validate"]( + "run-1", "mjcf-actuator", root / "out", node_data, [] + ) + + payload = MODULE.load_artifact_payload(artifacts[0]) + self.assertEqual(payload["datasetType"], "mjcf-actuator-validation") + self.assertTrue(payload["valid"]) + self.assertEqual(payload["modelCount"], 1) + self.assertEqual(payload["actuatorCount"], 2) + self.assertEqual(payload["invalidActuatorCount"], 0) + self.assertEqual(payload["issueCount"], 0) + self.assertEqual(payload["models"][0]["targetCounts"]["joints"], 1) + self.assertEqual(payload["models"][0]["targetCounts"]["sites"], 1) + + def test_tf_transform_tree_validate_reads_real_transform_jsonl(self): + with tempfile.TemporaryDirectory() as temp_dir: + root = pathlib.Path(temp_dir) / "tf" + root.mkdir() + rows = [ + { + "header": {"frame_id": "world"}, + "child_frame_id": "base_link", + "transform": { + "translation": {"x": 0.0, "y": 0.0, "z": 0.0}, + "rotation": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0}, + }, + }, + { + "header": {"frame_id": "base_link"}, + "child_frame_id": "camera", + "transform": { + "translation": {"x": 0.1, "y": 0.2, "z": 0.3}, + "rotation": {"x": 0.0, "y": 0.0, "z": 0.70710678, "w": 0.70710678}, + }, + }, + ] + (root / "transforms.jsonl").write_text("\n".join(json.dumps(row) for row in rows), encoding="utf-8") + node_data = {"label": "TF 坐标树校验", "hyperparams": [{"key": "SOURCE_PATH", "value": str(root)}]} + + artifacts = MODULE.BUILTIN_HANDLERS["tf_transform_tree_validate"]( + "run-1", "tf-tree", root / "out", node_data, [] + ) + + payload = MODULE.load_artifact_payload(artifacts[0]) + self.assertEqual(payload["datasetType"], "tf-transform-tree-validation") + self.assertTrue(payload["valid"]) + self.assertEqual(payload["transformCount"], 2) + self.assertEqual(payload["frameCount"], 3) + self.assertEqual(payload["rootFrames"], ["world"]) + self.assertEqual(payload["cycleCount"], 0) + self.assertEqual(payload["issueCount"], 0) + def test_joint_limit_validate_reads_real_urdf_and_parquet_positions(self): try: import pyarrow as pa # type: ignore diff --git a/backend/operators/builtin/mjcf_actuator_validate/__init__.py b/backend/operators/builtin/mjcf_actuator_validate/__init__.py new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/backend/operators/builtin/mjcf_actuator_validate/__init__.py @@ -0,0 +1 @@ + diff --git a/backend/operators/builtin/mjcf_actuator_validate/operator.json b/backend/operators/builtin/mjcf_actuator_validate/operator.json new file mode 100644 index 00000000..2b5f7704 --- /dev/null +++ b/backend/operators/builtin/mjcf_actuator_validate/operator.json @@ -0,0 +1,16 @@ +{ + "id": "operator-builtin-mjcf-actuator-validate", + "name": "MJCF 执行器校验", + "category": "ROBOTICS", + "type": "builtin", + "runtimeHandler": "builtin_mjcf_actuator_validate", + "runtimeSource": "backend/operators/builtin/mjcf_actuator_validate/operator.py", + "migrationStatus": "migrated", + "acceptance": { + "requiresRealInputs": true, + "mockOnlyAccepted": false, + "simulationOnlyAccepted": false, + "hardcodedOutputAccepted": false, + "shallowOnlyAccepted": false + } +} diff --git a/backend/operators/builtin/mjcf_actuator_validate/operator.py b/backend/operators/builtin/mjcf_actuator_validate/operator.py new file mode 100644 index 00000000..1a5e2591 --- /dev/null +++ b/backend/operators/builtin/mjcf_actuator_validate/operator.py @@ -0,0 +1,226 @@ +from __future__ import annotations + +import math +import pathlib +import xml.etree.ElementTree as ET +from typing import Any, Callable + + +HelperMap = dict[str, Callable[..., Any]] +MJCF_SUFFIXES = {".xml", ".mjcf"} +ACTUATOR_TAGS = {"general", "motor", "position", "velocity", "intvelocity", "damper", "cylinder", "muscle", "adhesion"} +TRUTHY = {"true", "1", "yes", "auto"} + + +def _int_param(params: dict[str, str], key: str, default: int) -> int: + raw = str(params.get(key, str(default)) or str(default)).strip() + try: + value = int(raw) + except ValueError as exc: + raise RuntimeError(f"{key} must be an integer") from exc + if value <= 0: + raise RuntimeError(f"{key} must be > 0") + return value + + +def _candidate_model_files(source_path: pathlib.Path, max_models: int) -> list[pathlib.Path]: + if source_path.is_file(): + return [source_path] if source_path.suffix.lower() in MJCF_SUFFIXES else [] + preferred = [ + source_path / "scene.xml", + source_path / "model.xml", + source_path / "robot.xml", + source_path / "model.mjcf", + ] + files = [item for item in preferred if item.is_file()] + files.extend( + item + for item in sorted(source_path.rglob("*")) + if item.is_file() and item.suffix.lower() in MJCF_SUFFIXES and item not in files + ) + return files[:max_models] + + +def _strip_tag(tag: str) -> str: + return tag.rsplit("}", 1)[-1] if "}" in tag else tag + + +def _number_list(value: str) -> list[float]: + numbers: list[float] = [] + for item in value.replace(",", " ").split(): + try: + number = float(item) + except ValueError: + return [] + if not math.isfinite(number): + return [] + numbers.append(number) + return numbers + + +def _validate_range(raw: str, key: str, issues: list[dict[str, Any]], actuator_name: str) -> list[float]: + numbers = _number_list(raw) + if len(numbers) != 2: + issues.append({"code": "invalid_range", "actuator": actuator_name, "attribute": key, "value": raw}) + return [] + if numbers[0] >= numbers[1]: + issues.append({"code": "non_increasing_range", "actuator": actuator_name, "attribute": key, "value": numbers}) + return numbers + + +def _named_elements(root: ET.Element, tags: set[str]) -> set[str]: + names: set[str] = set() + for element in root.iter(): + if _strip_tag(element.tag) in tags: + name = str(element.attrib.get("name", "")).strip() + if name: + names.add(name) + return names + + +def _actuator_elements(root: ET.Element) -> list[ET.Element]: + parent_map = {child: parent for parent in root.iter() for child in parent} + actuators: list[ET.Element] = [] + for element in root.iter(): + if _strip_tag(element.tag) not in ACTUATOR_TAGS: + continue + parent = parent_map.get(element) + if parent is not None and _strip_tag(parent.tag) == "actuator": + actuators.append(element) + return actuators + + +def _validate_actuator(index: int, element: ET.Element, references: dict[str, set[str]], seen_names: set[str]) -> dict[str, Any]: + tag = _strip_tag(element.tag) + name = str(element.attrib.get("name", "") or f"{tag}-{index}").strip() + issues: list[dict[str, Any]] = [] + if element.attrib.get("name"): + if name in seen_names: + issues.append({"code": "duplicate_actuator_name", "actuator": name}) + seen_names.add(name) + target_refs: dict[str, str] = {} + for attr, ref_set in ( + ("joint", references["joints"]), + ("tendon", references["tendons"]), + ("site", references["sites"]), + ("body", references["bodies"]), + ("cranksite", references["sites"]), + ("slidersite", references["sites"]), + ("refsite", references["sites"]), + ): + raw = str(element.attrib.get(attr, "")).strip() + if not raw: + continue + target_refs[attr] = raw + if raw not in ref_set: + issues.append({"code": "missing_actuator_target", "actuator": name, "attribute": attr, "target": raw}) + if not target_refs and tag != "adhesion": + issues.append({"code": "missing_actuator_target", "actuator": name}) + + ranges: dict[str, list[float]] = {} + for attr in ("ctrlrange", "forcerange", "actrange"): + if attr in element.attrib: + ranges[attr] = _validate_range(str(element.attrib[attr]), attr, issues, name) + for limited_attr, range_attr in (("ctrllimited", "ctrlrange"), ("forcelimited", "forcerange"), ("actlimited", "actrange")): + raw = str(element.attrib.get(limited_attr, "")).strip().lower() + if raw in TRUTHY and range_attr not in ranges: + issues.append({"code": "limited_without_range", "actuator": name, "limited": limited_attr, "range": range_attr}) + if "gear" in element.attrib and not _number_list(str(element.attrib["gear"])): + issues.append({"code": "invalid_gear_vector", "actuator": name, "gear": str(element.attrib["gear"])}) + + return { + "name": name, + "type": tag, + "valid": not issues, + "issueCount": len(issues), + "issues": issues, + "targets": target_refs, + "ranges": ranges, + "gear": _number_list(str(element.attrib.get("gear", ""))) if element.attrib.get("gear") else [], + } + + +def _summarize_model(path: pathlib.Path) -> dict[str, Any]: + try: + tree = ET.parse(path) + except ET.ParseError as exc: + raise RuntimeError(f"{path} is not valid MJCF XML: {exc}") from exc + root = tree.getroot() + root_tag = _strip_tag(root.tag) + model_issues: list[dict[str, Any]] = [] + if root_tag != "mujoco": + model_issues.append({"code": "not_mjcf_root", "rootTag": root_tag}) + references = { + "joints": _named_elements(root, {"joint"}), + "tendons": _named_elements(root, {"fixed", "spatial"}), + "sites": _named_elements(root, {"site"}), + "bodies": _named_elements(root, {"body"}), + } + seen_names: set[str] = set() + actuators = [_validate_actuator(index, element, references, seen_names) for index, element in enumerate(_actuator_elements(root))] + issues = list(model_issues) + issues.extend({"actuator": actuator["name"], **issue} for actuator in actuators for issue in actuator["issues"]) + if root_tag == "mujoco" and not actuators: + issues.append({"code": "missing_actuator_elements"}) + return { + "path": str(path), + "valid": not issues, + "issueCount": len(issues), + "issues": issues, + "rootTag": root_tag, + "jointCount": len(references["joints"]), + "tendonCount": len(references["tendons"]), + "siteCount": len(references["sites"]), + "bodyCount": len(references["bodies"]), + "actuatorCount": len(actuators), + "invalidActuatorCount": sum(1 for item in actuators if not item["valid"]), + "targetCounts": {key: len(value) for key, value in references.items()}, + "actuators": actuators, + } + + +def run( + run_id: str, + node_id: str, + output_dir: Any, + node_data: dict[str, Any], + inputs: list[dict[str, Any]], + helpers: HelperMap, +) -> list[dict[str, Any]]: + params = helpers["hyperparams"](node_data) + source_path = helpers["resolve_source_path"](params, inputs) + if source_path is None: + raise RuntimeError("MJCF 执行器校验需要 SOURCE_PATH 指向真实 MJCF XML 文件或目录") + max_models = _int_param(params, "MAX_MODELS", 20) + models = _candidate_model_files(source_path, max_models) + if not models: + raise RuntimeError(f"{source_path} does not contain MJCF XML files") + summaries = [_summarize_model(path) for path in models] + issues = [ + {"model": item["path"], **issue} + for item in summaries + for issue in item.get("issues", []) + ] + payload = { + "datasetType": "mjcf-actuator-validation", + "sourcePath": str(source_path), + "valid": not issues, + "issueCount": len(issues), + "issues": issues[:300], + "modelCount": len(summaries), + "actuatorCount": sum(int(item.get("actuatorCount", 0)) for item in summaries), + "invalidActuatorCount": sum(int(item.get("invalidActuatorCount", 0)) for item in summaries), + "jointCount": sum(int(item.get("jointCount", 0)) for item in summaries), + "siteCount": sum(int(item.get("siteCount", 0)) for item in summaries), + "models": summaries, + } + return [ + helpers["write_json_artifact"]( + run_id, + node_id, + output_dir, + "mjcf-actuator-validation.json", + payload, + output=helpers["output_binding"](node_data), + ) + ] diff --git a/backend/operators/builtin/mjcf_actuator_validate/repository.json b/backend/operators/builtin/mjcf_actuator_validate/repository.json new file mode 100644 index 00000000..40a4645a --- /dev/null +++ b/backend/operators/builtin/mjcf_actuator_validate/repository.json @@ -0,0 +1,31 @@ +{ + "acceptance": { + "hardcodedOutputAccepted": false, + "mockOnlyAccepted": false, + "pocFullAcceptanceScript": "scripts/poc-operator-full-acceptance.sh", + "requiresPersistentWorkspaceEvidence": true, + "requiresRealInputs": true, + "shallowOnlyAccepted": false, + "simulationOnlyAccepted": false + }, + "category": "ROBOTICS", + "containerEntrypoint": "backend/operator-runner/main.py", + "entrypoint": "operator.py", + "metadata": "operator.json", + "name": "MJCF 执行器校验", + "operatorId": "operator-builtin-mjcf-actuator-validate", + "operatorSlug": "mjcf_actuator_validate", + "preferredSlug": "mjcf_actuator_validate", + "pythonImport": "backend.operators.builtin.mjcf_actuator_validate.operator:run", + "repositoryId": "builtin/mjcf_actuator_validate", + "runtimeDependencies": [ + "mjcf-files", + "xml-parser" + ], + "runtimeHandler": "builtin_mjcf_actuator_validate", + "runtimeSource": "backend/operators/builtin/mjcf_actuator_validate/operator.py", + "schemaVersion": "droboticflow.operator.repository/v1", + "sourceRoot": "backend/operators/builtin/mjcf_actuator_validate", + "strictPocAcceptanceExternals": [], + "type": "builtin" +} diff --git a/backend/operators/builtin/robomimic_hdf5_validate/__init__.py b/backend/operators/builtin/robomimic_hdf5_validate/__init__.py new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/backend/operators/builtin/robomimic_hdf5_validate/__init__.py @@ -0,0 +1 @@ + diff --git a/backend/operators/builtin/robomimic_hdf5_validate/operator.json b/backend/operators/builtin/robomimic_hdf5_validate/operator.json new file mode 100644 index 00000000..9e186c3f --- /dev/null +++ b/backend/operators/builtin/robomimic_hdf5_validate/operator.json @@ -0,0 +1,16 @@ +{ + "id": "operator-builtin-robomimic-hdf5-validate", + "name": "robomimic HDF5 示教校验", + "category": "ROBOTICS", + "type": "builtin", + "runtimeHandler": "builtin_robomimic_hdf5_validate", + "runtimeSource": "backend/operators/builtin/robomimic_hdf5_validate/operator.py", + "migrationStatus": "migrated", + "acceptance": { + "requiresRealInputs": true, + "mockOnlyAccepted": false, + "simulationOnlyAccepted": false, + "hardcodedOutputAccepted": false, + "shallowOnlyAccepted": false + } +} diff --git a/backend/operators/builtin/robomimic_hdf5_validate/operator.py b/backend/operators/builtin/robomimic_hdf5_validate/operator.py new file mode 100644 index 00000000..8e3998f0 --- /dev/null +++ b/backend/operators/builtin/robomimic_hdf5_validate/operator.py @@ -0,0 +1,372 @@ +from __future__ import annotations + +import json +import math +import pathlib +from typing import Any, Callable + + +HelperMap = dict[str, Callable[..., Any]] + + +def _require_h5py(): + try: + import h5py # type: ignore + except Exception as exc: # pragma: no cover - runtime dependency check + raise RuntimeError("robomimic HDF5 校验需要 h5py 运行时依赖") from exc + return h5py + + +def _int_param(params: dict[str, str], key: str, default: int) -> int: + raw = str(params.get(key, str(default)) or str(default)).strip() + try: + value = int(raw) + except ValueError as exc: + raise RuntimeError(f"{key} must be an integer") from exc + if value <= 0: + raise RuntimeError(f"{key} must be > 0") + return value + + +def _float_param(params: dict[str, str], key: str, default: float) -> float: + raw = str(params.get(key, str(default)) or str(default)).strip() + try: + value = float(raw) + except ValueError as exc: + raise RuntimeError(f"{key} must be a number") from exc + if not math.isfinite(value) or value <= 0: + raise RuntimeError(f"{key} must be a positive finite number") + return value + + +def _bool_param(params: dict[str, str], key: str, default: bool) -> bool: + raw = str(params.get(key, str(default)) or str(default)).strip().lower() + if raw in {"1", "true", "yes", "y", "on"}: + return True + if raw in {"0", "false", "no", "n", "off"}: + return False + return default + + +def _find_hdf5_files(source_path: pathlib.Path, max_files: int) -> list[pathlib.Path]: + if source_path.is_file(): + return [source_path] if source_path.suffix.lower() in {".hdf5", ".h5"} else [] + preferred = [source_path / "low_dim.hdf5", source_path / "image.hdf5", source_path / "demo.hdf5"] + files = [item for item in preferred if item.is_file()] + files.extend( + item + for item in sorted(source_path.rglob("*")) + if item.is_file() and item.suffix.lower() in {".hdf5", ".h5"} and item not in files + ) + return files[:max_files] + + +def _jsonable(value: Any) -> Any: + if isinstance(value, bytes): + return value.decode("utf-8", errors="replace") + if isinstance(value, (str, int, float, bool)) or value is None: + return value + if hasattr(value, "item"): + try: + return _jsonable(value.item()) + except Exception: + pass + if isinstance(value, dict): + return {str(key): _jsonable(item) for key, item in value.items()} + if isinstance(value, (list, tuple)): + return [_jsonable(item) for item in value] + return str(value) + + +def _attrs_payload(node: Any) -> dict[str, Any]: + payload: dict[str, Any] = {} + for key, value in node.attrs.items(): + parsed = _jsonable(value) + if isinstance(parsed, str) and parsed.strip().startswith(("{", "[")): + try: + parsed = json.loads(parsed) + except json.JSONDecodeError: + pass + payload[str(key)] = parsed + return payload + + +def _shape(node: Any | None) -> list[int]: + if node is None or not hasattr(node, "shape"): + return [] + return [int(item) for item in node.shape] + + +def _first_dim(node: Any | None) -> int: + shape = _shape(node) + return int(shape[0]) if shape else 0 + + +def _demo_group(root: Any) -> Any | None: + if "data" in root and hasattr(root["data"], "keys"): + return root["data"] + return root if hasattr(root, "keys") else None + + +def _demo_keys(data_group: Any) -> list[str]: + keys: list[str] = [] + for key in sorted(data_group.keys()): + item = data_group[key] + if hasattr(item, "keys") and (key.startswith("demo") or "actions" in item): + keys.append(str(key)) + return keys + + +def _iter_dataset_paths(group: Any, prefix: str = "") -> list[tuple[str, Any]]: + datasets: list[tuple[str, Any]] = [] + if not hasattr(group, "keys"): + return datasets + for key in sorted(group.keys()): + item = group[key] + path = f"{prefix}/{key}" if prefix else str(key) + if hasattr(item, "shape") and hasattr(item, "dtype"): + datasets.append((path, item)) + else: + datasets.extend(_iter_dataset_paths(item, path)) + return datasets + + +def _dataset_values(dataset: Any) -> list[str]: + raw = dataset[()] + if hasattr(raw, "tolist"): + raw = raw.tolist() + if not isinstance(raw, list): + raw = [raw] + return [str(_jsonable(item)) for item in raw] + + +def _action_range_issue(actions: Any | None, max_abs_action: float) -> dict[str, Any] | None: + if actions is None or not hasattr(actions, "__getitem__"): + return None + try: + values = actions[()] + if hasattr(values, "tolist"): + values = values.tolist() + except Exception: + return {"code": "unreadable_actions"} + stack = list(values) if isinstance(values, list) else [values] + max_value = 0.0 + while stack: + item = stack.pop() + if isinstance(item, list): + stack.extend(item) + elif isinstance(item, (int, float)): + max_value = max(max_value, abs(float(item))) + if max_value > max_abs_action: + return {"code": "action_value_out_of_expected_range", "maxAbsAction": max_value, "limit": max_abs_action} + return None + + +def _validate_frame_dataset( + issues: list[dict[str, Any]], + dataset: Any | None, + dataset_path: str, + expected_frames: int, + required: bool, +) -> list[int]: + shape = _shape(dataset) + if not shape: + if required: + issues.append({"code": "missing_or_scalar_dataset", "dataset": dataset_path}) + return [] + if expected_frames > 0 and int(shape[0]) != expected_frames: + issues.append( + { + "code": "frame_count_mismatch", + "dataset": dataset_path, + "expected": expected_frames, + "actual": int(shape[0]), + } + ) + return shape + + +def _summarize_demo( + demo_id: str, + group: Any, + *, + require_rewards: bool, + require_dones: bool, + require_next_obs: bool, + check_action_range: bool, + max_abs_action: float, +) -> dict[str, Any]: + actions = group.get("actions") if hasattr(group, "get") else None + rewards = group.get("rewards") if hasattr(group, "get") else None + dones = group.get("dones") if hasattr(group, "get") else None + states = group.get("states") if hasattr(group, "get") else None + obs = group.get("obs") if hasattr(group, "get") else None + next_obs = group.get("next_obs") if hasattr(group, "get") else None + actions_shape = _shape(actions) + fallback_frames = _first_dim(actions) or _first_dim(states) + frame_count = int(group.attrs.get("num_samples", 0) or fallback_frames) + issues: list[dict[str, Any]] = [] + if frame_count <= 0: + issues.append({"code": "missing_num_samples_or_frame_dimension", "demo": demo_id}) + + _validate_frame_dataset(issues, actions, "actions", frame_count, required=True) + _validate_frame_dataset(issues, rewards, "rewards", frame_count, required=require_rewards) + _validate_frame_dataset(issues, dones, "dones", frame_count, required=require_dones) + _validate_frame_dataset(issues, states, "states", frame_count, required=False) + + obs_datasets = _iter_dataset_paths(obs) + next_obs_datasets = _iter_dataset_paths(next_obs) + if not obs_datasets: + issues.append({"code": "missing_observation_group", "group": "obs"}) + for path, dataset in obs_datasets: + _validate_frame_dataset(issues, dataset, f"obs/{path}", frame_count, required=True) + if require_next_obs and not next_obs_datasets: + issues.append({"code": "missing_next_observation_group", "group": "next_obs"}) + for path, dataset in next_obs_datasets: + _validate_frame_dataset(issues, dataset, f"next_obs/{path}", frame_count, required=True) + + if check_action_range: + issue = _action_range_issue(actions, max_abs_action) + if issue: + issues.append(issue) + + return { + "id": demo_id, + "valid": not issues, + "issueCount": len(issues), + "issues": issues, + "frameCount": frame_count, + "attrs": _attrs_payload(group), + "actionsShape": actions_shape, + "statesShape": _shape(states), + "rewardsShape": _shape(rewards), + "donesShape": _shape(dones), + "actionDimension": int(actions_shape[1]) if len(actions_shape) > 1 else 0, + "observationKeys": [path for path, _ in obs_datasets], + "nextObservationKeys": [path for path, _ in next_obs_datasets], + } + + +def _summarize_file(path: pathlib.Path, params: dict[str, str]) -> dict[str, Any]: + h5py = _require_h5py() + max_demos = _int_param(params, "MAX_DEMOS", 200) + require_rewards = _bool_param(params, "REQUIRE_REWARDS", True) + require_dones = _bool_param(params, "REQUIRE_DONES", True) + require_next_obs = _bool_param(params, "REQUIRE_NEXT_OBS", True) + check_action_range = _bool_param(params, "CHECK_ACTION_RANGE", False) + max_abs_action = _float_param(params, "MAX_ABS_ACTION", 1.0) + + with h5py.File(path, "r") as handle: + data_group = _demo_group(handle) + if data_group is None: + raise RuntimeError(f"{path} does not contain an HDF5 group tree") + demo_keys = _demo_keys(data_group) + demos = [ + _summarize_demo( + demo_id, + data_group[demo_id], + require_rewards=require_rewards, + require_dones=require_dones, + require_next_obs=require_next_obs, + check_action_range=check_action_range, + max_abs_action=max_abs_action, + ) + for demo_id in demo_keys[:max_demos] + ] + issues: list[dict[str, Any]] = [] + if not demo_keys: + issues.append({"code": "missing_demo_groups", "path": "/data/demo_*"}) + for demo in demos: + issues.extend({"demo": demo["id"], **issue} for issue in demo["issues"]) + total_samples = sum(int(item["frameCount"]) for item in demos) + declared_total = int(data_group.attrs.get("total", 0) or 0) + if declared_total and declared_total != total_samples: + issues.append( + { + "code": "declared_total_mismatch", + "declaredTotal": declared_total, + "actualTotal": total_samples, + } + ) + + mask_keys: list[str] = [] + mask_entries: dict[str, list[str]] = {} + if "mask" in handle and hasattr(handle["mask"], "keys"): + for key in sorted(handle["mask"].keys()): + dataset = handle["mask"][key] + if hasattr(dataset, "shape"): + refs = _dataset_values(dataset) + mask_keys.append(str(key)) + mask_entries[str(key)] = refs + missing = sorted(ref for ref in refs if ref not in demo_keys) + if missing: + issues.append({"code": "mask_references_missing_demos", "mask": str(key), "missing": missing}) + + return { + "path": str(path), + "fileSizeBytes": path.stat().st_size, + "rootAttrs": _attrs_payload(handle), + "dataAttrs": _attrs_payload(data_group), + "valid": not issues, + "issueCount": len(issues), + "issues": issues, + "demoCount": len(demo_keys), + "returnedDemoCount": len(demos), + "totalSamples": total_samples, + "declaredTotal": declared_total, + "maskKeys": mask_keys, + "maskEntries": mask_entries, + "actionDimensions": sorted({int(item["actionDimension"]) for item in demos if item.get("actionDimension")}), + "observationKeyCounts": { + key: sum(1 for demo in demos if key in demo.get("observationKeys", [])) + for key in sorted({key for demo in demos for key in demo.get("observationKeys", [])}) + }, + "demos": demos, + } + + +def run( + run_id: str, + node_id: str, + output_dir: Any, + node_data: dict[str, Any], + inputs: list[dict[str, Any]], + helpers: HelperMap, +) -> list[dict[str, Any]]: + params = helpers["hyperparams"](node_data) + source_path = helpers["resolve_source_path"](params, inputs) + if source_path is None: + raise RuntimeError("robomimic HDF5 校验需要 SOURCE_PATH 指向真实 .hdf5/.h5 文件或目录") + max_files = _int_param(params, "MAX_FILES", 20) + files = _find_hdf5_files(source_path, max_files) + if not files: + raise RuntimeError(f"{source_path} does not contain robomimic .hdf5/.h5 files") + file_summaries = [_summarize_file(path, params) for path in files] + issues = [ + {"file": item["path"], **issue} + for item in file_summaries + for issue in item.get("issues", []) + ] + payload = { + "datasetType": "robomimic-hdf5-validation", + "sourcePath": str(source_path), + "valid": not issues, + "issueCount": len(issues), + "issues": issues[:300], + "fileCount": len(file_summaries), + "demoCount": sum(int(item.get("demoCount", 0)) for item in file_summaries), + "totalSamples": sum(int(item.get("totalSamples", 0)) for item in file_summaries), + "maskKeys": sorted({key for item in file_summaries for key in item.get("maskKeys", [])}), + "actionDimensions": sorted({dim for item in file_summaries for dim in item.get("actionDimensions", [])}), + "files": file_summaries, + } + return [ + helpers["write_json_artifact"]( + run_id, + node_id, + output_dir, + "robomimic-hdf5-validation.json", + payload, + output=helpers["output_binding"](node_data), + ) + ] diff --git a/backend/operators/builtin/robomimic_hdf5_validate/repository.json b/backend/operators/builtin/robomimic_hdf5_validate/repository.json new file mode 100644 index 00000000..5ad86dea --- /dev/null +++ b/backend/operators/builtin/robomimic_hdf5_validate/repository.json @@ -0,0 +1,32 @@ +{ + "acceptance": { + "hardcodedOutputAccepted": false, + "mockOnlyAccepted": false, + "pocFullAcceptanceScript": "scripts/poc-operator-full-acceptance.sh", + "requiresPersistentWorkspaceEvidence": true, + "requiresRealInputs": true, + "shallowOnlyAccepted": false, + "simulationOnlyAccepted": false + }, + "category": "ROBOTICS", + "containerEntrypoint": "backend/operator-runner/main.py", + "entrypoint": "operator.py", + "metadata": "operator.json", + "name": "robomimic HDF5 示教校验", + "operatorId": "operator-builtin-robomimic-hdf5-validate", + "operatorSlug": "robomimic_hdf5_validate", + "preferredSlug": "robomimic_hdf5_validate", + "pythonImport": "backend.operators.builtin.robomimic_hdf5_validate.operator:run", + "repositoryId": "builtin/robomimic_hdf5_validate", + "runtimeDependencies": [ + "robomimic-hdf5-files", + "h5py", + "numpy" + ], + "runtimeHandler": "builtin_robomimic_hdf5_validate", + "runtimeSource": "backend/operators/builtin/robomimic_hdf5_validate/operator.py", + "schemaVersion": "droboticflow.operator.repository/v1", + "sourceRoot": "backend/operators/builtin/robomimic_hdf5_validate", + "strictPocAcceptanceExternals": [], + "type": "builtin" +} diff --git a/backend/operators/builtin/tf_transform_tree_validate/__init__.py b/backend/operators/builtin/tf_transform_tree_validate/__init__.py new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/backend/operators/builtin/tf_transform_tree_validate/__init__.py @@ -0,0 +1 @@ + diff --git a/backend/operators/builtin/tf_transform_tree_validate/operator.json b/backend/operators/builtin/tf_transform_tree_validate/operator.json new file mode 100644 index 00000000..4c44a749 --- /dev/null +++ b/backend/operators/builtin/tf_transform_tree_validate/operator.json @@ -0,0 +1,16 @@ +{ + "id": "operator-builtin-tf-transform-tree-validate", + "name": "TF 坐标树校验", + "category": "ROBOTICS", + "type": "builtin", + "runtimeHandler": "builtin_tf_transform_tree_validate", + "runtimeSource": "backend/operators/builtin/tf_transform_tree_validate/operator.py", + "migrationStatus": "migrated", + "acceptance": { + "requiresRealInputs": true, + "mockOnlyAccepted": false, + "simulationOnlyAccepted": false, + "hardcodedOutputAccepted": false, + "shallowOnlyAccepted": false + } +} diff --git a/backend/operators/builtin/tf_transform_tree_validate/operator.py b/backend/operators/builtin/tf_transform_tree_validate/operator.py new file mode 100644 index 00000000..a87e4e25 --- /dev/null +++ b/backend/operators/builtin/tf_transform_tree_validate/operator.py @@ -0,0 +1,294 @@ +from __future__ import annotations + +import csv +import json +import math +import pathlib +from typing import Any, Callable + + +HelperMap = dict[str, Callable[..., Any]] +TRANSFORM_SUFFIXES = {".json", ".jsonl", ".csv", ".yaml", ".yml"} + + +def _int_param(params: dict[str, str], key: str, default: int) -> int: + raw = str(params.get(key, str(default)) or str(default)).strip() + try: + value = int(raw) + except ValueError as exc: + raise RuntimeError(f"{key} must be an integer") from exc + if value <= 0: + raise RuntimeError(f"{key} must be > 0") + return value + + +def _float_param(params: dict[str, str], key: str, default: float) -> float: + raw = str(params.get(key, str(default)) or str(default)).strip() + try: + value = float(raw) + except ValueError as exc: + raise RuntimeError(f"{key} must be a number") from exc + if not math.isfinite(value) or value < 0: + raise RuntimeError(f"{key} must be a non-negative finite number") + return value + + +def _find_transform_files(source_path: pathlib.Path, max_files: int) -> list[pathlib.Path]: + if source_path.is_file(): + return [source_path] if source_path.suffix.lower() in TRANSFORM_SUFFIXES else [] + preferred = [ + source_path / "transforms.json", + source_path / "tf.json", + source_path / "tf_static.json", + source_path / "transforms.jsonl", + source_path / "transforms.csv", + source_path / "transforms.yaml", + ] + files = [item for item in preferred if item.is_file()] + files.extend( + item + for item in sorted(source_path.rglob("*")) + if item.is_file() and item.suffix.lower() in TRANSFORM_SUFFIXES and item not in files + ) + return files[:max_files] + + +def _load_yaml(path: pathlib.Path) -> Any: + try: + import yaml # type: ignore + except Exception as exc: # pragma: no cover - runtime dependency check + raise RuntimeError("TF 坐标树校验需要 PyYAML 以读取 YAML transform 文件") from exc + return yaml.safe_load(path.read_text(encoding="utf-8")) + + +def _load_records(path: pathlib.Path) -> list[dict[str, Any]]: + suffix = path.suffix.lower() + if suffix == ".jsonl": + rows = [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()] + elif suffix == ".json": + payload = json.loads(path.read_text(encoding="utf-8")) + rows = payload.get("transforms", payload.get("items", payload)) if isinstance(payload, dict) else payload + elif suffix == ".csv": + with path.open("r", encoding="utf-8", newline="") as handle: + rows = list(csv.DictReader(handle)) + else: + payload = _load_yaml(path) + rows = payload.get("transforms", payload.get("items", payload)) if isinstance(payload, dict) else payload + if isinstance(rows, dict): + rows = [rows] + if not isinstance(rows, list): + raise RuntimeError(f"{path} must contain a transform object or list") + return [row for row in rows if isinstance(row, dict)] + + +def _nested(payload: dict[str, Any], dotted: str) -> Any: + current: Any = payload + for part in dotted.split("."): + if not isinstance(current, dict) or part not in current: + return None + current = current[part] + return current + + +def _first_string(payload: dict[str, Any], keys: tuple[str, ...]) -> str: + for key in keys: + value = _nested(payload, key) if "." in key else payload.get(key) + if value is None: + continue + text = str(value).strip() + if text: + return text.lstrip("/") + return "" + + +def _float_value(value: Any) -> float | None: + if isinstance(value, (int, float)): + number = float(value) + elif isinstance(value, str) and value.strip(): + try: + number = float(value) + except ValueError: + return None + else: + return None + return number if math.isfinite(number) else None + + +def _vector(payload: dict[str, Any], keys: tuple[str, str, str], nested_prefix: str = "") -> list[float] | None: + values: list[float] = [] + for key in keys: + value = _nested(payload, f"{nested_prefix}.{key}") if nested_prefix else payload.get(key) + number = _float_value(value) + if number is None: + return None + values.append(number) + return values + + +def _quaternion(payload: dict[str, Any]) -> list[float] | None: + candidates = [ + ("transform.rotation", ("x", "y", "z", "w")), + ("rotation", ("x", "y", "z", "w")), + ("", ("qx", "qy", "qz", "qw")), + ] + for prefix, keys in candidates: + values: list[float] = [] + for key in keys: + value = _nested(payload, f"{prefix}.{key}") if prefix else payload.get(key) + number = _float_value(value) + if number is None: + break + values.append(number) + if len(values) == 4: + return values + return None + + +def _translation(payload: dict[str, Any]) -> list[float] | None: + for prefix in ("transform.translation", "translation", ""): + result = _vector(payload, ("x", "y", "z"), nested_prefix=prefix) + if result is not None: + return result + return None + + +def _normalize_record(file_path: pathlib.Path, index: int, payload: dict[str, Any], tolerance: float) -> dict[str, Any]: + parent = _first_string(payload, ("header.frame_id", "parent_frame", "parent", "frame_id", "source_frame")) + child = _first_string(payload, ("child_frame_id", "child_frame", "child", "target_frame")) + translation = _translation(payload) + rotation = _quaternion(payload) + issues: list[dict[str, Any]] = [] + if not parent: + issues.append({"code": "missing_parent_frame"}) + if not child: + issues.append({"code": "missing_child_frame"}) + if parent and child and parent == child: + issues.append({"code": "self_transform", "frame": parent}) + if translation is None: + issues.append({"code": "missing_or_invalid_translation"}) + if rotation is None: + issues.append({"code": "missing_or_invalid_quaternion"}) + norm = 0.0 + else: + norm = math.sqrt(sum(value * value for value in rotation)) + if abs(norm - 1.0) > tolerance: + issues.append({"code": "quaternion_norm_out_of_tolerance", "norm": norm, "tolerance": tolerance}) + return { + "file": str(file_path), + "index": index, + "valid": not issues, + "issueCount": len(issues), + "issues": issues, + "parentFrame": parent, + "childFrame": child, + "translation": translation or [], + "rotation": rotation or [], + "quaternionNorm": norm, + } + + +def _cycle_edges(edges: dict[str, str]) -> list[list[str]]: + cycles: list[list[str]] = [] + visited: set[str] = set() + for start in sorted(edges): + path: list[str] = [] + seen_at: dict[str, int] = {} + node = start + while node in edges: + if node in seen_at: + cycle = path[seen_at[node] :] + if cycle and cycle not in cycles: + cycles.append(cycle) + break + if node in visited: + break + seen_at[node] = len(path) + path.append(node) + node = edges[node] + visited.update(path) + return cycles + + +def run( + run_id: str, + node_id: str, + output_dir: Any, + node_data: dict[str, Any], + inputs: list[dict[str, Any]], + helpers: HelperMap, +) -> list[dict[str, Any]]: + params = helpers["hyperparams"](node_data) + source_path = helpers["resolve_source_path"](params, inputs) + if source_path is None: + raise RuntimeError("TF 坐标树校验需要 SOURCE_PATH 指向真实 JSON/JSONL/CSV/YAML transform 文件") + max_files = _int_param(params, "MAX_FILES", 50) + max_transforms = _int_param(params, "MAX_TRANSFORMS", 10000) + tolerance = _float_param(params, "QUATERNION_NORM_TOLERANCE", 0.01) + files = _find_transform_files(source_path, max_files) + if not files: + raise RuntimeError(f"{source_path} does not contain transform files") + + transforms: list[dict[str, Any]] = [] + for file_path in files: + for row in _load_records(file_path): + if len(transforms) >= max_transforms: + break + transforms.append(_normalize_record(file_path, len(transforms), row, tolerance)) + + issues: list[dict[str, Any]] = [] + issues.extend({"transformIndex": item["index"], **issue} for item in transforms for issue in item["issues"]) + child_to_parent: dict[str, str] = {} + edge_counts: dict[tuple[str, str], int] = {} + frames: set[str] = set() + for item in transforms: + parent = str(item.get("parentFrame", "")) + child = str(item.get("childFrame", "")) + if not parent or not child or parent == child: + continue + frames.update([parent, child]) + edge = (parent, child) + edge_counts[edge] = edge_counts.get(edge, 0) + 1 + if child in child_to_parent and child_to_parent[child] != parent: + issues.append( + { + "code": "child_frame_has_multiple_parents", + "childFrame": child, + "parents": sorted({child_to_parent[child], parent}), + } + ) + child_to_parent[child] = parent + for (parent, child), count in sorted(edge_counts.items()): + if count > 1: + issues.append({"code": "duplicate_transform_edge", "parentFrame": parent, "childFrame": child, "count": count}) + cycles = _cycle_edges({child: parent for child, parent in child_to_parent.items()}) + for cycle in cycles: + issues.append({"code": "cycle_detected", "frames": cycle}) + child_frames = set(child_to_parent) + root_frames = sorted(frames - child_frames) + leaf_frames = sorted(frames - set(child_to_parent.values())) + payload = { + "datasetType": "tf-transform-tree-validation", + "sourcePath": str(source_path), + "valid": not issues, + "issueCount": len(issues), + "issues": issues[:300], + "fileCount": len(files), + "transformCount": len(transforms), + "validTransformCount": sum(1 for item in transforms if item["valid"]), + "frameCount": len(frames), + "rootFrames": root_frames, + "rootFrameCount": len(root_frames), + "leafFrames": leaf_frames, + "cycleCount": len(cycles), + "transforms": transforms[:200], + } + return [ + helpers["write_json_artifact"]( + run_id, + node_id, + output_dir, + "tf-transform-tree-validation.json", + payload, + output=helpers["output_binding"](node_data), + ) + ] diff --git a/backend/operators/builtin/tf_transform_tree_validate/repository.json b/backend/operators/builtin/tf_transform_tree_validate/repository.json new file mode 100644 index 00000000..68b311a3 --- /dev/null +++ b/backend/operators/builtin/tf_transform_tree_validate/repository.json @@ -0,0 +1,31 @@ +{ + "acceptance": { + "hardcodedOutputAccepted": false, + "mockOnlyAccepted": false, + "pocFullAcceptanceScript": "scripts/poc-operator-full-acceptance.sh", + "requiresPersistentWorkspaceEvidence": true, + "requiresRealInputs": true, + "shallowOnlyAccepted": false, + "simulationOnlyAccepted": false + }, + "category": "ROBOTICS", + "containerEntrypoint": "backend/operator-runner/main.py", + "entrypoint": "operator.py", + "metadata": "operator.json", + "name": "TF 坐标树校验", + "operatorId": "operator-builtin-tf-transform-tree-validate", + "operatorSlug": "tf_transform_tree_validate", + "preferredSlug": "tf_transform_tree_validate", + "pythonImport": "backend.operators.builtin.tf_transform_tree_validate.operator:run", + "repositoryId": "builtin/tf_transform_tree_validate", + "runtimeDependencies": [ + "json-jsonl-csv-yaml-files", + "optional-pyyaml" + ], + "runtimeHandler": "builtin_tf_transform_tree_validate", + "runtimeSource": "backend/operators/builtin/tf_transform_tree_validate/operator.py", + "schemaVersion": "droboticflow.operator.repository/v1", + "sourceRoot": "backend/operators/builtin/tf_transform_tree_validate", + "strictPocAcceptanceExternals": [], + "type": "builtin" +} diff --git a/docs/operators/MJCF-执行器校验.md b/docs/operators/MJCF-执行器校验.md new file mode 100644 index 00000000..ba9fa117 --- /dev/null +++ b/docs/operators/MJCF-执行器校验.md @@ -0,0 +1,109 @@ +# MJCF 执行器校验 + +- 算子 ID:`operator-builtin-mjcf-actuator-validate` +- 类别:`ROBOTICS` +- 类型:`builtin` + +## 作用 + +读取真实 MuJoCo/MJCF XML,校验 actuator 下 motor/position/velocity/general 等执行器目标引用、ctrlrange/forcerange/actrange 和 gear 数值。 + +## 定位与职责边界 + +- 该算子属于 `ROBOTICS` 类,当前登记类型是 `builtin`。 +- 平台会在 `/api/operators` 中自动提供该算子元数据,运行时由 operator-runner 委派到独立算子入口。 + +## 平台语义 + +面向 MuJoCo、robosuite、ManiSkill 和 GitHub 常见 MJCF 仿真资产,真实解析 下执行器,验证 joint/tendon/site/body 引用存在,ctrlrange/forcerange/actrange 为递增有限数值,并识别重复 actuator 名称。 + +## 运行时契约 + +- Worker 会先把上游 artifact 汇总到 `INPUT_ARTIFACTS_PATH`,再把节点配置通过 `NODE_DATA_JSON` 注入运行容器。 +- 节点执行结果会写入 `OUTPUT_DIR`、`RESULT_OUTPUT_PATH` 和 `STAGE_MANIFEST_PATH` 对应的文件,再由 worker 汇总进运行记录。 +- 大文件和大 JSON 不应依赖 API 内联传输,应该通过 `artifact.path`、`dataRef.payloadPath`、共享 PVC 或对象存储引用传递。 +- 当前独立实现入口是 `backend/operators/builtin/mjcf_actuator_validate/operator.py` 中的 `run(...)`,平台 runtimeHandler 为 `builtin_mjcf_actuator_validate`。 + +## 设计边界 + +- 该算子应该只承担单一职责,不应在一个节点里同时混合索引、筛选、上传、审核等多个阶段性行为。 +- 如果一个节点要消费多个语义不同的结果,优先通过多节点拆分,而不是把所有逻辑塞进一个超大脚本。 + +## 数据流示意 + +```mermaid +flowchart LR + A[上游输入或运行时注入] --> B[MJCF 执行器校验] + B --> C[artifact / stage manifest / 外部副作用] +``` + +## 输入端口详解 + +- `in-1` / **input** / `json` / `bus`:MJCF XML 文件或包含 MJCF 文件的目录 作为输入端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 输出端口详解 + +- `out-1` / **validation** / `json` / `bus`:MJCF 执行器校验结果 作为输出端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 关键超参数 + +- `SOURCE_PATH`:类型 `string`,默认值 空字符串或由工作流显式填写。MJCF XML 文件或包含 MJCF 文件的目录 通常建议在工作流中显式配置。 +- `MAX_MODELS`:类型 `string`,默认值 `20`。最多扫描多少个 MJCF 文件,必须为正整数 可直接使用默认值,也可在节点级覆盖。 + +## 执行前准备 + +- 先确认上下游端口类型兼容,特别是 `json`、`file`、`video` 等端口不要混接。 +- 为每个关键超参数补齐明确值,避免依赖隐式默认值进入生产工作流。 +- 对需要跨节点长期保留的产物,提前规划对象存储前缀或外部落库集合,而不是只写临时目录。 + +## 数据通信与存储路径 + +- 标准输入来自 `INPUT_ARTIFACTS_PATH` 指向的 artifact 列表文件,artifact 可同时包含 `data`、`path`、`metadata` 与 `dataRef`。 +- 标准输出写入 `OUTPUT_DIR`,并通过 `stage-manifest.json` 对外暴露产物路径、payload 引用和摘要元数据。 + +## 典型上下游编排 + +- 该算子通常位于同类数据处理节点之间,承担结构化中间层职责。 + +## 节点配置示例 + +```json +{ + "label": "MJCF 执行器校验", + "operatorId": "operator-builtin-mjcf-actuator-validate", + "type": "builtin", + "category": "ROBOTICS", + "hyperparams": { + "SOURCE_PATH": "<按节点填写>", + "MAX_MODELS": "20" + } +} +``` + +## 输入输出示例 + +- 典型输入:worker 会把上游 artifact 序列化为 `INPUT_ARTIFACTS_PATH` 文件供节点读取。 +- 典型输出:节点会在 `OUTPUT_DIR` 下写业务文件,并在 `stage-manifest.json` 里登记对外可消费的结果。 + +## 成功判定 + +- 节点 execution 状态为 `completed`,且日志中没有隐藏的回退错误或重试未果记录。 +- `stage-manifest.json` 中能看到期望的 artifact 条目,且下游节点可以正常消费这些结果。 + +## 常见失败与排查 + +- 如果看不到预期结果,先检查 `OUTPUT_DIR`、`RESULT_OUTPUT_PATH` 和 `STAGE_MANIFEST_PATH` 是否真实写出。 +- 如果下游收不到数据,先检查当前节点输出 artifact 是否设置了正确的 `portId`、`portName` 和 `type`。 +- 如果日志中只有摘要没有大 payload,优先排查 `dataRef.payloadPath` 或外置文件是否存在,而不是误以为结果丢失。 + +## 验收检查清单 + +- 至少在一条真实工作流中跑通该算子,而不是只验证单元测试或空输入。 +- 确认该节点输出被下游节点实际消费,避免出现“本节点成功但链路无效”的假阳性。 +- 保留一次成功运行的示例日志、stage manifest 和关键产物路径,便于后续回归对照。 + +## 相关文档 + +- [ROBOTICS 类索引](README.md) +- [算子开发文档](../operator-authoring.md) +- [内建算子总手册](../builtin-operators-manual.zh-CN.md) diff --git a/docs/operators/README.md b/docs/operators/README.md index 14d56e52..206e0065 100644 --- a/docs/operators/README.md +++ b/docs/operators/README.md @@ -2,7 +2,7 @@ 当前目录按“每个内建算子一份 Markdown”组织,内容基于当前平台真实算子定义按算子名称去重生成。 -- 当前收录数量:`55` +- 当前收录数量:`58` - 文档定位:单算子详细手册,重点覆盖输入输出契约、运行时路径、配置示例、排障与验收。 - 配套总览:[`../builtin-operators-manual.zh-CN.md`](../builtin-operators-manual.zh-CN.md) @@ -72,13 +72,16 @@ - [LeRobot 数据集校验](LeRobot-数据集校验.md) - [LeRobot 数据集概览](LeRobot-数据集概览.md) - [MCAP 主题概览](MCAP-主题概览.md) +- [MJCF 执行器校验](MJCF-执行器校验.md) - [RGB-D 帧对齐校验](RGB-D-帧对齐校验.md) - [RLDS 轨迹概览](RLDS-轨迹概览.md) - [ROSBag 数据概览](ROSBag-数据概览.md) +- [TF 坐标树校验](TF-坐标树校验.md) - [TFRecord 结构校验](TFRecord-结构校验.md) - [URDF 关节限位校验](URDF-关节限位校验.md) - [VLA 样本清单校验](VLA-样本清单校验.md) - [Zarr 轨迹数组概览](Zarr-轨迹数组概览.md) +- [robomimic HDF5 示教校验](robomimic-HDF5-示教校验.md) - [分割 Mask 校验](分割-Mask-校验.md) - [动作状态数值质量校验](动作状态数值质量校验.md) - [多传感器时间同步校验](多传感器时间同步校验.md) diff --git a/docs/operators/TF-坐标树校验.md b/docs/operators/TF-坐标树校验.md new file mode 100644 index 00000000..c79cf6ac --- /dev/null +++ b/docs/operators/TF-坐标树校验.md @@ -0,0 +1,113 @@ +# TF 坐标树校验 + +- 算子 ID:`operator-builtin-tf-transform-tree-validate` +- 类别:`ROBOTICS` +- 类型:`builtin` + +## 作用 + +读取真实 ROS TransformStamped 风格 JSON/JSONL/YAML 或扁平 CSV 坐标变换,校验父子 frame、平移、四元数归一化、多父节点、重复边和环。 + +## 定位与职责边界 + +- 该算子属于 `ROBOTICS` 类,当前登记类型是 `builtin`。 +- 平台会在 `/api/operators` 中自动提供该算子元数据,运行时由 operator-runner 委派到独立算子入口。 + +## 平台语义 + +面向 ROS/ROS2 机器人数据集、相机外参和多传感器标定入库,真实读取 header.frame_id、child_frame_id、translation、rotation 或 parent_frame/child_frame/qx/qy/qz/qw,校验坐标树根、叶子、重复边、多父节点和环路。 + +## 运行时契约 + +- Worker 会先把上游 artifact 汇总到 `INPUT_ARTIFACTS_PATH`,再把节点配置通过 `NODE_DATA_JSON` 注入运行容器。 +- 节点执行结果会写入 `OUTPUT_DIR`、`RESULT_OUTPUT_PATH` 和 `STAGE_MANIFEST_PATH` 对应的文件,再由 worker 汇总进运行记录。 +- 大文件和大 JSON 不应依赖 API 内联传输,应该通过 `artifact.path`、`dataRef.payloadPath`、共享 PVC 或对象存储引用传递。 +- 当前独立实现入口是 `backend/operators/builtin/tf_transform_tree_validate/operator.py` 中的 `run(...)`,平台 runtimeHandler 为 `builtin_tf_transform_tree_validate`。 + +## 设计边界 + +- 该算子应该只承担单一职责,不应在一个节点里同时混合索引、筛选、上传、审核等多个阶段性行为。 +- 如果一个节点要消费多个语义不同的结果,优先通过多节点拆分,而不是把所有逻辑塞进一个超大脚本。 + +## 数据流示意 + +```mermaid +flowchart LR + A[上游输入或运行时注入] --> B[TF 坐标树校验] + B --> C[artifact / stage manifest / 外部副作用] +``` + +## 输入端口详解 + +- `in-1` / **input** / `json` / `bus`:transforms/tf/tf_static JSON、JSONL、CSV 或 YAML 文件/目录 作为输入端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 输出端口详解 + +- `out-1` / **validation** / `json` / `bus`:TF 坐标树校验结果 作为输出端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 关键超参数 + +- `SOURCE_PATH`:类型 `string`,默认值 空字符串或由工作流显式填写。坐标变换文件或包含坐标变换文件的目录 通常建议在工作流中显式配置。 +- `QUATERNION_NORM_TOLERANCE`:类型 `string`,默认值 `0.01`。四元数 norm 与 1 的允许误差 可直接使用默认值,也可在节点级覆盖。 +- `MAX_TRANSFORMS`:类型 `string`,默认值 `10000`。最多校验多少条 transform 记录,必须为正整数 可直接使用默认值,也可在节点级覆盖。 +- `MAX_FILES`:类型 `string`,默认值 `50`。最多扫描多少个 transform 文件,必须为正整数 可直接使用默认值,也可在节点级覆盖。 + +## 执行前准备 + +- 先确认上下游端口类型兼容,特别是 `json`、`file`、`video` 等端口不要混接。 +- 为每个关键超参数补齐明确值,避免依赖隐式默认值进入生产工作流。 +- 对需要跨节点长期保留的产物,提前规划对象存储前缀或外部落库集合,而不是只写临时目录。 + +## 数据通信与存储路径 + +- 标准输入来自 `INPUT_ARTIFACTS_PATH` 指向的 artifact 列表文件,artifact 可同时包含 `data`、`path`、`metadata` 与 `dataRef`。 +- 标准输出写入 `OUTPUT_DIR`,并通过 `stage-manifest.json` 对外暴露产物路径、payload 引用和摘要元数据。 + +## 典型上下游编排 + +- 该算子通常位于同类数据处理节点之间,承担结构化中间层职责。 + +## 节点配置示例 + +```json +{ + "label": "TF 坐标树校验", + "operatorId": "operator-builtin-tf-transform-tree-validate", + "type": "builtin", + "category": "ROBOTICS", + "hyperparams": { + "SOURCE_PATH": "<按节点填写>", + "QUATERNION_NORM_TOLERANCE": "0.01", + "MAX_TRANSFORMS": "10000", + "MAX_FILES": "50" + } +} +``` + +## 输入输出示例 + +- 典型输入:worker 会把上游 artifact 序列化为 `INPUT_ARTIFACTS_PATH` 文件供节点读取。 +- 典型输出:节点会在 `OUTPUT_DIR` 下写业务文件,并在 `stage-manifest.json` 里登记对外可消费的结果。 + +## 成功判定 + +- 节点 execution 状态为 `completed`,且日志中没有隐藏的回退错误或重试未果记录。 +- `stage-manifest.json` 中能看到期望的 artifact 条目,且下游节点可以正常消费这些结果。 + +## 常见失败与排查 + +- 如果看不到预期结果,先检查 `OUTPUT_DIR`、`RESULT_OUTPUT_PATH` 和 `STAGE_MANIFEST_PATH` 是否真实写出。 +- 如果下游收不到数据,先检查当前节点输出 artifact 是否设置了正确的 `portId`、`portName` 和 `type`。 +- 如果日志中只有摘要没有大 payload,优先排查 `dataRef.payloadPath` 或外置文件是否存在,而不是误以为结果丢失。 + +## 验收检查清单 + +- 至少在一条真实工作流中跑通该算子,而不是只验证单元测试或空输入。 +- 确认该节点输出被下游节点实际消费,避免出现“本节点成功但链路无效”的假阳性。 +- 保留一次成功运行的示例日志、stage manifest 和关键产物路径,便于后续回归对照。 + +## 相关文档 + +- [ROBOTICS 类索引](README.md) +- [算子开发文档](../operator-authoring.md) +- [内建算子总手册](../builtin-operators-manual.zh-CN.md) diff --git a/docs/operators/robomimic-HDF5-示教校验.md b/docs/operators/robomimic-HDF5-示教校验.md new file mode 100644 index 00000000..640d1a6b --- /dev/null +++ b/docs/operators/robomimic-HDF5-示教校验.md @@ -0,0 +1,121 @@ +# robomimic HDF5 示教校验 + +- 算子 ID:`operator-builtin-robomimic-hdf5-validate` +- 类别:`ROBOTICS` +- 类型:`builtin` + +## 作用 + +读取真实 robomimic HDF5 示教文件,校验 /data/demo_* 下 actions、rewards、dones、obs、next_obs、states、mask 与 total 样本数一致性。 + +## 定位与职责边界 + +- 该算子属于 `ROBOTICS` 类,当前登记类型是 `builtin`。 +- 平台会在 `/api/operators` 中自动提供该算子元数据,运行时由 operator-runner 委派到独立算子入口。 + +## 平台语义 + +面向 robomimic、D4RL/robosuite 派生示教数据和 GitHub 常见机器人模仿学习 HDF5 数据,真实读取 /data/demo_* group,校验 actions/rewards/dones 与 obs/next_obs 帧数、num_samples、data.attrs.total 和 mask/train/valid 引用关系。 + +## 运行时契约 + +- Worker 会先把上游 artifact 汇总到 `INPUT_ARTIFACTS_PATH`,再把节点配置通过 `NODE_DATA_JSON` 注入运行容器。 +- 节点执行结果会写入 `OUTPUT_DIR`、`RESULT_OUTPUT_PATH` 和 `STAGE_MANIFEST_PATH` 对应的文件,再由 worker 汇总进运行记录。 +- 大文件和大 JSON 不应依赖 API 内联传输,应该通过 `artifact.path`、`dataRef.payloadPath`、共享 PVC 或对象存储引用传递。 +- 当前独立实现入口是 `backend/operators/builtin/robomimic_hdf5_validate/operator.py` 中的 `run(...)`,平台 runtimeHandler 为 `builtin_robomimic_hdf5_validate`。 + +## 设计边界 + +- 该算子应该只承担单一职责,不应在一个节点里同时混合索引、筛选、上传、审核等多个阶段性行为。 +- 如果一个节点要消费多个语义不同的结果,优先通过多节点拆分,而不是把所有逻辑塞进一个超大脚本。 + +## 数据流示意 + +```mermaid +flowchart LR + A[上游输入或运行时注入] --> B[robomimic HDF5 示教校验] + B --> C[artifact / stage manifest / 外部副作用] +``` + +## 输入端口详解 + +- `in-1` / **input** / `json` / `bus`:robomimic .hdf5/.h5 文件或目录输入 作为输入端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 输出端口详解 + +- `out-1` / **validation** / `json` / `bus`:robomimic HDF5 示教结构校验结果 作为输出端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 关键超参数 + +- `SOURCE_PATH`:类型 `string`,默认值 空字符串或由工作流显式填写。.hdf5/.h5 文件或包含 robomimic HDF5 文件的目录 通常建议在工作流中显式配置。 +- `REQUIRE_REWARDS`:类型 `string`,默认值 `true`。是否要求每个 demo 包含 rewards 数据集 可直接使用默认值,也可在节点级覆盖。 +- `REQUIRE_DONES`:类型 `string`,默认值 `true`。是否要求每个 demo 包含 dones 数据集 可直接使用默认值,也可在节点级覆盖。 +- `REQUIRE_NEXT_OBS`:类型 `string`,默认值 `true`。是否要求每个 demo 包含 next_obs group 可直接使用默认值,也可在节点级覆盖。 +- `CHECK_ACTION_RANGE`:类型 `string`,默认值 `false`。是否检查 action 绝对值不超过 MAX_ABS_ACTION;默认关闭以兼容未归一化控制量 可直接使用默认值,也可在节点级覆盖。 +- `MAX_ABS_ACTION`:类型 `string`,默认值 `1.0`。开启 CHECK_ACTION_RANGE 后允许的最大 action 绝对值 可直接使用默认值,也可在节点级覆盖。 +- `MAX_DEMOS`:类型 `string`,默认值 `200`。每个文件最多校验多少个 demo,必须为正整数 可直接使用默认值,也可在节点级覆盖。 +- `MAX_FILES`:类型 `string`,默认值 `20`。最多校验多少个 HDF5 文件,必须为正整数 可直接使用默认值,也可在节点级覆盖。 + +## 执行前准备 + +- 先确认上下游端口类型兼容,特别是 `json`、`file`、`video` 等端口不要混接。 +- 为每个关键超参数补齐明确值,避免依赖隐式默认值进入生产工作流。 +- 对需要跨节点长期保留的产物,提前规划对象存储前缀或外部落库集合,而不是只写临时目录。 + +## 数据通信与存储路径 + +- 标准输入来自 `INPUT_ARTIFACTS_PATH` 指向的 artifact 列表文件,artifact 可同时包含 `data`、`path`、`metadata` 与 `dataRef`。 +- 标准输出写入 `OUTPUT_DIR`,并通过 `stage-manifest.json` 对外暴露产物路径、payload 引用和摘要元数据。 + +## 典型上下游编排 + +- 该算子通常位于同类数据处理节点之间,承担结构化中间层职责。 + +## 节点配置示例 + +```json +{ + "label": "robomimic HDF5 示教校验", + "operatorId": "operator-builtin-robomimic-hdf5-validate", + "type": "builtin", + "category": "ROBOTICS", + "hyperparams": { + "SOURCE_PATH": "<按节点填写>", + "REQUIRE_REWARDS": "true", + "REQUIRE_DONES": "true", + "REQUIRE_NEXT_OBS": "true", + "CHECK_ACTION_RANGE": "false", + "MAX_ABS_ACTION": "1.0", + "MAX_DEMOS": "200", + "MAX_FILES": "20" + } +} +``` + +## 输入输出示例 + +- 典型输入:worker 会把上游 artifact 序列化为 `INPUT_ARTIFACTS_PATH` 文件供节点读取。 +- 典型输出:节点会在 `OUTPUT_DIR` 下写业务文件,并在 `stage-manifest.json` 里登记对外可消费的结果。 + +## 成功判定 + +- 节点 execution 状态为 `completed`,且日志中没有隐藏的回退错误或重试未果记录。 +- `stage-manifest.json` 中能看到期望的 artifact 条目,且下游节点可以正常消费这些结果。 + +## 常见失败与排查 + +- 如果看不到预期结果,先检查 `OUTPUT_DIR`、`RESULT_OUTPUT_PATH` 和 `STAGE_MANIFEST_PATH` 是否真实写出。 +- 如果下游收不到数据,先检查当前节点输出 artifact 是否设置了正确的 `portId`、`portName` 和 `type`。 +- 如果日志中只有摘要没有大 payload,优先排查 `dataRef.payloadPath` 或外置文件是否存在,而不是误以为结果丢失。 + +## 验收检查清单 + +- 至少在一条真实工作流中跑通该算子,而不是只验证单元测试或空输入。 +- 确认该节点输出被下游节点实际消费,避免出现“本节点成功但链路无效”的假阳性。 +- 保留一次成功运行的示例日志、stage manifest 和关键产物路径,便于后续回归对照。 + +## 相关文档 + +- [ROBOTICS 类索引](README.md) +- [算子开发文档](../operator-authoring.md) +- [内建算子总手册](../builtin-operators-manual.zh-CN.md) diff --git a/internal/api/builtin_operators_catalog.json b/internal/api/builtin_operators_catalog.json index 77bbc146..ddf0486f 100644 --- a/internal/api/builtin_operators_catalog.json +++ b/internal/api/builtin_operators_catalog.json @@ -1490,6 +1490,84 @@ "runtimeSource": "backend/operators/builtin/hdf5_demonstration_summary/operator.py", "runtimeHandler": "builtin_hdf5_demonstration_summary" }, + { + "id": "operator-builtin-robomimic-hdf5-validate", + "name": "robomimic HDF5 示教校验", + "type": "builtin", + "category": "ROBOTICS", + "description": "读取真实 robomimic HDF5 示教文件,校验 /data/demo_* 下 actions、rewards、dones、obs、next_obs、states、mask 与 total 样本数一致性。", + "inputs": [ + { + "id": "in-1", + "name": "input", + "type": "json", + "description": "robomimic .hdf5/.h5 文件或目录输入", + "transmission": "bus" + } + ], + "outputs": [ + { + "id": "out-1", + "name": "validation", + "type": "json", + "description": "robomimic HDF5 示教结构校验结果", + "transmission": "bus" + } + ], + "skillDefinition": "面向 robomimic、D4RL/robosuite 派生示教数据和 GitHub 常见机器人模仿学习 HDF5 数据,真实读取 /data/demo_* group,校验 actions/rewards/dones 与 obs/next_obs 帧数、num_samples、data.attrs.total 和 mask/train/valid 引用关系。", + "hyperparams": [ + { + "key": "SOURCE_PATH", + "value": "", + "description": ".hdf5/.h5 文件或包含 robomimic HDF5 文件的目录", + "type": "string" + }, + { + "key": "REQUIRE_REWARDS", + "value": "true", + "description": "是否要求每个 demo 包含 rewards 数据集", + "type": "string" + }, + { + "key": "REQUIRE_DONES", + "value": "true", + "description": "是否要求每个 demo 包含 dones 数据集", + "type": "string" + }, + { + "key": "REQUIRE_NEXT_OBS", + "value": "true", + "description": "是否要求每个 demo 包含 next_obs group", + "type": "string" + }, + { + "key": "CHECK_ACTION_RANGE", + "value": "false", + "description": "是否检查 action 绝对值不超过 MAX_ABS_ACTION;默认关闭以兼容未归一化控制量", + "type": "string" + }, + { + "key": "MAX_ABS_ACTION", + "value": "1.0", + "description": "开启 CHECK_ACTION_RANGE 后允许的最大 action 绝对值", + "type": "string" + }, + { + "key": "MAX_DEMOS", + "value": "200", + "description": "每个文件最多校验多少个 demo,必须为正整数", + "type": "string" + }, + { + "key": "MAX_FILES", + "value": "20", + "description": "最多校验多少个 HDF5 文件,必须为正整数", + "type": "string" + } + ], + "runtimeSource": "backend/operators/builtin/robomimic_hdf5_validate/operator.py", + "runtimeHandler": "builtin_robomimic_hdf5_validate" + }, { "id": "operator-builtin-aloha-hdf5-validate", "name": "ALOHA HDF5 示教校验", @@ -2114,6 +2192,102 @@ "runtimeSource": "backend/operators/builtin/camera_calibration_validate/operator.py", "runtimeHandler": "builtin_camera_calibration_validate" }, + { + "id": "operator-builtin-tf-transform-tree-validate", + "name": "TF 坐标树校验", + "type": "builtin", + "category": "ROBOTICS", + "description": "读取真实 ROS TransformStamped 风格 JSON/JSONL/YAML 或扁平 CSV 坐标变换,校验父子 frame、平移、四元数归一化、多父节点、重复边和环。", + "inputs": [ + { + "id": "in-1", + "name": "input", + "type": "json", + "description": "transforms/tf/tf_static JSON、JSONL、CSV 或 YAML 文件/目录", + "transmission": "bus" + } + ], + "outputs": [ + { + "id": "out-1", + "name": "validation", + "type": "json", + "description": "TF 坐标树校验结果", + "transmission": "bus" + } + ], + "skillDefinition": "面向 ROS/ROS2 机器人数据集、相机外参和多传感器标定入库,真实读取 header.frame_id、child_frame_id、translation、rotation 或 parent_frame/child_frame/qx/qy/qz/qw,校验坐标树根、叶子、重复边、多父节点和环路。", + "hyperparams": [ + { + "key": "SOURCE_PATH", + "value": "", + "description": "坐标变换文件或包含坐标变换文件的目录", + "type": "string" + }, + { + "key": "QUATERNION_NORM_TOLERANCE", + "value": "0.01", + "description": "四元数 norm 与 1 的允许误差", + "type": "string" + }, + { + "key": "MAX_TRANSFORMS", + "value": "10000", + "description": "最多校验多少条 transform 记录,必须为正整数", + "type": "string" + }, + { + "key": "MAX_FILES", + "value": "50", + "description": "最多扫描多少个 transform 文件,必须为正整数", + "type": "string" + } + ], + "runtimeSource": "backend/operators/builtin/tf_transform_tree_validate/operator.py", + "runtimeHandler": "builtin_tf_transform_tree_validate" + }, + { + "id": "operator-builtin-mjcf-actuator-validate", + "name": "MJCF 执行器校验", + "type": "builtin", + "category": "ROBOTICS", + "description": "读取真实 MuJoCo/MJCF XML,校验 actuator 下 motor/position/velocity/general 等执行器目标引用、ctrlrange/forcerange/actrange 和 gear 数值。", + "inputs": [ + { + "id": "in-1", + "name": "input", + "type": "json", + "description": "MJCF XML 文件或包含 MJCF 文件的目录", + "transmission": "bus" + } + ], + "outputs": [ + { + "id": "out-1", + "name": "validation", + "type": "json", + "description": "MJCF 执行器校验结果", + "transmission": "bus" + } + ], + "skillDefinition": "面向 MuJoCo、robosuite、ManiSkill 和 GitHub 常见 MJCF 仿真资产,真实解析 下执行器,验证 joint/tendon/site/body 引用存在,ctrlrange/forcerange/actrange 为递增有限数值,并识别重复 actuator 名称。", + "hyperparams": [ + { + "key": "SOURCE_PATH", + "value": "", + "description": "MJCF XML 文件或包含 MJCF 文件的目录", + "type": "string" + }, + { + "key": "MAX_MODELS", + "value": "20", + "description": "最多扫描多少个 MJCF 文件,必须为正整数", + "type": "string" + } + ], + "runtimeSource": "backend/operators/builtin/mjcf_actuator_validate/operator.py", + "runtimeHandler": "builtin_mjcf_actuator_validate" + }, { "id": "operator-builtin-robot-model-asset-validate", "name": "机器人模型资产校验", diff --git a/scripts/generate_operator_repository_manifests.py b/scripts/generate_operator_repository_manifests.py index cd24eb38..c29c768c 100644 --- a/scripts/generate_operator_repository_manifests.py +++ b/scripts/generate_operator_repository_manifests.py @@ -41,6 +41,7 @@ RUNTIME_DEPENDENCIES: dict[str, list[str]] = { "lerobot_summary": ["lerobot-dataset-files"], "mcap_topic_summary": ["mcap-files", "mcap-python"], "merge": ["json-artifacts"], + "mjcf_actuator_validate": ["mjcf-files", "xml-parser"], "model_inference": ["json-model-or-command"], "mongodb_write": ["mongodb"], "package": ["filesystem"], @@ -49,6 +50,7 @@ RUNTIME_DEPENDENCIES: dict[str, list[str]] = { "real_source": ["filesystem"], "rgbd_frame_pair_validate": ["rgb-images", "depth-images", "opencv-python-headless", "numpy", "pyyaml"], "rlds_episode_summary": ["rlds-json-or-tfds-files"], + "robomimic_hdf5_validate": ["robomimic-hdf5-files", "h5py", "numpy"], "robot_model_asset_validate": ["urdf-files", "mjcf-files", "mesh-assets"], "rosbag_summary": ["rosbag2-files", "sqlite"], "sensor_timestamp_sync_validate": ["timestamp-csv-jsonl"], @@ -56,6 +58,7 @@ RUNTIME_DEPENDENCIES: dict[str, list[str]] = { "shell_command": ["container-shell"], "template_render": ["json-artifacts"], "tfrecord_structural_validate": ["tfrecord-files", "crc32c-structural-validation"], + "tf_transform_tree_validate": ["json-jsonl-csv-yaml-files", "optional-pyyaml"], "trajectory_integrity_validate": ["trajectory-json", "local-media-files"], "upload": ["filesystem", "optional-baidu-bos"], "video_annotate": ["video-files", "json-artifacts"],