simulo-interfaces 0.23.0__tar.gz → 0.25.0__tar.gz

{simulo_interfaces-0.23.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.23.0
+Version: 0.25.0
 Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.23.0 → simulo_interfaces-0.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.23.0"
+version = "0.25.0"
 description = "Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.23.0 → simulo_interfaces-0.25.0}/src/simulo/interfaces/authoring/__init__.py

@@ -1,13 +1,10 @@
 """Part C — the typed authoring surface.
 
-The **relocation and mirror destination** for the Simulo authoring value types.
-Each type here has exactly ONE definition — this one — shared by both
-distributions: the thin client authors these values at submit (torch-free,
-e.g. ``simulo.Pose(xyz=(1, 2, 3))``) and the backend executes them on the
-worker. There is no other copy and no re-export shim anywhere ("nuke as you
-go", per the owner's 2026-07-26 directive recorded in the plan): the former
-backend ``core`` modules for these types are deleted, so ``isinstance`` keeps
-working because only this definition exists.
+The relocation and mirror destination for shared authoring value types.
+Each value type has one definition here, used by the torch-free client when
+submitting a job and by the backend when executing it. Robot configuration
+records retain their existing backend import paths as re-exports of these
+same objects.
 
 Relocated so far — Wave C1: ``pose`` (``Pose``), ``materials`` (``Material``,
 ``SurfaceMaterial``), ``physics`` (``Physics``, ``Collision``, ``RigidPhysics``,
@@ -20,7 +17,7 @@ decision — to resolve that exact name collision), and ``light`` (``Light``,
 ``RoughTerrain``), ``primitives`` (``PrimitiveShape``, ``Cone``,
 ``Cuboid``, ``Sphere``, ``Cylinder``, ``Transform``), ``entity`` (``Entity``,
 ``AssetEntity``), and ``visual`` (``Visual``, ``VisualMarkerBase``,
-``AxesMarker``, ``SphereMarker``, ``ArrowMarker``, ``PointMarker``).
+``AxesMarker``, ``SphereMarker``, ``ArrowMarker``, ``PointMarker``, ``LineMarker``).
 Wave C4: ``record`` (``RecordConfig`` — the MCAP recording configuration;
 stdlib-only, so it classifies RELOCATE, and the backend recorder imports it
 from here), and ``world`` (``World``, ``USDWorld``): ``Terrain`` is the
@@ -53,8 +50,9 @@ clearly in a submit-only installation.
 Two relocation mechanisms select which types land here and how (see the derived
 plan for the full worked example and rejected alternatives):
 
-* **RELOCATE** — the class definition MOVES here; the old ``core/<module>.py``
-  is deleted and every call site rewritten in the same PR (no re-export shims).
+* **RELOCATE** — the class definition MOVES here. Dependency-bearing modules
+  that also exposed a shared value type can re-export its one definition for
+  existing callers; dependency-free modules move with their call sites.
   Reserved for types with zero import-time *or* call-time dependency on
   anything that cannot live in a zero-dependency package.
 * **MIRROR** — a ``typing.Protocol`` (named ``*Protocol``, matching the
@@ -86,11 +84,17 @@ and cross-references for cryptic engine-style names) — that table, not this
 docstring, is the source of truth for what lands here and when.
 """
 
+from simulo.interfaces.authoring.action_channel import ActionChannel
 from simulo.interfaces.authoring.actuator import ActuatorProtocol
 from simulo.interfaces.authoring.asset import AssetSource, URDFAsset, USDAsset
 from simulo.interfaces.authoring.checkpoint import PolicyCheckpoint
 from simulo.interfaces.authoring.entity import AssetEntity, Entity
-from simulo.interfaces.authoring.light import DistantLight, DomeLight, Light, LightConfig
+from simulo.interfaces.authoring.light import (
+    DistantLight,
+    DomeLight,
+    Light,
+    LightConfig,
+)
 from simulo.interfaces.authoring.materials import Material, SurfaceMaterial
 from simulo.interfaces.authoring.physics import (
     Collision,
@@ -99,6 +103,7 @@ from simulo.interfaces.authoring.physics import (
     Physics,
     RigidPhysics,
 )
+from simulo.interfaces.authoring.policy_inputs import PolicyInput, PolicyInputSchema
 from simulo.interfaces.authoring.pose import Pose
 from simulo.interfaces.authoring.primitives import (
     Cone,
@@ -108,10 +113,17 @@ from simulo.interfaces.authoring.primitives import (
     Sphere,
     Transform,
 )
-from simulo.interfaces.authoring.prop import PropProtocol, PropStateProtocol
+from simulo.interfaces.authoring.prop import PropProtocol, PropStateProtocol, VariantPropProtocol
+from simulo.interfaces.authoring.properties import (
+    ExternalForceProtocol,
+    PropPropertiesProtocol,
+    RobotPropertiesProtocol,
+    SceneGravityProtocol,
+)
 from simulo.interfaces.authoring.record import RecordConfig
 from simulo.interfaces.authoring.robot import RobotProtocol, RobotStateProtocol
-from simulo.interfaces.authoring.scene import SceneGroupProtocol, SceneProtocol
+from simulo.interfaces.authoring.robot_config import ActuatorGainsConfig, ArticulationConfig, JointConfig
+from simulo.interfaces.authoring.scene import SceneGroupProtocol, SceneProtocol, SceneVariantsProtocol
 from simulo.interfaces.authoring.sensor import CameraProtocol
 from simulo.interfaces.authoring.terrain import (
     GroundPlane,
@@ -120,9 +132,11 @@ from simulo.interfaces.authoring.terrain import (
     Terrain,
     TerrainConfig,
 )
+from simulo.interfaces.authoring.variants import ObjectVariants
 from simulo.interfaces.authoring.visual import (
     ArrowMarker,
     AxesMarker,
+    LineMarker,
     PointMarker,
     SphereMarker,
     Visual,
@@ -175,22 +189,39 @@ __all__ = [
     "RecordConfig",
     # injected policy input (dependency-free; loading is deferred to execution)
     "PolicyCheckpoint",
+    "PolicyInput",
+    "PolicyInputSchema",
     # visual
     "VisualMarkerBase",
     "AxesMarker",
     "SphereMarker",
     "ArrowMarker",
     "PointMarker",
+    "LineMarker",
     "Visual",
     # scene (MIRROR — the concrete classes live in the backend package)
+    "SceneGravityProtocol",
     "SceneProtocol",
     "SceneGroupProtocol",
+    "SceneVariantsProtocol",
+    # scene variants (dependency-free authoring data)
+    "ObjectVariants",
+    # robot configuration (dependency-free owning definitions)
+    "ActuatorGainsConfig",
+    "ArticulationConfig",
+    "JointConfig",
     # robot / prop / sensor / actuator (MIRROR — the concrete classes live in
     # the backend package and explicitly inherit these Protocols)
+    "ExternalForceProtocol",
+    "RobotPropertiesProtocol",
+    "PropPropertiesProtocol",
     "RobotProtocol",
     "RobotStateProtocol",
     "PropProtocol",
     "PropStateProtocol",
+    "VariantPropProtocol",
     "CameraProtocol",
     "ActuatorProtocol",
+    # action-to-joint metadata
+    "ActionChannel",
 ]

simulo_interfaces-0.25.0/src/simulo/interfaces/authoring/action_channel.py

@@ -0,0 +1,22 @@
+"""Dependency-free metadata for a policy action column."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+ActionKind = Literal["position", "velocity", "effort", "command"]
+
+
+@dataclass(frozen=True)
+class ActionChannel:
+    """One named policy action and the command it represents.
+
+    ``joint`` is ``None`` for a task-level command. Resolver code validates
+    the value against a task's action width and the engine's available joints.
+    """
+
+    name: str
+    joint: str | None
+    kind: ActionKind
+    scale: float = 1.0
+    offset: float = 0.0
+    hold_steps: int = 1

simulo_interfaces-0.25.0/src/simulo/interfaces/authoring/policy_inputs.py

@@ -0,0 +1,207 @@
+"""Dependency-free declarations for raw actor and critic inputs.
+
+Images must be batched RGB uint8 NHWC. The contract requires future trainer
+and export consumers to convert the current minibatch to NCHW float and divide
+by 255; ``center`` also subtracts 0.5. These transforms belong in the actor's
+graph. This module checks declarations and raw values, not graph behavior.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from typing import Any, Literal
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PolicyInput:
+    """One named input, with ``shape`` excluding the environment batch.
+
+    Names match ``[A-Za-z][A-Za-z0-9_]*``; shape dimensions are positive.
+    Tuple and list shapes are accepted and stored as tuples. Defaults are
+    ``dtype="float32"``, ``kind="numeric"`` and ``preprocessing="none"``.
+    Numeric inputs require float32, no camera and no preprocessing. Image
+    inputs require uint8, shape ``(H, W, 3)`` and a nonblank camera scene name:
+    the last segment of ``scene.add(camera, at="/World/<name>")``. Full paths
+    are rejected. LearningEnv setup requires that camera's purpose to be
+    ``"policy"``. Two policy cameras cannot share a scene name.
+    """
+
+    name: str
+    shape: tuple[int, ...]
+    dtype: str = "float32"
+    kind: Literal["numeric", "image"] = "numeric"
+    camera: str | None = None
+    preprocessing: Literal["none", "center"] = "none"
+
+    def __post_init__(self) -> None:
+        label = f"Input {self.name!r}"
+        if isinstance(self.shape, list):
+            object.__setattr__(self, "shape", tuple(self.shape))
+        if not isinstance(self.name, str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", self.name):
+            raise ValueError(f"{label}: name must start with a letter and contain only letters, digits or underscores.")
+        if (
+            not isinstance(self.shape, tuple)
+            or not self.shape
+            or any(type(dim) is not int or dim <= 0 for dim in self.shape)
+        ):
+            raise ValueError(f"{label}: shape must be a nonempty tuple of positive dimensions, excluding batch.")
+        if self.kind not in ("numeric", "image"):
+            raise ValueError(f"{label}: kind must be 'numeric' or 'image'.")
+        if self.preprocessing not in ("none", "center"):
+            raise ValueError(f"{label}: preprocessing must be 'none' or 'center'.")
+        if self.kind == "image":
+            if self.dtype != "uint8":
+                raise ValueError(f"{label}: image dtype must be uint8 RGB NHWC, got {self.dtype!r}.")
+            if len(self.shape) != 3 or self.shape[-1] != 3:
+                raise ValueError(f"{label}: image shape must be (H, W, 3) RGB NHWC, excluding batch, got {self.shape}.")
+            if not isinstance(self.camera, str) or not self.camera.strip():
+                raise ValueError(f"{label}: image inputs require a camera identity.")
+            if "/" in self.camera or self.camera != self.camera.strip():
+                raise ValueError(f"{label}: camera must be a scene name, the last segment of scene.add(..., at=...).")
+        elif self.dtype != "float32" or self.camera is not None or self.preprocessing != "none":
+            raise ValueError(f"{label}: numeric inputs require float32, no camera, and preprocessing='none'.")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return JSON metadata, converting the stored tuple shape to a list."""
+        return {**asdict(self), "shape": list(self.shape)}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> PolicyInput:
+        """Parse JSON, converting list shapes to tuples; reject unknown fields."""
+        if not isinstance(value, Mapping):
+            raise ValueError("Input declaration must be an object.")
+        allowed = {"name", "shape", "dtype", "kind", "camera", "preprocessing"}
+        if set(value) - allowed or not {"name", "shape"} <= set(value):
+            raise ValueError(f"Input {value.get('name')!r}: declaration has missing or unknown fields.")
+        shape = value["shape"]
+        if not isinstance(shape, (list, tuple)):
+            raise ValueError(f"Input {value['name']!r}: shape must be an array of positive dimensions.")
+        return cls(**{**value, "shape": tuple(shape)})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PolicyInputSchema:
+    """Ordered actor inputs and optional separate training-only critic inputs.
+
+    ``critic=None`` means the critic uses exactly the actor declarations.
+    Future export and playback consumers must use only ``actor``. A critic
+    declaration sharing an actor name must be identical. Actor inputs omitted
+    from an explicit critic are not supplied to that critic. Order is part of
+    checkpoint compatibility, including numeric concatenation order.
+    """
+
+    actor: tuple[PolicyInput, ...]
+    critic: tuple[PolicyInput, ...] | None = None
+
+    def __post_init__(self) -> None:
+        for role, inputs in (("actor", self.actor), ("critic", self.critic_inputs)):
+            if not isinstance(inputs, tuple) or not inputs:
+                raise ValueError(f"{role} inputs must be a nonempty tuple of PolicyInput declarations.")
+            seen: set[str] = set()
+            for spec in inputs:
+                if not isinstance(spec, PolicyInput):
+                    raise ValueError(f"{role} inputs must contain PolicyInput declarations.")
+                if spec.name in seen:
+                    raise ValueError(f"{role} input {spec.name!r}: duplicate input name.")
+                seen.add(spec.name)
+        actor = {spec.name: spec for spec in self.actor}
+        for spec in self.critic_inputs:
+            if spec.name in actor and spec != actor[spec.name]:
+                raise ValueError(
+                    f"critic input {spec.name!r}: declaration contradicts the actor input of the same name."
+                )
+
+    @property
+    def critic_inputs(self) -> tuple[PolicyInput, ...]:
+        """Effective critic declarations, defaulting to actor inputs."""
+        return self.actor if self.critic is None else self.critic
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the actor/critic schema for a checkpoint sidecar."""
+        return {
+            "actor": [spec.to_dict() for spec in self.actor],
+            "critic": None if self.critic is None else [spec.to_dict() for spec in self.critic],
+        }
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> PolicyInputSchema:
+        """Parse a schema without permitting undeclared metadata."""
+        if not isinstance(value, Mapping) or set(value) != {"actor", "critic"}:
+            raise ValueError("Policy input schema requires exactly actor and critic fields.")
+        actor, critic = value["actor"], value["critic"]
+        if not isinstance(actor, (list, tuple)) or (critic is not None and not isinstance(critic, (list, tuple))):
+            raise ValueError("Policy input schema actor and critic must be arrays (critic may be null).")
+        return cls(
+            actor=tuple(PolicyInput.from_dict(spec) for spec in actor),
+            critic=None if critic is None else tuple(PolicyInput.from_dict(spec) for spec in critic),
+        )
+
+    @property
+    def fingerprint(self) -> str:
+        """SHA-256 of ordered inputs, including camera and preprocessing.
+
+        An omitted critic and an explicitly identical critic are equivalent.
+        Batch size is absent, so a checkpoint can change parallelism.
+        """
+
+        def canonical(spec: PolicyInput) -> dict[str, Any]:
+            # Pin v1's subset: future defaulted fields do not invalidate hashes.
+            return {name: getattr(spec, name) for name in ("name", "shape", "dtype", "kind", "camera", "preprocessing")}
+
+        metadata = {
+            "version": "simulo.policy-input-fingerprint.v1",
+            "actor": [canonical(spec) for spec in self.actor],
+            "critic": [canonical(spec) for spec in self.critic_inputs],
+        }
+        return hashlib.sha256(json.dumps(metadata, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+    def validate_values(
+        self,
+        actor: Any,
+        critic: Any,
+        *,
+        batch_size: int | None = None,
+    ) -> None:
+        """Check raw names, shapes, dtypes and batch size at LearningEnv._init_spaces.
+
+        Values need only ``shape`` and ``dtype`` attributes. No engine or tensor
+        package is imported. One declared numeric input may use the legacy
+        tensor return; multiple or image inputs require a named mapping. Values
+        must have a leading num_envs batch. Failures raise ValueError naming the
+        role and input. Legacy tasks with no schema are not checked by setup.
+        """
+        expected_batch = batch_size
+        for role, specs, values in (("actor", self.actor, actor), ("critic", self.critic_inputs, critic)):
+            if not isinstance(values, Mapping):
+                if len(specs) != 1 or specs[0].kind != "numeric":
+                    raise ValueError(f"{role} input {specs[0].name!r}: named inputs require a mapping.")
+                values = {specs[0].name: values}
+            declared = {spec.name for spec in specs}
+            for name in values:
+                if name not in declared:
+                    raise ValueError(f"{role} input {name!r}: unknown input name.")
+            for spec in specs:
+                if spec.name not in values:
+                    raise ValueError(f"{role} input {spec.name!r}: missing input.")
+                value = values[spec.name]
+                shape = tuple(getattr(value, "shape", ()))
+                if (
+                    len(shape) != len(spec.shape) + 1
+                    or shape[1:] != spec.shape
+                    or type(shape[0]) is not int
+                    or shape[0] <= 0
+                ):
+                    raise ValueError(
+                        f"{role} input {spec.name!r}: expected batched shape (N, {spec.shape}), got {shape}."
+                    )
+                if expected_batch is None:
+                    expected_batch = shape[0]
+                if shape[0] != expected_batch:
+                    raise ValueError(f"{role} input {spec.name!r}: expected batch {expected_batch}, got {shape[0]}.")
+                dtype = str(getattr(value, "dtype", "")).removeprefix("torch.")
+                if dtype != spec.dtype:
+                    raise ValueError(f"{role} input {spec.name!r}: expected dtype {spec.dtype}, got {dtype!r}.")

{simulo_interfaces-0.23.0 → simulo_interfaces-0.25.0}/src/simulo/interfaces/authoring/prop.py

@@ -154,15 +154,21 @@ class PropProtocol(Protocol):
 
     @property
     def default_pose(self) -> TensorLike:
-        """The prop's spawn pose in the **world** frame, ``(num_envs, 7)``.
+        """The prop's spawn pose in the **world** frame.
 
-        The pose the prop was authored at, already offset by each
-        environment's own origin — so it is directly comparable with
-        ``state.pose`` and directly usable as the base for a randomised
-        reset. Index it with the environments being reset
-        (``prop.default_pose[env_ids]``), perturb, and write it back with
+        For a prop added with ``per_environment=True`` (the default), the pose
+        has shape ``(num_envs, 7)`` and includes each environment's origin, so
+        it is directly comparable with ``state.pose`` and directly usable as
+        the base for a randomised reset. Index it with the environments being
+        reset (``prop.default_pose[env_ids]``), perturb, and write it back with
         :meth:`set_pose`.
 
+        For a prop added with ``per_environment=False``, this is one row
+        containing its authored world pose with no environment origin. A
+        shared prop is supported only when the scene has one environment;
+        scene building refuses ``per_environment=False`` for a prop when
+        ``num_envs > 1``.
+
         Raises ``RuntimeError`` until the simulation runtime has attached the
         prop.
         """
@@ -208,3 +214,21 @@ class PropProtocol(Protocol):
                 environment.
         """
         ...
+
+
+@runtime_checkable
+class VariantPropProtocol(PropProtocol, Protocol):
+    """The opt-in prop surface for a scene item with per-copy variants.
+
+    :class:`PropProtocol` remains the legacy-compatible pose contract. A task
+    that chooses scene variants depends on this narrower capability instead.
+    """
+
+    @property
+    def variant_index(self) -> TensorLike:
+        """Active option index for every environment copy, shape ``(num_envs,)``."""
+        ...
+
+    def set_variant(self, index: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Switch selected copies to an option index. Supported for pool variants."""
+        ...

simulo_interfaces-0.25.0/src/simulo/interfaces/authoring/properties.py

@@ -0,0 +1,92 @@
+"""Optional per-copy physics capabilities, independent of the base authoring protocols.
+
+Backends opt into each capability they implement. The frozen legacy backend
+continues to satisfy RobotProtocol, PropProtocol and SceneProtocol without them.
+K is the number of selected copies; B, S and J are body, shape and joint counts.
+"""
+
+from typing import Optional, Protocol, runtime_checkable
+
+from simulo.interfaces.runtime.tensors import TensorLike
+
+
+@runtime_checkable
+class RobotPropertiesProtocol(Protocol):
+    """Per-copy articulation properties supported by the engine backend."""
+
+    def set_mass(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set link mass, shape ``(K, B)``, for selected copies."""
+        ...
+
+    def set_center_of_mass(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set link centres of mass in body frames, shape ``(K, B, 3)``."""
+        ...
+
+    def set_friction(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set shape friction, shape ``(K, S)``, for selected copies."""
+        ...
+
+    def set_restitution(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set shape restitution, shape ``(K, S)``, for selected copies."""
+        ...
+
+    def set_joint_gains(
+        self,
+        stiffness: TensorLike,
+        damping: TensorLike,
+        env_ids: Optional[TensorLike] = ...,
+    ) -> None:
+        """Set joint stiffness and damping, each shape ``(K, J)``."""
+        ...
+
+    def set_joint_armature(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set output-side joint armature, shape ``(K, J)``, for selected copies."""
+        ...
+
+
+@runtime_checkable
+class PropPropertiesProtocol(Protocol):
+    """Per-copy rigid-prop properties supported by the engine backend."""
+
+    def set_mass(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set the prop body mass, shape ``(K, 1)``, for selected copies."""
+        ...
+
+    def set_center_of_mass(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set the prop centre of mass in its body frame, shape ``(K, 1, 3)``."""
+        ...
+
+    def set_friction(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set prop-shape friction, shape ``(K, S)``, for selected copies."""
+        ...
+
+    def set_restitution(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set prop-shape restitution, shape ``(K, S)``, for selected copies."""
+        ...
+
+    def set_scale(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set primitive-shape scale, shape ``(K, S, 3)``, for selected copies."""
+        ...
+
+
+@runtime_checkable
+class ExternalForceProtocol(Protocol):
+    """World-frame forces and torques for selected copies of an entity."""
+
+    def apply_external_force(
+        self,
+        forces: TensorLike,
+        torques: TensorLike,
+        env_ids: Optional[TensorLike] = ...,
+    ) -> None:
+        """Apply forces and torques, each shape ``(K, B, 3)``; props have B=1."""
+        ...
+
+
+@runtime_checkable
+class SceneGravityProtocol(Protocol):
+    """Per-copy gravity supported by the engine backend."""
+
+    def set_gravity(self, values: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Set world-frame gravity, shape ``(K, 3)``, for selected copies."""
+        ...

{simulo_interfaces-0.23.0 → simulo_interfaces-0.25.0}/src/simulo/interfaces/authoring/record.py

@@ -195,6 +195,11 @@ class RecordConfig:
     profile precedence can distinguish "user passed False" from "default
     None". Do not edit defaults to plain ``bool`` — the silent-default
     mitigation depends on the tri-state.
+
+    ``record_all_envs`` expands numeric recording data only. Policy camera
+    video always uses ``env_indices`` (default: environment 0), so host frame
+    buffers and encoder count are bounded by the selected environments and
+    declared cameras, independently of the total environment count.
     """
 
     output_path: Optional[Union[str, "os.PathLike[str]", Path]] = None

{simulo_interfaces-0.23.0 → simulo_interfaces-0.25.0}/src/simulo/interfaces/authoring/robot.py

@@ -64,6 +64,7 @@ from typing import Any, Dict, List, Optional, Protocol, Tuple, runtime_checkable
 
 from simulo.interfaces.authoring.asset import AssetSource
 from simulo.interfaces.authoring.pose import Pose
+from simulo.interfaces.authoring.robot_config import ArticulationConfig, JointConfig
 from simulo.interfaces.runtime.tensors import TensorLike
 
 
@@ -183,17 +184,21 @@ class RobotProtocol(Protocol):
     scale: Tuple[float, float, float]
     """Per-axis spawn scale factor."""
 
-    articulation: Any
+    articulation: ArticulationConfig
     """Articulation physics and control configuration."""
 
-    joint_config: Optional[List[Any]]
+    joint_config: Optional[List[JointConfig]]
     """Optional per-joint configurations."""
 
     disable_gravity: bool
     """If ``True``, gravity is disabled for this robot."""
 
     actuator_gains: Optional[Dict[str, Any]]
-    """Optional mapping of actuator-group names to gain configurations."""
+    """Optional mapping of actuator-group names to gain configurations.
+
+    Catalog robots support only the ``"all_joints"`` key; other keys are ignored
+    with a warning.
+    """
 
     # -- Identity and attachment ------------------------------------------
 
@@ -257,12 +262,19 @@ class RobotProtocol(Protocol):
 
     @property
     def default_pose(self) -> TensorLike:
-        """Base pose that :meth:`reset` writes in the world frame, shape
-        ``(num_envs, 7)`` with columns ``[x, y, z, qw, qx, qy, qz]``:
-        position in m followed by a w-first unit quaternion. Each
-        environment's origin is included. Available from ``on_start``
-        onward. Each read returns a new tensor, so writing into it cannot
-        change a later reset."""
+        """Base pose that :meth:`reset` writes in the world frame.
+
+        Columns are ``[x, y, z, qw, qx, qy, qz]``: position in m followed by a
+        w-first unit quaternion. For a robot added with
+        ``per_environment=True`` (the default), the shape is ``(num_envs, 7)``
+        and each environment's origin is included. For a robot added with
+        ``per_environment=False``, this is one row containing its authored
+        world pose with no environment origin. A shared robot is supported
+        only when the scene has one environment; scene building refuses
+        ``per_environment=False`` for a robot when ``num_envs > 1``. Available
+        from ``on_start`` onward. Each read returns a new tensor, so writing
+        into it cannot change a later reset.
+        """
         ...
 
     @property