forked from longtao.wu/droboticflow
✨ Add RoboMIND HDF5 quality validator
This commit is contained in:
parent
90766aacb2
commit
82c78f0a5d
@ -80,6 +80,7 @@ from backend.operators.builtin.pointcloud_summary import operator as pointcloud_
|
||||
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.rh20t_scene_validate import operator as rh20t_scene_validate_operator
|
||||
from backend.operators.builtin.robomind_hdf5_quality_validate import operator as robomind_hdf5_quality_validate_operator
|
||||
from backend.operators.builtin.robomimic_hdf5_validate import operator as robomimic_hdf5_validate_operator
|
||||
from backend.operators.builtin.robocasa_hdf5_demonstration_validate import operator as robocasa_hdf5_demonstration_validate_operator
|
||||
from backend.operators.builtin.robot_model_asset_validate import operator as robot_model_asset_validate_operator
|
||||
@ -4971,6 +4972,7 @@ BUILTIN_HANDLER_RULES: tuple[tuple[str, tuple[str, ...]], ...] = (
|
||||
("libero_hdf5_task_validate", ("libero hdf5", "libero 任务", "libero 数据集", "libero benchmark")),
|
||||
("robocasa_hdf5_demonstration_validate", ("robocasa hdf5", "robocasa 示教", "robocasa 数据集", "robocasa demonstration")),
|
||||
("rh20t_scene_validate", ("rh20t", "rh20t 场景", "rh20t scene", "real human 20t")),
|
||||
("robomind_hdf5_quality_validate", ("robomind hdf5", "robomind 质量", "robomind 数据", "multi-embodiment intelligence")),
|
||||
("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")),
|
||||
@ -5067,6 +5069,7 @@ BUILTIN_HANDLERS: dict[str, BuiltinHandler] = {
|
||||
"robomimic_hdf5_validate": operator_handler(robomimic_hdf5_validate_operator),
|
||||
"robocasa_hdf5_demonstration_validate": operator_handler(robocasa_hdf5_demonstration_validate_operator),
|
||||
"rh20t_scene_validate": operator_handler(rh20t_scene_validate_operator),
|
||||
"robomind_hdf5_quality_validate": operator_handler(robomind_hdf5_quality_validate_operator),
|
||||
"vla_sample_manifest_validate": operator_handler(vla_sample_manifest_validate_operator),
|
||||
"rlbench_dataset_validate": operator_handler(rlbench_dataset_validate_operator),
|
||||
"maniskill_trajectory_validate": operator_handler(maniskill_trajectory_validate_operator),
|
||||
|
||||
@ -279,6 +279,7 @@ class RuntimeFileContractTests(unittest.TestCase):
|
||||
self.assertEqual(MODULE.select_handler("LIBERO HDF5任务校验"), "libero_hdf5_task_validate")
|
||||
self.assertEqual(MODULE.select_handler("RoboCasa HDF5示教校验"), "robocasa_hdf5_demonstration_validate")
|
||||
self.assertEqual(MODULE.select_handler("RH20T 场景结构校验"), "rh20t_scene_validate")
|
||||
self.assertEqual(MODULE.select_handler("RoboMIND HDF5质量校验"), "robomind_hdf5_quality_validate")
|
||||
self.assertEqual(MODULE.select_handler("LeRobot v3 Episode索引校验"), "lerobot_v3_episode_index_validate")
|
||||
self.assertEqual(MODULE.select_handler("数据集切分泄漏校验"), "dataset_split_leakage_validate")
|
||||
self.assertEqual(MODULE.select_handler("媒体引用可读性校验"), "media_reference_validate")
|
||||
@ -3154,6 +3155,87 @@ class EmbodiedDatasetOperatorTests(unittest.TestCase):
|
||||
self.assertTrue(scene_payload["highFreq"]["present"])
|
||||
self.assertIn("intrinsics.npy", scene_payload["calibration"]["files"])
|
||||
|
||||
def test_robomind_hdf5_quality_validate_reads_real_hdf5_joint_position_and_end_effector(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:
|
||||
root = pathlib.Path(temp_dir) / "robomind" / "benchmark1_0"
|
||||
data_dir = root / "h5_franka_1rgb" / "bread_in_basket" / "success_episodes" / "train" / "1014_144602" / "data"
|
||||
data_dir.mkdir(parents=True)
|
||||
path = data_dir / "trajectory.hdf5"
|
||||
with h5py.File(path, "w") as handle:
|
||||
puppet = handle.create_group("puppet")
|
||||
puppet.create_dataset(
|
||||
"joint_position",
|
||||
data=np.array(
|
||||
[
|
||||
[0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6],
|
||||
[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7],
|
||||
[0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
|
||||
],
|
||||
dtype=np.float32,
|
||||
),
|
||||
)
|
||||
puppet.create_dataset(
|
||||
"end_effector",
|
||||
data=np.array(
|
||||
[
|
||||
[0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
|
||||
[0.1, 0.0, 0.0, 0.0, 0.0, 0.1],
|
||||
[0.2, 0.0, 0.0, 0.0, 0.0, 0.2],
|
||||
],
|
||||
dtype=np.float32,
|
||||
),
|
||||
)
|
||||
master = handle.create_group("master")
|
||||
master.create_dataset(
|
||||
"joint_position",
|
||||
data=np.array(
|
||||
[
|
||||
[1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6],
|
||||
[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7],
|
||||
[1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8],
|
||||
],
|
||||
dtype=np.float32,
|
||||
),
|
||||
)
|
||||
rgb_images = handle.create_group("rgb_images")
|
||||
rgb_images.create_dataset("front", data=np.zeros((3, 4, 4, 3), dtype=np.uint8))
|
||||
handle.create_dataset("action", data=np.ones((3, 7), dtype=np.float32))
|
||||
node_data = {
|
||||
"label": "RoboMIND HDF5质量校验",
|
||||
"hyperparams": [{"key": "SOURCE_PATH", "value": str(root)}],
|
||||
}
|
||||
|
||||
artifacts = MODULE.BUILTIN_HANDLERS["robomind_hdf5_quality_validate"](
|
||||
"run-1", "robomind", root / "out", node_data, []
|
||||
)
|
||||
|
||||
payload = MODULE.load_artifact_payload(artifacts[0])
|
||||
self.assertEqual(payload["datasetType"], "robomind-hdf5-quality-validation")
|
||||
self.assertTrue(payload["valid"])
|
||||
self.assertEqual(payload["fileCount"], 1)
|
||||
self.assertEqual(payload["trajectoryCount"], 1)
|
||||
self.assertEqual(payload["validFileCount"], 1)
|
||||
self.assertEqual(payload["jointPositionFileCount"], 1)
|
||||
self.assertEqual(payload["endEffectorFileCount"], 1)
|
||||
self.assertEqual(payload["stuckJointPositionCount"], 0)
|
||||
self.assertEqual(payload["stuckEndEffectorCount"], 0)
|
||||
self.assertEqual(payload["imageDatasetCount"], 1)
|
||||
file_payload = payload["files"][0]
|
||||
self.assertEqual(file_payload["benchmark"], "benchmark1_0")
|
||||
self.assertEqual(file_payload["robotType"], "h5_franka_1rgb")
|
||||
self.assertEqual(file_payload["taskName"], "bread_in_basket")
|
||||
self.assertEqual(file_payload["split"], "train")
|
||||
self.assertEqual(file_payload["episodeId"], "1014_144602")
|
||||
self.assertEqual(file_payload["frameCount"], 3)
|
||||
self.assertEqual(file_payload["puppetJointPosition"]["key"], "puppet/joint_position")
|
||||
self.assertEqual(file_payload["puppetJointPosition"]["shape"], [3, 7])
|
||||
self.assertEqual(file_payload["puppetEndEffector"]["key"], "puppet/end_effector")
|
||||
|
||||
def test_hdf5_demonstration_summary_reads_real_hdf5_file(self):
|
||||
try:
|
||||
import h5py # type: ignore
|
||||
|
||||
@ -0,0 +1 @@
|
||||
|
||||
@ -0,0 +1,16 @@
|
||||
{
|
||||
"id": "operator-builtin-robomind-hdf5-quality-validate",
|
||||
"name": "RoboMIND HDF5质量校验",
|
||||
"category": "ROBOTICS",
|
||||
"type": "builtin",
|
||||
"runtimeHandler": "builtin_robomind_hdf5_quality_validate",
|
||||
"runtimeSource": "backend/operators/builtin/robomind_hdf5_quality_validate/operator.py",
|
||||
"migrationStatus": "migrated",
|
||||
"acceptance": {
|
||||
"requiresRealInputs": true,
|
||||
"mockOnlyAccepted": false,
|
||||
"simulationOnlyAccepted": false,
|
||||
"hardcodedOutputAccepted": false,
|
||||
"shallowOnlyAccepted": false
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,412 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
import pathlib
|
||||
from typing import Any, Callable
|
||||
|
||||
|
||||
HelperMap = dict[str, Callable[..., Any]]
|
||||
HDF5_SUFFIXES = {".h5", ".hdf5"}
|
||||
PUPPET_EE_CANDIDATES = (
|
||||
"puppet/end_effector",
|
||||
"puppet/end_effector_left",
|
||||
"franka/end_effector",
|
||||
)
|
||||
PUPPET_JOINT_CANDIDATES = (
|
||||
"puppet/joint_position",
|
||||
"puppet/joint_position_left",
|
||||
"franka/joint_position",
|
||||
)
|
||||
MASTER_JOINT_CANDIDATES = (
|
||||
"master/joint_position",
|
||||
"master/joint_position_left",
|
||||
)
|
||||
IMAGE_KEY_TOKENS = ("rgb", "image", "camera")
|
||||
ACTION_KEY_TOKENS = ("action", "gripper", "command")
|
||||
|
||||
|
||||
def _require_h5py():
|
||||
try:
|
||||
import h5py # type: ignore
|
||||
except Exception as exc: # pragma: no cover - runtime dependency check
|
||||
raise RuntimeError("RoboMIND HDF5质量校验需要 h5py 读取真实 trajectory.hdf5 文件") from exc
|
||||
return h5py
|
||||
|
||||
|
||||
def _require_numpy():
|
||||
try:
|
||||
import numpy as np # type: ignore
|
||||
except Exception as exc: # pragma: no cover - runtime dependency check
|
||||
raise RuntimeError("RoboMIND HDF5质量校验需要 numpy 计算关节和末端执行器质量指标") 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 _positive_float(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(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 _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_SUFFIXES else []
|
||||
files = [item for item in sorted(source_path.rglob("*")) if item.is_file() and item.suffix.lower() in HDF5_SUFFIXES]
|
||||
files.sort(key=lambda path: (0 if path.name == "trajectory.hdf5" else 1, path.as_posix()))
|
||||
return files[:max_files]
|
||||
|
||||
|
||||
def _parse_robomind_path(path: pathlib.Path, root: pathlib.Path) -> dict[str, str]:
|
||||
parts = pathlib.PurePosixPath(_relative(path, root)).parts
|
||||
robot_index = next((idx for idx, part in enumerate(parts) if part.startswith("h5_")), -1)
|
||||
benchmark = parts[robot_index - 1] if robot_index > 0 and parts[robot_index - 1].startswith("benchmark") else ""
|
||||
if not benchmark and robot_index == 0 and root.name.startswith("benchmark"):
|
||||
benchmark = root.name
|
||||
robot_type = parts[robot_index] if robot_index >= 0 else ""
|
||||
task_name = parts[robot_index + 1] if robot_index >= 0 and len(parts) > robot_index + 1 else ""
|
||||
split = ""
|
||||
episode_id = ""
|
||||
if "success_episodes" in parts:
|
||||
success_index = parts.index("success_episodes")
|
||||
split = parts[success_index + 1] if len(parts) > success_index + 1 else ""
|
||||
episode_id = parts[success_index + 2] if len(parts) > success_index + 2 else ""
|
||||
elif path.parent.name == "data":
|
||||
episode_id = path.parent.parent.name
|
||||
return {
|
||||
"benchmark": benchmark,
|
||||
"robotType": robot_type,
|
||||
"taskName": task_name,
|
||||
"split": split,
|
||||
"episodeId": episode_id,
|
||||
}
|
||||
|
||||
|
||||
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_at(handle: Any, candidates: tuple[str, ...]) -> tuple[str, Any | None]:
|
||||
for candidate in candidates:
|
||||
if candidate in handle and hasattr(handle[candidate], "shape") and hasattr(handle[candidate], "dtype"):
|
||||
return candidate, handle[candidate]
|
||||
return "", None
|
||||
|
||||
|
||||
def _dataset_shape(dataset: Any | None) -> list[int]:
|
||||
if dataset is None or not hasattr(dataset, "shape"):
|
||||
return []
|
||||
return [int(item) for item in dataset.shape]
|
||||
|
||||
|
||||
def _frame_count(dataset: Any | None) -> int:
|
||||
shape = _dataset_shape(dataset)
|
||||
return int(shape[0]) if shape else 0
|
||||
|
||||
|
||||
def _sample_dataset(np: Any, dataset: Any, max_rows: int) -> Any:
|
||||
shape = _dataset_shape(dataset)
|
||||
if not shape:
|
||||
return dataset[()]
|
||||
frame_count = int(shape[0])
|
||||
if frame_count <= max_rows:
|
||||
return dataset[()]
|
||||
indices = np.unique(np.linspace(0, frame_count - 1, num=max_rows, dtype=np.int64))
|
||||
return dataset[indices, ...]
|
||||
|
||||
|
||||
def _array_quality(np: Any, key: str, dataset: Any | None, tolerance: float, max_rows: int) -> dict[str, Any]:
|
||||
if dataset is None:
|
||||
return {
|
||||
"key": "",
|
||||
"exists": False,
|
||||
"shape": [],
|
||||
"dtype": "",
|
||||
"frameCount": 0,
|
||||
"sampleFrameCount": 0,
|
||||
"finiteNumeric": True,
|
||||
"maxRange": 0.0,
|
||||
"rangePerDim": [],
|
||||
"isStuck": False,
|
||||
"uniqueCount": 0,
|
||||
"uniqueRatio": 0.0,
|
||||
}
|
||||
shape = _dataset_shape(dataset)
|
||||
frame_count = int(shape[0]) if shape else 1
|
||||
dtype = str(getattr(dataset, "dtype", ""))
|
||||
if not np.issubdtype(dataset.dtype, np.number):
|
||||
return {
|
||||
"key": key,
|
||||
"exists": True,
|
||||
"shape": shape,
|
||||
"dtype": dtype,
|
||||
"frameCount": frame_count,
|
||||
"sampleFrameCount": 0,
|
||||
"finiteNumeric": True,
|
||||
"maxRange": 0.0,
|
||||
"rangePerDim": [],
|
||||
"isStuck": False,
|
||||
"uniqueCount": 0,
|
||||
"uniqueRatio": 0.0,
|
||||
}
|
||||
|
||||
values = np.asarray(_sample_dataset(np, dataset, max_rows))
|
||||
if values.ndim == 0:
|
||||
rows = values.reshape(1, 1)
|
||||
elif values.ndim == 1:
|
||||
rows = values.reshape(values.shape[0], 1)
|
||||
else:
|
||||
rows = values.reshape(values.shape[0], -1)
|
||||
finite_numeric = bool(np.isfinite(rows).all())
|
||||
if rows.size and finite_numeric:
|
||||
range_per_dim = (np.max(rows, axis=0) - np.min(rows, axis=0)).astype(float)
|
||||
max_range = float(np.max(range_per_dim)) if range_per_dim.size else 0.0
|
||||
range_values = [float(item) for item in range_per_dim[:64].tolist()]
|
||||
else:
|
||||
max_range = 0.0
|
||||
range_values = []
|
||||
unique_count = 0
|
||||
unique_ratio = 0.0
|
||||
if rows.size:
|
||||
try:
|
||||
unique_count = int(np.unique(rows, axis=0).shape[0])
|
||||
except Exception:
|
||||
unique_count = int(len({tuple(row.tolist()) for row in rows}))
|
||||
unique_ratio = float(unique_count / max(1, int(rows.shape[0])))
|
||||
return {
|
||||
"key": key,
|
||||
"exists": True,
|
||||
"shape": shape,
|
||||
"dtype": dtype,
|
||||
"frameCount": frame_count,
|
||||
"sampleFrameCount": int(rows.shape[0]) if rows.ndim else 1,
|
||||
"finiteNumeric": finite_numeric,
|
||||
"maxRange": max_range,
|
||||
"rangePerDim": range_values,
|
||||
"isStuck": bool(frame_count > 1 and finite_numeric and max_range < tolerance),
|
||||
"uniqueCount": unique_count,
|
||||
"uniqueRatio": unique_ratio,
|
||||
}
|
||||
|
||||
|
||||
def _dataset_name_matches(path: str, tokens: tuple[str, ...]) -> bool:
|
||||
lowered = path.lower()
|
||||
return any(token in lowered for token in tokens)
|
||||
|
||||
|
||||
def _summarize_file(
|
||||
path: pathlib.Path,
|
||||
root: pathlib.Path,
|
||||
*,
|
||||
max_rows: int,
|
||||
ee_tolerance: float,
|
||||
joint_tolerance: float,
|
||||
require_joint_position: bool,
|
||||
require_end_effector: bool,
|
||||
require_images: bool,
|
||||
) -> dict[str, Any]:
|
||||
h5py = _require_h5py()
|
||||
np = _require_numpy()
|
||||
base_payload: dict[str, Any] = {
|
||||
"path": _relative(path, root),
|
||||
"fileName": path.name,
|
||||
"fileSizeBytes": path.stat().st_size,
|
||||
**_parse_robomind_path(path, root),
|
||||
}
|
||||
issues: list[dict[str, Any]] = []
|
||||
try:
|
||||
with h5py.File(path, "r") as handle:
|
||||
datasets = _iter_dataset_paths(handle)
|
||||
if not datasets:
|
||||
issues.append({"code": "missing_hdf5_datasets"})
|
||||
image_datasets = [dataset_path for dataset_path, _ in datasets if _dataset_name_matches(dataset_path, IMAGE_KEY_TOKENS)]
|
||||
action_datasets = [dataset_path for dataset_path, _ in datasets if _dataset_name_matches(dataset_path, ACTION_KEY_TOKENS)]
|
||||
puppet_ee_key, puppet_ee_dataset = _dataset_at(handle, PUPPET_EE_CANDIDATES)
|
||||
puppet_joint_key, puppet_joint_dataset = _dataset_at(handle, PUPPET_JOINT_CANDIDATES)
|
||||
master_joint_key, master_joint_dataset = _dataset_at(handle, MASTER_JOINT_CANDIDATES)
|
||||
puppet_ee = _array_quality(np, puppet_ee_key, puppet_ee_dataset, ee_tolerance, max_rows)
|
||||
puppet_joint = _array_quality(np, puppet_joint_key, puppet_joint_dataset, joint_tolerance, max_rows)
|
||||
master_joint = _array_quality(np, master_joint_key, master_joint_dataset, joint_tolerance, max_rows)
|
||||
frame_candidates = [
|
||||
_frame_count(puppet_ee_dataset),
|
||||
_frame_count(puppet_joint_dataset),
|
||||
_frame_count(master_joint_dataset),
|
||||
]
|
||||
for dataset_path, dataset in datasets:
|
||||
if _dataset_name_matches(dataset_path, IMAGE_KEY_TOKENS + ACTION_KEY_TOKENS):
|
||||
frame_candidates.append(_frame_count(dataset))
|
||||
frame_count = max(frame_candidates or [0])
|
||||
if require_joint_position and not puppet_joint["exists"]:
|
||||
issues.append({"code": "missing_puppet_joint_position", "candidates": list(PUPPET_JOINT_CANDIDATES)})
|
||||
if require_end_effector and not puppet_ee["exists"]:
|
||||
issues.append({"code": "missing_puppet_end_effector", "candidates": list(PUPPET_EE_CANDIDATES)})
|
||||
if require_images and not image_datasets:
|
||||
issues.append({"code": "missing_image_datasets"})
|
||||
for label, quality in (
|
||||
("puppet_end_effector", puppet_ee),
|
||||
("puppet_joint_position", puppet_joint),
|
||||
("master_joint_position", master_joint),
|
||||
):
|
||||
if not quality["exists"]:
|
||||
continue
|
||||
if not quality["finiteNumeric"]:
|
||||
issues.append({"code": "non_finite_numeric_values", "dataset": quality["key"], "field": label})
|
||||
if quality["isStuck"]:
|
||||
issues.append(
|
||||
{
|
||||
"code": "stuck_numeric_values",
|
||||
"dataset": quality["key"],
|
||||
"field": label,
|
||||
"maxRange": quality["maxRange"],
|
||||
}
|
||||
)
|
||||
if frame_count <= 1:
|
||||
issues.append({"code": "insufficient_frame_count", "frameCount": frame_count})
|
||||
return {
|
||||
**base_payload,
|
||||
"valid": not issues,
|
||||
"issueCount": len(issues),
|
||||
"issues": issues,
|
||||
"frameCount": frame_count,
|
||||
"datasetCount": len(datasets),
|
||||
"imageDatasetCount": len(image_datasets),
|
||||
"imageDatasets": image_datasets[:50],
|
||||
"actionDatasetCount": len(action_datasets),
|
||||
"actionDatasets": action_datasets[:50],
|
||||
"puppetEndEffector": puppet_ee,
|
||||
"puppetJointPosition": puppet_joint,
|
||||
"masterJointPosition": master_joint,
|
||||
}
|
||||
except Exception as exc:
|
||||
issues.append({"code": "unreadable_hdf5_file", "error": str(exc)})
|
||||
return {
|
||||
**base_payload,
|
||||
"valid": False,
|
||||
"issueCount": len(issues),
|
||||
"issues": issues,
|
||||
"frameCount": 0,
|
||||
"datasetCount": 0,
|
||||
"imageDatasetCount": 0,
|
||||
"imageDatasets": [],
|
||||
"actionDatasetCount": 0,
|
||||
"actionDatasets": [],
|
||||
"puppetEndEffector": _array_quality(_require_numpy(), "", None, ee_tolerance, max_rows),
|
||||
"puppetJointPosition": _array_quality(_require_numpy(), "", None, joint_tolerance, max_rows),
|
||||
"masterJointPosition": _array_quality(_require_numpy(), "", None, joint_tolerance, max_rows),
|
||||
}
|
||||
|
||||
|
||||
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("RoboMIND HDF5质量校验需要 SOURCE_PATH 指向真实 RoboMIND trajectory.hdf5 文件或目录")
|
||||
if not source_path.exists():
|
||||
raise RuntimeError(f"{source_path} does not exist")
|
||||
max_files = _positive_int(params, "MAX_FILES", 100)
|
||||
max_rows = _positive_int(params, "MAX_ROWS", 200000)
|
||||
ee_tolerance = _positive_float(params, "EE_TOLERANCE", 0.001)
|
||||
joint_tolerance = _positive_float(params, "JOINT_TOLERANCE", 0.001)
|
||||
require_joint_position = _bool_param(helpers, params, "REQUIRE_JOINT_POSITION", True)
|
||||
require_end_effector = _bool_param(helpers, params, "REQUIRE_END_EFFECTOR", False)
|
||||
require_images = _bool_param(helpers, params, "REQUIRE_IMAGES", False)
|
||||
files = _find_hdf5_files(source_path, max_files)
|
||||
if not files:
|
||||
raise RuntimeError(f"{source_path} does not contain RoboMIND .hdf5/.h5 files")
|
||||
root = source_path.parent if source_path.is_file() else source_path
|
||||
file_payloads = [
|
||||
_summarize_file(
|
||||
path,
|
||||
root,
|
||||
max_rows=max_rows,
|
||||
ee_tolerance=ee_tolerance,
|
||||
joint_tolerance=joint_tolerance,
|
||||
require_joint_position=require_joint_position,
|
||||
require_end_effector=require_end_effector,
|
||||
require_images=require_images,
|
||||
)
|
||||
for path in files
|
||||
]
|
||||
invalid = [item for item in file_payloads if not item["valid"]]
|
||||
issues: list[dict[str, Any]] = []
|
||||
if invalid:
|
||||
issues.append({"code": "invalid_robomind_trajectories", "count": len(invalid), "examples": invalid[:20]})
|
||||
payload = {
|
||||
"datasetType": "robomind-hdf5-quality-validation",
|
||||
"sourcePath": str(source_path),
|
||||
"valid": not issues,
|
||||
"issueCount": len(issues),
|
||||
"issues": issues,
|
||||
"fileCount": len(file_payloads),
|
||||
"trajectoryCount": len(file_payloads),
|
||||
"validFileCount": len(file_payloads) - len(invalid),
|
||||
"invalidFileCount": len(invalid),
|
||||
"frameCount": sum(int(item["frameCount"]) for item in file_payloads),
|
||||
"jointPositionFileCount": sum(
|
||||
1
|
||||
for item in file_payloads
|
||||
if item["puppetJointPosition"]["exists"] or item["masterJointPosition"]["exists"]
|
||||
),
|
||||
"endEffectorFileCount": sum(1 for item in file_payloads if item["puppetEndEffector"]["exists"]),
|
||||
"stuckJointPositionCount": sum(
|
||||
1
|
||||
for item in file_payloads
|
||||
if item["puppetJointPosition"]["isStuck"] or item["masterJointPosition"]["isStuck"]
|
||||
),
|
||||
"stuckEndEffectorCount": sum(1 for item in file_payloads if item["puppetEndEffector"]["isStuck"]),
|
||||
"imageDatasetCount": sum(int(item["imageDatasetCount"]) for item in file_payloads),
|
||||
"actionDatasetCount": sum(int(item["actionDatasetCount"]) for item in file_payloads),
|
||||
"files": file_payloads,
|
||||
}
|
||||
return [
|
||||
helpers["write_json_artifact"](
|
||||
run_id,
|
||||
node_id,
|
||||
output_dir,
|
||||
"robomind-hdf5-quality-validation.json",
|
||||
payload,
|
||||
output=helpers["output_binding"](node_data),
|
||||
)
|
||||
]
|
||||
@ -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": "RoboMIND HDF5质量校验",
|
||||
"operatorId": "operator-builtin-robomind-hdf5-quality-validate",
|
||||
"operatorSlug": "robomind_hdf5_quality_validate",
|
||||
"preferredSlug": "robomind_hdf5_quality_validate",
|
||||
"pythonImport": "backend.operators.builtin.robomind_hdf5_quality_validate.operator:run",
|
||||
"repositoryId": "builtin/robomind_hdf5_quality_validate",
|
||||
"runtimeDependencies": [
|
||||
"robomind-trajectory-hdf5-files",
|
||||
"h5py",
|
||||
"numpy"
|
||||
],
|
||||
"runtimeHandler": "builtin_robomind_hdf5_quality_validate",
|
||||
"runtimeSource": "backend/operators/builtin/robomind_hdf5_quality_validate/operator.py",
|
||||
"schemaVersion": "droboticflow.operator.repository/v1",
|
||||
"sourceRoot": "backend/operators/builtin/robomind_hdf5_quality_validate",
|
||||
"strictPocAcceptanceExternals": [],
|
||||
"type": "builtin"
|
||||
}
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
当前目录按“每个内建算子一份 Markdown”组织,内容基于当前平台真实算子定义按算子名称去重生成。
|
||||
|
||||
- 当前收录数量:`77`
|
||||
- 当前收录数量:`78`
|
||||
- 文档定位:单算子详细手册,重点覆盖输入输出契约、运行时路径、配置示例、排障与验收。
|
||||
- 配套总览:[`../builtin-operators-manual.zh-CN.md`](../builtin-operators-manual.zh-CN.md)
|
||||
|
||||
@ -92,6 +92,7 @@
|
||||
- [ROSBag 数据概览](ROSBag-数据概览.md)
|
||||
- [RT-X动作空间Schema校验](RT-X动作空间Schema校验.md)
|
||||
- [RoboCasa HDF5示教校验](RoboCasa-HDF5示教校验.md)
|
||||
- [RoboMIND HDF5质量校验](RoboMIND-HDF5质量校验.md)
|
||||
- [TF 坐标树校验](TF-坐标树校验.md)
|
||||
- [TFRecord 结构校验](TFRecord-结构校验.md)
|
||||
- [URDF 关节限位校验](URDF-关节限位校验.md)
|
||||
|
||||
121
docs/operators/RoboMIND-HDF5质量校验.md
Normal file
121
docs/operators/RoboMIND-HDF5质量校验.md
Normal file
@ -0,0 +1,121 @@
|
||||
# RoboMIND HDF5质量校验
|
||||
|
||||
- 算子 ID:`operator-builtin-robomind-hdf5-quality-validate`
|
||||
- 类别:`ROBOTICS`
|
||||
- 类型:`builtin`
|
||||
|
||||
## 作用
|
||||
|
||||
读取真实 RoboMIND trajectory.hdf5,校验 puppet/master joint_position、puppet/end_effector 卡死、非有限值、帧数和多模态字段。
|
||||
|
||||
## 定位与职责边界
|
||||
|
||||
- 该算子属于 `ROBOTICS` 类,当前登记类型是 `builtin`。
|
||||
- 平台会在 `/api/operators` 中自动提供该算子元数据,运行时由 operator-runner 委派到独立算子入口。
|
||||
|
||||
## 平台语义
|
||||
|
||||
面向 RoboMIND、Multi-embodiment Intelligence、真实遥操作 VLA 训练数据,读取 h5_franka_1rgb/h5_franka_3rgb/h5_ur_1rgb/h5_agilex_3rgb/h5_tienkung 等目录下的 trajectory.hdf5,解析 robot/task/split/episode 元信息,检查 puppet/end_effector、puppet/joint_position、master/joint_position、franka/* 候选字段的 shape、finite 数值、unique ratio 和卡死状态,并统计 RGB/image/camera 与 action/gripper/command 数据集。
|
||||
|
||||
## 运行时契约
|
||||
|
||||
- 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/robomind_hdf5_quality_validate/operator.py` 中的 `run(...)`,平台 runtimeHandler 为 `builtin_robomind_hdf5_quality_validate`。
|
||||
|
||||
## 设计边界
|
||||
|
||||
- 该算子应该只承担单一职责,不应在一个节点里同时混合索引、筛选、上传、审核等多个阶段性行为。
|
||||
- 如果一个节点要消费多个语义不同的结果,优先通过多节点拆分,而不是把所有逻辑塞进一个超大脚本。
|
||||
|
||||
## 数据流示意
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[上游输入或运行时注入] --> B[RoboMIND HDF5质量校验]
|
||||
B --> C[artifact / stage manifest / 外部副作用]
|
||||
```
|
||||
|
||||
## 输入端口详解
|
||||
|
||||
- `in-1` / **input** / `json` / `bus`:RoboMIND trajectory.hdf5 文件或包含 h5_* 轨迹目录的根目录 作为输入端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。
|
||||
|
||||
## 输出端口详解
|
||||
|
||||
- `out-1` / **validation** / `json` / `bus`:RoboMIND HDF5 轨迹质量校验结果 作为输出端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。
|
||||
|
||||
## 关键超参数
|
||||
|
||||
- `SOURCE_PATH`:类型 `string`,默认值 空字符串或由工作流显式填写。RoboMIND trajectory.hdf5 文件、data 目录或包含 benchmark/h5_* 的根目录 通常建议在工作流中显式配置。
|
||||
- `MAX_FILES`:类型 `string`,默认值 `100`。最多校验多少个 .hdf5/.h5 轨迹文件,优先读取 trajectory.hdf5 可直接使用默认值,也可在节点级覆盖。
|
||||
- `MAX_ROWS`:类型 `string`,默认值 `200000`。每个数值数组最多采样多少帧用于 range 和 unique ratio 计算 可直接使用默认值,也可在节点级覆盖。
|
||||
- `EE_TOLERANCE`:类型 `string`,默认值 `0.001`。末端执行器数据 max(range_per_dim) 小于该阈值时判定卡死 可直接使用默认值,也可在节点级覆盖。
|
||||
- `JOINT_TOLERANCE`:类型 `string`,默认值 `0.001`。关节数据 max(range_per_dim) 小于该阈值时判定卡死 可直接使用默认值,也可在节点级覆盖。
|
||||
- `REQUIRE_JOINT_POSITION`:类型 `boolean`,默认值 `true`。是否要求存在 puppet/joint_position、puppet/joint_position_left 或 franka/joint_position 可直接使用默认值,也可在节点级覆盖。
|
||||
- `REQUIRE_END_EFFECTOR`:类型 `boolean`,默认值 `false`。是否要求存在 puppet/end_effector、puppet/end_effector_left 或 franka/end_effector;默认仅在存在时检查质量 可直接使用默认值,也可在节点级覆盖。
|
||||
- `REQUIRE_IMAGES`:类型 `boolean`,默认值 `false`。是否要求 HDF5 中存在 rgb/image/camera 相关观测数据集 可直接使用默认值,也可在节点级覆盖。
|
||||
|
||||
## 执行前准备
|
||||
|
||||
- 先确认上下游端口类型兼容,特别是 `json`、`file`、`video` 等端口不要混接。
|
||||
- 为每个关键超参数补齐明确值,避免依赖隐式默认值进入生产工作流。
|
||||
- 对需要跨节点长期保留的产物,提前规划对象存储前缀或外部落库集合,而不是只写临时目录。
|
||||
|
||||
## 数据通信与存储路径
|
||||
|
||||
- 标准输入来自 `INPUT_ARTIFACTS_PATH` 指向的 artifact 列表文件,artifact 可同时包含 `data`、`path`、`metadata` 与 `dataRef`。
|
||||
- 标准输出写入 `OUTPUT_DIR`,并通过 `stage-manifest.json` 对外暴露产物路径、payload 引用和摘要元数据。
|
||||
|
||||
## 典型上下游编排
|
||||
|
||||
- 该算子通常位于同类数据处理节点之间,承担结构化中间层职责。
|
||||
|
||||
## 节点配置示例
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "RoboMIND HDF5质量校验",
|
||||
"operatorId": "operator-builtin-robomind-hdf5-quality-validate",
|
||||
"type": "builtin",
|
||||
"category": "ROBOTICS",
|
||||
"hyperparams": {
|
||||
"SOURCE_PATH": "<按节点填写>",
|
||||
"MAX_FILES": "100",
|
||||
"MAX_ROWS": "200000",
|
||||
"EE_TOLERANCE": "0.001",
|
||||
"JOINT_TOLERANCE": "0.001",
|
||||
"REQUIRE_JOINT_POSITION": "true",
|
||||
"REQUIRE_END_EFFECTOR": "false",
|
||||
"REQUIRE_IMAGES": "false"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 输入输出示例
|
||||
|
||||
- 典型输入: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)
|
||||
@ -1928,6 +1928,84 @@
|
||||
"runtimeSource": "backend/operators/builtin/rh20t_scene_validate/operator.py",
|
||||
"runtimeHandler": "builtin_rh20t_scene_validate"
|
||||
},
|
||||
{
|
||||
"id": "operator-builtin-robomind-hdf5-quality-validate",
|
||||
"name": "RoboMIND HDF5质量校验",
|
||||
"type": "builtin",
|
||||
"category": "ROBOTICS",
|
||||
"description": "读取真实 RoboMIND trajectory.hdf5,校验 puppet/master joint_position、puppet/end_effector 卡死、非有限值、帧数和多模态字段。",
|
||||
"inputs": [
|
||||
{
|
||||
"id": "in-1",
|
||||
"name": "input",
|
||||
"type": "json",
|
||||
"description": "RoboMIND trajectory.hdf5 文件或包含 h5_* 轨迹目录的根目录",
|
||||
"transmission": "bus"
|
||||
}
|
||||
],
|
||||
"outputs": [
|
||||
{
|
||||
"id": "out-1",
|
||||
"name": "validation",
|
||||
"type": "json",
|
||||
"description": "RoboMIND HDF5 轨迹质量校验结果",
|
||||
"transmission": "bus"
|
||||
}
|
||||
],
|
||||
"skillDefinition": "面向 RoboMIND、Multi-embodiment Intelligence、真实遥操作 VLA 训练数据,读取 h5_franka_1rgb/h5_franka_3rgb/h5_ur_1rgb/h5_agilex_3rgb/h5_tienkung 等目录下的 trajectory.hdf5,解析 robot/task/split/episode 元信息,检查 puppet/end_effector、puppet/joint_position、master/joint_position、franka/* 候选字段的 shape、finite 数值、unique ratio 和卡死状态,并统计 RGB/image/camera 与 action/gripper/command 数据集。",
|
||||
"hyperparams": [
|
||||
{
|
||||
"key": "SOURCE_PATH",
|
||||
"value": "",
|
||||
"description": "RoboMIND trajectory.hdf5 文件、data 目录或包含 benchmark/h5_* 的根目录",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"key": "MAX_FILES",
|
||||
"value": "100",
|
||||
"description": "最多校验多少个 .hdf5/.h5 轨迹文件,优先读取 trajectory.hdf5",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"key": "MAX_ROWS",
|
||||
"value": "200000",
|
||||
"description": "每个数值数组最多采样多少帧用于 range 和 unique ratio 计算",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"key": "EE_TOLERANCE",
|
||||
"value": "0.001",
|
||||
"description": "末端执行器数据 max(range_per_dim) 小于该阈值时判定卡死",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"key": "JOINT_TOLERANCE",
|
||||
"value": "0.001",
|
||||
"description": "关节数据 max(range_per_dim) 小于该阈值时判定卡死",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"key": "REQUIRE_JOINT_POSITION",
|
||||
"value": "true",
|
||||
"description": "是否要求存在 puppet/joint_position、puppet/joint_position_left 或 franka/joint_position",
|
||||
"type": "boolean"
|
||||
},
|
||||
{
|
||||
"key": "REQUIRE_END_EFFECTOR",
|
||||
"value": "false",
|
||||
"description": "是否要求存在 puppet/end_effector、puppet/end_effector_left 或 franka/end_effector;默认仅在存在时检查质量",
|
||||
"type": "boolean"
|
||||
},
|
||||
{
|
||||
"key": "REQUIRE_IMAGES",
|
||||
"value": "false",
|
||||
"description": "是否要求 HDF5 中存在 rgb/image/camera 相关观测数据集",
|
||||
"type": "boolean"
|
||||
}
|
||||
],
|
||||
"runtimeSource": "backend/operators/builtin/robomind_hdf5_quality_validate/operator.py",
|
||||
"runtimeHandler": "builtin_robomind_hdf5_quality_validate"
|
||||
},
|
||||
{
|
||||
"id": "operator-builtin-hdf5-demonstration-summary",
|
||||
"name": "HDF5 示教数据概览",
|
||||
|
||||
@ -65,6 +65,7 @@ RUNTIME_DEPENDENCIES: dict[str, list[str]] = {
|
||||
"rgbd_frame_pair_validate": ["rgb-images", "depth-images", "opencv-python-headless", "numpy", "pyyaml"],
|
||||
"rlds_episode_summary": ["rlds-json-or-tfds-files"],
|
||||
"rh20t_scene_validate": ["rh20t-scene-directory", "numpy", "npy-files", "image-video-files"],
|
||||
"robomind_hdf5_quality_validate": ["robomind-trajectory-hdf5-files", "h5py", "numpy"],
|
||||
"robomimic_hdf5_validate": ["robomimic-hdf5-files", "h5py", "numpy"],
|
||||
"robocasa_hdf5_demonstration_validate": ["robocasa-hdf5-demo-files", "h5py", "numpy"],
|
||||
"robot_model_asset_validate": ["urdf-files", "mjcf-files", "mesh-assets"],
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user