Files
chenlin ceca51b0d8
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
Improve generic robot onboarding, walking controls and end-effector interaction
Default humanoid intake to command-following gait and support bounded Cartesian target dragging for arms. Carry model and actuator semantics through calibration, native verification and packaging. Document reusable intake decisions and cover them with regression tests.
2026-11-06 10:54:58 +08:00

208 lines
8.8 KiB
Python

#!/usr/bin/env python3
"""Inspect, build, calibrate and verify new robot inputs."""
from __future__ import annotations
import argparse
import sys
from pathlib import Path
from typing import Any
from mjrl.onboarding._report import atomic_write, json_text, read_object
def _parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
commands = parser.add_subparsers(dest="command", required=True)
inspect = commands.add_parser(
"inspect", help="inventory robot inputs and recommend an intake tier"
)
inspect.add_argument("source", type=Path, help="file or directory to inspect")
inspect.add_argument("--profile", type=Path, help="declarative JSON robot profile")
inspect.add_argument("--mesh-root", type=Path, help="alternate URDF mesh or package directory")
inspect.add_argument("--policy", type=Path, help="select a policy file")
inspect.add_argument("--metadata", type=Path, help="select reviewed metadata or upstream config")
build = commands.add_parser("build-mjcf", help="build MJCF from a robot model or mesh")
build.add_argument("source", type=Path, help="URDF, MJCF, STL, OBJ, MSH, or asset directory")
build.add_argument("--output", "--out", required=True, type=Path, help="destination XML")
build.add_argument("--floating-base", action="store_true", help="add a free URDF root joint")
build.add_argument("--mesh-root", type=Path)
build.add_argument(
"--visual-fallback",
action="store_true",
help="create collision geoms where URDF provides visuals only",
)
build.add_argument(
"--mesh-scale", type=float, default=1.0, help="standalone mesh scale to metres (default 1)"
)
build.add_argument(
"--collision-hull-dirs", type=int, default=64,
help="fallback mesh hull sampling directions (default 64; 0 keeps the full hull)",
)
build.add_argument(
"--collision-hull-exclude", action="append", default=[], metavar="MESH",
help="preserve a fallback mesh, e.g. a support surface; repeat for multiple meshes",
)
build.add_argument("--replace", action="store_true", help="replace an existing destination XML")
calibrate = commands.add_parser("calibrate", help="refine a stance and measure native PD hold")
verify = commands.add_parser(
"verify", help="measure native dynamics and actual control response"
)
setup = commands.add_parser("setup-tier2", help="prepare a deterministic simulation controller")
for command in (calibrate, verify, setup):
command.add_argument("--model", required=True, type=Path, help="input MJCF XML")
command.add_argument("--config", required=True, type=Path, help="JSON configuration")
setup.add_argument("--output", "--out", required=True, type=Path, help="output directory")
extract = commands.add_parser("extract-tier1", help="extract and review upstream policy metadata")
extract.add_argument("configs", nargs="*", type=Path,
help="YAML, JSON or Python training configs; omit with --model for facts only")
extract.add_argument("--output", "--out", required=True, type=Path, help="new draft directory")
extract.add_argument("--model", type=Path, help="MJCF model for metadata validation")
extract.add_argument("--overrides", type=Path, help="reviewed JSON/YAML field overrides")
adapt = commands.add_parser("adapt-tier1", help="adapt a policy using reviewed or upstream metadata")
adapt.add_argument("source", type=Path, help="policy graph")
inputs = adapt.add_mutually_exclusive_group(required=True)
inputs.add_argument("--metadata", type=Path, help="reviewed JSON/YAML policy metadata")
inputs.add_argument("--config", action="append", type=Path, help="upstream config; repeat to combine")
adapt.add_argument("--overrides", type=Path, help="reviewed JSON/YAML overrides for --config")
adapt.add_argument(
"--model", type=Path, help="MJCF model to check joint names and limits against"
)
adapt.add_argument("--output", "--out", required=True, type=Path, help="output directory")
scaffold = commands.add_parser(
"scaffold-tier3", help="write a literal legged robot specification"
)
scaffold.add_argument("--config", required=True, type=Path, help="JSON RobotSpec")
scaffold.add_argument("--calibration", type=Path, help="reuse a passing calibration report")
scaffold.add_argument("--tasks-root", type=Path, help="destination tasks directory")
for command in (inspect, build, calibrate, verify, setup, extract, adapt, scaffold):
command.add_argument("--report", type=Path, help="write the JSON report to a new file")
return parser
def _run(args: argparse.Namespace) -> dict[str, Any]:
if args.command == "inspect":
from mjrl.onboarding import inspect_asset
profile = read_object(args.profile) if args.profile else None
return inspect_asset(
args.source,
profile=profile,
mesh_root=args.mesh_root,
policy=args.policy,
policy_metadata=args.metadata,
)
if args.command == "build-mjcf":
from mjrl.onboarding import build_mjcf
return build_mjcf(
args.source,
args.output,
floating_base=args.floating_base,
mesh_root=args.mesh_root,
visual_fallback=args.visual_fallback,
collision_hull_dirs=args.collision_hull_dirs,
collision_hull_exclude=tuple(args.collision_hull_exclude),
mesh_scale=args.mesh_scale,
replace=args.replace,
)
if args.command == "calibrate":
from mjrl.onboarding import calibrate_model
return calibrate_model(args.model, read_object(args.config))
if args.command == "verify":
from mjrl.onboarding import verify_model
return verify_model(
args.model, read_object(args.config), base_dir=args.config.resolve().parent
)
if args.command == "setup-tier2":
from mjrl.controllers import setup_controller
setup = setup_controller(args.model, args.config, args.output)
return {
"schema": "mjrl.onboarding.setup/1",
"model": str(setup.model),
"config": str(setup.config),
"controls": str(setup.controls) if setup.controls else None,
}
if args.command in {"extract-tier1", "adapt-tier1"}:
model = None
if args.model:
from mjrl.onboarding._physics import load_spec
model = load_spec(args.model).compile()
overrides = None
if args.overrides:
from mjrl.onboarding.upstream import load_overrides
if args.command == "adapt-tier1" and args.metadata:
raise ValueError("--overrides requires --config; review --metadata directly")
overrides = load_overrides(args.overrides)
if args.command == "extract-tier1":
from mjrl.onboarding.policy_intake import extract_to_directory
return extract_to_directory(args.configs, args.output, overrides=overrides, model=model)
if args.config:
from mjrl.onboarding.policy_intake import adapt_from_configs
return adapt_from_configs(args.source, args.config, args.output,
overrides=overrides, model=model)
from mjrl.adapter import adapt_policy
policy = adapt_policy(args.source, args.metadata, args.output, model=model)
return {
"schema": "mjrl.onboarding.adapt/1",
"layout": str(policy.layout),
"actor": str(policy.actor),
"config": str(policy.config),
"controls": str(policy.controls) if policy.controls else None,
"max_abs_error": policy.max_abs_error,
}
from mjrl.onboarding import scaffold_task
return scaffold_task(
read_object(args.config),
base_dir=args.config.resolve().parent,
calibration=read_object(args.calibration) if args.calibration else None,
tasks_root=args.tasks_root,
)
def main(argv: list[str] | None = None) -> int:
args = _parser().parse_args(argv)
try:
if args.report is not None and args.report.exists():
raise FileExistsError(f"report already exists: {args.report}")
report = _run(args)
code = int(report.get("passed", True) is False)
except (ImportError, OSError, RuntimeError, TypeError, ValueError) as exc:
print(f"{args.command}: {exc}", file=sys.stderr)
return 1
try:
result = json_text(report)
if args.report:
atomic_write(args.report, result)
except (OSError, ValueError) as exc:
print(f"{args.command}: {exc}", file=sys.stderr)
return 1
print(result, end="")
return code
if __name__ == "__main__":
raise SystemExit(main())