OrcaGym

https://openverse-orca.github.io/OrcaGym.github.io
Admin
OrcaGym is a Gymnasium-based reinforcement learning environment that integrates MuJoCo physics...
Tokens:57,138
Snippets:379
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Initialize and Reset OrcaGym Environment using Gymnasium

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

Demonstrates the initialization and reset of an OrcaGym environment using the Gymnasium library. It shows how to create an environment instance with specific configurations and then perform an initial reset to get the starting observation and info.

```python
import gymnasium as gym

# 使用已注册的 env_id（例如任务环境 ID）
env = gym.make(
    "YOUR_ENV_ID",
    frame_skip=5,
    orcagym_addr="localhost:50051",
    agent_names=["agent0"],
    time_step=0.001,
    render_mode="none",
)

obs, info = env.reset()
print("obs keys/type:", type(obs), getattr(obs, "keys", lambda: None)())

```

--------------------------------

### Initialize Model State (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Initializes the model's position (qpos) and velocity (qvel). This method is crucial for setting the starting configuration of the simulated system before an episode begins.

```python
def init_qpos_qvel(self) -> None:
    """Initializes the model's joint positions (qpos) and velocities (qvel).
    """
    # Sets the initial state of the simulated model.
```

--------------------------------

### Joint Address Querying

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Methods to get the starting address (index) of joint data within the global `qpos`, `qvel`, and `qacc` arrays.

```APIDOC
## OrcaGymLocal.jnt_qposadr

### Description
Queries the starting address (index) of a joint within the `qpos` array. This is useful for directly accessing a specific joint's position data.

### Method
`jnt_qposadr(self, joint_name)`

### Parameters
#### Arguments
- **joint_name** (str) - The name of the joint.

### Returns
- int: The starting index of the joint's data in the `qpos` array.

### Notes
- The address remains constant after the model is loaded.

## OrcaGymLocal.jnt_dofadr

### Description
Queries the starting address (index) of a joint within the `qvel` or `qacc` arrays. This helps in accessing a specific joint's velocity or acceleration data.

### Method
`jnt_dofadr(self, joint_name)`

### Parameters
#### Arguments
- **joint_name** (str) - The name of the joint.

### Returns
- int: The starting index of the joint's data in the `qvel` or `qacc` arrays.

### Notes
- The address remains constant after the model is loaded.
```

--------------------------------

### Construct Simple Observation from qpos and qvel in Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

This code snippet shows how to create a basic observation by concatenating the generalized positions (qpos) and velocities (qvel) from the environment's data. This is a common starting point for observation construction, though real-world applications often involve normalization or more complex feature engineering. It assumes the environment's data has been updated.

```python
import numpy as np

# Assuming 'env' is an initialized OrcaGym environment instance and data is updated
qpos = env.data.qpos.copy()  # Use .copy() to prevent modification issues
qvel = env.data.qvel.copy()

# Simple observation: concatenate qpos and qvel
# In practice, normalization or clipping might be applied
obs = np.concatenate([qpos, qvel]).astype(np.float32)
```

--------------------------------

### Start Video Recording

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Initiates video recording to a specified file path. Supports asynchronous (ASYNC) capture for higher performance with potentially misaligned frames, and synchronous (SYNC) capture for frame-accurate recording at the cost of performance. Recording is stopped by calling `stop_save_video()`.

```python
async def begin_save_video(self, file_path, capture_mode=CaptureMode.ASYNC)

```

```

--------------------------------

### Get All Site Dictionaries - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the dictionary containing all sites defined in the model. This provides access to all marker positions and properties.

```python
def get_site_dict(self)

```

--------------------------------

### OrcaGymModel: Initialize Model Info (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Initializes the basic model information, including dimension parameters like nq (generalized coordinates), nv (degrees of freedom), nu (actuators), and ngeom (geometries). This is a crucial step during environment setup.

```python
def init_model_info(self, model_info):
    # ... implementation details ...
    pass
```

--------------------------------

### Save Video

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Manages video recording. `begin_save_video` starts recording to a specified file path with options for asynchronous or synchronous capture. `stop_save_video` halts the recording process.

```APIDOC
## OrcaGymLocal.begin_save_video

### Description
Starts saving the simulation video to a specified file path. You can choose between asynchronous capture (higher performance, potentially less frame alignment) or synchronous capture (ensures frame alignment with simulation steps, lower performance).

### Method
`async def begin_save_video(self, file_path, capture_mode=CaptureMode.ASYNC)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file_path** (str) - Required - The path where the video file will be saved (e.g., "output.mp4").
- **capture_mode** (CaptureMode) - Optional - The capture mode, either `CaptureMode.ASYNC` (default) or `CaptureMode.SYNC`.

### Request Example
```python
# Start saving video asynchronously
await self.gym.begin_save_video('simulation_output.mp4')

# Start saving video synchronously
await self.gym.begin_save_video('aligned_simulation.mp4', capture_mode=CaptureMode.SYNC)

```

```APIDOC
## OrcaGymLocal.stop_save_video

### Description
Stops the video recording process that was initiated by `begin_save_video()`. The video file will be finalized upon calling this method.

### Method
`async def stop_save_video(self)`

### Parameters
None

### Request Example
```python
# Assuming video recording has started
await self.gym.stop_save_video()

```

--------------------------------

### Get Prefixed Site Name (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Retrieves the name of a site, prefixed with the agent's identifier if specified. This function aids in referencing specific sites associated with individual agents.

```python
def site(self, name, agent_id=None) -> str:
    """Gets the site name with an agent prefix.

    Args:
        name: The base name of the site.
        agent_id: Optional identifier for the agent.

    Returns:
        The prefixed site name.
    """
    # Example: If agent_id is 'agent1' and name is 'marker', it might return 'agent1_marker'.
```

--------------------------------

### Query Contact Information and Forces in OrcaGym

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

This Python code demonstrates how to retrieve contact information and corresponding forces from the OrcaGym environment. It first queries for active contacts using `query_contact_simple()`, then uses the contact IDs to get detailed force data with `query_contact_force()`. Alternatively, `get_cfrc_ext()` can be used to directly query external constraint forces on bodies. Requires the environment data to be updated.

```python
# Assuming 'env' is an initialized OrcaGym environment instance and data is updated

# Get a list of current contacts
contacts = env.query_contact_simple()
contact_ids = [c["ID"] for c in contacts]

# If there are contacts, query their forces
if contact_ids:
    forces = env.query_contact_force(contact_ids)
    first_id = contact_ids[0]
    print(f"First contact force (6D vector): {forces[first_id]}")

# Alternatively, get external constraint forces for all bodies
cfrc_ext = env.get_cfrc_ext()
print(f"Shape of cfrc_ext (nbody, 6): {cfrc_ext.shape}")
```

--------------------------------

### Get Camera Frame PNG and Pose

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Fetches the PNG image of the current camera frame along with its pose information (position and orientation). Returns a dictionary mapping camera names to their pose details ('pos' and 'quat').

```python
async def get_frame_png(self, image_path)

```

```

--------------------------------

### Get Site Information by Name or ID - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves information about a specific site using either its name or its numerical ID. This is a versatile method for accessing site data.

```python
def get_site(self, name_or_id)

```

--------------------------------

### Get Environment Time Step (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Returns the environment's time step (dt), which is the duration of one simulation step in the RL environment. It's calculated as the physics timestep multiplied by frame_skip. This value is crucial for accurate time integration and control frequency calculations.

```python
def dt(self) -> float:
    """Gets the environment time step (physics timestep * frame_skip).

    Returns:
        The duration of one environment step in seconds.
    """
    # Example usage:
    # REALTIME_STEP = TIME_STEP * FRAME_SKIP * ACTION_SKIP
    # CONTROL_FREQ = 1 / REALTIME_STEP  # e.g., 50 Hz
    # In a loop:
    # dt = env.dt
    # sim_time += dt
```

--------------------------------

### Get Prefixed Joint Name (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Retrieves the name of a joint, prefixed with the agent's identifier if specified. This function helps in uniquely identifying joints across different agents in a multi-agent setup.

```python
def joint(self, name, agent_id=None) -> str:
    """Gets the joint name with an agent prefix.

    Args:
        name: The base name of the joint.
        agent_id: Optional identifier for the agent.

    Returns:
        The prefixed joint name.
    """
    # Example: If agent_id is 'agent1' and name is 'shoulder_joint', it might return 'agent1_shoulder_joint'.
```

--------------------------------

### Standard Gymnasium Step Loop with OrcaGym

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

Illustrates a typical training loop using the Gymnasium `step` function with an OrcaGym environment. It includes sampling actions from the action space, stepping the environment, and handling episode termination or truncation by resetting the environment.

```python
import numpy as np
import gymnasium as gym

env = gym.make(
    "YOUR_ENV_ID",
    frame_skip=5,
    orcagym_addr="localhost:50051",
    agent_names=["agent0"],
    time_step=0.001,
    render_mode="none",
)
osb, info = env.reset()

for _ in range(100):
    # 最稳妥：从 action_space 采样，保证 shape/范围正确
    action = env.action_space.sample().astype(np.float32)
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()

```

--------------------------------

### Get Joint qvel/qacc Address

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Returns the starting address (index) of a specific joint within the qvel or qacc arrays. This function helps in locating joint velocity and acceleration data by index.

```python
def jnt_dofadr(self, joint_name):
    """查询关节在 `qvel/qacc` 数组中的起始地址。
    参数：
      * `joint_name`：关节名称

    返回：
      * `qvel/qacc` 数组中的起始索引（int）

    说明：
      * 用于定位关节在全局 `qvel/qacc` 数组中的位置。
      * 与 `query_joint_offsets` 类似，但只返回单个关节的地址。

    注意：
      * 地址在模型加载后保持不变。
    """
    pass
```

--------------------------------

### Get Joint qpos Address

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Returns the starting address (index) of a specific joint within the global qpos array. This is useful for direct manipulation or querying of joint data when working with indices.

```python
def jnt_qposadr(self, joint_name):
    """查询关节在 `qpos` 数组中的起始地址。
    参数：
      * `joint_name`：关节名称

    返回：
      * `qpos` 数组中的起始索引（int）

    说明：
      * 用于定位关节在全局 `qpos` 数组中的位置。
      * 与 `query_joint_offsets` 类似，但只返回单个关节的地址。

    注意：
      * 地址在模型加载后保持不变。
    """
    pass
```

--------------------------------

### Local Environment Implementation

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

Details on OrcaGymLocalEnv, which provides a local gRPC environment implementation.

```APIDOC
## POST /env/local/initialize_simulation

### Description
Initializes the simulation backend for the local environment by loading the model XML and initializing the MuJoCo data.

### Method
POST

### Endpoint
/env/local/initialize_simulation

### Response
#### Success Response (200)
- **model** (object) - The MuJoCo model object.
- **data** (object) - The MuJoCo data object.
```

--------------------------------

### OrcaGymModel: Get Equality Constraint List (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the current list of equality constraints. This allows for inspection and modification of constraints, for example, to change the target body of a constraint during runtime for object interaction.

```python
def get_eq_list(self):
    # ... implementation details ...
    pass

# Example usage:
# eq_list = self.model.get_eq_list()
# for eq in eq_list:
#     if eq["obj1_id"] == self._anchor_body_id:
#         # Modify constraint target
#         eq["obj2_id"] = self.model.body_name2id(actor_name)
```

--------------------------------

### Initialize Site Dictionary - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Initializes the site dictionary, establishing mappings for sites within the model. Sites are markers used for querying positions and orientations, not involved in physics simulation.

```python
def init_site_dict(self, site_dict)

# Example usage:
# Sites are automatically initialized during model loading.
# Querying sites:
site_pos, site_quat = self.query_site_pos_and_quat(["end_effector"])
```

--------------------------------

### Query Joint DOF Addresses in OrcaGymLocal

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Queries the starting addresses of specified joints within the `qvel/qacc` arrays. It accepts a list of joint names and returns a dictionary where keys are joint names and values are their corresponding starting indices. This is crucial for accessing joint-specific data in global arrays.

```python
def query_joint_dofadrs(self, joint_names):
    """
    查询指定关节在 `qvel/qacc` 数组中的起始地址。
    参数：
      * `joint_names`：关节名称列表


    返回：
      * 字典，键为关节名称，值为 `qvel/qacc` 数组中的起始索引


    说明：
      * 用于定位关节在全局 `qvel/qacc` 数组中的位置。
      * 与 `query_joint_offsets` 类似，但只返回 DOF 地址。


    注意：
      * 地址在模型加载后保持不变。
    """
    pass
```

--------------------------------

### Human Rendering and UI Control in OrcaGym

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

Demonstrates how to use `render_mode='human'` in OrcaGym to enable UI interactions and control overrides. Periodic rendering is essential for these interactive elements to be processed and reflected in the simulation's control loop.

```python
import time
import gymnasium as gym

env = gym.make(
    "YOUR_ENV_ID",
    frame_skip=5,
    orcagym_addr="localhost:50051",
    agent_names=["agent0"],
    time_step=0.001,
    render_mode="human",
)
env.reset()

# 在 human 模式下周期 render，UI 侧的交互/override 才会被处理并回传
for _ in range(200):
    env.render()
    time.sleep(env.dt)

```

--------------------------------

### Get Agent Count (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Returns the total number of agents in the simulation. This property is essential for understanding the scale of the multi-agent environment.

```python
def agent_num(self) -> int:
    """Gets the number of agents in the environment.

    Returns:
        The integer count of agents.
    """
    # This property is likely read-only and reflects the environment's configuration.
```

--------------------------------

### OrcaGymBaseEnv Class Methods

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Documentation for the methods available in the OrcaGymBaseEnv class, which serves as the base class for all OrcaGym environments.

```APIDOC
## OrcaGymBaseEnv Methods

### `step`

#### Description
Performs a simulation step with the given action.

#### Method
`step(self, action)`

#### Parameters
*   **action** (Any) - The action to be applied in the environment.

#### Returns
- **observation** (NDArray[np.float64]) - The observation after the step.
- **reward** (np.float64) - The reward received after the step.
- **terminated** (bool) - Whether the episode has terminated.
- **truncated** (bool) - Whether the episode has been truncated.
- **info** (Dict[str, np.float64]) - Additional information.

### `reset_model`

#### Description
Resets the robot degrees of freedom (qpos and qvel).

#### Method
`reset_model(self) -> tuple[dict, dict]`

#### Returns
- **qpos** (dict) - The reset joint positions.
- **qvel** (dict) - The reset joint velocities.

### `initialize_simulation`

#### Description
Initializes MuJoCo simulation data structures mjModel and mjData.

#### Method
`initialize_simulation(self) -> Tuple[OrcaGymModel, OrcaGymData]`

#### Returns
- **model** (OrcaGymModel) - The initialized MuJoCo model.
- **data** (OrcaGymData) - The initialized MuJoCo data.

### `render`

#### Description
Renders a frame from the MuJoCo simulation based on the render_mode.

#### Method
`render(self) -> Union[NDArray[np.float64], None]`

#### Returns
- **frame** (NDArray[np.float64] or None) - The rendered frame or None if rendering is not supported.

### `generate_action_space`

#### Description
Generates the action space for the environment.

#### Method
`generate_action_space(self, bounds)`

#### Parameters
*   **bounds** (Any) - The bounds for the action space.

#### Returns
- **space** (Space) - The generated action space.

### `generate_observation_space`

#### Description
Generates the observation space for the environment.

#### Method
`generate_observation_space(self, obs) -> spaces.Space`

#### Parameters
*   **obs** (Any) - An example observation to infer the space.

#### Returns
- **space** (spaces.Space) - The generated observation space.

### `reset`

#### Description
Resets the environment to an initial state.

#### Method
`reset(self, *, seed=None, options=None)`

#### Parameters
*   **seed** (int, optional) - The seed for randomization. Defaults to None.
*   **options** (dict, optional) - Additional options for resetting. Defaults to None.

### `set_seed_value`

#### Description
Sets the random number seed.

#### Method
`set_seed_value(self, seed=None)`

#### Parameters
*   **seed** (Any, optional) - The seed value. Defaults to None.

### `body`

#### Description
Gets the body name with an agent prefix.

#### Method
`body(self, name, agent_id=None) -> str`

#### Parameters
*   **name** (str) - The name of the body.
*   **agent_id** (int, optional) - The ID of the agent. Defaults to None.

#### Returns
- **prefixed_name** (str) - The prefixed body name.

### `joint`

#### Description
Gets the joint name with an agent prefix.

#### Method
`joint(self, name, agent_id=None) -> str`

#### Parameters
*   **name** (str) - The name of the joint.
*   **agent_id** (int, optional) - The ID of the agent. Defaults to None.

#### Returns
- **prefixed_name** (str) - The prefixed joint name.

### `actuator`

#### Description
Gets the actuator name with an agent prefix.

#### Method
`actuator(self, name, agent_id=None) -> str`

#### Parameters
*   **name** (str) - The name of the actuator.
*   **agent_id** (int, optional) - The ID of the agent. Defaults to None.

#### Returns
- **prefixed_name** (str) - The prefixed actuator name.

### `site`

#### Description
Gets the site name with an agent prefix.

#### Method
`site(self, name, agent_id=None) -> str`

#### Parameters
*   **name** (str) - The name of the site.
*   **agent_id** (int, optional) - The ID of the agent. Defaults to None.

#### Returns
- **prefixed_name** (str) - The prefixed site name.

### `mocap`

#### Description
Gets the mocap name with an agent prefix.

#### Method
`mocap(self, name, agent_id=None) -> str`

#### Parameters
*   **name** (str) - The name of the mocap.
*   **agent_id** (int, optional) - The ID of the agent. Defaults to None.

#### Returns
- **prefixed_name** (str) - The prefixed mocap name.

### `sensor`

#### Description
Gets the sensor name with an agent prefix.

#### Method
`sensor(self, name, agent_id=None) -> str`

#### Parameters
*   **name** (str) - The name of the sensor.
*   **agent_id** (int, optional) - The ID of the agent. Defaults to None.

#### Returns
- **prefixed_name** (str) - The prefixed sensor name.

### `dt` (property)

#### Description
Gets the time step of the environment (physics timestep * frame_skip).

#### Method
`dt(self) -> float`

#### Returns
- **time_step** (float) - The environment time step.

### `agent_num` (property)

#### Description
Gets the number of agents in the environment.

#### Method
`agent_num(self) -> int`

#### Returns
- **num_agents** (int) - The number of agents.

### `do_simulation`

#### Description
Steps the simulation for a specified number of frames, applying a control action.

#### Method
`do_simulation(self, ctrl, n_frames)`

#### Parameters
*   **ctrl** (Any) - The control signal to apply.
*   **n_frames** (int) - The number of frames to simulate.

### `close`

#### Description
Closes all associated processes, such as rendering contexts.

#### Method
`close(self)`

### `initialize_grpc`

#### Description
Initializes the GRPC communication channel.

#### Method
`initialize_grpc(self)`

### `pause_simulation`

#### Description
Pauses the simulation.

#### Method
`pause_simulation(self)`

### `init_qpos_qvel`

#### Description
Initializes the qpos and qvel of the model.

#### Method
`init_qpos_qvel(self)`

### `reset_simulation`

#### Description
Resets the simulation.

#### Method
`reset_simulation(self)`

### `set_time_step`

#### Description
Sets the time step of the simulation.

#### Method
`set_time_step(self, time_step)`

#### Parameters
*   **time_step** (Any) - The desired time step for the simulation.
```

--------------------------------

### Get All Joint Dictionaries - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the dictionary containing all joints in the model. This provides a comprehensive overview of the joints and their properties.

```python
def get_joint_dict(self)

```

--------------------------------

### Grasping and Anchoring using Mocap and Constraints in OrcaGym

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

Outlines the process of grasping or anchoring objects in OrcaGym, which involves updating mocap poses for anchors and applying equality constraints (WELD or CONNECT). This snippet provides a conceptual overview and points to the necessary functions for implementation.

```python
import numpy as np
from orca_gym.core.orca_gym_local import AnchorType

# 1) 选择目标 actor（物体 body 名称），以及锚点类型
actor_name = "SomeObjectBodyName"
anchor_type = AnchorType.WELD  # 或 AnchorType.BALL

# 2) 让环境层完成“锚定逻辑”（会处理 eq_list、obj id 等转换）
env.anchor_actor(actor_name, anchor_type)

# 3) 通过 mocap 移动锚点（驱动物体跟随）

```

--------------------------------

### OrcaGymLocal.modify_equality_objects

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Modifies the target objects of an equality constraint. This is useful for transferring constraints between bodies, for example, during object manipulation tasks.

```APIDOC
## POST /modify_equality_objects

### Description
Modifies the target objects of an equality constraint. This is useful for transferring constraints between bodies, for example, during object manipulation tasks.

### Method
POST

### Endpoint
/modify_equality_objects

### Parameters
#### Request Body
- **old_obj1_id** (int) - Required - The ID of the first body in the original constraint.
- **old_obj2_id** (int) - Required - The ID of the second body in the original constraint.
- **new_obj1_id** (int) - Required - The ID of the first body in the new constraint.
- **new_obj2_id** (int) - Required - The ID of the second body in the new constraint.

### Request Example
```json
{
  "old_obj1_id": 1,
  "old_obj2_id": 2,
  "new_obj1_id": 3,
  "new_obj2_id": 4
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful modification of the equality constraint.

#### Response Example
```json
{
  "message": "Equality constraint objects modified successfully."
}
```
```

--------------------------------

### OrcaGymModel Sensor Access and Conversion

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Provides methods to get sensor information by name or ID, and to convert between sensor names and IDs.

```APIDOC
## GET /sensors/{name_or_id}

### Description
Retrieves sensor information based on its name or ID.

### Method
GET

### Endpoint
`/sensors/{name_or_id}`

### Parameters
#### Path Parameters
- **name_or_id** (string) - Required - The name or ID of the sensor to retrieve.

### Response
#### Success Response (200)
- **sensor_info** (object) - Description of the sensor details.

#### Response Example
```json
{
  "sensor_info": {
    "id": "sensor_123",
    "name": "camera_front",
    "type": "RGB",
    "resolution": [640, 480]
  }
}
```

## GET /sensors/name2id

### Description
Converts a sensor name to its corresponding ID.

### Method
GET

### Endpoint
`/sensors/name2id`

### Parameters
#### Query Parameters
- **sensor_name** (string) - Required - The name of the sensor.

### Response
#### Success Response (200)
- **sensor_id** (string) - The ID of the sensor.

#### Response Example
```json
{
  "sensor_id": "sensor_123"
}
```

## GET /sensors/id2name

### Description
Converts a sensor ID to its corresponding name.

### Method
GET

### Endpoint
`/sensors/id2name`

### Parameters
#### Query Parameters
- **sensor_id** (string) - Required - The ID of the sensor.

### Response
#### Success Response (200)
- **sensor_name** (string) - The name of the sensor.

#### Response Example
```json
{
  "sensor_name": "camera_front"
}
```
```

--------------------------------

### Initialize GRPC Communication (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Initializes the GRPC communication channel. This method is likely used for inter-process communication, potentially between the simulation environment and an external agent or control system.

```python
def initialize_grpc(self) -> None:
    """Initializes the GRPC communication channel.
    """
    # Indicates the use of gRPC for communication, possibly for distributed training or real-time control.
```

--------------------------------

### Get Prefixed Actuator Name (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Retrieves the name of an actuator, prefixed with the agent's identifier if specified. This is useful for targeting specific actuators in multi-agent simulations.

```python
def actuator(self, name, agent_id=None) -> str:
    """Gets the actuator name with an agent prefix.

    Args:
        name: The base name of the actuator.
        agent_id: Optional identifier for the agent.

    Returns:
        The prefixed actuator name.
    """
    # Example: If agent_id is 'agent1' and name is 'motor_1', it might return 'agent1_motor_1'.
```

--------------------------------

### Initialize OrcaGym Local Simulation Environment

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Initializes the OrcaGym local simulation environment, responsible for interacting with the local MuJoCo simulator. This involves loading the model XML, initializing the simulation, and setting up encapsulated model and data objects.

```python
class OrcaGymLocal:
    """OrcaGym local simulation interface"""
    def __init__(self, stub):
        # ... initialization logic ...
        self.gym = OrcaGymLocal(self.stub)

    async def load_model_xml(self):
        """Loads the model XML file from the server."""
        # ... implementation ...
        return "/path/to/model.xml"

    async def init_simulation(self, model_xml_path):
        """Initializes the MuJoCo simulation."""
        # ... implementation ...
        self.model = self.gym.model
        self.data = self.gym.data
```

--------------------------------

### Advance Simulation and Update Data in OrcaGym

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

This snippet demonstrates advancing the simulation state and then updating the environment's internal data structures. `env.mj_forward()` is used to compute forward dynamics, and `env.update_data()` synchronizes the internal state after modifications or simulation steps. These are essential for ensuring data consistency.

```python
# Assuming 'env' is an initialized OrcaGym environment instance

# Advance simulation (e.g., after setting mocap or other states)
env.mj_forward()

# Update internal data structures to reflect the new simulation state
env.update_data()
```

--------------------------------

### Get All Body Names - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves a list of all body names present in the model. This is useful for iterating through bodies or searching for specific ones.

```python
def get_body_names(self)

# Example usage:
# Find bodies containing specific keywords
all_bodies = self.model.get_body_names()
for body in all_bodies:
    if "base" in body.lower() and "link" in body.lower():
        self.base_body_name = body
        break

# Iterate through all bodies for queries
for body_name in self.model.get_body_names():
    pos, _, quat = self.get_body_xpos_xmat_xquat([body_name])
```

--------------------------------

### Core Simulation Step

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

This is the most common call chain for controlling the simulation. It involves setting control inputs, stepping the physics simulation, and then updating the environment's data.

```APIDOC
## POST /sim/step

### Description
Executes a single step of the physics simulation with the given control inputs and updates the internal data structures.

### Method
POST

### Endpoint
/sim/step

### Parameters
#### Query Parameters
- **nstep** (integer) - Required - The number of physics steps to simulate.

#### Request Body
- **ctrl** (array) - Required - A vector of control inputs of length `nu`.

### Request Example
{
  "ctrl": [0.1, -0.2, 0.05, ...]
}

### Response
#### Success Response (200)
- **status** (string) - Indicates successful execution.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### OrcaGymModel: Get Actuator Dictionary (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the dictionary containing all actuators. This allows access to actuator information and facilitates name-to-ID lookups.

```python
def get_actuator_dict(self):
    # ... implementation details ...
    pass
```

--------------------------------

### Get Body ID by Geometry ID - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the ID of the body to which a specific geometry belongs. This provides the numerical identifier of the parent body.

```python
def get_geom_body_id(self, geom_id)

```

--------------------------------

### Initialize MuJoCo Simulation in OrcaGymLocal

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Initializes the MuJoCo simulation using a provided XML file path. This involves loading the MuJoCo model, creating the data object, initializing all model information containers, and creating encapsulated model and data objects for easier access.

```python
async def init_simulation(self, model_xml_path):
    """Initializes the MuJoCo simulation."""
    # Args:
    #   model_xml_path: Path to the model XML file.
    pass
```

--------------------------------

### Reset Environment (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Resets the environment to its initial state. This method is called at the beginning of each episode in reinforcement learning. It allows for optional seeding and setting of environment options.

```python
def reset(self, *, seed=None, options=None):
    """Resets the environment to its initial state.

    Args:
        seed: An optional integer for seeding the random number generator.
        options: Optional dictionary for environment-specific options.
    """
    # No specific implementation details provided in the source, relies on base class or further implementation.
```

--------------------------------

### Get All Geometry Dictionaries - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the dictionary containing all geometric elements within the model. This provides a consolidated view of all geoms and their associated data.

```python
def get_geom_dict(self)

```

--------------------------------

### Get Current Camera Frame Index

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the index of the current camera frame being rendered. This is useful for frame synchronization, particularly when saving videos.

```python
async def get_current_frame(self) -> int

```

```

--------------------------------

### Grasping and Manipulation

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

APIs related to grasping and manipulating objects using mocap bodies and equality constraints.

```APIDOC
## POST /manipulation/mocap/pose

### Description
Sets the position and quaternion of a mocap body.

### Method
POST

### Endpoint
/manipulation/mocap/pose

### Parameters
#### Request Body
- **mocap_data** (object) - Required - A dictionary containing mocap body name and its new pose (position and quaternion).
- **send_remote** (boolean) - Optional - Whether to send this update remotely.

### Request Example
{
  "mocap_data": {
    "mocap_body_name": {
      "pos": [0.1, 0.2, 0.3],
      "quat": [1.0, 0.0, 0.0, 0.0]
    }
  },
  "send_remote": false
}

### Response
#### Success Response (200)
- **status** (string) - Indicates successful execution.

## POST /manipulation/equality/modify_objects

### Description
Modifies the objects involved in an equality constraint.

### Method
POST

### Endpoint
/manipulation/equality/modify_objects

### Parameters
#### Request Body
- **old_obj1_id** (integer) - Required - ID of the first object in the old constraint.
- **old_obj2_id** (integer) - Required - ID of the second object in the old constraint.
- **new_obj1_id** (integer) - Required - ID of the first object in the new constraint.
- **new_obj2_id** (integer) - Required - ID of the second object in the new constraint.

### Response
#### Success Response (200)
- **status** (string) - Indicates successful execution.

## POST /manipulation/equality/update_constraints

### Description
Updates the list of equality constraints.

### Method
POST

### Endpoint
/manipulation/equality/update_constraints

### Parameters
#### Request Body
- **constraint_list** (array) - Required - A list of equality constraint definitions.

### Response
#### Success Response (200)
- **status** (string) - Indicates successful execution.
```

--------------------------------

### Set Simulation Time Step (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Sets the time step for the simulation. This allows for dynamic adjustment of the simulation's temporal resolution, which can affect stability and performance.

```python
def set_time_step(self, time_step) -> None:
    """Sets the time step of the simulation.

    Args:
        time_step: The desired time step duration.
    """
    # Allows modification of the simulation's internal time step.
```

--------------------------------

### Get Prefixed Sensor Name (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Retrieves the name of a sensor, prefixed with the agent's identifier if specified. This function allows for clear identification of sensors belonging to different agents.

```python
def sensor(self, name, agent_id=None) -> str:
    """Gets the sensor name with an agent prefix.

    Args:
        name: The base name of the sensor.
        agent_id: Optional identifier for the agent.

    Returns:
        The prefixed sensor name.
    """
    # Example: If agent_id is 'agent1' and name is 'imu', it might return 'agent1_imu'.
```

--------------------------------

### Simulate Frames (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Advances the simulation by a specified number of frames (n_frames) while applying a control action. This method is the core of the simulation stepping mechanism, allowing for discrete updates to the environment state.

```python
def do_simulation(self, ctrl, n_frames) -> None:
    """Steps the simulation forward by n_frames, applying the control action.

    Args:
        ctrl: The control action to apply to the actuators.
        n_frames: The number of simulation frames to advance.
    """
    # This method is fundamental for running the simulation step-by-step.
```

--------------------------------

### Get Prefixed Body Name (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Retrieves the name of a body, prefixed with the agent's identifier if specified. This is useful in multi-agent scenarios to distinguish between bodies belonging to different agents.

```python
def body(self, name, agent_id=None) -> str:
    """Gets the body name with an agent prefix.

    Args:
        name: The base name of the body.
        agent_id: Optional identifier for the agent.

    Returns:
        The prefixed body name.
    """
    # Example: If agent_id is 'agent1' and name is 'torso', it might return 'agent1_torso'.
```

--------------------------------

### Execute MuJoCo Simulation Steps

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Executes nstep physical simulation steps. Requires control inputs to be set beforehand. Each step uses a timestep. This function is essential for advancing the simulation.

```python
def mj_step(self, nstep):
    """执行 MuJoCo 仿真步进
    执行 nstep 次物理仿真步进，每次步进的时间为 timestep。 在调用前需要先设置控制输入 (set_ctrl)。
    术语说明: - mj_step: MuJoCo 的核心步进函数，执行一次完整的物理仿真 - 包括: 前向计算、约束求解、积分等步骤
    Args: nstep: 步进次数，通常为 1 或 frame_skip
    使用示例: `python     # 在 do_simulation 中调用     self.gym.set_ctrl(ctrl)     self.gym.mj_step(nstep=5)  # 步进 5 次    `
    """
    pass
```

--------------------------------

### State Setting and Consistency

Source: https://openverse-orca.github.io/OrcaGym.github.io/index

APIs for setting joint positions and velocities, and ensuring the consistency of simulation data after modifications.

```APIDOC
## POST /sim/state/set_qpos

### Description
Sets the joint positions of the simulation. After setting, `mj_forward` should be called to refresh derived quantities.

### Method
POST

### Endpoint
/sim/state/set_qpos

### Parameters
#### Request Body
- **joint_qpos** (object) - Required - A dictionary mapping joint names to their desired positions.

### Request Example
{
  "joint_qpos": {
    "joint1": 0.5,
    "joint2": -0.2
  }
}

### Response
#### Success Response (200)
- **status** (string) - Indicates successful execution.

## POST /sim/state/set_qvel

### Description
Sets the joint velocities of the simulation. After setting, `mj_forward` should be called to refresh derived quantities.

### Method
POST

### Endpoint
/sim/state/set_qvel

### Parameters
#### Request Body
- **joint_qvel** (object) - Required - A dictionary mapping joint names to their desired velocities.

### Request Example
{
  "joint_qvel": {
    "joint1": 0.1,
    "joint2": -0.05
  }
}

### Response
#### Success Response (200)
- **status** (string) - Indicates successful execution.

## POST /sim/forward

### Description
Performs a forward dynamics calculation to refresh derived quantities like kinematics and sensor data, ensuring consistency.

### Method
POST

### Endpoint
/sim/forward

### Response
#### Success Response (200)
- **status** (string) - Indicates successful execution.
```

--------------------------------

### Get Body Name by Geometry ID - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the name of the body to which a specific geometry belongs. This helps in associating geometric shapes with their parent bodies.

```python
def get_geom_body_name(self, geom_id)

```

--------------------------------

### Query Site Position and Rotation Matrix

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the position (xpos) and rotation matrix (xmat) for specified sites in the world coordinate frame. Returns a dictionary where keys are site names and values are dictionaries containing 'xpos' and 'xmat'. The returned arrays are views.

```python
def query_site_pos_and_mat(self, site_names):
    """查询 site 的位置和旋转矩阵。
    参数：
      * `site_names`：site 名称列表

    返回：
      * 字典，键为 site 名称，值为包含 ‘xpos’ 和 ‘xmat’ 的字典

    说明：
      * `xpos`：site 在世界坐标系中的位置 `[x, y, z]`
      * `xmat`：site 在世界坐标系中的旋转矩阵（3x3，按行展开为 9 个元素）

    注意：
      * 返回的数组是视图（view），修改会影响原始数据；如需独立副本，应使用 `copy()`。
    """
    pass
```

--------------------------------

### OrcaGymModel: Get Body Dictionary (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves the dictionary containing all bodies. This provides access to all defined bodies within the MuJoCo model and their associated information.

```python
def get_body_dict(self):
    # ... implementation details ...
    pass
```

--------------------------------

### Reset Simulation (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Resets the simulation to a state defined by its initial configuration. This is often a more thorough reset than just resetting the environment state, potentially re-initializing the physics engine.

```python
def reset_simulation(self) -> None:
    """Resets the simulation.
    """
    # Re-initializes the physics simulation, distinct from resetting agent state.
```

--------------------------------

### OrcaGymModel: Get Actuator by ID (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves information for a specific actuator using its unique ID. This is useful for accessing detailed properties of individual actuators.

```python
def get_actuator_byid(self, id):
    # ... implementation details ...
    pass
```

--------------------------------

### Query Simple Contact Information - Python

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_detail/core

Retrieves basic information about all current contact points in the simulation. The returned list contains details for each contact, including the IDs of the two participating geometries. This provides a high-level overview of physical interactions.

```Python
def query_contact_simple(self):
    """
    查询简单接触信息
    返回当前所有接触点的基本信息，包括接触的几何体对。
    术语说明: - 接触 (Contact): 两个几何体之间的碰撞或接触 - Geom1, Geom2: 接触的两个几何体的 ID - Dim: 接触的维度，通常为 3（点接触）或 6（面接触）
    Returns: contacts: 接触信息列表，每个元素包含接触 ID、维度、几何体 ID 等
    使用示例: `python     # 查询当前所有接触     contacts = self.gym.query_contact_simple()
    for contact in contacts:
        print(f"Contact between geom {contact['Geom1']} and {contact['Geom2']}")
    `
    """
    pass  # Placeholder for actual implementation
```

--------------------------------

### Get Prefixed Mocap Name (Python)

Source: https://openverse-orca.github.io/OrcaGym.github.io/api_manual/environment

Retrieves the name of a mocap data point, prefixed with the agent's identifier if specified. This is useful for handling motion capture data in multi-agent contexts.

```python
def mocap(self, name, agent_id=None) -> str:
    """Gets the mocap name with an agent prefix.

    Args:
        name: The base name of the mocap data.
        agent_id: Optional identifier for the agent.

    Returns:
        The prefixed mocap name.
    """
    # Example: If agent_id is 'agent1' and name is 'hip_marker', it might return 'agent1_hip_marker'.
```
Tokens:
Raw