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

246 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Command reference
Install this checkout in a Python 3.10–3.13 environment with
`python -m pip install -e ".[dev]"`. See [Agent setup](AGENT_SETUP.md) for
platform-specific setup. The editable install connects both package roots.
## Onboard
```bash
python scripts/onboard.py --help
python scripts/onboard.py inspect <model-or-directory> --profile <profile.json>
python scripts/onboard.py build-mjcf <model-mesh-or-directory> --output <robot.xml>
python scripts/onboard.py extract-tier1 env.yaml agent.yaml --model <robot.xml> --output <metadata-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --metadata <metadata.json> --model <robot.xml> --output <policy-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --config env.yaml --config agent.yaml --overrides reviewed.json --model <robot.xml> --output <policy-dir>
python scripts/onboard.py setup-tier2 --model <robot.xml> --config <controller.json> --output <control-dir>
python scripts/onboard.py calibrate --model <robot.xml> --config <stance.json> --report <calibration.json>
python scripts/onboard.py verify --model <robot.xml> --config <probe.json> --report <verification.json>
python scripts/onboard.py scaffold-tier3 --config <robot.json> --calibration <calibration.json>
```
Each subcommand has its own `--help`. `inspect` accepts optional `--policy`,
`--metadata`, and `--mesh-root`. In an asset directory, `build-mjcf` searches
recursively for one URDF or MJCF, or one STL, OBJ, or MSH when there is no
model. Pass a file explicitly when the directory has several candidates at
the selected level. The requested output path is excluded from the search.
`--floating-base` adds a free URDF root, `--mesh-root` extends URDF asset search,
`--mesh-scale` scales standalone meshes, and `--visual-fallback` opts into
approximate URDF collision geometry.
Choose fresh report and output paths unless the command explicitly allows
replacement. Calibration and verification emit JSON and return a failing
status when the requested checks fail.
`extract-tier1` reads selected YAML, JSON or static Python training configs.
Use `--overrides` to supply reviewed JSON or YAML values and `--report` for a
separate extraction report. The output directory contains `metadata.json`
and `manifest.json`, including on an incomplete extraction with exit status
1. Review the provenance and unresolved fields. Adapt from a manifest with
`ready: true`, or supply the same reviewed inputs through repeated `--config`
arguments in place of `--metadata`.
See the [Tier 1 walkthrough](CONTROLLER_SETUP.md#extract-metadata-from-upstream-configs).
### Python API
```python
from mjrl.onboarding import build_mjcf, calibrate_model, inspect_asset, scaffold_task, verify_model
intake = inspect_asset(source, profile=profile)
build = build_mjcf(source, model_path)
calibration = calibrate_model(model_path, stance_config)
verification = verify_model(model_path, probe_config, base_dir=config_directory)
registration = scaffold_task(robot_config, base_dir=config_directory, calibration=calibration)
```
These functions return report dictionaries. The profiles and configs are
Python mappings. `base_dir` resolves relative verification configuration paths
and defaults to the model's directory for verification. Scaffolding requires
`base_dir` for relative model and controls paths. Supply `tasks_root` to write
the specification into a different task directory.
Use `mjrl.onboarding.extract_policy_metadata` for programmatic Tier 1 metadata
extraction and readiness diagnostics. Pass a sequence of config paths and, if
available, the compiled MuJoCo model and a mapping of reviewed overrides.
```python
from mjrl.onboarding import extract_policy_metadata
extraction = extract_policy_metadata(
[env_config_path, agent_config_path], overrides=reviewed, model=compiled_model
)
```
The result contains the canonical draft under `metadata` and the readiness
and provenance fields written by the CLI.
### Robot specification
The calibrated scaffold config names `robot_id`, `family`, `model_path`, and
`action_scales` keyed by calibrated position-joint name. It can also name
`controls_path`, `velocity_joints`, `foot_sites`, `penalized_contact_geoms`, and
`termination_contact_geoms`. Model and controls paths resolve relative to the
input JSON. The calibration must match the model XML and compiled dependencies.
Optional `posture_stds` is an exact-name map covering every calibrated position
joint with a positive finite value. Scaffolding writes these values into each
joint's `posture_std` and consumes the top-level map; omitting it uses `0.35`.
Without `--calibration`, give a full `RobotSpec` from verified model facts.
This example shows the file shape:
```json
{
"robot_id": "sample_biped",
"family": "biped",
"model_path": "assets/sample_biped/robot.xml",
"base_body": "base",
"base_height": 0.32,
"foot_geoms": ["left_foot", "right_foot"],
"penalized_contact_geoms": ["left_shin", "right_shin"],
"termination_contact_geoms": ["torso"],
"position_joints": [
{"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1},
{"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}
]
}
```
Use calibrated values for the robot. `base_height` is its standing root
height. Each joint's `home` supplies its default joint position. Optional
`armature` is additional inertia at that joint. Supply either `foot_geoms`
or `foot_bodies`. Each named foot body needs named collision geoms directly
on it. The minimum support counts are two for biped and wheeled biped, four
for quadruped, and five for multipod. A wheeled biped also needs at least two
named unlimited wheel hinges in `velocity_joints`, with `kp: 0`, positive
`kd`, an effort limit, and a velocity action scale.
Optional `posture_std` on each joint is its positive finite posture allowance
in radians, defaulting to `0.35`. It supplies calibration data for the template's
speed-dependent pose term, not a reward weight. Different joints can declare
different allowances without adding robot-specific logic to the template.
Optional `foot_sites` lists one unique, nonempty, unqualified MuJoCo site name
per named foot support, in the same order as `foot_geoms` or `foot_bodies`.
These sites provide authored measurement locations for foot-clearance terms.
The default empty list preserves existing specifications without sites. A
nonempty list must match the support count; use actual sites in the robot model.
Full `RobotSpec` input and literal scaffolding preserve both fields.
Scaffolding writes only `tasks/<robot_id>/robot_spec.py` in the task tree.
The robot ID is the task ID. Family values are `biped`, `quadruped`,
`wheeled_biped`, and `multipod`. The controls file for a locomotion policy
uses the body-frame `twist` term feeding `velocity_commands`, with
`lin_vel_x`, `lin_vel_y`, and `ang_vel_z` in that order. A new biped defaults to W/S for forward/reverse and A/D for left/right
yaw. To supply a custom layout, set `controls_path` in the input JSON. See
the [control profiles](CONTROLS.md#training-template-controls) for wheeled
and omnidirectional layouts.
## Train and replay
```bash
python scripts/train.py --list
python scripts/train.py --task <robot_id> --dry-run
python scripts/train.py --task <robot_id> --backend native --device cpu --num_envs 64 --headless
python scripts/train.py --task <robot_id> --resume --max-iterations 100
python scripts/play.py --task <robot_id> --checkpoint <model_N.pt> --headless --steps 300 --speed 0 --measure
```
Use `--backend warp --device cuda` for the GPU path. Explicit requests fail
when their device is unavailable. Native starts at 64 parallel environments
and Warp at 4096 when no count is set. Start with fewer for an execution smoke
or an asset with high memory use.
Warp constraint and contact capacities can be set with positive integers
using `--warp-max-constraints N` and `--warp-max-contacts N`. Constraints
are capped per world. Contacts share a pool sized from the per-world setting
and the environment count. A Warp buffer overflow stops the run before it
uses the affected observations. For example, the G1 flat setup uses
`--warp-max-constraints 300`.
EPA horizon overflow is a separate convex-collision scratch-buffer limit;
increasing contact or constraint pools does not enlarge it. The checked Warp
backend reserves at least 128 horizon entries before capturing simulation graphs
(MuJoCo Warp 3.11 defaults to 24), preserves larger upstream buffers, and records
the effective size. It still stops on every reported overflow.
A Warp run saves selected and effective capacities in `warp-allocation.json`
beside its checkpoints. Warp resume, replay, and export read this file when
present. Explicit flags take precedence. Otherwise, the larger of the saved
capacity and the task or scene requirement is used. Without a run record or
a configured capacity, Warp chooses the size.
Training logs to `logs/<model>/<robot_id>/<timestamp>/`. The default
`--logger` is `tensorboard`. Use `--no-tensorboard` to skip starting its
server. `--max-iterations` caps this invocation. `--resume` selects the
latest checkpoint and `--checkpoint` selects a particular one. Both restore
the optimizer, iteration, and curriculum state. On resume,
`--max-iterations` is the number of additional iterations.
Replay retains actor observation noise by default. Use `--no-obs-noise` for
a clean comparison. `--checkpoint-command-ranges` restores the checkpoint's
command curriculum ranges. To evaluate a fixed body command, use
`--command VX VY YAW --evaluation-out <metrics.json>` with a trained checkpoint
and positive `--steps`. `--measure` records joint signals. Use `--physics-hz`
only when deliberately evaluating a different integration rate. The default
task simulation rate comes from its template. Built-in scenes work in
training and replay. Imported `.map` scenes are replay-only.
Rough terrain uses explicit nominal dimensions, not a hidden robot model:
`--terrain-robot-height 0.25`, `--terrain-stance 0.40`, and
`--terrain-foot-lift 0.04` (metres). With `--scene rough`, set these to the
calibrated asset's dimensions when comparing terrain difficulty. Height and
stance scale vertical and horizontal obstacles independently; foot lift sets
continuous roughness. The Python scene arguments are `robot_height`, `stance`,
and `foot_lift`. All must be finite and positive.
## Export and package
```bash
python scripts/export.py --task <robot_id> --checkpoint <model_N.pt> --out <policy-dir>
python scripts/deploy.py --robot <robot_id> --model <robot.xml> --bundle <output-parent>
python scripts/play.py --app <output-parent>/<robot_id>.app --headless --steps 100
```
Export writes the actor, its layout, a checkpoint copy, and a README. It checks
observation and action dimensions, home pose, and ONNX parity. Add
`--native-layout` to export a replay-ready native model and controller next to
the policy. Hybrid position and velocity actions automatically use the native
layout. Legacy Rust consumers accept their position-action layout. See
[Controller setup](CONTROLLER_SETUP.md#native-hybrid-policy-export).
A model-only build creates a viewer app. A controlled native build includes
`--control <controller.json>`, `--verification <verification.json>`, and
`--controls <controls.yaml>` when the report verified operator bindings.
For a compatible ONNX mode, also pass `--policy <policy-dir>`. For multiple
modes, use `--platform-manifest <manifest.json>`. See the
[bundle format](../deploy/BUNDLE.md) for mode fields and runtime requirements.
The legacy target flags build the separate Rust bundle format.
## Defaults
Precedence is command line, shell environment, `.env.local`, `.env`, then the
argument default. Copy `.env.example` to `.env` to set local defaults. A blank
task means a task is required on task entry points. A blank model selects the
robot's registered model. The effective defaults are:
```dotenv
MJRL_TASK=
MJRL_MODEL=
MJRL_SCENE=
MJRL_TERRAIN_ROW=
MJRL_TERRAIN_COL=
MJRL_BACKEND=auto
MJRL_DEVICE=auto
MJRL_NUM_ENVS=
MJRL_PLAY_NUM_ENVS=1
MJRL_CPU_THREADS=0
MJRL_STRIP_VISUAL=auto
MJRL_TENSORBOARD=on
MJRL_TB_PORT=6006
```
The terrain row and column select one rough-terrain tile when set. Native
`MJRL_CPU_THREADS=0` selects threads automatically. Native visual stripping
can reduce per-environment memory and affects camera sensor appearance.
TensorBoard binds to localhost and skips occupied ports.