Kinematics

robot.kinematics is a plugin namespace solving inverse kinematics for head gaze and arm reach/aim, working in the robot base frame (origin at the bottom of the robot: x forward, y left, z up). These examples assume you already have a connected robot — see Connection if you haven't set one up yet.

Setup

mkdir ~/example
cd ~/example
python -m venv .venv
# or: uv venv .venv

source .venv/bin/activate

pip install luxai-robot
# or: uv pip install luxai-robot

Connect

from luxai.robot.core import Robot

robot = Robot.connect_zmq(robot_id="QTRD000123")
print(f"connected to {robot.robot_id} ({robot.robot_type})")

See Connection for MQTT, WebRTC, and other connection options.

Enable the plugin

It runs locally, so no remote endpoint is needed:

robot.enable_plugin_local("kinematics")

# Optional: override camera intrinsics or motor wait timeout.
# Default values match the QTrobot RealSense hardware — skip this call if unchanged.
# robot.kinematics.configure(motor_timeout=15.0)

Look at a point (head gaze)

# Look straight ahead at roughly face height
robot.kinematics.look_at_point(1.0, 0.0, 0.6)

# Look slightly to the left
robot.kinematics.look_at_point(1.0, -0.5, 1.5)

# Move eyes only, without moving the head
robot.kinematics.look_at_point(1.0, -0.2, 0.6, only_gaze=True)

# Look at a pixel from the camera image (e.g. a detected face centre)
robot.kinematics.look_at_pixel(100, 240, depth=1.0)

# Non-blocking variant — start the motion and do other work while waiting
h = robot.kinematics.look_at_point_async(1.0, -1.0, 0.6)
h.wait()

# Utility: convert a pixel to a 3-D point, with no motor movement
pt = robot.kinematics.pixel_to_point(320, 240, depth=1.0)

Aim at a point (arm)

The arm is auto-selected by the sign of y (left arm if y >= 0, right arm if y < 0):

# Aim at (1.0, -0.5, 1.5) — right arm selected
robot.kinematics.aim_at_point(1.0, -0.5, 1.5)

# Aim at a pixel from the camera image
robot.kinematics.aim_at_pixel(400, 300, depth=1.0)

# Non-blocking arm motion with explicit velocity
h = robot.kinematics.reach_left_async(1.0, 0.2, 0.6, velocity=30)
h.wait()

# Cancel an in-flight action
h = robot.kinematics.reach_right_async(1.0, -0.3, 0.6)
h.cancel()

Resetting before disconnecting

import time

robot.face.look([0, 0], [0, 0])  # look straight ahead
robot.motor.home_all()
time.sleep(1)  # wait for homing to finish before closing
robot.close()

Next steps

Continue with the Plugins tutorial, or see the full robot.kinematics namespace in the Python API Reference.