Merge pull request #27 from KraHsu/feat/m4-asset-zoo-franka-menagerie

Upgrade FrankaPandaCfg to Menagerie franka_emika_panda

Author: KraHsu

CHANGELOG.md

@@ -12,9 +12,9 @@ trajectory so breaking changes can land in any minor release until the 1.0 stabi
   `UnitreeG1Cfg` (29-DoF humanoid, 6 DCMotor groups mirroring
   `examples/unitree/.../g1/constants.py`), `UnitreeGo1Cfg` (12-DoF quadruped, 3
   ImplicitPD groups aligned to Isaac Lab Go1 defaults), and `AnymalCCfg` (12-DoF
-  quadruped, single ImplicitPD group aligned to Isaac Lab Anymal C defaults). The three
-  Menagerie-sourced robots ship as `.tar.gz` bundles in `KraHsu/genelab-assets`,
-  preserving BSD-3-Clause attribution.
+  quadruped, single ImplicitPD group aligned to Isaac Lab Anymal C defaults). All four
+  Menagerie-sourced robots (Franka, G1, Go1, Anymal C) ship as `.tar.gz` bundles in
+  `KraHsu/genelab-assets`, preserving the upstream LICENSE and README.
 - `AssetSpec.archive_member`: optional field that switches `fetch_asset` from
   single-file to archive mode. The URL is treated as a `.tar.gz`, the blob's md5 is
   verified end-to-end, and `tarfile`'s `data` filter extracts the contents into
@@ -28,6 +28,14 @@ trajectory so breaking changes can land in any minor release until the 1.0 stabi
   `examples/inverted_pendulum` (`stiffness=80`, passive pole); Franka follows Isaac
   Lab's high-PD configuration (`panda_arm` k=400, `panda_hand` k=1e4) with the
   Menagerie home pose.
+
+### Changed
+
+- **Breaking** (asset zoo only — no released API): `FrankaPandaCfg` now sources the full
+  MuJoCo Menagerie `franka_emika_panda` model (Apache-2.0) instead of the minimal stub
+  shipped during initial M4. Joint regexes drop the `panda_` prefix (`joint[1-7]`,
+  `finger_joint.*`) to match the upstream MJCF, and `default_joint_pos` follows the
+  Menagerie `home` keyframe (`joint4=-1.57079`, `joint6=1.57079`, `joint7=-0.7853`).
 - `genelab.utils.download.fetch_asset` + `AssetSpec` + `AssetDownloadError`: md5-verified
   download helper for asset zoo entries. Files cache under
   `<project_root>/.cache/assets/<name>/<md5>/<filename>` via atomic stage-and-rename;

docs/concepts/asset_zoo.en.md

@@ -42,18 +42,20 @@ every subsequent call resolves to the cached path.
 
 Use `genelab info <name>` to print the full override-path tree once registered.
 Cartpole mirrors `examples/inverted_pendulum`'s gains; G1 mirrors
-`examples/unitree/.../g1/constants.py`; Go1 and Anymal C follow Isaac Lab's published
-defaults so cross-stack experiments stay comparable.
+`examples/unitree/.../g1/constants.py`; Franka, Go1, and Anymal C follow Isaac Lab's
+published defaults so cross-stack experiments stay comparable. The four Menagerie-sourced
+entries (`franka`, `g1`, `go1`, `anymal-c`) ship as `.tar.gz` archives so meshes and
+textures travel with the MJCF.
 
 ## Cache layout and md5 verification
 
-Single-file mode (cartpole, franka):
+Single-file mode (cartpole):
 
 ```
 .cache/assets/<name>/<md5>/<filename>
 ```
 
-Archive mode (g1, go1, anymal-c):
+Archive mode (franka, g1, go1, anymal-c):
 
 ```
 .cache/assets/<name>/<md5>/extracted/<archive_member>

docs/concepts/asset_zoo.zh.md

@@ -24,17 +24,17 @@ Isaac Lab 自带 40+ 现成机器人配置，MjLab 自带 3 个；两者都把
 | `go1` | `UnitreeGo1Cfg()` | 12 | `hip` / `thigh` / `calf`（ImplicitPD，k=25） |
 | `anymal-c` | `AnymalCCfg()` | 12 | `legs`（单 ImplicitPD 组，k=80） |
 
-注册完成后用 `genelab info <name>` 打印完整的 override 路径树。Cartpole 的增益与 `examples/inverted_pendulum` 保持一致；G1 与 `examples/unitree/.../g1/constants.py` 对齐；Go1 与 Anymal C 沿用 Isaac Lab 公开的默认值，方便跨栈对比实验。
+注册完成后用 `genelab info <name>` 打印完整的 override 路径树。Cartpole 的增益与 `examples/inverted_pendulum` 保持一致；G1 与 `examples/unitree/.../g1/constants.py` 对齐；Franka、Go1 与 Anymal C 沿用 Isaac Lab 公开的默认值，方便跨栈对比实验。4 个 Menagerie 来源条目（`franka`、`g1`、`go1`、`anymal-c`）以 `.tar.gz` archive 形式发布，mesh 与纹理随 MJCF 一并发送。
 
 ## 缓存目录与 md5 校验
 
-单文件模式（cartpole、franka）：
+单文件模式（cartpole）：
 
 ```
 .cache/assets/<name>/<md5>/<filename>
 ```
 
-archive 模式（g1、go1、anymal-c）：
+archive 模式（franka、g1、go1、anymal-c）：
 
 ```
 .cache/assets/<name>/<md5>/extracted/<archive_member>

src/genelab/asset_zoo/franka.py

@@ -1,9 +1,10 @@
 """Franka Emika Panda asset zoo entry — 7-DoF arm + 2-finger parallel gripper.
 
-Joints split into two actuator groups: a high-PD arm group covering ``panda_joint1..7``
-and a stiffer finger group covering the parallel-jaw fingers. Gain values follow
-Isaac Lab's ``FRANKA_PANDA_HIGH_PD_CFG`` so behaviour transfers when downstream code
-mixes the two stacks. ``default_joint_pos`` matches the MuJoCo Menagerie home keyframe.
+Sourced from MuJoCo Menagerie ``franka_emika_panda`` (Apache-2.0). Joint names follow
+the upstream convention (``joint1..7`` plus ``finger_joint1..2``) and the default pose
+matches the Menagerie ``home`` keyframe. Two actuator groups split arm and hand with
+the Isaac Lab ``FRANKA_PANDA_HIGH_PD_CFG`` gains so cross-stack behaviour stays
+comparable.
 """
 
 from typing import Final
@@ -15,20 +16,22 @@
 
 _MJCF: Final = AssetSpec(
     name="franka",
-    url="https://raw.githubusercontent.com/KraHsu/genelab-assets/main/franka/franka.xml",
-    md5="4c413c93f77e8e7bd5364c23a772c72d",
-    filename="franka.xml",
+    url="https://raw.githubusercontent.com/KraHsu/genelab-assets/main/franka_emika_panda/franka_emika_panda.tar.gz",
+    md5="6890871be5fbb852a13b6be2a766f270",
+    filename="franka_emika_panda.tar.gz",
+    archive_member="franka_emika_panda/panda.xml",
 )
 
+# Menagerie home keyframe: qpos = "0 0 0 -1.57079 0 1.57079 -0.7853 0.04 0.04".
 _HOME_POSE: Final[dict[str, float]] = {
-    "panda_joint1": 0.0,
-    "panda_joint2": -0.785,
-    "panda_joint3": 0.0,
-    "panda_joint4": -2.356,
-    "panda_joint5": 0.0,
-    "panda_joint6": 1.571,
-    "panda_joint7": 0.785,
-    "panda_finger_joint.*": 0.04,
+    "joint1": 0.0,
+    "joint2": 0.0,
+    "joint3": 0.0,
+    "joint4": -1.57079,
+    "joint5": 0.0,
+    "joint6": 1.57079,
+    "joint7": -0.7853,
+    "finger_joint.*": 0.04,
 }
 
 
@@ -47,15 +50,15 @@ def FrankaPandaCfg() -> ArticulationCfg:
         default_joint_pos=dict(_HOME_POSE),
         actuators={
             "panda_arm": ImplicitPDActuatorCfg(
-                target_names_expr=(r"panda_joint[1-7]",),
+                target_names_expr=(r"joint[1-7]",),
                 stiffness=400.0,
                 damping=80.0,
                 effort_limit=87.0,
                 velocity_limit=2.175,
                 action_scale=0.5,
             ),
             "panda_hand": ImplicitPDActuatorCfg(
-                target_names_expr=(r"panda_finger_joint.*",),
+                target_names_expr=(r"finger_joint.*",),
                 stiffness=1.0e4,
                 damping=200.0,
                 effort_limit=20.0,
@@ -69,7 +72,7 @@ def FrankaPandaCfg() -> ArticulationCfg:
 register_robot(
     "franka",
     FrankaPandaCfg,
-    description="Franka Emika Panda 7-DoF arm with parallel-jaw gripper; high-PD gains.",
+    description="Franka Emika Panda 7-DoF arm + parallel gripper (Menagerie source); high-PD gains.",
     cfg_type=ArticulationCfg,
     examples=[
         "genelab info franka",

tests/test_asset_zoo.py

@@ -59,13 +59,15 @@ def test_franka_actuator_groups(monkeypatch: pytest.MonkeyPatch) -> None:
     cfg = FrankaPandaCfg()
     arm = cfg.actuators["panda_arm"]
     hand = cfg.actuators["panda_hand"]
-    assert arm.target_names_expr == (r"panda_joint[1-7]",)
+    # Menagerie panda.xml uses unprefixed joint names.
+    assert arm.target_names_expr == (r"joint[1-7]",)
     assert arm.stiffness == 400.0
     assert arm.damping == 80.0
-    assert hand.target_names_expr == (r"panda_finger_joint.*",)
+    assert hand.target_names_expr == (r"finger_joint.*",)
     assert hand.stiffness == 1.0e4
     assert hand.damping == 200.0
-    assert cfg.default_joint_pos["panda_joint4"] == pytest.approx(-2.356)
+    # Home keyframe qpos[3] (joint4) = -1.57079.
+    assert cfg.default_joint_pos["joint4"] == pytest.approx(-1.57079)
 
 
 def test_registry_examples() -> None: