RoboSpace API Reference

Getting Started

Execution Model

RoboSpace executes Python scripts directly inside your browser with zero setup. Scripts run synchronously with real-time physics stepping, eliminating network latency and installation overhead.

Quick Start Example

Control a UR5e manipulator to move to spatial target coordinates and close its end-effector gripper.

import time

# Initialize high-level robot instance
robot = get_robot()

print("Moving UR5e arm to target [0.4, 0.0, 0.25]...")
robot.arm.move_to([0.40, 0.00, 0.25])

print("Closing gripper...")
robot.gripper.close()

# Pause execution for 1 second in physics time
wait(1.0)

High-Level Robot Object API

get_robot()

get_robot() -> Robot

Instantiates a component-based Robot interface providing unified access to arm kinematics, gripper control, mobile base velocity, and joint references.

robot = get_robot()
print(robot)
# Output: <Robot with 6 joints, arm=tool0>

robot.arm.move_to(target, duration=1.0)

robot.arm.move_to(target: list[float], duration: float = 1.0) -> None

Moves the arm end-effector tool frame to target 3D Cartesian coordinates [X, Y, Z] in meters using inverse kinematics and smooth trajectory interpolation.

robot = get_robot()

# Move arm end-effector to [0.4, 0.1, 0.3] over 1.5 seconds
robot.arm.move_to([0.40, 0.10, 0.30], duration=1.5)

robot.arm.home()

robot.arm.home() -> None

Returns the robot arm to its default home joint position configuration.

robot = get_robot()
robot.arm.home()

robot.gripper.open() & robot.gripper.close()

robot.gripper.open(seconds: float = 0.8) -> None
robot.gripper.close(seconds: float = 0.8) -> None

Opens or closes the end-effector parallel gripper mechanism over the specified time duration.

robot = get_robot()
robot.gripper.open()
wait(0.5)
robot.gripper.close()

robot.gripper.set_position(opening)

robot.gripper.set_position(opening: float, seconds: float = 0.8) -> None

Sets explicit jaw opening width target in meters for variable-width gripping.

robot = get_robot()
# Set gripper opening width to 0.04m (4cm)
robot.gripper.set_position(0.04)

robot.base.drive(forward, turn, seconds)

robot.base.drive(forward: float = 0.0, turn: float = 0.0, seconds: float = 1.0) -> None

Drives mobile base velocity actuators with linear forward velocity (m/s) and angular turning velocity (rad/s) for a specified duration.

robot = get_robot()
# Drive forward at 0.5 m/s while turning at 0.2 rad/s for 2.0s
robot.base.drive(forward=0.5, turn=0.2, seconds=2.0)
robot.base.stop()

robot.get_joint(name).set_angle(degrees)

robot.get_joint(name: str).set_angle(degrees: float) -> None

Retrieves a joint proxy by name and sets target angular position in degrees.

robot = get_robot()
# Rotate wrist_1 joint to -90 degrees
robot.get_joint("wrist_1").set_angle(-90.0)

wait(seconds) / sleep(seconds)

wait(seconds: float = 1.0) -> None
sleep(seconds: float = 1.0) -> None

Pauses Python script execution while advancing physics stepping smoothly in synchronized simulation time.

# Pause execution for 2.5 seconds of simulation time
wait(2.5)

3D Stage & Selection

get_selected_body()

get_selected_body() -> str | None

Returns the unique string identifier of the 3D body currently selected or double-clicked by the user on the viewport stage.

selected = get_selected_body()
if selected:
    print(f"User selected body: {selected}")
else:
    print("No 3D object selected.")

body_pos(name) & body_quat(name)

body_pos(name: str) -> numpy.ndarray
body_quat(name: str) -> numpy.ndarray

Retrieves spatial position [X,Y,Z] array and orientation quaternion [W,X,Y,Z] array for any named body in world coordinates.

# Track spatial coordinates of an interactive stage target
target_name = get_selected_body() or "box_target"
pos = body_pos(target_name)
print(f"Target X: {pos[0]:.3f}, Y: {pos[1]:.3f}, Z: {pos[2]:.3f}")

# Move robot arm to target spatial position
robot = get_robot()
robot.arm.move_to([pos[0], pos[1], pos[2] + 0.1])

print_selection()

print_selection() -> None

Prints telemetry analysis of the currently selected 3D body, including position vector and ready-to-use code snippet.

print_selection()
# Output:
# Selected 3D Body: 'red_cube'
#   Position: [0.35, -0.12, 0.15]
#   Snippet:  body_pos('red_cube')

Kinematics & IK

move_to(target, duration=1.0)

move_to(target: list[float], duration: float = 1.0) -> None

Low-level motion executor that solves Inverse Kinematics for a target end-effector coordinate and interpolates joint positions over execution time.

# Move to spatial target [0.3, 0.2, 0.4]
move_to([0.3, 0.2, 0.4], duration=2.0)

ik_solve(target_pos, target_quat=None)

ik_solve(target_pos: list[float], target_quat: list[float] = None) -> numpy.ndarray

Calculates exact joint angle configuration array for requested Cartesian target position and optional quaternion orientation.

target_pos = [0.4, 0.0, 0.25]
target_quat = tool_down()

joint_angles = ik_solve(target_pos, target_quat)
print(f"Solved joint angles: {joint_angles}")

tool_down()

tool_down() -> numpy.ndarray

Returns standard downward-pointing orientation quaternion [W, X, Y, Z] for pick-and-place end-effectors.

down_quat = tool_down()
# Use downward orientation quaternion in IK solver
q = ik_solve([0.3, 0.0, 0.2], down_quat)

Low-Level Physics & State Control

get_num_actuators() & get_actuator_ranges()

get_num_actuators() -> int
get_actuator_ranges() -> list[list[float]]

Retrieves total actuator count and control limit range tuples [[min, max], ...] from the active physics simulation model.

n = get_num_actuators()
ranges = get_actuator_ranges()

for i in range(n):
    print(f"Actuator {i}: limits = {ranges[i]}")

set_control(ctrl) & get_control()

set_control(ctrl: list[float]) -> None
get_control() -> numpy.ndarray

Direct low-level actuator control input setter and getter.

import math

n = get_num_actuators()
# Apply sine wave velocity controls across actuators
t = get_time()
ctrl = [0.5 * math.sin(t + i * 0.5) for i in range(n)]
set_control(ctrl)

get_qpos() & get_qvel()

get_qpos() -> numpy.ndarray
get_qvel() -> numpy.ndarray

Returns complete physics joint position and joint velocity state arrays.

qpos = get_qpos()
qvel = get_qvel()

print(f"Joint Positions (qpos): {qpos[:6].round(3)}")
print(f"Joint Velocities (qvel): {qvel[:6].round(3)}")

step(n=1) & reset()

step(n: int = 1) -> int
reset() -> None

Manually advances physics simulation by n timestep increments or resets simulation to initial keyframe state.

# Step simulation forward by 10 timesteps
step(10)

# Reset simulation state
reset()

Custom Robot Import (URDF / MJCF)

Importing Custom Robots

RoboSpace supports loading custom robot models from raw URDF, MJCF XML, or compressed ZIP packages (containing meshes, textures, and XML definitions).

Visual Auto-Rigging Wizard

When importing a new robot model, the system automatically parses kinematically linked rigid bodies, identifies revolute and prismatic joints, generates position/velocity actuators, and sets up high-level Python API component bindings.

# Programmatically inspecting imported custom robot model
robot = get_robot()
print(f"Loaded joints: {list(robot.joints.keys())}")

# Set joint targets on custom imported robot
if "shoulder_pan_joint" in robot.joints:
    robot.get_joint("shoulder_pan_joint").set_angle(45.0)

Sensors & Cameras

get_sensor_data() & print_sensors()

get_sensor_data() -> list[float]
print_sensors() -> None

Retrieves sensor telemetry array (force sensors, touch sensors, IMU gyros, joint velocity sensors) defined in the robot scene model.

# Print available sensors and camera feeds
print_sensors()

# Read sensor data array
data = get_sensor_data()
print(f"Readings: {data}")

get_camera_names() & get_camera_info()

get_camera_names() -> list[str]
get_camera_info() -> list[dict]

Returns list of named viewpoints and camera perspective configurations attached to the robot or environment stage.

cameras = get_camera_names()
print(f"Available camera perspectives: {cameras}")