pyCub: Python iCub Simulation Framework

• pyCub is a Python-based simulation and exercise framework for the iCub humanoid that removes middleware complexity to facilitate learning and prototyping.
• It leverages PyBullet and Open3D for realistic physics and customized visualization, enabling experiments in control, vision, tactile sensing, and reactive behavior.
• The framework offers a progressive set of exercises from basic joint control to integrated tasks like gaze tracking and grasping, making it ideal for education and early-stage research.

Searching arXiv for the relevant pyCub paper and closely related work. pyCub is an open-source, Python-based, physics-based simulation and exercise framework built around the humanoid robot iCub. It combines a full-body simulator of the robot with a structured set of exercises intended to teach the basics of humanoid robotics, while also providing a lightweight environment for experimentation with control, vision, tactile sensing, gaze, grasping, and reactive behavior. Its defining design choice is to remove the YARP middleware and C++ dependency characteristic of the traditional iCub simulation stack, replacing them with a Python-only workflow centered on PyBullet, Open3D, YAML configuration, and publicly distributed exercises, documentation, Docker images, and example videos (Rustler et al., 2 Jun 2025).

1. Definition, scope, and positioning

pyCub is presented as more than a simulator in the narrow sense. It is a combined simulation-and-exercise framework for the iCub humanoid, designed primarily for education but also usable for prototyping core humanoid-robotics tasks (Rustler et al., 2 Jun 2025). The framework simulates the complete robot with all articulations, includes the two eye cameras, and models the characteristic whole-body artificial skin of the iCub with more than 4000 tactile receptors. The exercises span basic joint and Cartesian control as well as more integrated tasks such as gazing, grasping, and tactile reactive control.

The intended role of pyCub is explicitly limited. It is not proposed as a replacement for the established iCub simulators for full research deployment or transfer to the physical robot. Rather, it is positioned as a lower-barrier entry point to iCub-centered humanoid robotics, especially for learners and users who would otherwise be blocked by the middleware, compilation, and systems complexity of the traditional toolchain (Rustler et al., 2 Jun 2025).

A useful disambiguation is that pyCub is distinct from similarly named software in other domains, including the Python-based data-cube tool pyCube (Vang et al., 2023). Within the robotics literature considered here, pyCub specifically denotes the Python-based iCub simulation framework introduced in 2025 (Rustler et al., 2 Jun 2025).

2. Motivation and relation to the iCub simulation ecosystem

The immediate motivation for pyCub is pedagogical. The iCub ecosystem already included two established simulators, iCub SIM and iCub Gazebo, but both were described as difficult for beginners because they are controlled primarily in C++, depend on YARP, and require a setup process that students found intricate. In prior course deployments based on Gazebo, YARP, and C++, student complaints reportedly centered on middleware complexity, compilation issues, and overall infrastructure burden rather than on robotics concepts themselves (Rustler et al., 2 Jun 2025).

pyCub addresses that problem by removing YARP entirely and exposing the simulator through Python. This changes the teaching workflow in a material way: students can focus on kinematics, control, sensing, gaze, and manipulation rather than on mastering an additional middleware stack. The framework is described as usable even by people with “small or almost no programming practice,” which indicates that its accessibility target is relative to the established iCub stack rather than to robotics software in general (Rustler et al., 2 Jun 2025).

The contrast with the older simulators can be summarized concisely.

Feature	iCub SIM / iCub Gazebo	pyCub
Programming interface	C++ with wrappers	Python
Middleware	YARP	None
Transfer to real iCub	Yes	No
Physics / rendering	ODE or DART; OpenGL or OGRE	Bullet via PyBullet; Open3D (OpenGL)

This positioning entails a deliberate trade-off. pyCub sacrifices transferability to the real iCub, high-level planner integration, and deeper linkage to the mature YARP-based ecosystem in exchange for a simpler, more inspectable, and more easily teachable environment (Rustler et al., 2 Jun 2025).

3. Simulation architecture and embodiment model

The simulation backbone of pyCub is PyBullet, chosen because it is open-source, cross-platform, and not excessively computationally demanding. Visualization is handled through a custom Open3D interface rather than PyBullet’s native GUI, which the authors found insufficiently customizable, slow, and incompatible with their preferred manual stepping mode (Rustler et al., 2 Jun 2025). Configuration is controlled through YAML files, while robot and object descriptions use URDF and mesh assets such as .obj.

A central architectural choice is manual stepping. The simulator does not run autonomously in the background; instead, the user explicitly advances time through update_simulation(). This decouples simulation stepping from GUI updates and allows inspection, control computation, debugging, and slowed execution between steps. The framework also supports a mode in which a new step occurs only after a predefined elapsed duration, enabling slow-motion inspection of behavior (Rustler et al., 2 Jun 2025).

The robot model aims to represent the full iCub rather than an educational simplification. The real iCub has 53 active degrees of freedom, and pyCub simulates the full articulated structure, including limbs, head and eyes, and fingers in the detailed model. Because the full model is computationally demanding, the framework also provides a simplified model without fingers and with simpler meshes. The paper reports that this simplified model yields roughly a $2\times$ speedup. On a Ryzen 7 PRO 4750U CPU, average performance with GUI and skin enabled is around real time. The authors additionally note that with smaller robots the same infrastructure can run at orders of magnitude of real time, which they identify as useful for reinforcement learning (Rustler et al., 2 Jun 2025).

The YAML configuration layer controls GUI, skin, eye-camera output, logging, self-collision settings, initial posture, selected end-effector for Cartesian control, simulation timestep, and insertion of environment objects. Objects can be inserted either as URDF models or as direct .obj meshes, with configurable initial pose, color, gravity, and movability (Rustler et al., 2 Jun 2025). This makes exercise variation possible without modifying the control code itself.

4. Sensing, control interfaces, and formal task primitives

pyCub exposes three control modes: joint velocity control, joint position control, and Cartesian position control (Rustler et al., 2 Jun 2025). Joint velocity control lets the user set joint velocities in radians per second and is particularly recommended for reactive control. Joint position control sets target joint positions in radians, with optional stopping on collision and optional consideration of self-collisions. Cartesian position control commands a selected end-effector to a 6D pose, comprising 3D position and 3D orientation; internally, pyCub computes inverse kinematics and then invokes joint position control. The inverse kinematics in PyBullet is stated to use Damped Least Squares with null-space support.

A key limitation is that Cartesian control in pyCub does not include a motion planner. Consequently, there is no reachability guarantee, no collision-free path planning, and no path smoothing. The authors treat this partly as a pedagogical feature, since it exposes the behavior of raw IK-plus-position-control without planner-mediated regularization (Rustler et al., 2 Jun 2025).

The sensor model includes the eye cameras and the full-body tactile skin. The two eye cameras can be displayed in the GUI and can save RGB and depth images to file. In the grasping exercise, these are used to detect a ball and recover its 3D position from the pixel center $(u,v)$, its depth, and camera parameters such as image width, height, and focal length (Rustler et al., 2 Jun 2025).

The tactile skin is one of pyCub’s distinctive technical features. It simulates more than 4000 taxels and attempts to model graded activation rather than binary contact. Because the real iCub skin has 8-bit resolution, pyCub uses raycasting: from each taxel, a short ray is cast; if the ray hits another robot part or an external object, the output is set proportionally to the ray length. This approximates both contact intensity and the spread of activation around a contact point. To make this tractable, pyCub first checks each skin part for nearby objects through bounding-box overlap and only then performs the more expensive batched raycasting. Activated taxels are stored in a dictionary, and binary activations are shown as green points in the visualization (Rustler et al., 2 Jun 2025).

Two formal relations are explicitly used in the exercises. For the gaze task, the angular error between the current gaze vector and the target vector is defined as

$$\theta = \arctan2\left( \left\| \mathbf{x} \times \mathbf{y} \right\|, \mathbf{x} \cdot \mathbf{y} \right),$$

where $\mathbf{x}$ and $\mathbf{y}$ are the two vectors. For tactile reactive control, the framework introduces resolved-rate motion control (RRMC): $$\dot{\mathbf{q}} = \mathbf{J}(\mathbf{q})^{*}\dot{\mathbf{x}},$$ where $\mathbf{J}(\mathbf{q})^{*}$ may be the transpose, inverse, or Moore-Penrose pseudoinverse of the Jacobian. The paper explicitly notes the trade-offs among these choices, including singularity sensitivity for the pseudoinverse and the lack of straight-line guarantees for the transpose method (Rustler et al., 2 Jun 2025).

5. Exercise framework and pedagogical progression

A major part of pyCub is the exercise suite. The exercises are explicitly arranged in increasing difficulty, and each exercise comes with a configuration file, an assignment script, and a testing script (Rustler et al., 2 Jun 2025). The progression is intended to move learners from basic interaction with the simulator to more integrated perception-action tasks.

Exercise	Core task	Evaluation
Push the Ball!	Move a ball away from a table	Distance from ball to table
Smooth Movements	Produce straight or shaped smooth motion	Compared with reference trajectory
Gaze	Track a moving ball in the XY plane	Mean and maximum angular error
Reactive Control and Skin Processing	Move away from tactile contact	Manual evaluation
Grasping	Detect, approach, grasp, and lift a ball	Ball distance from table after lifting

“Push the Ball!” is intentionally open-ended and serves as an introductory familiarization exercise. Self-collisions are disabled, and success is measured by the distance between the ball and the table two seconds after the robot’s last movement. “Smooth Movements” teaches that a single Cartesian setpoint does not define a smooth or geometrically straight trajectory; students must generate and preempt waypoints to avoid stop-and-go motion. “Gaze” simplifies the full iCub gaze problem to tracking a ball in the XY plane primarily with neck joints, using vector geometry and angular error as the main concepts (Rustler et al., 2 Jun 2025).

“Reactive Control and Skin Processing” combines tactile signal processing, contact clustering, geometric reasoning, and Jacobian-based velocity control. Students are given the positions and normals of activated taxels grouped by skin part, then asked to identify contact clusters and generate motions away from the contact normal. “Grasping” integrates vision, depth, motion sequencing, and finger control around a green ball whose position varies on the table (Rustler et al., 2 Jun 2025).

The framework emphasizes scalability of difficulty. Difficulty can be adjusted by changing thresholds, limiting perceptual information, altering object positions, selecting different body parts, changing the number of simultaneous contacts, or modifying the YAML environment configuration. This makes pyCub suitable for heterogeneous student populations and for incremental course design (Rustler et al., 2 Jun 2025).

6. Course deployment, limitations, and subsequent use in research

pyCub was tested in two runs of a course on humanoid robotics. The reported evaluation is qualitative rather than statistical: there are no controlled studies, no quantitative learning-gain tables, no usability survey instruments, and no enrollment or completion statistics in the paper. The reported outcome is that after replacing the previous Gazebo-plus-YARP-plus-C++ setup, the class dynamic improved and students were able to focus more on robotics than on infrastructure. The “Push the Ball!” exercise is used as an illustrative example of exploratory engagement, since students reportedly devised strategies such as grasping and throwing or kicking rather than only the expected arm hit (Rustler et al., 2 Jun 2025).

The limitations of pyCub are stated clearly. It is not transferable to the real iCub. It has no high-level planners. Cartesian control lacks collision-aware path planning and smoothing. The full articulated model with tactile skin is computationally demanding. Some exercise evaluation remains manual, notably for reactive control (Rustler et al., 2 Jun 2025). The future directions mentioned by the authors include a better Cartesian planner, potentially a ROS interface to leverage planning capabilities, and more advanced exercises such as humanoid walking and event-based sensing.

Subsequent work has already used pyCub outside the original teaching context. In a 2026 framework for simulating infant first-person sensorimotor experience via motion retargeting, pyCub was used as the simulated version of the iCub embodiment, alongside the physical iCub, EMFANT, and MIMo (López et al., 30 Apr 2026). In that setting, pyCub served as a safe and instrumented proxy for replaying retargeted infant motions, including configurations outside real joint limits, self-penetrating poses, and motions that could damage hardware. The framework used pyCub to produce visual information, first-person eye views, proprioception, and artificial skin activations. Although pyCub was not the best morphology-matched embodiment for infant pose reconstruction, the simulated iCub was reported to best capture the distributional nuances of self-touch annotation in that experiment, especially lateralization (López et al., 30 Apr 2026).

This later use suggests that pyCub’s importance is not confined to pedagogy. A plausible implication is that its combination of full iCub morphology, tactile sensing, vision, and Python accessibility makes it a useful intermediary platform between educational robotics and more experimentally oriented developmental-robotics workflows. Even so, the original characterization remains valid: pyCub’s central contribution is not a new control-theoretic formalism, but a carefully scoped software environment that lowers the entry barrier to nontrivial humanoid-robotics tasks while preserving much of what makes the iCub platform technically distinctive (Rustler et al., 2 Jun 2025).