hand-tracking-teleop 0.1.0__py3-none-any.whl

hand_tracking/__init__.py

@@ -0,0 +1,17 @@
+"""Hand tracking package for robot teleoperation.
+
+This package provides real-time hand tracking using MediaPipe with
+scale-invariant 3D coordinate normalization for robust robot control.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Bruk Gebregziabher"
+__email__ = "bruk@signalbotics.com"
+
+from .hand_detector import HandDetector, HandLandmarks
+
+__all__ = [
+    "HandDetector",
+    "HandLandmarks",
+    "__version__",
+]

hand_tracking/cli.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Command-line interface for hand tracking package."""
+
+import argparse
+import sys
+from pathlib import Path
+from .hand_detector import HandDetector
+
+
+def main():
+    """Main CLI entry point for 2D hand tracking."""
+    parser = argparse.ArgumentParser(
+        description="Hand tracking for robot teleoperation"
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        help="Path to configuration YAML file",
+        default=None,
+    )
+    parser.add_argument(
+        "--camera",
+        type=int,
+        help="Camera device ID",
+        default=0,
+    )
+    
+    args = parser.parse_args()
+    
+    try:
+        detector = HandDetector(config_path=args.config)
+        print("Starting hand tracking (2D mode)...")
+        print("Press 'q' to quit")
+        detector.run_interactive(mode='2d')
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def main_3d():
+    """CLI entry point for 3D hand tracking visualization."""
+    parser = argparse.ArgumentParser(
+        description="3D hand tracking visualization"
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        help="Path to configuration YAML file",
+        default=None,
+    )
+    
+    args = parser.parse_args()
+    
+    try:
+        detector = HandDetector(config_path=args.config)
+        print("Starting 3D hand tracking visualization...")
+        print("Controls: Rotate (drag), Zoom (scroll), Close window to exit")
+        detector.run_interactive(mode='3d')
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def main_combined():
+    """CLI entry point for combined 2D + 3D visualization."""
+    parser = argparse.ArgumentParser(
+        description="Combined 2D + 3D hand tracking visualization"
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        help="Path to configuration YAML file",
+        default=None,
+    )
+
+    args = parser.parse_args()
+
+    try:
+        detector = HandDetector(config_path=args.config)
+        print("Starting combined 2D + 3D visualization...")
+        print("Controls: Rotate 3D (drag), Zoom (scroll), Close window to exit")
+        detector.run_interactive(mode='combined')
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def main_rerun():
+    """CLI entry point for Rerun visualization."""
+    parser = argparse.ArgumentParser(
+        description="Rerun hand tracking visualization"
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        help="Path to configuration YAML file",
+        default=None,
+    )
+
+    args = parser.parse_args()
+
+    try:
+        detector = HandDetector(config_path=args.config)
+        print("Starting Rerun visualization...")
+        print("The Rerun viewer will open automatically.")
+        print("Press Ctrl+C to stop.")
+        detector.run_interactive(mode='rerun')
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def calibrate():
+    """CLI entry point for hand calibration."""
+    parser = argparse.ArgumentParser(
+        description="Calibrate hand tracking system"
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        help="Output configuration file path",
+        default="config/calibrated_config.yaml",
+    )
+    parser.add_argument(
+        "--distance",
+        type=float,
+        help="Reference distance from camera in cm (default: 50cm)",
+        default=50.0,
+    )
+    parser.add_argument(
+        "--samples",
+        type=int,
+        help="Number of samples to collect (default: 30)",
+        default=30,
+    )
+    
+    args = parser.parse_args()
+    
+    print("Hand Tracking Calibration")
+    print("=" * 50)
+    print(f"\nCalibration parameters:")
+    print(f"  Reference distance: {args.distance} cm")
+    print(f"  Samples to collect: {args.samples}")
+    print(f"  Output file: {args.output}")
+    print("\nInstructions:")
+    print(f"1. Measure and mark a distance of {args.distance} cm from your camera")
+    print("2. Place your hand at this marked distance")
+    print("3. Hold your hand steady with fingers spread")
+    print("4. Keep hand visible in camera frame")
+    print("\nPress Enter to start calibration, or Ctrl+C to cancel...")
+    
+    try:
+        input()
+        
+        import cv2
+        import yaml
+        import numpy as np
+        
+        detector = HandDetector()
+        print("\n🎥 Starting camera...")
+        print("Position your hand at the marked distance...")
+        
+        palm_widths = []
+        sample_count = 0
+        
+        while sample_count < args.samples:
+            frame = detector.get_frame()
+            if frame is None:
+                print("❌ Failed to get frame from camera")
+                sys.exit(1)
+            
+            hands = detector.detect_hands(frame)
+            
+            # Draw frame
+            frame_display = detector.draw_landmarks(frame.copy(), hands)
+            
+            # Add calibration info
+            cv2.putText(frame_display, f"Calibration: {sample_count}/{args.samples}", 
+                       (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+            cv2.putText(frame_display, f"Distance: {args.distance} cm", 
+                       (10, 70), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2)
+            
+            if len(hands) > 0:
+                hand = hands[0]  # Use first detected hand
+                palm_width = hand.get_palm_width()
+                palm_widths.append(palm_width)
+                sample_count += 1
+                
+                cv2.putText(frame_display, f"Palm width: {palm_width:.1f}px", 
+                           (10, 110), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)
+                cv2.putText(frame_display, "✓ Sample captured", 
+                           (10, 150), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)
+            else:
+                cv2.putText(frame_display, "No hand detected - please show hand", 
+                           (10, 110), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 255), 2)
+            
+            cv2.imshow("Calibration", frame_display)
+            
+            if cv2.waitKey(100) & 0xFF == ord('q'):
+                print("\n❌ Calibration cancelled by user")
+                cv2.destroyAllWindows()
+                sys.exit(0)
+        
+        cv2.destroyAllWindows()
+        
+        # Calculate calibrated reference palm width
+        palm_widths = np.array(palm_widths)
+        mean_palm_width = np.mean(palm_widths)
+        std_palm_width = np.std(palm_widths)
+        
+        print(f"\n✓ Calibration complete!")
+        print(f"\nResults:")
+        print(f"  Mean palm width: {mean_palm_width:.2f} px")
+        print(f"  Std deviation: {std_palm_width:.2f} px")
+        print(f"  Min: {np.min(palm_widths):.2f} px")
+        print(f"  Max: {np.max(palm_widths):.2f} px")
+        
+        # Save calibration
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        calibration_data = {
+            'calibration': {
+                'reference_palm_width': float(mean_palm_width),
+                'reference_distance_cm': float(args.distance),
+                'std_deviation': float(std_palm_width),
+                'samples_collected': len(palm_widths),
+            },
+            'hand_tracking': {
+                'camera': {'device_id': 0, 'width': 1280, 'height': 720, 'fps': 30},
+                'mediapipe': {
+                    'max_num_hands': 2,
+                    'min_detection_confidence': 0.7,
+                    'min_tracking_confidence': 0.5,
+                    'model_complexity': 1
+                },
+                'landmarks': {'smoothing_factor': 0.8, 'confidence_threshold': 0.6},
+                'display': {
+                    'show_landmarks': True,
+                    'show_connections': True,
+                    'show_bounding_box': True,
+                    'window_name': 'Hand Tracking'
+                },
+                'normalization': {
+                    'use_calibrated_reference': True,
+                    'reference_palm_width': float(mean_palm_width),
+                }
+            }
+        }
+        
+        with open(output_path, 'w') as f:
+            yaml.dump(calibration_data, f, default_flow_style=False)
+        
+        print(f"\n✓ Calibration saved to: {output_path}")
+        print(f"\nTo use this calibration:")
+        print(f"  detector = HandDetector(config_path='{output_path}')")
+        print(f"  # Or use normalized landmarks with custom reference:")
+        print(f"  normalized = hand.get_normalized_landmarks(reference_palm_width={mean_palm_width:.2f})")
+        
+    except KeyboardInterrupt:
+        print("\n\n❌ Calibration cancelled")
+        sys.exit(0)
+    except Exception as e:
+        print(f"\n❌ Error during calibration: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()