diff --git a/backend/operator-runner/main.py b/backend/operator-runner/main.py index e6c0fcd4..82517e32 100644 --- a/backend/operator-runner/main.py +++ b/backend/operator-runner/main.py @@ -55,6 +55,7 @@ from backend.operators.builtin.human_review import operator as human_review_oper from backend.operators.builtin.hdf5_demonstration_summary import operator as hdf5_demonstration_summary_operator from backend.operators.builtin.hf_dataset_probe import operator as hf_dataset_probe_operator from backend.operators.builtin.hand_object_pose_validate import operator as hand_object_pose_validate_operator +from backend.operators.builtin.ho3d_dataset_validate import operator as ho3d_dataset_validate_operator from backend.operators.builtin.joint_limit_validate import operator as joint_limit_validate_operator from backend.operators.builtin.json_field_extract import operator as json_field_extract_operator from backend.operators.builtin.json_filter import operator as json_filter_operator @@ -5013,6 +5014,7 @@ BUILTIN_HANDLER_RULES: tuple[tuple[str, tuple[str, ...]], ...] = ( ("tf_transform_tree_validate", ("tf 坐标树", "transform tree", "tf tree", "坐标树校验", "frametree")), ("ros_joint_state_validate", ("ros jointstate", "jointstate", "joint state", "joint_states", "ros 关节状态")), ("dexycb_dataset_validate", ("dexycb 数据集", "dex-ycb", "dexycb", "ycb hand", "hand grasping object")), + ("ho3d_dataset_validate", ("ho3d 数据集", "ho-3d", "ho3d", "h2o3d", "h2o-3d", "honnotate")), ("hand_object_pose_validate", ("手-物体姿态", "手物体姿态", "hand object pose", "dexycb", "ho3d")), ("mjcf_actuator_validate", ("mjcf 执行器", "mjcf actuator", "mujoco actuator", "执行器校验", "ctrlrange")), ("robot_model_asset_validate", ("机器人模型资产校验", "robot model asset", "urdf", "mjcf")), @@ -5106,6 +5108,7 @@ BUILTIN_HANDLERS: dict[str, BuiltinHandler] = { "tfrecord_structural_validate": operator_handler(tfrecord_structural_validate_operator), "dataset_provenance_audit": operator_handler(dataset_provenance_audit_operator), "dexycb_dataset_validate": operator_handler(dexycb_dataset_validate_operator), + "ho3d_dataset_validate": operator_handler(ho3d_dataset_validate_operator), "webdataset_shard_summary": operator_handler(webdataset_shard_summary_operator), "umi_zarr_dataset_validate": operator_handler(umi_zarr_dataset_validate_operator), "zarr_trajectory_summary": operator_handler(zarr_trajectory_summary_operator), diff --git a/backend/operator-runner/test_main.py b/backend/operator-runner/test_main.py index 8a149710..62695ffd 100644 --- a/backend/operator-runner/test_main.py +++ b/backend/operator-runner/test_main.py @@ -6,6 +6,7 @@ import io import json import os import pathlib +import pickle import sqlite3 import struct import tarfile @@ -267,6 +268,7 @@ class RuntimeFileContractTests(unittest.TestCase): self.assertEqual(MODULE.select_handler("LeRobot 视频对齐校验"), "lerobot_video_alignment_validate") self.assertEqual(MODULE.select_handler("ROS JointState 校验"), "ros_joint_state_validate") self.assertEqual(MODULE.select_handler("DexYCB 数据集校验"), "dexycb_dataset_validate") + self.assertEqual(MODULE.select_handler("HO3D/H2O3D 数据集校验"), "ho3d_dataset_validate") self.assertEqual(MODULE.select_handler("手-物体姿态标注校验"), "hand_object_pose_validate") self.assertEqual(MODULE.select_handler("RLBench 数据集校验"), "rlbench_dataset_validate") self.assertEqual(MODULE.select_handler("ManiSkill 轨迹校验"), "maniskill_trajectory_validate") @@ -4874,6 +4876,74 @@ class EmbodiedDatasetOperatorTests(unittest.TestCase): self.assertIn(255, sample["segUniqueLabels"]) self.assertEqual(sample["visibleJointCount"], 21) + def test_ho3d_dataset_validate_reads_meta_pickle_and_media_pairs(self): + try: + import cv2 # type: ignore + import numpy as np # type: ignore + except Exception as exc: + self.skipTest(f"cv2/numpy not available: {exc}") + with tempfile.TemporaryDirectory() as temp_dir: + root = pathlib.Path(temp_dir) / "ho3d" + frame_id = "0000" + seq_dir = root / "train" / "ABF10" + for folder in ("rgb", "depth", "segr", "meta"): + (seq_dir / folder).mkdir(parents=True) + cv2.imwrite(str(seq_dir / "rgb" / f"{frame_id}.jpg"), np.full((6, 8, 3), 120, dtype=np.uint8)) + cv2.imwrite(str(seq_dir / "depth" / f"{frame_id}.png"), np.full((6, 8, 3), 20, dtype=np.uint8)) + cv2.imwrite(str(seq_dir / "segr" / f"{frame_id}.png"), np.full((6, 8, 3), 255, dtype=np.uint8)) + meta = { + "camMat": np.array([[610.0, 0.0, 320.0], [0.0, 611.0, 240.0], [0.0, 0.0, 1.0]], dtype=np.float32), + "objRot": np.array([0.1, 0.2, 0.3], dtype=np.float32), + "objTrans": np.array([0.01, -0.02, -0.45], dtype=np.float32), + "objCorners3DRest": np.arange(24, dtype=np.float32).reshape(8, 3), + "objName": "003_cracker_box", + "handPose": np.zeros((48,), dtype=np.float32), + "handTrans": np.array([0.0, 0.0, -0.35], dtype=np.float32), + "handBeta": np.zeros((10,), dtype=np.float32), + "handJoints3D": np.ones((21, 3), dtype=np.float32), + "handBoundingBox": np.array([1.0, 1.0, 7.0, 5.0], dtype=np.float32), + "handVertContact": np.array([0.0, 1.0, 0.5], dtype=np.float32), + } + with (seq_dir / "meta" / f"{frame_id}.pkl").open("wb") as handle: + pickle.dump(meta, handle) + node_data = { + "label": "HO3D/H2O3D 数据集校验", + "hyperparams": [ + {"key": "SOURCE_PATH", "value": str(root)}, + {"key": "CHECK_SEGMENTATION_FILES", "value": "true"}, + ], + } + + artifacts = MODULE.BUILTIN_HANDLERS["ho3d_dataset_validate"]( + "run-1", "ho3d", root / "out", node_data, [] + ) + + payload = MODULE.load_artifact_payload(artifacts[0]) + self.assertEqual(payload["datasetType"], "ho3d-dataset-validation") + self.assertTrue(payload["valid"]) + self.assertEqual(payload["issueCount"], 0) + self.assertEqual(payload["sampleCount"], 1) + self.assertEqual(payload["validSampleCount"], 1) + self.assertEqual(payload["invalidSampleCount"], 0) + self.assertEqual(payload["splitCounts"], {"train": 1}) + self.assertEqual(payload["sequenceCounts"], {"ABF10": 1}) + self.assertEqual(payload["objectCounts"], {"003_cracker_box": 1}) + self.assertEqual(payload["handAnnotationCounts"], {"manoHand": 1, "handJoints3D": 1, "handVertContact": 1}) + self.assertTrue(payload["assets"]["hasTrainDir"]) + sample = payload["samples"][0] + self.assertEqual(sample["frameId"], "0000") + self.assertEqual(sample["metaPath"], "train/ABF10/meta/0000.pkl") + self.assertEqual(sample["rgbPath"], "train/ABF10/rgb/0000.jpg") + self.assertEqual(sample["depthPath"], "train/ABF10/depth/0000.png") + self.assertEqual(sample["segmentationPath"], "train/ABF10/segr/0000.png") + self.assertTrue(sample["hasObjectPose"]) + self.assertTrue(sample["hasManoHand"]) + self.assertTrue(sample["hasHandJoints3D"]) + self.assertEqual(sample["arrayShapes"]["camMat"], [3, 3]) + self.assertEqual(sample["arrayShapes"]["objCorners3DRest"], [8, 3]) + self.assertEqual(sample["arrayShapes"]["handPose"], [48]) + self.assertEqual(sample["arrayShapes"]["handJoints3D"], [21, 3]) + def test_hand_object_pose_validate_reads_real_pose_jsonl_and_images(self): try: import cv2 # type: ignore diff --git a/backend/operators/builtin/ho3d_dataset_validate/__init__.py b/backend/operators/builtin/ho3d_dataset_validate/__init__.py new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/backend/operators/builtin/ho3d_dataset_validate/__init__.py @@ -0,0 +1 @@ + diff --git a/backend/operators/builtin/ho3d_dataset_validate/operator.json b/backend/operators/builtin/ho3d_dataset_validate/operator.json new file mode 100644 index 00000000..92348490 --- /dev/null +++ b/backend/operators/builtin/ho3d_dataset_validate/operator.json @@ -0,0 +1,16 @@ +{ + "id": "operator-builtin-ho3d-dataset-validate", + "name": "HO3D/H2O3D 数据集校验", + "category": "ROBOTICS", + "type": "builtin", + "runtimeHandler": "builtin_ho3d_dataset_validate", + "runtimeSource": "backend/operators/builtin/ho3d_dataset_validate/operator.py", + "migrationStatus": "migrated", + "acceptance": { + "requiresRealInputs": true, + "mockOnlyAccepted": false, + "simulationOnlyAccepted": false, + "hardcodedOutputAccepted": false, + "shallowOnlyAccepted": false + } +} diff --git a/backend/operators/builtin/ho3d_dataset_validate/operator.py b/backend/operators/builtin/ho3d_dataset_validate/operator.py new file mode 100644 index 00000000..3a69f5f4 --- /dev/null +++ b/backend/operators/builtin/ho3d_dataset_validate/operator.py @@ -0,0 +1,373 @@ +from __future__ import annotations + +import pathlib +import pickle +from typing import Any, Callable + + +HelperMap = dict[str, Callable[..., Any]] +SPLIT_NAMES = ("train", "training", "evaluation") +RGB_SUFFIXES = (".jpg", ".png") + + +def _require_numpy(): + try: + import numpy as np # type: ignore + except Exception as exc: # pragma: no cover - runtime dependency check + raise RuntimeError("HO3D/H2O3D 数据集校验需要 numpy 读取真实 meta/*.pkl 注解") from exc + return np + + +def _positive_int(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 _bool_param(helpers: HelperMap, params: dict[str, str], key: str, default: bool) -> bool: + return bool(helpers["parse_bool_param"](params, key, default)) + + +def _relative(path: pathlib.Path, root: pathlib.Path) -> str: + try: + return path.relative_to(root).as_posix() + except ValueError: + return str(path) + + +def _dataset_root(source_path: pathlib.Path) -> pathlib.Path: + base = source_path if source_path.is_dir() else source_path.parent + for candidate in [base, *base.parents]: + if any((candidate / split).is_dir() for split in SPLIT_NAMES): + return candidate + if base.name in SPLIT_NAMES: + return base.parent + return base + + +def _find_meta_files(source_path: pathlib.Path, max_samples: int) -> list[pathlib.Path]: + if source_path.is_file(): + return [source_path] if source_path.suffix.lower() == ".pkl" else [] + preferred = [ + path + for split in SPLIT_NAMES + for path in sorted((source_path / split).glob("*/meta/*.pkl")) + if path.is_file() + ] + if preferred: + return preferred[:max_samples] + return [ + path + for path in sorted(source_path.rglob("*.pkl")) + if path.is_file() and path.parent.name == "meta" + ][:max_samples] + + +def _sample_context(meta_path: pathlib.Path, root: pathlib.Path) -> dict[str, str]: + frame_id = meta_path.stem + sequence = meta_path.parent.parent.name if meta_path.parent.name == "meta" else meta_path.parent.name + split = "" + try: + rel_parts = meta_path.relative_to(root).parts + except ValueError: + rel_parts = meta_path.parts + if rel_parts and rel_parts[0] in SPLIT_NAMES: + split = rel_parts[0] + return {"split": split, "sequenceId": sequence, "frameId": frame_id} + + +def _media_paths(root: pathlib.Path, context: dict[str, str]) -> dict[str, pathlib.Path | None]: + split = context.get("split") or "train" + sequence = context["sequenceId"] + frame_id = context["frameId"] + seq_dir = root / split / sequence + rgb_path = next((seq_dir / "rgb" / f"{frame_id}{suffix}" for suffix in RGB_SUFFIXES if (seq_dir / "rgb" / f"{frame_id}{suffix}").is_file()), None) + return { + "rgb": rgb_path, + "rgbExpected": seq_dir / "rgb" / f"{frame_id}.jpg", + "depth": seq_dir / "depth" / f"{frame_id}.png", + "segmentation": seq_dir / "segr" / f"{frame_id}.png", + } + + +def _load_pickle(path: pathlib.Path) -> Any: + with path.open("rb") as handle: + try: + return pickle.load(handle, encoding="latin1") + except TypeError: + handle.seek(0) + return pickle.load(handle) + + +def _shape(np: Any, value: Any) -> list[int]: + try: + return [int(item) for item in np.asarray(value).shape] + except Exception: + return [] + + +def _dtype(np: Any, value: Any) -> str: + try: + return str(np.asarray(value).dtype) + except Exception: + return "" + + +def _finite(np: Any, value: Any) -> bool: + try: + array = np.asarray(value) + except Exception: + return True + if not np.issubdtype(array.dtype, np.number): + return True + return bool(np.isfinite(array).all()) + + +def _valid_shape(np: Any, value: Any, expected: tuple[int, ...]) -> bool: + return _shape(np, value) == [int(item) for item in expected] + + +def _valid_hand_joints_shape(np: Any, value: Any) -> bool: + shape = _shape(np, value) + return shape in ([3], [1, 3], [21, 3], [1, 21, 3]) + + +def _bbox_valid(np: Any, value: Any) -> bool: + if not _valid_shape(np, value, (4,)): + return False + bbox = np.asarray(value, dtype=float).reshape(4) + return bool(bbox[2] > bbox[0] and bbox[3] > bbox[1]) + + +def _sample_issue(code: str, **details: Any) -> dict[str, Any]: + return {"code": code, **details} + + +def _validate_sample( + np: Any, + meta_path: pathlib.Path, + root: pathlib.Path, + *, + check_rgb_depth_files: bool, + check_segmentation_files: bool, + require_object_pose: bool, + require_hand_annotation: bool, + require_finite_numeric: bool, +) -> dict[str, Any]: + context = _sample_context(meta_path, root) + issues: list[dict[str, Any]] = [] + media = _media_paths(root, context) + rgb_path = media["rgb"] + depth_path = media["depth"] + seg_path = media["segmentation"] + + if check_rgb_depth_files and rgb_path is None: + issues.append(_sample_issue("missing_rgb_file", path=_relative(media["rgbExpected"], root))) + if check_rgb_depth_files and (not isinstance(depth_path, pathlib.Path) or not depth_path.is_file()): + issues.append(_sample_issue("missing_depth_file", path=_relative(depth_path if isinstance(depth_path, pathlib.Path) else root / "depth", root))) + if check_segmentation_files and (not isinstance(seg_path, pathlib.Path) or not seg_path.is_file()): + issues.append(_sample_issue("missing_segmentation_file", path=_relative(seg_path if isinstance(seg_path, pathlib.Path) else root / "segr", root))) + + try: + payload = _load_pickle(meta_path) + except Exception as exc: + return { + **context, + "metaPath": _relative(meta_path, root), + "valid": False, + "issueCount": 1, + "issues": [_sample_issue("meta_pickle_load_failed", message=str(exc))], + "metaKeys": [], + "arrayShapes": {}, + "arrayDtypes": {}, + } + if not isinstance(payload, dict): + return { + **context, + "metaPath": _relative(meta_path, root), + "valid": False, + "issueCount": 1, + "issues": [_sample_issue("meta_payload_not_dict", payloadType=type(payload).__name__)], + "metaKeys": [], + "arrayShapes": {}, + "arrayDtypes": {}, + } + + meta_keys = sorted(str(key) for key in payload.keys()) + expected_shapes: dict[str, tuple[int, ...]] = { + "camMat": (3, 3), + "objRot": (3,), + "objTrans": (3,), + "objCorners3DRest": (8, 3), + "handPose": (48,), + "handTrans": (3,), + "handBeta": (10,), + "handBoundingBox": (4,), + } + array_shapes: dict[str, list[int]] = {} + array_dtypes: dict[str, str] = {} + for key in expected_shapes: + if key in payload and payload[key] is not None: + array_shapes[key] = _shape(np, payload[key]) + array_dtypes[key] = _dtype(np, payload[key]) + if not _valid_shape(np, payload[key], expected_shapes[key]): + issues.append(_sample_issue("meta_array_shape_mismatch", array=key, shape=array_shapes[key])) + if require_finite_numeric and not _finite(np, payload[key]): + issues.append(_sample_issue("non_finite_meta_array", array=key)) + if "handJoints3D" in payload and payload["handJoints3D"] is not None: + array_shapes["handJoints3D"] = _shape(np, payload["handJoints3D"]) + array_dtypes["handJoints3D"] = _dtype(np, payload["handJoints3D"]) + if not _valid_hand_joints_shape(np, payload["handJoints3D"]): + issues.append(_sample_issue("hand_joints3d_shape_mismatch", shape=array_shapes["handJoints3D"])) + if require_finite_numeric and not _finite(np, payload["handJoints3D"]): + issues.append(_sample_issue("non_finite_meta_array", array="handJoints3D")) + + if "camMat" not in payload or payload.get("camMat") is None: + issues.append(_sample_issue("missing_camera_matrix")) + has_object_pose = payload.get("objRot") is not None and payload.get("objTrans") is not None + if require_object_pose and not has_object_pose: + issues.append(_sample_issue("missing_object_pose", requiredKeys=["objRot", "objTrans"])) + if "objCorners3DRest" not in payload or payload.get("objCorners3DRest") is None: + issues.append(_sample_issue("missing_object_corners")) + obj_name = str(payload.get("objName") or "").strip() + if not obj_name: + issues.append(_sample_issue("missing_object_name")) + has_mano_hand = all(payload.get(key) is not None for key in ("handPose", "handTrans", "handBeta")) + has_hand_joints = payload.get("handJoints3D") is not None + if require_hand_annotation and not has_mano_hand and not has_hand_joints: + issues.append(_sample_issue("missing_hand_annotation", acceptedKeys=["handPose/handTrans/handBeta", "handJoints3D"])) + if payload.get("handBoundingBox") is not None and not _bbox_valid(np, payload["handBoundingBox"]): + issues.append(_sample_issue("invalid_hand_bounding_box", shape=_shape(np, payload["handBoundingBox"]))) + if payload.get("handVertContact") is not None: + array_shapes["handVertContact"] = _shape(np, payload["handVertContact"]) + array_dtypes["handVertContact"] = _dtype(np, payload["handVertContact"]) + if require_finite_numeric and not _finite(np, payload["handVertContact"]): + issues.append(_sample_issue("non_finite_meta_array", array="handVertContact")) + + return { + **context, + "metaPath": _relative(meta_path, root), + "rgbPath": _relative(rgb_path, root) if isinstance(rgb_path, pathlib.Path) else "", + "depthPath": _relative(depth_path, root) if isinstance(depth_path, pathlib.Path) else "", + "segmentationPath": _relative(seg_path, root) if isinstance(seg_path, pathlib.Path) else "", + "valid": not issues, + "issueCount": len(issues), + "issues": issues, + "metaKeys": meta_keys, + "objectName": obj_name, + "hasObjectPose": has_object_pose, + "hasManoHand": has_mano_hand, + "hasHandJoints3D": has_hand_joints, + "hasHandVertContact": payload.get("handVertContact") is not None, + "arrayShapes": array_shapes, + "arrayDtypes": array_dtypes, + } + + +def _asset_summary(root: pathlib.Path, meta_files: list[pathlib.Path]) -> dict[str, Any]: + sequences = sorted( + { + _sample_context(path, root)["sequenceId"] + for path in meta_files + if path.parent.name == "meta" + } + ) + return { + "datasetRoot": str(root), + "hasTrainDir": (root / "train").is_dir(), + "hasTrainingDir": (root / "training").is_dir(), + "hasEvaluationDir": (root / "evaluation").is_dir(), + "sequenceCount": len(sequences), + "metaFileCount": len(meta_files), + "sequences": sequences[:100], + } + + +def _count_by(samples: list[dict[str, Any]], key: str) -> dict[str, int]: + result: dict[str, int] = {} + for sample in samples: + value = str(sample.get(key) or "") + if value: + result[value] = result.get(value, 0) + 1 + return result + + +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("HO3D/H2O3D 数据集校验需要 SOURCE_PATH 指向真实数据根目录、split/sequence 目录或 meta/*.pkl 文件") + + max_samples = _positive_int(params, "MAX_SAMPLES", 200) + check_rgb_depth_files = _bool_param(helpers, params, "CHECK_RGB_DEPTH_FILES", True) + check_segmentation_files = _bool_param(helpers, params, "CHECK_SEGMENTATION_FILES", False) + require_object_pose = _bool_param(helpers, params, "REQUIRE_OBJECT_POSE", True) + require_hand_annotation = _bool_param(helpers, params, "REQUIRE_HAND_ANNOTATION", True) + require_finite_numeric = _bool_param(helpers, params, "REQUIRE_FINITE_NUMERIC", True) + + root = _dataset_root(source_path) + np = _require_numpy() + meta_files = _find_meta_files(source_path, max_samples) + if not meta_files: + raise RuntimeError(f"{source_path} does not contain HO3D/H2O3D meta/*.pkl annotation files") + + samples = [ + _validate_sample( + np, + meta_path, + root, + check_rgb_depth_files=check_rgb_depth_files, + check_segmentation_files=check_segmentation_files, + require_object_pose=require_object_pose, + require_hand_annotation=require_hand_annotation, + require_finite_numeric=require_finite_numeric, + ) + for meta_path in meta_files + ] + invalid_samples = [ + {"code": "invalid_sample", "metaPath": item["metaPath"], "issues": item["issues"]} + for item in samples + if not item.get("valid") + ] + payload = { + "datasetType": "ho3d-dataset-validation", + "sourcePath": str(source_path), + "valid": not invalid_samples, + "issueCount": len(invalid_samples), + "issues": invalid_samples, + "sampleCount": len(samples), + "validSampleCount": sum(1 for item in samples if item.get("valid")), + "invalidSampleCount": sum(1 for item in samples if not item.get("valid")), + "splitCounts": _count_by(samples, "split"), + "sequenceCounts": _count_by(samples, "sequenceId"), + "objectCounts": _count_by(samples, "objectName"), + "handAnnotationCounts": { + "manoHand": sum(1 for item in samples if item.get("hasManoHand")), + "handJoints3D": sum(1 for item in samples if item.get("hasHandJoints3D")), + "handVertContact": sum(1 for item in samples if item.get("hasHandVertContact")), + }, + "assets": _asset_summary(root, meta_files), + "samples": samples, + } + return [ + helpers["write_json_artifact"]( + run_id, + node_id, + output_dir, + "ho3d-dataset-validation.json", + payload, + output=helpers["output_binding"](node_data), + ) + ] diff --git a/backend/operators/builtin/ho3d_dataset_validate/repository.json b/backend/operators/builtin/ho3d_dataset_validate/repository.json new file mode 100644 index 00000000..3266cd65 --- /dev/null +++ b/backend/operators/builtin/ho3d_dataset_validate/repository.json @@ -0,0 +1,33 @@ +{ + "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": "HO3D/H2O3D 数据集校验", + "operatorId": "operator-builtin-ho3d-dataset-validate", + "operatorSlug": "ho3d_dataset_validate", + "preferredSlug": "ho3d_dataset_validate", + "pythonImport": "backend.operators.builtin.ho3d_dataset_validate.operator:run", + "repositoryId": "builtin/ho3d_dataset_validate", + "runtimeDependencies": [ + "ho3d-h2o3d-dataset-files", + "pickle", + "numpy", + "rgb-depth-image-files" + ], + "runtimeHandler": "builtin_ho3d_dataset_validate", + "runtimeSource": "backend/operators/builtin/ho3d_dataset_validate/operator.py", + "schemaVersion": "droboticflow.operator.repository/v1", + "sourceRoot": "backend/operators/builtin/ho3d_dataset_validate", + "strictPocAcceptanceExternals": [], + "type": "builtin" +} diff --git a/docs/operators/HO3D-H2O3D-数据集校验.md b/docs/operators/HO3D-H2O3D-数据集校验.md new file mode 100644 index 00000000..1643c885 --- /dev/null +++ b/docs/operators/HO3D-H2O3D-数据集校验.md @@ -0,0 +1,119 @@ +# HO3D/H2O3D 数据集校验 + +- 算子 ID:`operator-builtin-ho3d-dataset-validate` +- 类别:`ROBOTICS` +- 类型:`builtin` + +## 作用 + +读取真实 HO-3D/H2O-3D 数据根目录、split/sequence 目录或 meta/*.pkl,校验 train/evaluation 下 rgb、depth、segr、meta pickle 和手-物体 3D 姿态核心字段。 + +## 定位与职责边界 + +- 该算子属于 `ROBOTICS` 类,当前登记类型是 `builtin`。 +- 平台会在 `/api/operators` 中自动提供该算子元数据,运行时由 operator-runner 委派到独立算子入口。 + +## 平台语义 + +面向 HO-3D v2/v3 与 H2O-3D 手-物体 3D 姿态数据,真实读取 train//rgb、depth、segr、meta/.pkl 这类结构,校验 camMat、objRot、objTrans、objCorners3DRest、objName、handPose、handTrans、handBeta、handJoints3D、handBoundingBox 和可选 contact map 字段,并统计 split、sequence、object 与手部注解覆盖。 + +## 运行时契约 + +- 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/ho3d_dataset_validate/operator.py` 中的 `run(...)`,平台 runtimeHandler 为 `builtin_ho3d_dataset_validate`。 + +## 设计边界 + +- 该算子应该只承担单一职责,不应在一个节点里同时混合索引、筛选、上传、审核等多个阶段性行为。 +- 如果一个节点要消费多个语义不同的结果,优先通过多节点拆分,而不是把所有逻辑塞进一个超大脚本。 + +## 数据流示意 + +```mermaid +flowchart LR + A[上游输入或运行时注入] --> B[HO3D/H2O3D 数据集校验] + B --> C[artifact / stage manifest / 外部副作用] +``` + +## 输入端口详解 + +- `in-1` / **input** / `json` / `bus`:HO-3D/H2O-3D 数据根目录、split/sequence 目录或单个 meta/*.pkl 文件 作为输入端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 输出端口详解 + +- `out-1` / **validation** / `json` / `bus`:HO-3D/H2O-3D 目录与 meta 注解校验结果 作为输出端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。 + +## 关键超参数 + +- `SOURCE_PATH`:类型 `string`,默认值 空字符串或由工作流显式填写。HO-3D/H2O-3D 数据根目录、split/sequence 目录或单个 meta/*.pkl 文件 通常建议在工作流中显式配置。 +- `MAX_SAMPLES`:类型 `string`,默认值 `200`。最多校验多少个 meta/*.pkl 样本,必须为正整数 可直接使用默认值,也可在节点级覆盖。 +- `CHECK_RGB_DEPTH_FILES`:类型 `boolean`,默认值 `true`。是否要求每个 meta/*.pkl 对应 rgb/.jpg|png 与 depth/.png 可直接使用默认值,也可在节点级覆盖。 +- `CHECK_SEGMENTATION_FILES`:类型 `boolean`,默认值 `false`。是否要求每个样本存在 segr/.png 分割图 可直接使用默认值,也可在节点级覆盖。 +- `REQUIRE_OBJECT_POSE`:类型 `boolean`,默认值 `true`。是否要求 objRot 与 objTrans 存在且 shape 合法 可直接使用默认值,也可在节点级覆盖。 +- `REQUIRE_HAND_ANNOTATION`:类型 `boolean`,默认值 `true`。是否要求存在 MANO handPose/handTrans/handBeta 或 handJoints3D 手部注解 可直接使用默认值,也可在节点级覆盖。 +- `REQUIRE_FINITE_NUMERIC`:类型 `boolean`,默认值 `true`。是否检查 meta 数组不含 NaN/Inf 可直接使用默认值,也可在节点级覆盖。 + +## 执行前准备 + +- 先确认上下游端口类型兼容,特别是 `json`、`file`、`video` 等端口不要混接。 +- 为每个关键超参数补齐明确值,避免依赖隐式默认值进入生产工作流。 +- 对需要跨节点长期保留的产物,提前规划对象存储前缀或外部落库集合,而不是只写临时目录。 + +## 数据通信与存储路径 + +- 标准输入来自 `INPUT_ARTIFACTS_PATH` 指向的 artifact 列表文件,artifact 可同时包含 `data`、`path`、`metadata` 与 `dataRef`。 +- 标准输出写入 `OUTPUT_DIR`,并通过 `stage-manifest.json` 对外暴露产物路径、payload 引用和摘要元数据。 + +## 典型上下游编排 + +- 该算子通常位于同类数据处理节点之间,承担结构化中间层职责。 + +## 节点配置示例 + +```json +{ + "label": "HO3D/H2O3D 数据集校验", + "operatorId": "operator-builtin-ho3d-dataset-validate", + "type": "builtin", + "category": "ROBOTICS", + "hyperparams": { + "SOURCE_PATH": "<按节点填写>", + "MAX_SAMPLES": "200", + "CHECK_RGB_DEPTH_FILES": "true", + "CHECK_SEGMENTATION_FILES": "false", + "REQUIRE_OBJECT_POSE": "true", + "REQUIRE_HAND_ANNOTATION": "true", + "REQUIRE_FINITE_NUMERIC": "true" + } +} +``` + +## 输入输出示例 + +- 典型输入: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 868c5a4e..c6ffacb4 100644 --- a/docs/operators/README.md +++ b/docs/operators/README.md @@ -2,7 +2,7 @@ 当前目录按“每个内建算子一份 Markdown”组织,内容基于当前平台真实算子定义按算子名称去重生成。 -- 当前收录数量:`83` +- 当前收录数量:`84` - 文档定位:单算子详细手册,重点覆盖输入输出契约、运行时路径、配置示例、排障与验收。 - 配套总览:[`../builtin-operators-manual.zh-CN.md`](../builtin-operators-manual.zh-CN.md) @@ -77,6 +77,7 @@ - [Episode 边界校验](Episode-边界校验.md) - [FurnitureBench PKL示教校验](FurnitureBench-PKL示教校验.md) - [HDF5 示教数据概览](HDF5-示教数据概览.md) +- [HO3D/H2O3D 数据集校验](HO3D-H2O3D-数据集校验.md) - [LIBERO HDF5任务校验](LIBERO-HDF5任务校验.md) - [LeRobot v3 Episode索引校验](LeRobot-v3-Episode索引校验.md) - [LeRobot 元数据一致性校验](LeRobot-元数据一致性校验.md) diff --git a/internal/api/builtin_operators_catalog.json b/internal/api/builtin_operators_catalog.json index 2e40d882..e0484fc6 100644 --- a/internal/api/builtin_operators_catalog.json +++ b/internal/api/builtin_operators_catalog.json @@ -3680,6 +3680,78 @@ "runtimeSource": "backend/operators/builtin/dexycb_dataset_validate/operator.py", "runtimeHandler": "builtin_dexycb_dataset_validate" }, + { + "id": "operator-builtin-ho3d-dataset-validate", + "name": "HO3D/H2O3D 数据集校验", + "type": "builtin", + "category": "ROBOTICS", + "description": "读取真实 HO-3D/H2O-3D 数据根目录、split/sequence 目录或 meta/*.pkl,校验 train/evaluation 下 rgb、depth、segr、meta pickle 和手-物体 3D 姿态核心字段。", + "inputs": [ + { + "id": "in-1", + "name": "input", + "type": "json", + "description": "HO-3D/H2O-3D 数据根目录、split/sequence 目录或单个 meta/*.pkl 文件", + "transmission": "bus" + } + ], + "outputs": [ + { + "id": "out-1", + "name": "validation", + "type": "json", + "description": "HO-3D/H2O-3D 目录与 meta 注解校验结果", + "transmission": "bus" + } + ], + "skillDefinition": "面向 HO-3D v2/v3 与 H2O-3D 手-物体 3D 姿态数据,真实读取 train//rgb、depth、segr、meta/.pkl 这类结构,校验 camMat、objRot、objTrans、objCorners3DRest、objName、handPose、handTrans、handBeta、handJoints3D、handBoundingBox 和可选 contact map 字段,并统计 split、sequence、object 与手部注解覆盖。", + "hyperparams": [ + { + "key": "SOURCE_PATH", + "value": "", + "description": "HO-3D/H2O-3D 数据根目录、split/sequence 目录或单个 meta/*.pkl 文件", + "type": "string" + }, + { + "key": "MAX_SAMPLES", + "value": "200", + "description": "最多校验多少个 meta/*.pkl 样本,必须为正整数", + "type": "string" + }, + { + "key": "CHECK_RGB_DEPTH_FILES", + "value": "true", + "description": "是否要求每个 meta/*.pkl 对应 rgb/.jpg|png 与 depth/.png", + "type": "boolean" + }, + { + "key": "CHECK_SEGMENTATION_FILES", + "value": "false", + "description": "是否要求每个样本存在 segr/.png 分割图", + "type": "boolean" + }, + { + "key": "REQUIRE_OBJECT_POSE", + "value": "true", + "description": "是否要求 objRot 与 objTrans 存在且 shape 合法", + "type": "boolean" + }, + { + "key": "REQUIRE_HAND_ANNOTATION", + "value": "true", + "description": "是否要求存在 MANO handPose/handTrans/handBeta 或 handJoints3D 手部注解", + "type": "boolean" + }, + { + "key": "REQUIRE_FINITE_NUMERIC", + "value": "true", + "description": "是否检查 meta 数组不含 NaN/Inf", + "type": "boolean" + } + ], + "runtimeSource": "backend/operators/builtin/ho3d_dataset_validate/operator.py", + "runtimeHandler": "builtin_ho3d_dataset_validate" + }, { "id": "operator-builtin-hand-object-pose-validate", "name": "手-物体姿态标注校验", diff --git a/scripts/generate_operator_repository_manifests.py b/scripts/generate_operator_repository_manifests.py index aad1163f..7394b4da 100644 --- a/scripts/generate_operator_repository_manifests.py +++ b/scripts/generate_operator_repository_manifests.py @@ -40,6 +40,7 @@ RUNTIME_DEPENDENCIES: dict[str, list[str]] = { "hdf5_demonstration_summary": ["hdf5-files", "h5py"], "hf_dataset_probe": ["huggingface-dataset-viewer-api"], "hand_object_pose_validate": ["json-jsonl-csv-parquet-files", "image-files", "mask-files", "pyarrow"], + "ho3d_dataset_validate": ["ho3d-h2o3d-dataset-files", "pickle", "numpy", "rgb-depth-image-files"], "human_review": ["json-artifacts"], "json_field_extract": ["json-artifacts"], "json_filter": ["json-artifacts"],