Getting Started with ManipulaPy

Welcome to ManipulaPy! This guide will get you up and running with modern robotics programming in Python.

🚀 Ready to Build Robots?

ManipulaPy makes robot programming accessible with GPU acceleration, computer vision, and a clean Python API. Let's get started!

Installation

🔧 Quick Install

The fastest way to get started:

pip install manipulapy

🚀 Recommended Install (with GPU acceleration)

For the best performance:

pip install manipulapy[cuda]

📦 Full Installation (all features)

To unlock all capabilities:

pip install manipulapy[all]

🛠️ Development Installation

If you want to contribute or modify the library:

git clone https://github.com/yourusername/ManipulaPy.git
cd ManipulaPy
pip install -e .[dev]

Note

System Requirements:

• Python 3.8 or higher

• NumPy, SciPy (automatically installed)

• Optional: CUDA for GPU acceleration

• Optional: PyBullet for simulation

Verify Your Installation

Let’s make sure everything is working:

import ManipulaPy
print("🎉 ManipulaPy installed successfully!")
print(f"Version: {ManipulaPy.__version__}")

Your First Robot

🤖 Load a Robot Model

ManipulaPy comes with built-in robot models. Let’s start with the xArm:

import numpy as np
from ManipulaPy.urdf_processor import URDFToSerialManipulator
from ManipulaPy.ManipulaPy_data.xarm import urdf_file as xarm_urdf_file

# Load the built-in xArm robot
print("📁 Loading xArm robot model...")
urdf_processor = URDFToSerialManipulator(xarm_urdf_file)
robot = urdf_processor.serial_manipulator
dynamics = urdf_processor.dynamics

print(f"✅ Robot loaded with {len(robot.S_list[0])} degrees of freedom")

🎯 Forward Kinematics

Calculate where the robot’s end-effector is:

# Robot at home position (all joints at 0°)
home_angles = np.zeros(6)
end_effector_pose = robot.forward_kinematics(home_angles, frame="space")

print("🏠 Home position:")
print(f"   Position: {end_effector_pose[:3, 3]}")
print(f"   Orientation:\n{end_effector_pose[:3, :3]}")

🔄 Inverse Kinematics

Find joint angles to reach a target position:

# Define a target pose
target_position = np.array([0.5, 0.3, 0.8, 0.0, 0.5, 0.0])
T_target = robot.forward_kinematics(target_position)

# Solve inverse kinematics
print("🎯 Solving inverse kinematics...")
solution, success, iterations = robot.iterative_inverse_kinematics(
    T_desired=T_target,
    thetalist0=np.zeros(6),
    max_iterations=1000
)

if success:
    print(f"✅ Solution found in {iterations} iterations!")
    print(f"🔧 Joint angles: {np.degrees(solution):.2f}°")
else:
    print("❌ No solution found")

Your First Trajectory

⚡ GPU-Accelerated Planning

Plan smooth robot motions with CUDA acceleration:

from ManipulaPy.path_planning import TrajectoryPlanning

# Set up trajectory planner
joint_limits = np.array([[-np.pi, np.pi]] * 6)
planner = TrajectoryPlanning(robot, xarm_urdf_file, dynamics, joint_limits)

# Plan a smooth trajectory
start_angles = np.zeros(6)
end_angles = np.array([0.5, -0.3, 0.8, 0.0, 0.5, 0.0])

print("📈 Planning trajectory...")
trajectory = planner.joint_trajectory(
    thetastart=start_angles,
    thetaend=end_angles,
    Tf=5.0,          # 5 seconds
    N=100,           # 100 waypoints
    method=5         # Quintic (smooth) interpolation
)

print(f"✅ Generated {trajectory['positions'].shape[0]} waypoints")
print(f"🚀 Start velocity: {trajectory['velocities'][0]}")
print(f"🏁 End velocity: {trajectory['velocities'][-1]}")

📊 Visualize the Trajectory

See your robot’s planned motion:

# Plot the trajectory
planner.plot_trajectory(trajectory, 5.0, title="My First Robot Trajectory")

Your First Simulation

🎬 PyBullet Physics Simulation

Bring your robot to life with realistic physics:

from ManipulaPy.sim import Simulation

# Create physics simulation
print("🎬 Starting simulation...")
sim = Simulation(
    urdf_file_path=xarm_urdf_file,
    joint_limits=joint_limits,
    torque_limits=np.array([[-50, 50]] * 6),
    time_step=0.01
)

# Initialize robot and controllers
sim.initialize_robot()
sim.initialize_planner_and_controller()

# Execute the trajectory in simulation
waypoints = trajectory["positions"][::10]  # Use every 10th point

print("🏃 Running simulation...")
final_position = sim.run_trajectory(waypoints)
print(f"🏁 Final end-effector position: {final_position}")

Your First Control System

🎛️ Intelligent Robot Control

Control your robot with advanced algorithms:

from ManipulaPy.control import ManipulatorController

# Create smart controller
controller = ManipulatorController(dynamics)

# Current and desired robot states
current_pos = np.zeros(6)
current_vel = np.zeros(6)
desired_pos = np.array([0.2, -0.1, 0.3, 0.0, 0.2, 0.0])
desired_vel = np.zeros(6)

# Auto-tune controller gains
ultimate_gain = 50.0    # Experiment to find this
ultimate_period = 0.5   # Measure from oscillations
Kp, Ki, Kd = controller.tune_controller(ultimate_gain, ultimate_period, kind="PID")

print(f"🎛️ Auto-tuned gains:")
print(f"   Kp: {Kp[0]:.2f}, Ki: {Ki[0]:.2f}, Kd: {Kd[0]:.2f}")

# Compute control torques
control_torques = controller.computed_torque_control(
    thetalistd=desired_pos,
    dthetalistd=desired_vel,
    ddthetalistd=np.zeros(6),
    thetalist=current_pos,
    dthetalist=current_vel,
    g=np.array([0, 0, -9.81]),
    dt=0.01,
    Kp=Kp, Ki=Ki, Kd=Kd
)

print(f"⚡ Control torques: {control_torques}")

Your First Vision System

👁️ Computer Vision & Perception

Add eyes to your robot:

from ManipulaPy.vision import Vision
from ManipulaPy.perception import Perception

# Setup camera system
camera_config = {
    "name": "workspace_camera",
    "translation": [0.0, 0.0, 1.0],  # 1m above workspace
    "rotation": [0, 45, 0],           # Look down at 45°
    "fov": 60,
    "intrinsic_matrix": np.array([
        [500, 0, 320],
        [0, 500, 240],
        [0, 0, 1]
    ], dtype=np.float32),
    "distortion_coeffs": np.zeros(5, dtype=np.float32)
}

# Create vision system
print("👁️ Setting up vision system...")
vision = Vision(camera_configs=[camera_config])
perception = Perception(vision_instance=vision)

# Detect objects in the workspace
obstacle_points, cluster_labels = perception.detect_and_cluster_obstacles(
    camera_index=0,
    depth_threshold=3.0,  # Objects within 3m
    eps=0.1,              # Clustering parameter
    min_samples=3         # Minimum points per cluster
)

num_clusters = len(set(cluster_labels)) - (1 if -1 in cluster_labels else 0)
print(f"🔍 Detected {len(obstacle_points)} obstacle points")
print(f"📦 Found {num_clusters} distinct objects")

What’s Next?

🎉 Congratulations! You’ve just built your first robot system with ManipulaPy.

📚 Learn the Fundamentals

• 🔧 Kinematics Deep Dive
• ⚖️ Robot Dynamics
• 🛤️ Motion Planning

🎓 Explore Tutorials

• 🤖 Build a Pick & Place Robot
• 👁️ Vision-Guided Manipulation
• 🏭 Multi-Robot Coordination

🛠️ API Reference

• 📖 Kinematics API
• 📖 Dynamics API
• 📖 Control API
• 📖 Planning API

Common Issues & Solutions

⚠️ Installation Problems

# If you get permission errors
pip install --user manipulapy

# If you need CUDA support
pip install manipulapy[cuda]
# Verify CUDA is available
python -c "import cupy; print('CUDA available!')"

⚠️ Import Errors

# If ManipulaPy modules aren't found
import sys
sys.path.append('/path/to/ManipulaPy')
import ManipulaPy

⚠️ Simulation Issues

# If PyBullet simulation fails
pip install pybullet

# Test PyBullet installation
import pybullet as p
p.connect(p.DIRECT)
print("PyBullet working!")

⚠️ Performance Issues

# Check if CUDA acceleration is working
try:
    import cupy
    print("🚀 CUDA acceleration available")
except ImportError:
    print("⚠️ Install CuPy for GPU acceleration")

💡 Pro Tips

🎯 Start Simple
Begin with forward kinematics before inverse kinematics

📊 Visualize Everything
Use the plotting functions to understand robot behavior

⚡ Use GPU Acceleration
Install CUDA for 7x faster computations

🔧 Check Joint Limits
Always define realistic joint limits for safety

📞 Need Help?

• 📖 Check the 🔧 API Reference Guide for detailed function documentation

• 🐛 Report bugs on GitHub Issues

• 💬 Join our community discussions

• 📧 Contact the maintainers for support