.. _user_guide_index:
.. _user_guide/index:

User Guide
==========

Welcome to the comprehensive ManipulaPy User Guide! This section provides detailed tutorials and explanations for all aspects of robotic manipulation using ManipulaPy.

.. raw:: html

   <div class="user-guide-hero">
      <div class="hero-content">
         <h2>🎓 Master Modern Robotics</h2>
         <p>From basic kinematics to advanced GPU-accelerated control systems, 
            this guide will take you from beginner to expert.</p>
         
         <div class="learning-stats">
            <div class="stat">
               <span class="stat-number">13</span>
               <span class="stat-label">Comprehensive Guides</span>
            </div>
            <div class="stat">
               <span class="stat-number">60+</span>
               <span class="stat-label">Code Examples</span>
            </div>
            <div class="stat">
               <span class="stat-number">120+</span>
               <span class="stat-label">Practical Tips</span>
            </div>
         </div>
      </div>
   </div>

.. contents:: **Quick Navigation**
   :local:
   :depth: 2
   :backlinks: none

📚 Complete Guide Overview
--------------------------

.. toctree::
   :maxdepth: 2
   :caption: Core Robotics Fundamentals

   Kinematics
   Dynamics
   Control
   URDF_Processor

.. toctree::
   :maxdepth: 2
   :caption: Motion Planning & Simulation

   Trajectory_Planning
   Path_Planning
   Simulation
   Singularity_Analysis
   Collision_Checker
   Potential_Field

.. toctree::
   :maxdepth: 2
   :caption: Perception & Intelligence

   vision
   Perception

.. toctree::
   :maxdepth: 2
   :caption: Advanced Topics

   CUDA_Kernels

🗺️ Learning Pathways
--------------------

Choose your learning path based on your experience level and goals:

.. raw:: html

   <div class="learning-pathways">
      <div class="pathway beginner">
         <div class="pathway-header">
            <span class="pathway-icon">🌱</span>
            <h3>Complete Beginner</h3>
            <p>New to robotics? Start here!</p>
         </div>
         <div class="pathway-steps">
            <div class="step">
               <span class="step-number">1</span>
               <div class="step-content">
                  <a href="Kinematics.html"><strong>Kinematics Basics</strong></a>
                  <p>Learn forward and inverse kinematics fundamentals</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">2</span>
               <div class="step-content">
                  <a href="URDF_Processor.html"><strong>Robot Models</strong></a>
                  <p>Load and work with robot URDF files</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">3</span>
               <div class="step-content">
                  <a href="Simulation.html"><strong>Virtual Robots</strong></a>
                  <p>Simulate robots in PyBullet</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">4</span>
               <div class="step-content">
                  <a href="Trajectory_Planning.html"><strong>Motion Planning</strong></a>
                  <p>Plan smooth robot motions</p>
               </div>
            </div>
         </div>
      </div>

      <div class="pathway intermediate">
         <div class="pathway-header">
            <span class="pathway-icon">🎯</span>
            <h3>Robotics Engineer</h3>
            <p>Ready for advanced control?</p>
         </div>
         <div class="pathway-steps">
            <div class="step">
               <span class="step-number">1</span>
               <div class="step-content">
                  <a href="Dynamics.html"><strong>Robot Dynamics</strong></a>
                  <p>Understand forces, torques, and physics</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">2</span>
               <div class="step-content">
                  <a href="Control.html"><strong>Control Systems</strong></a>
                  <p>Implement PID, computed torque control</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">3</span>
               <div class="step-content">
                  <a href="Collision_Checker.html"><strong>Safety Systems</strong></a>
                  <p>Collision detection and avoidance</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">4</span>
               <div class="step-content">
                  <a href="Singularity_Analysis.html"><strong>Singularity Analysis</strong></a>
                  <p>Analyze robot workspace and limitations</p>
               </div>
            </div>
         </div>
      </div>

      <div class="pathway advanced">
         <div class="pathway-header">
            <span class="pathway-icon">🚀</span>
            <h3>Performance Expert</h3>
            <p>Master GPU acceleration!</p>
         </div>
         <div class="pathway-steps">
            <div class="step">
               <span class="step-number">1</span>
               <div class="step-content">
                  <a href="CUDA_Kernels.html"><strong>CUDA Programming</strong></a>
                  <p>GPU acceleration fundamentals</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">2</span>
               <div class="step-content">
                  <a href="Trajectory_Planning.html"><strong>GPU Trajectories</strong></a>
                  <p>Accelerated motion planning</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">3</span>
               <div class="step-content">
                  <a href="Potential_Field.html"><strong>Field Methods</strong></a>
                  <p>Advanced obstacle avoidance</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">4</span>
               <div class="step-content">
                  <a href="../tutorials/index.html"><strong>Optimization</strong></a>
                  <p>Performance tuning techniques</p>
               </div>
            </div>
         </div>
      </div>

      <div class="pathway perception">
         <div class="pathway-header">
            <span class="pathway-icon">👁️</span>
            <h3>Vision & Perception</h3>
            <p>Master intelligent robotics!</p>
         </div>
         <div class="pathway-steps">
            <div class="step">
               <span class="step-number">1</span>
               <div class="step-content">
                  <a href="vision.html"><strong>Vision Systems</strong></a>
                  <p>Camera setup, calibration, and processing</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">2</span>
               <div class="step-content">
                  <a href="Perception.html"><strong>Perception Pipeline</strong></a>
                  <p>Object detection and environmental understanding</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">3</span>
               <div class="step-content">
                  <a href="Trajectory_Planning.html"><strong>Intelligent Planning</strong></a>
                  <p>Perception-aware motion planning</p>
               </div>
            </div>
            <div class="step">
               <span class="step-number">4</span>
               <div class="step-content">
                  <a href="Control.html"><strong>Adaptive Control</strong></a>
                  <p>Reactive and vision-guided control</p>
               </div>
            </div>
         </div>
      </div>
   </div>

📖 Guide Categories
-----------------------

Core Robotics
~~~~~~~~~~~~~~~~~

Essential concepts every robotics engineer should master:

.. raw:: html

   <div class="guide-grid">
      <div class="guide-card fundamental">
         <div class="guide-icon">🔧</div>
         <h4><a href="Kinematics.html">Kinematics</a></h4>
         <p><strong>Difficulty:</strong> Beginner</p>
         <p>Robot geometry, forward/inverse kinematics, Jacobians, and workspace analysis.</p>
         <div class="guide-features">
            <span class="feature-tag">📊 Workspace Visualization</span>
         </div>
      </div>

      <div class="guide-card fundamental">
         <div class="guide-icon">⚖️</div>
         <h4><a href="Dynamics.html">Dynamics</a></h4>
         <p><strong>Difficulty:</strong> Intermediate</p>
         <p>Mass matrices, inverse/forward dynamics, Coriolis forces, and gravity compensation.</p>
         <div class="guide-features">
            <span class="feature-tag">🔄 Smart Caching</span>
            <span class="feature-tag">⚡ GPU Accelerated</span>
         </div>
      </div>

      <div class="guide-card fundamental">
         <div class="guide-icon">🎛️</div>
         <h4><a href="Control.html">Control Systems</a></h4>
         <p><strong>Difficulty:</strong> Intermediate</p>
         <p>PID control, computed torque, adaptive controllers, and auto-tuning.</p>
         <div class="guide-features">
            <span class="feature-tag">🎯 Auto-tuning</span>
            <span class="feature-tag">📈 Performance Analysis</span>
         </div>
      </div>

      <div class="guide-card fundamental">
         <div class="guide-icon">🤖</div>
         <h4><a href="URDF_Processor.html">Robot Models</a></h4>
         <p><strong>Difficulty:</strong> Beginner</p>
         <p>Load URDF files, extract robot parameters, and create manipulator objects.</p>
         <div class="guide-features">
            <span class="feature-tag">📁 URDF Support</span>
            <span class="feature-tag">🔧 Built-in Models</span>
         </div>
      </div>
   </div>

Motion Planning & Simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Advanced motion planning and realistic simulation:

.. raw:: html

   <div class="guide-grid">
      <div class="guide-card planning">
         <div class="guide-icon">🛤️</div>
         <h4><a href="Trajectory_Planning.html">Trajectory Planning</a></h4>
         <p><strong>Difficulty:</strong> Intermediate</p>
         <p>CUDA-accelerated joint and Cartesian trajectory generation with collision avoidance.</p>
         <div class="guide-features">
            <span class="feature-tag">⚡ CUDA Kernels</span>
            <span class="feature-tag">🚧 Collision Avoidance</span>
         </div>
      </div>

      <div class="guide-card planning">
         <div class="guide-icon">🎮</div>
         <h4><a href="Simulation.html">PyBullet Simulation</a></h4>
         <p><strong>Difficulty:</strong> Beginner</p>
         <p>Physics simulation, trajectory execution, and interactive robot control.</p>
         <div class="guide-features">
            <span class="feature-tag">🎯 Real-time Control</span>
            <span class="feature-tag">📊 Visualization</span>
         </div>
      </div>

      <div class="guide-card planning">
         <div class="guide-icon">🛡️</div>
         <h4><a href="Collision_Checker.html">Collision Detection</a></h4>
         <p><strong>Difficulty:</strong> Intermediate</p>
         <p>Self-collision detection, environment obstacles, and safety monitoring.</p>
         <div class="guide-features">
            <span class="feature-tag">🔍 Convex Hull</span>
            <span class="feature-tag">⚡ Fast Detection</span>
         </div>
      </div>

      <div class="guide-card planning">
         <div class="guide-icon">🌊</div>
         <h4><a href="Potential_Field.html">Potential Fields</a></h4>
         <p><strong>Difficulty:</strong> Advanced</p>
         <p>Artificial potential fields for path planning and obstacle avoidance.</p>
         <div class="guide-features">
            <span class="feature-tag">🧲 Attractive Fields</span>
            <span class="feature-tag">⚡ Repulsive Forces</span>
         </div>
      </div>
   </div>

Perception & Intelligence
~~~~~~~~~~~~~~~~~~~~~~~~~

Computer vision, environmental understanding, and intelligent robot behavior:

.. raw:: html

   <div class="guide-grid">
      <div class="guide-card perception">
         <div class="guide-icon">📷</div>
         <h4><a href="vision.html">Vision Systems</a></h4>
         <p><strong>Difficulty:</strong> Intermediate</p>
         <p>Camera setup, stereo vision, depth processing, and multi-camera systems.</p>
         <div class="guide-features">
            <span class="feature-tag">📐 Stereo Vision</span>
            <span class="feature-tag">🎛️ PyBullet Debug</span>
         </div>
      </div>

      <div class="guide-card perception">
         <div class="guide-icon">🧠</div>
         <h4><a href="Perception.html">Perception Pipeline</a></h4>
         <p><strong>Difficulty:</strong> Advanced</p>
         <p>Object detection, 3D clustering, environmental understanding, and robot integration.</p>
         <div class="guide-features">
            <span class="feature-tag">🔍 YOLO Detection</span>
            <span class="feature-tag">🌐 3D Clustering</span>
         </div>
      </div>
   </div>

Advanced Topics
~~~~~~~~~~~~~~~~~~~

Cutting-edge techniques for performance and analysis:

.. raw:: html

   <div class="guide-grid">
      <div class="guide-card advanced">
         <div class="guide-icon">⚠️</div>
         <h4><a href="Singularity_Analysis.html">Singularity Analysis</a></h4>
         <p><strong>Difficulty:</strong> Advanced</p>
         <p>Workspace analysis, manipulability ellipsoids, and singularity avoidance.</p>
         <div class="guide-features">
            <span class="feature-tag">📊 Workspace Mapping</span>
            <span class="feature-tag">🎯 Monte Carlo</span>
         </div>
      </div>

      <div class="guide-card advanced">
         <div class="guide-icon">🚀</div>
         <h4><a href="CUDA_Kernels.html">GPU Acceleration</a></h4>
         <p><strong>Difficulty:</strong> Expert</p>
         <p>Custom CUDA kernels, parallel processing, and performance optimization.</p>
         <div class="guide-features">
            <span class="feature-tag">⚡ 50x Speedup</span>
            <span class="feature-tag">🔧 Custom Kernels</span>
         </div>
      </div>
   </div>

🎯 Quick Reference
----------------------

.. raw:: html

   <div class="quick-reference">
      <div class="ref-section">
         <h4>🚀 Getting Started</h4>
         <ul>
            <li><a href="../getting_started/index.html">Installation Guide</a></li>
            <li><a href="Kinematics.html#basic-forward-kinematics">First Robot Analysis</a></li>
            <li><a href="URDF_Processor.html#loading-built-in-models">Built-in Robot Models</a></li>
            <li><a href="Simulation.html#basic-simulation">Your First Simulation</a></li>
         </ul>
      </div>
      
      <div class="ref-section">
         <h4>⚡ Performance</h4>
         <ul>
            <li><a href="CUDA_Kernels.html#installation">CUDA Setup</a></li>
            <li><a href="Trajectory_Planning.html#cuda-acceleration">GPU Trajectories</a></li>
            <li><a href="Dynamics.html#caching">Smart Caching</a></li>
            <li><a href="../tutorials/index.html">Optimization Tips</a></li>
         </ul>
      </div>
      
      <div class="ref-section">
         <h4>🔧 Common Tasks</h4>
         <ul>
            <li><a href="Kinematics.html#inverse-kinematics">Solve Inverse Kinematics</a></li>
            <li><a href="Control.html#pid-control">Implement PID Control</a></li>
            <li><a href="Trajectory_Planning.html#joint-trajectories">Plan Trajectories</a></li>
            <li><a href="Collision_Checker.html#basic-collision-detection">Check Collisions</a></li>
         </ul>
      </div>
      
      <div class="ref-section">
         <h4>👁️ Perception</h4>
         <ul>
            <li><a href="vision.html#camera-setup">Setup Cameras</a></li>
            <li><a href="Perception.html#obstacle-detection">Detect Obstacles</a></li>
            <li><a href="Perception.html#data-flow-architecture">Data Flow Pipeline</a></li>
            <li><a href="vision.html#stereo-vision">Stereo Processing</a></li>
         </ul>
      </div>
      
      <div class="ref-section">
         <h4>🎓 Advanced Topics</h4>
         <ul>
            <li><a href="Control.html#computed-torque-control">Computed Torque Control</a></li>
            <li><a href="Singularity_Analysis.html#manipulability">Manipulability Analysis</a></li>
            <li><a href="Potential_Field.html#artificial-potential-fields">Potential Field Planning</a></li>
            <li><a href="CUDA_Kernels.html#custom-kernels">Custom CUDA Kernels</a></li>
         </ul>
      </div>
   </div>

💡 Study Tips
-------------------

.. raw:: html

   <div class="study-tips">
      <div class="tip-card">
         <div class="tip-icon">📚</div>
         <h4>Follow the Order</h4>
         <p>The guides are designed to build on each other. Start with Kinematics and work your way through systematically.</p>
      </div>
      
      <div class="tip-card">
         <div class="tip-icon">💻</div>
         <h4>Code Along</h4>
         <p>Each guide includes working code examples. Type them out yourself - don't just copy-paste!</p>
      </div>
      
      <div class="tip-card">
         <div class="tip-icon">🧪</div>
         <h4>Experiment</h4>
         <p>Modify the examples, try different parameters, and break things. Learning happens through experimentation.</p>
      </div>
      
      <div class="tip-card">
         <div class="tip-icon">📊</div>
         <h4>Visualize</h4>
         <p>Use the plotting functions extensively. Understanding robotics requires good spatial intuition.</p>
      </div>
      
      <div class="tip-card">
         <div class="tip-icon">👁️</div>
         <h4>See & Think</h4>
         <p>Use the Vision and Perception modules to add intelligence to your robots. Modern robotics is perception-driven!</p>
      </div>
   </div>

🆘 Need Help?
----------------

If you get stuck:

1. **Check the Examples** - Each guide has complete working examples

2. **API Reference** - Detailed function documentation in :doc:`../api/index`

3. **GitHub Issues** - Report bugs or ask questions on `GitHub <https://github.com/boelnasr/ManipulaPy/issues>`_

.. raw:: html

   <style>
   .user-guide-hero {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
      padding: 2rem;
      border-radius: 12px;
      margin: 2rem 0;
      text-align: center;
   }
   
   .user-guide-hero h2 {
      margin-top: 0;
      font-size: 2.2rem;
   }
   
   .learning-stats {
      display: flex;
      justify-content: center;
      gap: 2rem;
      margin-top: 1.5rem;
      flex-wrap: wrap;
   }
   
   .stat {
      display: flex;
      flex-direction: column;
      align-items: center;
   }
   
   .stat-number {
      font-size: 2.5rem;
      font-weight: bold;
      color: #ffd700;
   }
   
   .stat-label {
      font-size: 0.9rem;
      opacity: 0.9;
   }
   
   .learning-pathways {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
      gap: 2rem;
      margin: 2rem 0;
   }
   
   .pathway {
      border: 1px solid #e1e4e8;
      border-radius: 12px;
      overflow: hidden;
      background: white;
      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
   }
   
   .pathway-header {
      padding: 1.5rem;
      text-align: center;
   }
   
   .beginner .pathway-header { background: linear-gradient(135deg, #84fab0 0%, #8fd3f4 100%); }
   .intermediate .pathway-header { background: linear-gradient(135deg, #ffecd2 0%, #fcb69f 100%); }
   .advanced .pathway-header { background: linear-gradient(135deg, #a8edea 0%, #fed6e3 100%); }
   .perception .pathway-header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; }
   
   .pathway-icon {
      font-size: 2.5rem;
      display: block;
      margin-bottom: 0.5rem;
   }
   
   .pathway-header h3 {
      margin: 0.5rem 0;
      color: #333;
   }
   
   .perception .pathway-header h3 {
      color: white;
   }
   
   .pathway-header p {
      margin: 0;
      color: #666;
      font-style: italic;
   }
   
   .perception .pathway-header p {
      color: rgba(255, 255, 255, 0.9);
   }
   
   .pathway-steps {
      padding: 1rem;
   }
   
   .step {
      display: flex;
      align-items: flex-start;
      margin-bottom: 1rem;
      padding: 0.5rem;
      border-radius: 8px;
      background: #f8f9fa;
   }
   
   .step-number {
      background: #007acc;
      color: white;
      border-radius: 50%;
      width: 24px;
      height: 24px;
      display: flex;
      align-items: center;
      justify-content: center;
      font-weight: bold;
      font-size: 0.8rem;
      margin-right: 1rem;
      flex-shrink: 0;
   }
   
   .step-content h4 {
      margin: 0 0 0.25rem 0;
   }
   
   .step-content p {
      margin: 0;
      font-size: 0.9rem;
      color: #666;
   }
   
   .guide-grid {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
      gap: 1.5rem;
      margin: 1.5rem 0;
   }
   
   .guide-card {
      border: 1px solid #e1e4e8;
      border-radius: 10px;
      padding: 1.5rem;
      background: white;
      transition: all 0.3s ease;
      position: relative;
      overflow: hidden;
   }
   
   .guide-card:hover {
      transform: translateY(-2px);
      box-shadow: 0 8px 25px rgba(0,0,0,0.15);
   }
   
   .fundamental { border-left: 4px solid #28a745; }
   .planning { border-left: 4px solid #007bff; }
   .perception { border-left: 4px solid #6f42c1; }
   .advanced { border-left: 4px solid #dc3545; }
   
   .guide-icon {
      font-size: 2rem;
      margin-bottom: 1rem;
      display: block;
   }
   
   .guide-card h4 {
      margin: 0 0 0.5rem 0;
   }
   
   .guide-card p {
      margin: 0.5rem 0;
      color: #666;
   }
   
   .guide-features {
      margin-top: 1rem;
      display: flex;
      flex-wrap: wrap;
      gap: 0.5rem;
   }
   
   .feature-tag {
      background: #e9ecef;
      color: #495057;
      padding: 0.25rem 0.5rem;
      border-radius: 4px;
      font-size: 0.8rem;
      font-weight: 500;
   }
   
   .quick-reference {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
      gap: 1.5rem;
      margin: 2rem 0;
   }
   
   .ref-section {
      background: #f8f9fa;
      border: 1px solid #e9ecef;
      border-radius: 8px;
      padding: 1rem;
   }
   
   .ref-section h4 {
      margin: 0 0 1rem 0;
      color: #495057;
   }
   
   .ref-section ul {
      margin: 0;
      padding-left: 1rem;
   }
   
   .ref-section li {
      margin-bottom: 0.5rem;
   }
   
   .study-tips {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
      gap: 1rem;
      margin: 2rem 0;
   }
   
   .tip-card {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
      padding: 1.5rem;
      border-radius: 10px;
      text-align: center;
   }
   
   .tip-icon {
      font-size: 2rem;
      display: block;
      margin-bottom: 1rem;
   }
   
   .tip-card h4 {
      margin: 0 0 0.5rem 0;
   }
   
   .tip-card p {
      margin: 0;
      font-size: 0.9rem;
      opacity: 0.9;
   }
   
   @media (max-width: 768px) {
      .learning-pathways {
         grid-template-columns: 1fr;
      }
      
      .guide-grid {
         grid-template-columns: 1fr;
      }
      
      .learning-stats {
         flex-direction: column;
         gap: 1rem;
      }
   }
   </style>