react-manip 0.1.0__py3-none-any.whl

react_manip/cameras.py

@@ -0,0 +1,301 @@
+"""Shared camera contract. World cameras are fixed; robot cameras are body mounted.
+
+No rendering is performed unless explicitly requested. Legacy MJCF names stay
+available, while canonical names have the same meaning in every task.
+"""
+from dataclasses import dataclass
+import xml.etree.ElementTree as ET
+import numpy as np
+
+FIXED_CAMERAS = ('workspace_oblique', 'workspace_top', 'room_overview')
+LABELS = {'workspace_oblique': 'Workspace oblique', 'workspace_top': 'Workspace top',
+          'room_overview': 'Room overview', 'basket_top': 'Basket top'}
+
+
+@dataclass(frozen=True)
+class Workspace:
+    center: tuple = (0., 0., .75)
+    half_size: tuple = (.6, .8)
+    forward: tuple = (1., 0.)
+    room_half_size: tuple = (3., 3.)
+
+
+# Task-level declarations, not robot geometry or hidden object state. The
+# table envelope is refined from the compiled static support where available.
+WORKSPACES = {
+    'find_object_in_drawer': Workspace((.10, 0., .80), (.65, .65)),
+    'find_object_in_drawer1': Workspace((.10, 0., .80), (.65, .65)),
+    'find_object_in_drawer2': Workspace((-.10, 0., .48), (.80, .75)),
+    'rope_hang': Workspace((.55, 0., .85), (.55, .55)),
+    'pan_flip': Workspace((.6, 0., 1.0), (.45, .4)),
+    'rail_ball_to_cup': Workspace((.7, 0., .65), (.65, .5)),
+    'conveyor_grasp': Workspace((2., 0., .9), (.9, .3), (0., -1.), (3.3, 2.5)),
+    'laptop_into_drawer': Workspace((.1, 0., .8), (.65, .65)),
+    'box_insertion': Workspace((.25, 0., .78), (.45, .8)),
+    'button_indicator_matching': Workspace((.25, 0., .78), (.45, .8)),
+    'pen_strike': Workspace((0., 0., .75), (.5, .5)),
+    'pitch_pot': Workspace((-.25, 0., .18), (.65, .65)),
+    'paddle_juggle': Workspace((.15, 0., .8), (.7, .7)),
+    'phone_power_on': Workspace((0., 0., .15), (.5, .5)),
+    'turntable_gamble': Workspace((-.05, 0., .54), (.65, .65)),
+    'ball_to_target_hole': Workspace((0., 0., .75), (.7, .7)),
+    'cup_lid_matching': Workspace(), 'leveling_board': Workspace(),
+    'ring_toss': Workspace(), 'phone_cup': Workspace(),
+    'car_drive': Workspace((1.25, 0., .07), (1.25, 1.), (1., 0.), (5., 5.)),
+    # Local target view; the room view covers the entire curling lane.
+    'curling_sweep': Workspace((6., 0., .68), (1., .8), (1., 0.), (7., 3.)),
+    'curling_push': Workspace((2.85, 0., .65), (2.65, .55), (1., 0.), (4., 2.)),
+}
+
+
+def _vec(x):
+    return ' '.join(f'{float(v):.9g}' for v in x)
+
+
+def look_at(position, target, up=(0., 0., 1.)):
+    """MuJoCo basis: -Z optical forward, +Y image-up, +X image-right."""
+    z = np.asarray(position, float) - target
+    z /= np.linalg.norm(z)
+    x = np.cross(up, z)
+    if np.linalg.norm(x) < 1e-8:
+        raise ValueError('camera up is parallel to viewing direction')
+    x /= np.linalg.norm(x)
+    return np.column_stack((x, np.cross(z, x), z))
+
+
+def fixed_poses(workspace):
+    c = np.array(workspace.center, float)
+    forward = np.r_[workspace.forward, 0.]
+    forward /= np.linalg.norm(forward)
+    side = np.cross(forward, [0, 0, 1])
+    # Prefer 1.5 m above the surface; enlarge for broad native workspaces
+    # instead of silently cropping them or using extreme fisheye-like FOVs.
+    height = max(1.5, max(workspace.half_size) / np.tan(np.deg2rad(37.5)) * 1.12)
+    top = c + [0, 0, height]
+    distance = max(1.6, max(workspace.half_size) * 1.7)
+    oblique = c + forward * distance + side * distance * .25 + [0, 0, distance]
+    room_center = c.copy()
+    if workspace.center[0] == 2. and workspace.forward == (0., -1.):
+        room_center[1] = 1.0
+    rx, ry = workspace.room_half_size
+    room = room_center + np.array([rx * .8, ry * .8, max(2.4, .9 * max(rx, ry))])
+    return {'workspace_top': (top, look_at(top, c, forward), 75.),
+            'workspace_oblique': (oblique, look_at(oblique, c), 65.),
+            'room_overview': (room, look_at(room, room_center), 85.)}
+
+
+def ensure_scene_cameras(arena, task_id=None):
+    """Insert canonical fixed cameras before compilation; retain old names."""
+    world = arena.worldbody
+    task_id = task_id or arena.root.get('model', '')
+    workspace = WORKSPACES.get(task_id, Workspace())
+    poses = fixed_poses(workspace)
+    # Always reserve the optional regional view for this multi-zone task.
+    if 'conveyor' in task_id:
+        poses['basket_top'] = (np.array([2., 1.3, 2.25]), np.eye(3), 65.)
+    existing = {c.get('name') for c in world.iter('camera')}
+    for name, (position, rotation, fovy) in poses.items():
+        if name not in existing:
+            ET.SubElement(world, 'camera', name=name, pos=_vec(position),
+                          xyaxes=_vec(np.r_[rotation[:, 0], rotation[:, 1]]), fovy=str(fovy))
+
+
+def ensure_robot_cameras(robot):
+    """Normalize imported names using embodiment-owned sensor parameters."""
+    from copy import deepcopy
+    from .robots.sensors import sensor_profile, install_declared_cameras
+    install_declared_cameras(robot)
+    profile = sensor_profile(robot)
+    prefix = robot.naming_prefix
+    entries = [(b, c) for b in robot.worldbody.iter('body') for c in b.findall('camera')]
+    existing = {c.get('name') for _, c in entries}
+    for body, camera in entries:
+        name = camera.get('name', '')
+        canonical = None
+        if name.endswith('_head_camera'):
+            canonical = prefix + 'head'
+        elif name.endswith('eye_in_hand'):
+            arm = 'left' if 'left' in name else 'right'
+            canonical = prefix + 'wrist_' + arm
+        elif name.endswith('overhead_camera'):
+            canonical = prefix + 'overhead_debug'
+        if canonical and canonical not in existing:
+            clone = deepcopy(camera)
+            clone.set('name', canonical)
+            if canonical.endswith('_head') and profile.head_xyaxes is not None:
+                # Fixed mount pitch, not target tracking. The legacy head
+                # name retains its original horizontal optical axis.
+                for attr in ('quat', 'euler', 'axisangle', 'zaxis'):
+                    clone.attrib.pop(attr, None)
+                clone.set('xyaxes', profile.head_xyaxes)
+                # The imported mast visual encloses the old x=.16 sensor.
+                # A small forward bracket puts the optical centre outside it.
+                position = np.fromstring(clone.get('pos', '0 0 0'), sep=' ')
+                if profile.head_min_x is not None:
+                    position[0] = max(profile.head_min_x, position[0])
+                clone.set('pos', _vec(position))
+                camera.set('pos', _vec(position))
+            elif '_wrist_' in canonical and profile.wrist_target is not None:
+                # Mount the sensor on the eef rear/top face.  The imported
+                # asset used a +Y side offset, which made the view look
+                # rolled by roughly 90 degrees.  Use an explicit local
+                # position when the embodiment declares one, then aim at a
+                # point 6 cm beyond TCP with a tool-frame up vector.
+                position = (np.asarray(profile.wrist_position, dtype=float)
+                            if profile.wrist_position is not None else
+                            np.fromstring(clone.get('pos', '0 0 0'), sep=' '))
+                rotation = look_at(position, np.array(profile.wrist_target), profile.wrist_up)
+                for attr in ('quat', 'euler', 'axisangle', 'zaxis'):
+                    clone.attrib.pop(attr, None)
+                    camera.attrib.pop(attr, None)
+                camera.set('pos', _vec(position))
+                clone.set('pos', _vec(position))
+                clone.set('xyaxes', _vec(np.r_[rotation[:, 0], rotation[:, 1]]))
+                camera.set('xyaxes', clone.get('xyaxes'))
+            body.append(clone)
+            existing.add(canonical)
+
+
+def raw_sim(env):
+    sim = getattr(env, 'sim', env)
+    model = getattr(sim.model, '_model', sim.model)
+    data = getattr(sim.data, '_data', sim.data)
+    return sim, model, data
+
+
+def configure_fixed_cameras(env):
+    """Called after reset, never during step: no tracking or hidden-state input."""
+    import mujoco
+    _, model, data = raw_sim(env)
+    module = type(env).__module__.split('.')
+    task_id = getattr(env, 'task_id', module[1] if len(module) > 1 else '')
+    w = getattr(env, 'camera_workspace', WORKSPACES.get(task_id, Workspace()))
+    if isinstance(w, dict):
+        w = Workspace(**w)
+    center, half = np.array(w.center), np.array(w.half_size)
+    # Read only static table supports, not the randomly placed target objects.
+    if task_id != 'conveyor_grasp':
+        for name in ('table', 'table_top', 'table_top_col', 'table_collision'):
+            gid = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_GEOM, name)
+            if gid >= 0 and model.geom_type[gid] == mujoco.mjtGeom.mjGEOM_BOX:
+                extent = np.abs(data.geom_xmat[gid].reshape(3, 3)) @ model.geom_size[gid]
+                center = data.geom_xpos[gid].copy() + [0, 0, extent[2]]
+                half = extent[:2] * 1.08
+                break
+    if task_id == 'pitch_pot':
+        bid = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_BODY, 'pot')
+        if bid >= 0:
+            center = data.xpos[bid].copy() + [0, 0, .18]
+            half = np.array([.65, .65])
+    forward = np.array(w.forward)
+    robots = getattr(env, 'robots', ())
+    if robots:
+        root = robots[0].robot_model.root_body
+        bid = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_BODY, root)
+        if bid >= 0:
+            direction = center[:2] - data.xpos[bid, :2]
+            if np.linalg.norm(direction) > .1:
+                forward = direction / np.linalg.norm(direction)
+    poses = fixed_poses(Workspace(tuple(center), tuple(half), tuple(forward), w.room_half_size))
+    if robots and bid >= 0:
+        anchors = [center[:2] - half, center[:2] + half, data.xpos[bid, :2]]
+        if hasattr(env, 'bin_centers'):
+            anchors.extend(np.asarray(env.bin_centers)[:, :2])
+        anchors = np.asarray(anchors)
+        room_center = np.r_[(anchors.min(axis=0) + anchors.max(axis=0)) / 2, center[2]]
+        rx, ry = w.room_half_size
+        room_pos = room_center + [rx * .8, ry * .8, max(2.4, .9 * max(rx, ry))]
+        poses['room_overview'] = (room_pos, look_at(room_pos, room_center), 85.)
+    if task_id == 'car_drive':
+        ids = [i for i in range(model.ngeom) if (mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_GEOM, i) or '').startswith('road_')]
+        if ids:
+            route_center = data.geom_xpos[ids].mean(axis=0)
+            room_pos = route_center + [4, -5, 5]
+            poses['room_overview'] = (room_pos, look_at(room_pos, route_center), 85.)
+    if hasattr(env, 'bin_centers'):
+        bins = np.asarray(env.bin_centers)
+        c = bins.mean(axis=0)
+        p = c + [0, 0, 1.5]
+        poses['basket_top'] = (p, look_at(p, c, np.r_[forward, 0]), 65.)
+    # Optional task-owned static framing, reconstructed from scene dimensions.
+    # Preserve it through both factory setup and hard resets.
+    poses.update(getattr(env, 'fixed_camera_poses', {}))
+    for name, (position, rotation, fovy) in poses.items():
+        cid = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_CAMERA, name)
+        if cid < 0:
+            raise ValueError(f'{task_id}: missing canonical camera {name}')
+        model.cam_pos[cid] = position
+        mujoco.mju_mat2Quat(model.cam_quat[cid], rotation.flatten())
+        model.cam_fovy[cid] = fovy
+    mujoco.mj_forward(model, data)
+
+
+def camera_specs(env):
+    import mujoco
+    _, model, _ = raw_sim(env)
+    result = []
+    for i in range(model.ncam):
+        name = mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_CAMERA, i)
+        canonical = name in FIXED_CAMERAS or name == 'basket_top' or name.endswith(('_head', '_wrist_right', '_wrist_left', '_overhead_debug'))
+        role = 'fixed' if model.cam_bodyid[i] == 0 else 'mounted'
+        default_policy = name in ('workspace_top', 'workspace_oblique') or name.endswith(('_head', '_wrist_right', '_wrist_left'))
+        result.append(dict(id=name, label=LABELS.get(name, name.replace('_head', ' head').replace('_wrist_right', ' right wrist').replace('_wrist_left', ' left wrist')),
+                           canonical=canonical, display_default=canonical and not name.endswith('_overhead_debug'),
+                           mounting=role, parent_body=mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_BODY, int(model.cam_bodyid[i])),
+                           width=640, height=480, fovy=float(model.cam_fovy[i]), policy_default=default_policy,
+                           calibrated=False, image_format='RGB uint8 HWC, top-left origin'))
+    def order(s):
+        n = s['id']
+        if n in FIXED_CAMERAS:
+            return (FIXED_CAMERAS.index(n), n)
+        return (3 if n.endswith('_head') else 4 if n.endswith('_wrist_right') else 5 if n.endswith('_wrist_left') else 6, n)
+    return sorted(result, key=order)
+
+
+def display_camera_names(env, *, include_legacy=False):
+    """Standard operator views; retain legacy/debug cameras only by opt-in.
+
+    An unmigrated environment with no standard views keeps its original views.
+    This selection does not change model cameras or policy observations.
+    """
+    specs = camera_specs(env)
+    selected = [s['id'] for s in specs if s['display_default']]
+    if include_legacy or not selected:
+        return [s['id'] for s in specs]
+    return selected
+
+
+# Fixed mounts, expressed in the robot mount frame (+X forward, +Z up).
+# Task profiles describe static workspace framing, never target tracking.
+POLICY_CAMERA = 'robot0_head_camera'
+EGO_PROFILES = {
+    'car_drive2': (50., 100.),
+    'curling_push': (40., 80.),
+    'conveyor_grasp': (70., 100.),
+    'tilte_maze': (65., 60.),
+    # These two tasks use a tall vertical workspace.  The generic 60-degree
+    # downward pitch puts the pan's toss arc and the ring-toss far row against
+    # (or beyond) the top edge of the 4:3 policy image.  Lower pitch means the
+    # optical axis is tilted upward while preserving the robot-mounted pose.
+    'pan_flip': (40., 85.),
+    'ring_toss1': (50., 80.),
+}
+
+
+def configure_policy_camera(env):
+    """Pitch the robot main sensor; preserve its body attachment."""
+    import mujoco
+    _, model, data = raw_sim(env)
+    module = type(env).__module__.split('.')
+    task_id = getattr(env, 'task_id', module[1] if len(module) > 1 else '')
+    pitch, fovy = EGO_PROFILES.get(task_id, (60., 80.))
+    angle = np.deg2rad(pitch)
+    rotation = look_at(np.zeros(3), np.array([np.cos(angle), 0., -np.sin(angle)]))
+    for name in (POLICY_CAMERA, 'robot0_head'):
+        cid = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_CAMERA, name)
+        if cid < 0:
+            continue
+        if model.cam_bodyid[cid] == 0:
+            raise ValueError(f'{name} must be mounted on the robot')
+        mujoco.mju_mat2Quat(model.cam_quat[cid], rotation.flatten())
+        model.cam_fovy[cid] = fovy

react_manip/category_objects.py

@@ -0,0 +1,248 @@
+"""Shared category-object assets and collision proxies, independent of tasks."""
+from pathlib import Path
+from typing import Any
+import json
+import xml.etree.ElementTree as ET
+import numpy as np
+
+OBJECT_LINEAR_SCALE = 1.55
+OBJECT_CATEGORY_NAMES = (
+    "footwear",
+    "drinkware",
+    "electronics",
+    "toys",
+    "kitchen_tools",
+    "office_supplies",
+    "personal_care",
+    "planters",
+)
+CATEGORY_VARIANTS = {
+    category: tuple(range(10)) for category in OBJECT_CATEGORY_NAMES
+}
+CATEGORY_COLORS = (
+    (0.78, 0.16, 0.10, 1.0),
+    (0.10, 0.58, 0.22, 1.0),
+    (0.12, 0.30, 0.82, 1.0),
+    (0.66, 0.18, 0.72, 1.0),
+    (0.84, 0.48, 0.08, 1.0),
+    (0.10, 0.62, 0.66, 1.0),
+    (0.76, 0.28, 0.48, 1.0),
+    (0.38, 0.56, 0.18, 1.0),
+)
+# Keep the existing shared download cache and attribution paths intact.
+ASSET_ROOT = Path(__file__).resolve().parents[1] / "assets/category_drawer_sorting"
+ASSET_MANIFEST = ASSET_ROOT / "manifest.json"
+
+
+def _load_asset_manifest() -> dict[str, Any]:
+    if not ASSET_MANIFEST.is_file():
+        return {"categories": {}}
+    return json.loads(ASSET_MANIFEST.read_text(encoding="utf-8"))
+
+
+_EXTERNAL_ASSET_MANIFEST = _load_asset_manifest()
+
+
+def _external_asset(category: int, variant: int) -> dict[str, Any] | None:
+    category_name = OBJECT_CATEGORY_NAMES[category]
+    entries = _EXTERNAL_ASSET_MANIFEST.get("categories", {}).get(category_name, ())
+    if variant >= len(entries):
+        return None
+    asset_id = str(entries[variant])
+    directory = ASSET_ROOT / "gso" / asset_id
+    metadata_path = directory / "cl_manip_asset.json"
+    if not metadata_path.is_file():
+        return None
+    metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+    mesh = directory / str(metadata.get("visual_mesh", "meshes/model.obj"))
+    texture = directory / str(metadata.get("texture", "materials/textures/texture.png"))
+    if not mesh.is_file() or not texture.is_file():
+        return None
+    return {**metadata, "mesh_path": mesh, "texture_path": texture}
+
+
+def _vec(values) -> str:
+    return " ".join(f"{float(value):.6g}" for value in values)
+
+
+def _variant_spec(category: int, variant: int) -> dict[str, Any]:
+    """Return one of ten deterministic, graspable variants per category."""
+
+    if not 0 <= category < len(OBJECT_CATEGORY_NAMES):
+        raise ValueError(f"invalid category index: {category}")
+    if not 0 <= variant < 10:
+        raise ValueError(f"variant must be in [0, 9], got {variant}")
+    scale = 0.86 + 0.028 * variant
+    aspect = 0.88 + 0.06 * (variant % 3)
+    height = 0.024 + 0.0015 * (variant % 5)
+    rgba = np.asarray(CATEGORY_COLORS[category], dtype=float).copy()
+    rgba[:3] *= 0.86 + 0.025 * (variant % 6)
+    if category == 0:  # footwear fallback: elongated sole plus rounded toe
+        long = 0.040 * scale
+        width = 0.022 * aspect
+        half_height = 0.018 + 0.001 * (variant % 4)
+        toe = 0.019 + 0.0008 * (variant % 5)
+        geoms = [
+            ("box", (long, width, half_height), (-0.006, 0.0, 0.0), None),
+            ("sphere", (toe,), (long - 0.004, 0.0, 0.003), None),
+        ]
+        extent = np.array([long + toe, max(width, toe), max(half_height, toe + 0.003)])
+    elif category == 1:  # drinkware fallback: upright canister
+        radius = 0.030 * scale
+        half_height = 0.030 + 0.0015 * (variant % 4)
+        geoms = [("cylinder", (radius, half_height), (0.0, 0.0, 0.0), None)]
+        extent = np.array([radius, radius, half_height])
+    elif category == 2:  # electronics fallback: flat device with raised control area
+        long = 0.043 * scale
+        width = 0.030 * aspect
+        half_height = 0.014 + 0.001 * (variant % 4)
+        geoms = [
+            ("box", (long, width, half_height), (0.0, 0.0, 0.0), None),
+            ("box", (long * 0.45, width * 0.55, 0.004), (0.006, 0.0, half_height + 0.004), None),
+        ]
+        extent = np.array([long, width, half_height + 0.008])
+    elif category == 3:  # toys fallback: stable dumbbell with rounded end caps
+        long = 0.040 * scale
+        radius = 0.018 + 0.001 * (variant % 4)
+        half_height = 0.023 + 0.001 * (variant % 3)
+        geoms = [
+            ("box", (long, 0.013, half_height), (0.0, 0.0, 0.0), None),
+            ("sphere", (radius,), (-long, 0.0, 0.006), None),
+            ("sphere", (radius,), (long, 0.0, 0.006), None),
+        ]
+        extent = np.array([long + radius, radius, max(half_height, radius + 0.006)])
+    elif category == 4:  # kitchen tools: elongated handle with a broad head
+        long = 0.042 * scale
+        width = 0.013 + 0.001 * (variant % 3)
+        half_height = 0.012 + 0.001 * (variant % 4)
+        geoms = [
+            ("box", (long, width, half_height), (0.0, 0.0, 0.0), None),
+            ("sphere", (width * 1.45,), (long, 0.0, 0.002), None),
+        ]
+        extent = np.array([long + width * 1.45, width * 1.45, max(half_height, width * 1.45)])
+    elif category == 5:  # office supplies: compact trays, holders and cartridges
+        long = 0.038 * scale
+        width = 0.029 * aspect
+        half_height = 0.020 + 0.0015 * (variant % 4)
+        geoms = [
+            ("box", (long, width, half_height), (0.0, 0.0, 0.0), None),
+            ("box", (long * 0.72, width * 0.65, 0.004), (0.0, 0.0, half_height + 0.004), None),
+        ]
+        extent = np.array([long, width, half_height + 0.008])
+    elif category == 6:  # personal care: bottle-like containers
+        radius = 0.022 + 0.001 * (variant % 4)
+        half_height = 0.034 * scale
+        geoms = [
+            ("cylinder", (radius, half_height), (0.0, 0.0, 0.0), None),
+            ("cylinder", (radius * 0.52, 0.006), (0.0, 0.0, half_height + 0.006), None),
+        ]
+        extent = np.array([radius, radius, half_height + 0.012])
+    else:  # planters: squat, stable containers
+        radius = 0.031 * scale
+        half_height = 0.027 + 0.0015 * (variant % 4)
+        geoms = [
+            ("cylinder", (radius, half_height), (0.0, 0.0, 0.0), None),
+            ("cylinder", (radius * 1.08, 0.004), (0.0, 0.0, half_height + 0.004), None),
+        ]
+        extent = np.array([radius * 1.08, radius * 1.08, half_height + 0.008])
+    # Normalize the horizontal grasp width, leaving clearance inside an
+    # 8 cm parallel gripper. Uniform scaling preserves primitive geometry.
+    scaled_extent = np.asarray(extent, dtype=float) * OBJECT_LINEAR_SCALE
+    grasp_width = 2.0 * float(np.min(scaled_extent[:2]))
+    grasp_scale = float(np.clip(grasp_width, 0.045, 0.060) / grasp_width)
+    object_scale = OBJECT_LINEAR_SCALE * grasp_scale
+    geoms = [
+        (
+            geom_type,
+            tuple(np.asarray(size, dtype=float) * object_scale),
+            tuple(np.asarray(offset, dtype=float) * object_scale),
+            quat,
+        )
+        for geom_type, size, offset, quat in geoms
+    ]
+    return {
+        "geoms": geoms,
+        "extent": np.asarray(extent, dtype=float) * object_scale,
+        "rgba": rgba,
+    }
+
+
+def _add_geom(parent, *, name: str, geom_type: str, size, pos, rgba, collision: bool):
+    attrs = {
+        "name": name,
+        "type": geom_type,
+        "size": _vec(size),
+        "pos": _vec(pos),
+        "rgba": _vec(rgba),
+        "friction": "0.8 0.01 0.001",
+        # 1 m drops reach ~4.4 m/s: the default 20 ms soft response can
+        # penetrate a 5 cm tabletop. 5 ms remains above 2 physics steps.
+        "solref": "0.005 1",
+        # Include torsional and rolling resistance, not just sliding friction.
+        "condim": "6" if collision else "3",
+        "group": "0" if collision else "1",
+        "contype": "1" if collision else "0",
+        "conaffinity": "1" if collision else "0",
+        "density": "320" if collision else "0",
+    }
+    return ET.SubElement(parent, "geom", **attrs)
+
+
+def _add_object(asset, world, *, name: str, category: int, variant: int, pos) -> np.ndarray:
+    spec = _variant_spec(category, variant)
+    body = ET.SubElement(world, "body", name=name, pos=_vec(pos))
+    ET.SubElement(body, "freejoint", name=f"{name}_free")
+    external = _external_asset(category, variant)
+    for index, (geom_type, size, offset, _quat) in enumerate(spec["geoms"]):
+        _add_geom(
+            body, name=f"{name}_collision_{index}", geom_type=geom_type,
+            size=size, pos=offset, rgba=spec["rgba"], collision=True,
+        )
+        if external is None:
+            _add_geom(
+                body, name=f"{name}_visual_{index}", geom_type=geom_type,
+                size=size, pos=offset, rgba=spec["rgba"], collision=False,
+            )
+    if spec["geoms"][0][0] == "cylinder":
+        # A flat, inset foot supports upright containers with stable box/box
+        # contacts. The analytic rim otherwise rocks on changing CCD points.
+        # Extend only 1 mm below the rim; preserve the visible cylinder body.
+        radius, half_height = spec["geoms"][0][1]
+        foot_half_width = radius * 0.65
+        _add_geom(
+            body, name=f"{name}_collision_foot", geom_type="box",
+            size=(foot_half_width, foot_half_width, 0.001),
+            pos=(0, 0, -half_height), rgba=spec["rgba"], collision=True,
+        )
+    if external is not None:
+        minimum = np.asarray(external["bounds_min"], dtype=float)
+        maximum = np.asarray(external["bounds_max"], dtype=float)
+        source_size = maximum - minimum
+        target_size = 2.0 * np.asarray(spec["extent"], dtype=float) * 0.96
+        # Fit each axis to the physical proxy. An inscribed uniform fit can
+        # make a thin scan nearly invisible inside a much larger collider.
+        mesh_scale = target_size / source_size
+        source_center = (minimum + maximum) / 2.0
+        mesh_name = f"{name}_scan_mesh"
+        texture_name = f"{name}_scan_texture"
+        material_name = f"{name}_scan_material"
+        ET.SubElement(
+            asset, "mesh", name=mesh_name,
+            file=str(external["mesh_path"].resolve()),
+            scale=_vec(mesh_scale),
+        )
+        ET.SubElement(
+            asset, "texture", name=texture_name, type="2d",
+            file=str(external["texture_path"].resolve()),
+        )
+        ET.SubElement(
+            asset, "material", name=material_name, texture=texture_name,
+            texuniform="false", specular="0.05", reflectance="0",
+        )
+        ET.SubElement(
+            body, "geom", name=f"{name}_scan_visual", type="mesh",
+            mesh=mesh_name, material=material_name,
+            pos=_vec(-source_center * mesh_scale),
+            group="1", contype="0", conaffinity="0", density="0",
+        )
+    return np.asarray(spec["extent"], dtype=float)

react_manip/core/__init__.py

@@ -0,0 +1,60 @@
+"""Public API for the extensible, fixed-horizon react_manip.
+
+The modules in :mod:`react_manip.core` deliberately do not import MuJoCo or
+robosuite.  This keeps the protocol, metrics, and registry usable by tooling
+and CI on machines where the simulator is not installed.
+"""
+
+from .metrics import SustainedSuccessTracker
+from .aggregate import aggregate_results
+from .compatibility import validate_task_robot
+from .protocol import BenchmarkTask, Policy, StepResult, normalize_reset, normalize_step
+from .registry import (
+    RobotRegistry,
+    TaskDefinition,
+    TaskRegistry,
+    get_robot_registry,
+    get_task_registry,
+    register_robot,
+    register_task,
+)
+from .runner import BenchmarkRunner, EvaluationResult
+from .specs import SuccessRule, TaskSpec
+from .scenarios import Scenario, sample_scenario
+from .contracts import ObservationSpec, ActionSpec, FeedbackSpec
+from .geometry import GeometryFeatureAdapter
+from .observation import policy_observation
+from .language import EpisodeLanguagePrompt, build_episode_prompt
+from .visual_randomization import ensure_workspace_camera
+
+__all__ = [
+    "BenchmarkRunner",
+    "BenchmarkTask",
+    "EvaluationResult",
+    "Policy",
+    "RobotRegistry",
+    "StepResult",
+    "SuccessRule",
+    "SustainedSuccessTracker",
+    "TaskDefinition",
+    "TaskRegistry",
+    "TaskSpec",
+    "get_robot_registry",
+    "get_task_registry",
+    "register_robot",
+    "register_task",
+    "normalize_reset",
+    "normalize_step",
+    "validate_task_robot",
+    "Scenario",
+    "sample_scenario",
+    "ObservationSpec",
+    "ActionSpec",
+    "FeedbackSpec",
+    "GeometryFeatureAdapter",
+    "policy_observation",
+    "aggregate_results",
+    "EpisodeLanguagePrompt",
+    "build_episode_prompt",
+    "ensure_workspace_camera",
+]

react_manip/core/aggregate.py

@@ -0,0 +1,59 @@
+"""Aggregate fixed-horizon episode results into benchmark-level statistics."""
+
+from __future__ import annotations
+
+from math import sqrt
+from typing import Any, Iterable, Mapping
+
+
+NUMERIC_FIELDS = (
+    "success_occupancy",
+    "longest_success_streak_sec",
+    "completed_events",
+    "event_rate_hz",
+    "failure_count",
+    "recoverable_failure_count",
+    "recovery_count",
+    "peak_force_N",
+    "mean_inference_latency_ms",
+    "mean_action_age_ms",
+    "real_time_factor",
+)
+
+
+def aggregate_results(results: Iterable[Any]) -> dict[str, Any]:
+    """Return deterministic summary statistics for a set of episodes."""
+
+    rows = [_as_mapping(item) for item in results]
+    if not rows:
+        raise ValueError("cannot aggregate an empty result set")
+    passed = [bool(row.get("passed", row.get("metrics", {}).get("passed", False))) for row in rows]
+    summary: dict[str, Any] = {
+        "episodes": len(rows),
+        "pass_count": sum(passed),
+        "pass_rate": round(sum(passed) / len(passed), 6),
+    }
+    for field in NUMERIC_FIELDS:
+        values = []
+        for row in rows:
+            value = row.get(field)
+            if value is None and isinstance(row.get("metrics"), Mapping):
+                value = row["metrics"].get(field)
+            if isinstance(value, (int, float)):
+                values.append(float(value))
+        if values:
+            mean = sum(values) / len(values)
+            variance = sum((value - mean) ** 2 for value in values) / len(values)
+            summary[f"mean_{field}"] = round(mean, 6)
+            summary[f"std_{field}"] = round(sqrt(variance), 6)
+    return summary
+
+
+def _as_mapping(value: Any) -> Mapping[str, Any]:
+    if isinstance(value, Mapping):
+        return value
+    if hasattr(value, "to_dict"):
+        result = value.to_dict()
+        if isinstance(result, Mapping):
+            return result
+    raise TypeError(f"result must be a mapping or expose to_dict(), got {type(value).__name__}")