ManipulaPy

<div align="center">

A comprehensive, GPU-accelerated Python package for robotic manipulator analysis, simulation, planning, control, and perception.

Quick Start • Documentation • Examples • Installation • Contributing

</div>

---

🎯 Overview

ManipulaPy is a modern, comprehensive framework that bridges the gap between basic robotics libraries and sophisticated research tools. It provides seamless integration of kinematics, dynamics, control, and perception systems with optional CUDA acceleration for real-time applications.

What's New in 1.3.1

• TRAC-IK Solver (96% success at 200ms): DLS-first strategy with SQP fallback, SVD-robust Jacobian solve, perturbation recovery, and backtracking line search
• Redesigned IK Solvers: All inverse kinematics algorithms overhauled — convergence rates improved from ~70% to 96%+
• Geometric Error Model: iterative_inverse_kinematics uses position + orientation geometric error instead of twist-based error
• SVD-Robust Jacobian: Condition-number-based damping prevents NaN/Inf in near-singular configurations
• Stagnation Recovery: Automatic perturbation detection breaks solvers out of local minima
• GIL-Aware Threading: Sequential mode (default) avoids Python GIL contention; parallel mode uses 3-worker architecture for DLS+SQP
• Smart Fallback: smart_inverse_kinematics auto-falls back to robust_inverse_kinematics on failure
• Multi-Start Rewrite: robust_inverse_kinematics uses 10 diverse initial-guess strategies for broader workspace coverage

Why ManipulaPy?

🔧 Unified Framework: Complete integration from low-level kinematics to high-level perception
⚡ GPU Accelerated: CUDA kernels for trajectory planning and dynamics computation
🔬 Research Ready: Mathematical rigor with practical implementation
🧩 Modular Design: Use individual components or the complete system
📖 Well Documented: Comprehensive guides with theoretical foundations
🆓 Open Source: AGPL-3.0 licensed for transparency and collaboration

---

✨ Key Features

<table> <tr> <td width="50%">

🔧 Core Robotics

• Kinematics: Forward/inverse kinematics with Jacobian analysis
• Dynamics: Mass matrix, Coriolis forces, gravity compensation
• Control: PID, computed torque, adaptive, robust algorithms
• Singularity Analysis: Detect singularities and workspace boundaries

</td> <td width="50%">

🚀 Advanced Capabilities

• Path Planning: CUDA-accelerated trajectory generation
• Simulation: Real-time PyBullet physics simulation
• Vision: Stereo vision, YOLO detection, point clouds
• URDF Processing: Convert robot models to Python objects

</td> </tr> </table>

---

📋 Feature Availability Matrix

ManipulaPy automatically enables features based on available dependencies. Here's what you can expect:

Core Features (Always Available)

| Feature | CPU Performance | Dependencies | Notes | |---------|----------------|--------------|-------| | Kinematics | Excellent | numpy, scipy | Forward/inverse kinematics, Jacobians | | Basic Dynamics | Good | numpy, scipy | Mass matrix, Coriolis, gravity | | Control Systems | Excellent | numpy, scipy | PID, computed torque, adaptive | | URDF Processing | Fast | numpy only (native) | Robot model conversion, NumPy 2.0+ | | Small Trajectories | Good | numba | N < 1000 points, auto-optimized |

GPU-Accelerated Features (Optional)

| Feature | CPU vs GPU | Requirements | Speedup | |---------|------------|--------------|---------| | Large Trajectories | 40x+ faster | CUDA, cupy | N > 1000 points | | Batch Processing | 20x+ faster | CUDA, cupy | Multiple trajectories | | Inverse Dynamics | 100x+ faster | CUDA, cupy | Large datasets | | Workspace Analysis | 10x+ faster | CUDA, cupy | Monte Carlo sampling |

Vision Features (Requires System Dependencies)

| Feature | Requirements | Common Issues | Solutions | |---------|-------------|---------------|-----------| | Camera Capture | OpenCV, libGL.so.1 | ImportError: libGL.so.1 | apt install libgl1-mesa-glx | | Object Detection | ultralytics, internet | YOLO download fails | Check network, manual download | | Stereo Vision | OpenCV, calibration | Poor depth quality | Camera calibration required | | 3D Point Clouds | OpenCV, numpy | Memory issues | Reduce point cloud density |

Installation Check Commands

import ManipulaPy

# Quick check - shows ✅/❌ for each feature
ManipulaPy.check_dependencies()

# Detailed system information
ManipulaPy.print_system_info()

# Get missing dependencies install commands
print(ManipulaPy.get_installation_command())

# Check specific feature
try:
    ManipulaPy.require_feature('cuda')
    print("GPU acceleration ready!")
except ImportError as e:
    print(f"GPU not available: {e}")

---

<a id="quick-start"></a>🚀 Quick Start

Installation

Before installing ManipulaPy, make sure your system has:

1. NVIDIA Drivers & CUDA Toolkit

   • nvcc on your PATH (e.g. via sudo apt install nvidia-cuda-toolkit or the official NVIDIA CUDA installer).
   • Verify with:

     nvidia-smi       # should list your GPU(s) and driver version
     nvcc --version   # should print CUDA version
     

2. cuDNN

   • Download and install cuDNN for your CUDA version from NVIDIA's cuDNN installation guide.
   • Verify headers/libs under /usr/include and /usr/lib/x86_64-linux-gnu (or your distro’s equivalent).

---

ManipulaPy attempts to install all dependencies by default for the best user experience. Missing dependencies are handled gracefully - the package will still work with available features.

# One command installs everything (recommended)
pip install ManipulaPy

What gets installed automatically:

• ✅ Core robotics (always): kinematics, dynamics, control, basic trajectory planning
• 🚀 GPU acceleration (if CUDA available): 40x+ speedups for large problems (N > 1000)
• 👁️ Vision features (if system supports): camera capture, object detection, stereo vision
• 🎮 Simulation (if compatible): PyBullet physics simulation and visualization

Check Your Installation

After installation, verify which features are available:

import ManipulaPy

# Quick feature availability check
ManipulaPy.check_dependencies()

# Detailed system information
ManipulaPy.print_system_info()

Alternative Installation Options

# Minimal installation (core features only)
pip install ManipulaPy[minimal]

# Specific CUDA version if auto-detection fails
pip install ManipulaPy[gpu-cuda12]  # For CUDA 12.x

# Headless environments (CI/Docker)
pip install ManipulaPy[vision-headless]

# Development environment
pip install ManipulaPy[dev]

Troubleshooting Common Issues

🚀 GPU Acceleration Not Working:

# Check CUDA installation
nvidia-smi

# Verify CUDA toolkit
nvcc --version

# Install specific CUDA version if needed
pip install cupy-cuda11x  # or cupy-cuda12x

👁️ Vision Features Not Working:

# Ubuntu/Debian - fix libGL.so.1 error
sudo apt-get install libgl1-mesa-glx libglib2.0-0

# CentOS/RHEL
sudo yum install mesa-libGL libglib2.0

# Test OpenCV
python -c "import cv2; print('OpenCV OK')"

🔧 Verify Installation:

# Test core functionality (always works)
from ManipulaPy.kinematics import SerialManipulator
print("✅ Core features working")

# Test GPU acceleration (if available)  
try:
    from ManipulaPy.cuda_kernels import check_cuda_availability
    if check_cuda_availability():
        print("🚀 GPU acceleration available")
    else:
        print("⚠️ GPU acceleration not available")
except ImportError:
    print("⚠️ GPU acceleration not installed")

# Test vision (if available)
try:
    from ManipulaPy.vision import Vision
    print("👁️ Vision features available")
except ImportError:
    print("⚠️ Vision features not available")

What Works Without Additional Setup

✅ Always Available (CPU-only):

• Forward/inverse kinematics and Jacobians
• PID, computed torque, adaptive, and robust control
• URDF processing and robot model conversion
• PyBullet simulation and visualization
• Small trajectory planning (N < 1000 points)
• Singularity analysis and workspace computation

🚀 GPU-Accelerated (optional 40x+ speedup):

• Large trajectory planning (N > 1000 points)
• Batch processing multiple trajectories
• Monte Carlo workspace analysis
• Inverse dynamics for long trajectories

👁️ Requires System Dependencies:

• Vision features: OpenCV, system graphics libraries (libGL.so.1)
• Object detection: YOLO models (auto-downloaded on first use)
• Stereo processing: Camera calibration data

---

🤖 Included Robot Models

ManipulaPy comes with 25 pre-configured robot models from 8 manufacturers, ready to use out of the box:

Universal Robots (7 models): UR3, UR5, UR10, UR3e, UR5e, UR10e, UR16e *Fanuc