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

hand_tracking/hand_detector.py

@@ -0,0 +1,475 @@
+#!/usr/bin/env python3
+"""
+Hand detection using MediaPipe for data collection.
+
+This module handles real-time hand landmark detection and tracking.
+"""
+
+import cv2
+import mediapipe as mp
+import numpy as np
+from typing import Dict, List, Optional, Tuple, NamedTuple
+import yaml
+from dataclasses import dataclass
+
+
+@dataclass
+class HandLandmarks:
+    """Container for hand landmark data."""
+    landmarks: np.ndarray  # Shape: (21, 3) - x, y, z coordinates
+    handedness: str  # "Left" or "Right"
+    confidence: float
+    bbox: Tuple[int, int, int, int]  # x, y, width, height
+    
+    def get_normalized_landmarks(self, palm_size_meters: float = 0.08,
+                                 image_center: Tuple[float, float] = (640, 360),
+                                 reference_distance_m: float = 0.5,
+                                 reference_palm_width_px: float = 180.0) -> np.ndarray:
+        """
+        Get landmarks scaled to realistic hand proportions with depth estimation.
+
+        Centers on image center (not wrist) so hand position tracks movement in frame.
+        Scales so palm width ≈ palm_size_meters with uniform scaling on all axes.
+        Estimates Z depth from palm size using perspective geometry.
+
+        Args:
+            palm_size_meters: Target palm width in meters (default 0.08m for adult hand)
+            image_center: Center of image in pixels (x, y), default (640, 360) for 1280x720
+            reference_distance_m: Distance from camera during calibration in meters
+            reference_palm_width_px: Palm width in pixels at reference distance
+
+        Returns:
+            np.ndarray: Normalized landmarks in meters, shape (21, 3)
+        """
+        # Calculate current palm width in pixels (wrist to middle finger MCP)
+        wrist = self.landmarks[0]
+        middle_mcp = self.landmarks[9]
+        palm_width_px = np.sqrt((middle_mcp[0] - wrist[0])**2 +
+                                (middle_mcp[1] - wrist[1])**2)
+
+        # Scale factor: convert pixels to meters based on palm size
+        if palm_width_px > 1.0:
+            scale = palm_size_meters / palm_width_px
+        else:
+            scale = 0.001  # fallback for invalid detection
+
+        # Estimate camera distance from palm size (perspective geometry)
+        # closer hand = bigger palm, farther = smaller
+        if palm_width_px > 1.0:
+            estimated_distance_m = reference_distance_m * (reference_palm_width_px / palm_width_px)
+        else:
+            estimated_distance_m = reference_distance_m
+
+        # Z offset from reference distance (positive = farther, negative = closer)
+        z_base = estimated_distance_m - reference_distance_m
+
+        # Center on IMAGE CENTER (not wrist) and scale all axes uniformly
+        # This allows the hand to move in 3D space as it moves in the frame
+        normalized = self.landmarks.copy()
+        normalized[:, 0] = (self.landmarks[:, 0] - image_center[0]) * scale
+        normalized[:, 1] = (self.landmarks[:, 1] - image_center[1]) * scale
+        # MediaPipe z is relative finger depth within hand - add to estimated camera distance
+        normalized[:, 2] = z_base + (self.landmarks[:, 2] * scale)
+
+        return normalized
+    
+    def get_palm_width(self) -> float:
+        """
+        Get the palm width in pixels (distance between wrist and middle finger MCP).
+        
+        Returns:
+            float: Palm width in pixels
+        """
+        wrist = self.landmarks[0]
+        middle_mcp = self.landmarks[9]
+        return np.sqrt((middle_mcp[0] - wrist[0])**2 + (middle_mcp[1] - wrist[1])**2)
+
+
+class HandDetector:
+    """Real-time hand detection and tracking using MediaPipe."""
+    
+    def __init__(self, config_path: Optional[str] = None):
+        """Initialize hand detector with configuration."""
+        self.config = self._load_config(config_path)
+        self._setup_mediapipe()
+        self._setup_camera()
+        
+        # Load calibrated reference palm width if available
+        self.reference_palm_width = self._get_reference_palm_width()
+
+        # Load calibration parameters for metric conversion
+        self.reference_distance_m, self.calibrated_palm_width_px = self._get_calibration_params()
+
+        # Tracking state
+        self.is_tracking = False
+        self.frame_count = 0
+        self.last_landmarks = {}
+        self.last_hands = []  # Cache for frame skipping
+        
+    def _load_config(self, config_path: Optional[str]) -> Dict:
+        """Load configuration from YAML file."""
+        if config_path is None:
+            # Default configuration
+            return {
+                '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'
+                    }
+                }
+            }
+        
+        with open(config_path, 'r') as f:
+            return yaml.safe_load(f)
+    
+    def _get_reference_palm_width(self) -> float:
+        """Get reference palm width from config or use default."""
+        # Check for calibrated value first
+        if 'hand_tracking' in self.config:
+            if 'normalization' in self.config['hand_tracking']:
+                ref = self.config['hand_tracking']['normalization'].get('reference_palm_width')
+                if ref is not None:
+                    print(f"✓ Using calibrated reference palm width: {ref:.2f}px")
+                    return float(ref)
+
+        # Check old calibration format
+        if 'calibration' in self.config:
+            ref = self.config['calibration'].get('reference_palm_width')
+            if ref is not None:
+                print(f"✓ Using calibrated reference palm width: {ref:.2f}px")
+                return float(ref)
+
+        # Default value
+        return 100.0
+
+    def _get_calibration_params(self) -> Tuple[float, float]:
+        """Get calibration parameters from config.
+
+        Returns:
+            Tuple of (reference_distance_m, calibrated_palm_width_px)
+        """
+        if 'calibration' in self.config:
+            ref_dist = self.config['calibration'].get('reference_distance_cm', 50.0) / 100.0  # convert to meters
+            ref_palm = self.config['calibration'].get('reference_palm_width', 166.37)
+            return ref_dist, ref_palm
+        return 0.50, 166.37  # defaults in meters
+
+    def _get_reference_distance_m(self) -> float:
+        """Get reference distance in meters from config."""
+        if 'calibration' in self.config:
+            ref_cm = self.config['calibration'].get('reference_distance_cm', 50.0)
+            return ref_cm / 100.0
+        return 0.50
+    
+    def _setup_mediapipe(self):
+        """Initialize MediaPipe hands solution."""
+        self.mp_hands = mp.solutions.hands
+        self.mp_drawing = mp.solutions.drawing_utils
+        self.mp_drawing_styles = mp.solutions.drawing_styles
+        
+        # Initialize hands detector
+        mp_config = self.config['hand_tracking']['mediapipe']
+        self.hands = self.mp_hands.Hands(
+            static_image_mode=False,
+            max_num_hands=mp_config['max_num_hands'],
+            min_detection_confidence=mp_config['min_detection_confidence'],
+            min_tracking_confidence=mp_config['min_tracking_confidence'],
+            model_complexity=mp_config['model_complexity']
+        )
+    
+    def _setup_camera(self):
+        """Initialize camera capture."""
+        camera_config = self.config['hand_tracking']['camera']
+        self.cap = cv2.VideoCapture(camera_config['device_id'])
+        
+        # Set camera properties
+        self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, camera_config['width'])
+        self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, camera_config['height'])
+        self.cap.set(cv2.CAP_PROP_FPS, camera_config['fps'])
+        
+        if not self.cap.isOpened():
+            raise RuntimeError(f"Failed to open camera {camera_config['device_id']}")
+    
+    def start_tracking(self):
+        """Start hand tracking."""
+        self.is_tracking = True
+        self.frame_count = 0
+        print("Hand tracking started. Press 'q' to quit.")
+    
+    def stop_tracking(self):
+        """Stop hand tracking."""
+        self.is_tracking = False
+        print("Hand tracking stopped.")
+    
+    def get_frame(self) -> Optional[np.ndarray]:
+        """Capture a frame from the camera."""
+        if not self.cap.isOpened():
+            return None
+            
+        ret, frame = self.cap.read()
+        if not ret:
+            return None
+            
+        # Flip frame horizontally for mirror effect
+        frame = cv2.flip(frame, 1)
+        return frame
+    
+    def detect_hands(self, frame: np.ndarray) -> List[HandLandmarks]:
+        """Detect hands in the given frame."""
+        if frame is None:
+            return []
+        
+        # Convert BGR to RGB (MediaPipe requires RGB)
+        rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+        
+        # Improve performance by marking the image as not writeable
+        rgb_frame.flags.writeable = False
+        
+        # Process frame with MediaPipe
+        results = self.hands.process(rgb_frame)
+        
+        # Mark image as writeable again
+        rgb_frame.flags.writeable = True
+        
+        detected_hands = []
+        
+        if results.multi_hand_landmarks and results.multi_handedness:
+            for hand_landmarks, handedness in zip(results.multi_hand_landmarks, results.multi_handedness):
+                # Extract landmark coordinates
+                landmarks = self._extract_landmarks(hand_landmarks, frame.shape)
+                
+                # Get handedness
+                hand_label = handedness.classification[0].label
+                confidence = handedness.classification[0].score
+                
+                # Calculate bounding box
+                bbox = self._calculate_bbox(landmarks, frame.shape)
+                
+                # Apply smoothing if we have previous landmarks
+                if hand_label in self.last_landmarks:
+                    landmarks = self._apply_smoothing(landmarks, self.last_landmarks[hand_label])
+                
+                # Store current landmarks for next frame
+                self.last_landmarks[hand_label] = landmarks.copy()
+                
+                # Create HandLandmarks object
+                hand_data = HandLandmarks(
+                    landmarks=landmarks,
+                    handedness=hand_label,
+                    confidence=confidence,
+                    bbox=bbox
+                )
+                
+                detected_hands.append(hand_data)
+        
+        return detected_hands
+    
+    def _extract_landmarks(self, hand_landmarks, frame_shape: Tuple[int, int, int]) -> np.ndarray:
+        """Extract landmark coordinates from MediaPipe results."""
+        height, width = frame_shape[:2]
+        landmarks = np.zeros((21, 3))
+        
+        for i, landmark in enumerate(hand_landmarks.landmark):
+            landmarks[i] = [
+                landmark.x * width,   # x in pixel space
+                landmark.y * height,  # y in pixel space
+                landmark.z * width    # z in pixel space (same scale as x per MediaPipe docs)
+            ]
+        
+        return landmarks
+    
+    def _calculate_bbox(self, landmarks: np.ndarray, frame_shape: Tuple[int, int, int]) -> Tuple[int, int, int, int]:
+        """Calculate bounding box around hand landmarks."""
+        x_coords = landmarks[:, 0]
+        y_coords = landmarks[:, 1]
+        
+        x_min, x_max = int(np.min(x_coords)), int(np.max(x_coords))
+        y_min, y_max = int(np.min(y_coords)), int(np.max(y_coords))
+        
+        # Add padding
+        padding = 20
+        x_min = max(0, x_min - padding)
+        y_min = max(0, y_min - padding)
+        x_max = min(frame_shape[1], x_max + padding)
+        y_max = min(frame_shape[0], y_max + padding)
+        
+        return (x_min, y_min, x_max - x_min, y_max - y_min)
+    
+    def _apply_smoothing(self, current_landmarks: np.ndarray, previous_landmarks: np.ndarray) -> np.ndarray:
+        """Apply temporal smoothing to landmarks."""
+        alpha = self.config['hand_tracking']['landmarks']['smoothing_factor']
+        return alpha * previous_landmarks + (1 - alpha) * current_landmarks
+    
+    def draw_landmarks(self, frame: np.ndarray, hands: List[HandLandmarks]) -> np.ndarray:
+        """Draw hand landmarks and connections on the frame."""
+        display_config = self.config['hand_tracking']['display']
+        
+        for hand in hands:
+            if display_config['show_landmarks']:
+                # Convert landmarks back to MediaPipe format for drawing
+                mp_landmarks = self._landmarks_to_mediapipe(hand.landmarks, frame.shape)
+                
+                # Draw landmarks and connections
+                self.mp_drawing.draw_landmarks(
+                    frame,
+                    mp_landmarks,
+                    self.mp_hands.HAND_CONNECTIONS,
+                    self.mp_drawing_styles.get_default_hand_landmarks_style(),
+                    self.mp_drawing_styles.get_default_hand_connections_style()
+                )
+            
+            if display_config['show_bounding_box']:
+                # Draw bounding box
+                x, y, w, h = hand.bbox
+                cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2)
+                
+                # Draw hand label
+                label = f"{hand.handedness} ({hand.confidence:.2f})"
+                cv2.putText(frame, label, (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)
+        
+        return frame
+    
+    def _landmarks_to_mediapipe(self, landmarks: np.ndarray, frame_shape: Tuple[int, int, int]):
+        """Convert landmarks back to MediaPipe format for drawing."""
+        from mediapipe.framework.formats import landmark_pb2
+        
+        height, width = frame_shape[:2]
+        
+        # Create proper MediaPipe NormalizedLandmarkList
+        landmark_list = landmark_pb2.NormalizedLandmarkList()
+        
+        for i in range(21):
+            landmark = landmark_list.landmark.add()
+            landmark.x = landmarks[i, 0] / width
+            landmark.y = landmarks[i, 1] / height
+            landmark.z = landmarks[i, 2]
+        
+        return landmark_list
+    
+    def run_interactive(self, mode='combined'):
+        """Run interactive hand tracking with visualization.
+
+        Args:
+            mode: '2d' for OpenCV window, '3d' for matplotlib 3D,
+                  'combined' for both, 'rerun' for Rerun SDK visualization
+        """
+        if mode == '3d':
+            return self.run_3d_visualization()
+        elif mode == 'combined':
+            return self.run_combined_visualization()
+        elif mode == 'rerun':
+            return self.run_rerun_visualization()
+        
+        # Default 2D mode
+        self.start_tracking()
+        
+        try:
+            while self.is_tracking:
+                frame = self.get_frame()
+                if frame is None:
+                    break
+                
+                # Detect hands
+                hands = self.detect_hands(frame)
+                
+                # Draw landmarks
+                frame = self.draw_landmarks(frame, hands)
+                
+                # Add frame info
+                cv2.putText(frame, f"Frame: {self.frame_count}", (10, 30), 
+                           cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
+                cv2.putText(frame, f"Hands: {len(hands)}", (10, 70), 
+                           cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
+                
+                # Display frame
+                window_name = self.config['hand_tracking']['display']['window_name']
+                cv2.imshow(window_name, frame)
+                
+                # Check for quit
+                if cv2.waitKey(1) & 0xFF == ord('q'):
+                    break
+                
+                self.frame_count += 1
+                
+        except KeyboardInterrupt:
+            print("\nInterrupted by user")
+        finally:
+            self.cleanup()
+    
+    def run_3d_visualization(self):
+        """Run 3D visualization using matplotlib."""
+        try:
+            import matplotlib.pyplot as plt
+            from matplotlib.animation import FuncAnimation
+            from mpl_toolkits.mplot3d import Axes3D
+            import matplotlib
+            matplotlib.use('TkAgg')
+        except ImportError:
+            print("❌ matplotlib is required for 3D visualization")
+            print("Install with: pip install matplotlib")
+            return
+        
+        from .visualizer_3d import Hand3DVisualizer
+        visualizer = Hand3DVisualizer(self)
+        visualizer.run()
+    
+    def run_combined_visualization(self):
+        """Run combined 2D + 3D visualization."""
+        try:
+            import matplotlib.pyplot as plt
+            from matplotlib.animation import FuncAnimation
+            from mpl_toolkits.mplot3d import Axes3D
+            import matplotlib
+            matplotlib.use('TkAgg')
+        except ImportError:
+            print("❌ matplotlib is required for combined visualization")
+            print("Install with: pip install matplotlib")
+            return
+
+        from .visualizer_combined import CombinedVisualizer
+        visualizer = CombinedVisualizer(self)
+        visualizer.run()
+
+    def run_rerun_visualization(self):
+        """Run Rerun-based visualization.
+
+        Provides improved real-time performance and better 3D interaction
+        compared to matplotlib-based visualization.
+        """
+        try:
+            import rerun as rr
+        except ImportError:
+            print("❌ Rerun is required for this visualization mode")
+            print("Install with: pip install rerun-sdk")
+            return
+
+        from .visualizer_rerun import RerunVisualizer
+        visualizer = RerunVisualizer(self)
+        visualizer.run()
+
+    def cleanup(self):
+        """Clean up resources."""
+        self.stop_tracking()
+        if hasattr(self, 'cap'):
+            self.cap.release()
+        cv2.destroyAllWindows()
+    
+    def __del__(self):
+        """Destructor to ensure cleanup."""
+        self.cleanup()
+
+
+if __name__ == "__main__":
+    # Test the hand detector
+    detector = HandDetector()
+    detector.run_interactive()

hand_tracking/visualizer_3d.py

@@ -0,0 +1,214 @@
+"""3D visualization module for hand tracking."""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.animation import FuncAnimation
+from mpl_toolkits.mplot3d import Axes3D
+import matplotlib
+
+
+class Hand3DVisualizer:
+    """3D visualization of hand landmarks using matplotlib."""
+    
+    # MediaPipe hand connections
+    HAND_CONNECTIONS = [
+        (0, 1), (1, 2), (2, 3), (3, 4),      # Thumb
+        (0, 5), (5, 6), (6, 7), (7, 8),      # Index
+        (0, 9), (9, 10), (10, 11), (11, 12), # Middle
+        (0, 13), (13, 14), (14, 15), (15, 16), # Ring
+        (0, 17), (17, 18), (18, 19), (19, 20), # Pinky
+        (5, 9), (9, 13), (13, 17)            # Palm
+    ]
+    
+    FINGER_COLORS = {
+        'thumb': '#FF6B6B',
+        'index': '#4ECDC4',
+        'middle': '#45B7D1',
+        'ring': '#96CEB4',
+        'pinky': '#FFEAA7',
+        'palm': '#DFE6E9'
+    }
+    
+    def __init__(self, detector):
+        """Initialize with hand detector."""
+        self.detector = detector
+        self.is_running = False
+        
+        # Create figure
+        self.fig = plt.figure(figsize=(15, 6))
+        
+        # 3D plots
+        self.ax_left = self.fig.add_subplot(121, projection='3d')
+        self.ax_left.set_title('Left Hand', fontsize=14, fontweight='bold')
+        
+        self.ax_right = self.fig.add_subplot(122, projection='3d')
+        self.ax_right.set_title('Right Hand', fontsize=14, fontweight='bold')
+        
+        # Setup axes
+        for ax in [self.ax_left, self.ax_right]:
+            self._setup_axis(ax)
+        
+        # Initialize plots
+        self.left_hand_plots = self._init_hand_plots(self.ax_left)
+        self.right_hand_plots = self._init_hand_plots(self.ax_right)
+        
+        plt.tight_layout()
+    
+    def _setup_axis(self, ax):
+        """Setup 3D axis with metric units (meters).
+
+        Axis limits accommodate hand movement across the frame:
+        - X/Y: ±0.3m (hand can be ~300px from center, 300 * ~0.0005 scale ≈ 0.15m)
+        - Z: ±0.15m (depth range for hand distance variations)
+        """
+        ax.set_xlim([-0.30, 0.30])
+        ax.set_ylim([-0.30, 0.30])
+        ax.set_zlim([-0.15, 0.15])
+        ax.set_xlabel('X (m)', fontsize=10)
+        ax.set_ylabel('Y (m)', fontsize=10)
+        ax.set_zlabel('Z (m)', fontsize=10)
+        ax.view_init(elev=15, azim=45)
+        ax.grid(True, alpha=0.3)
+    
+    def _init_hand_plots(self, ax):
+        """Initialize plot elements."""
+        plots = {}
+        
+        # Landmarks
+        plots['landmarks'] = ax.scatter([], [], [], c='red', s=50, alpha=0.8)
+        
+        # Connections
+        plots['connections'] = []
+        for _ in self.HAND_CONNECTIONS:
+            line, = ax.plot([], [], [], 'b-', linewidth=2, alpha=0.6)
+            plots['connections'].append(line)
+        
+        # Coordinate axes for key landmarks
+        plots['axes'] = []
+        key_landmarks = [0, 4, 8, 12, 16, 20]
+        for _ in key_landmarks:
+            x_axis, = ax.plot([], [], [], 'r-', linewidth=1, alpha=0.7)
+            y_axis, = ax.plot([], [], [], 'g-', linewidth=1, alpha=0.7)
+            z_axis, = ax.plot([], [], [], 'b-', linewidth=1, alpha=0.7)
+            plots['axes'].append([x_axis, y_axis, z_axis])
+        
+        # Text
+        plots['text'] = ax.text2D(0.05, 0.95, '', transform=ax.transAxes,
+                                 fontsize=10, verticalalignment='top')
+        
+        return plots
+    
+    def _get_connection_color(self, conn_idx):
+        """Get color for connection."""
+        start, end = self.HAND_CONNECTIONS[conn_idx]
+        
+        if max(start, end) <= 4:
+            return self.FINGER_COLORS['thumb']
+        elif max(start, end) <= 8:
+            return self.FINGER_COLORS['index']
+        elif max(start, end) <= 12:
+            return self.FINGER_COLORS['middle']
+        elif max(start, end) <= 16:
+            return self.FINGER_COLORS['ring']
+        elif max(start, end) <= 20:
+            return self.FINGER_COLORS['pinky']
+        else:
+            return self.FINGER_COLORS['palm']
+    
+    def _update_hand_plot(self, ax, plots, hand_data):
+        """Update 3D plot for one hand."""
+        if hand_data is None:
+            plots['landmarks']._offsets3d = ([], [], [])
+            for line in plots['connections']:
+                line.set_data([], [])
+                line.set_3d_properties([])
+            for axis_lines in plots['axes']:
+                for line in axis_lines:
+                    line.set_data([], [])
+                    line.set_3d_properties([])
+            plots['text'].set_text('No hand detected')
+            return
+        
+        # Get normalized landmarks in meters (palm width ≈ 0.08m)
+        # Pass calibration params for depth estimation from palm size
+        normalized = hand_data.get_normalized_landmarks(
+            palm_size_meters=0.08,
+            reference_distance_m=self.detector.reference_distance_m,
+            reference_palm_width_px=self.detector.calibrated_palm_width_px
+        )
+        
+        # Update landmarks
+        plots['landmarks']._offsets3d = (normalized[:, 0], normalized[:, 1], normalized[:, 2])
+        
+        # Update connections
+        for idx, (start, end) in enumerate(self.HAND_CONNECTIONS):
+            x_data = [normalized[start, 0], normalized[end, 0]]
+            y_data = [normalized[start, 1], normalized[end, 1]]
+            z_data = [normalized[start, 2], normalized[end, 2]]
+            plots['connections'][idx].set_data(x_data, y_data)
+            plots['connections'][idx].set_3d_properties(z_data)
+            plots['connections'][idx].set_color(self._get_connection_color(idx))
+        
+        # Update coordinate axes
+        key_landmarks = [0, 4, 8, 12, 16, 20]
+        axis_length = 0.01  # 1cm axis lines in meters
+        
+        for i, landmark_idx in enumerate(key_landmarks):
+            if i < len(plots['axes']):
+                point = normalized[landmark_idx]
+                
+                # X axis (red)
+                plots['axes'][i][0].set_data([point[0], point[0] + axis_length], [point[1], point[1]])
+                plots['axes'][i][0].set_3d_properties([point[2], point[2]])
+                
+                # Y axis (green)
+                plots['axes'][i][1].set_data([point[0], point[0]], [point[1], point[1] + axis_length])
+                plots['axes'][i][1].set_3d_properties([point[2], point[2]])
+                
+                # Z axis (blue)
+                plots['axes'][i][2].set_data([point[0], point[0]], [point[1], point[1]])
+                plots['axes'][i][2].set_3d_properties([point[2], point[2] + axis_length])
+        
+        # Update text (show wrist position to verify hand tracking in 3D space)
+        wrist = normalized[0]
+        plots['text'].set_text(f"{hand_data.handedness}\nConf: {hand_data.confidence:.2f}\nWrist: ({wrist[0]*100:.1f}, {wrist[1]*100:.1f}, {wrist[2]*100:.1f})cm")
+    
+    def update(self, frame_num):
+        """Animation update."""
+        frame = self.detector.get_frame()
+        if frame is None:
+            return []
+        
+        hands = self.detector.detect_hands(frame)
+        
+        left_hand = next((h for h in hands if h.handedness == 'Left'), None)
+        right_hand = next((h for h in hands if h.handedness == 'Right'), None)
+        
+        self._update_hand_plot(self.ax_left, self.left_hand_plots, left_hand)
+        self._update_hand_plot(self.ax_right, self.right_hand_plots, right_hand)
+        
+        self.fig.suptitle(f'3D Hand Tracking - Frame: {self.detector.frame_count}',
+                         fontsize=16, fontweight='bold')
+        
+        self.detector.frame_count += 1
+        return []
+    
+    def run(self):
+        """Run visualization."""
+        print("Starting 3D visualization...")
+        print("Controls: Rotate (drag), Zoom (scroll), Close window to exit")
+        
+        self.is_running = True
+        
+        try:
+            anim = FuncAnimation(self.fig, self.update, interval=33, blit=False)
+            plt.show()
+        except KeyboardInterrupt:
+            print("\nVisualization stopped")
+        finally:
+            self.cleanup()
+    
+    def cleanup(self):
+        """Cleanup."""
+        self.is_running = False
+        plt.close('all')