{"id":30626380,"url":"https://github.com/ollielarkins/mediapipe-handtrackerv2","last_synced_at":"2026-05-20T05:13:18.671Z","repository":{"id":312150232,"uuid":"1046520225","full_name":"ollielarkins/mediapipe-handtrackerv2","owner":"ollielarkins","description":"A Python tool for tracking hands in videos using MediaPipe, logging positions to CSV, and advanced analytics—all built into the CLI.","archived":false,"fork":false,"pushed_at":"2025-08-28T21:15:28.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-29T01:59:00.066Z","etag":null,"topics":["handtracking","mediapipe","mediapipe-hands","python","tracking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ollielarkins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-28T20:06:39.000Z","updated_at":"2025-08-28T21:15:31.000Z","dependencies_parsed_at":"2025-08-29T01:59:01.376Z","dependency_job_id":"3fd741c4-510c-4245-b271-6d25d8c2a665","html_url":"https://github.com/ollielarkins/mediapipe-handtrackerv2","commit_stats":null,"previous_names":["ollielarkins/mediapipe-handtrackerv2"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ollielarkins/mediapipe-handtrackerv2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollielarkins%2Fmediapipe-handtrackerv2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollielarkins%2Fmediapipe-handtrackerv2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollielarkins%2Fmediapipe-handtrackerv2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollielarkins%2Fmediapipe-handtrackerv2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ollielarkins","download_url":"https://codeload.github.com/ollielarkins/mediapipe-handtrackerv2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ollielarkins%2Fmediapipe-handtrackerv2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272892514,"owners_count":25010795,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["handtracking","mediapipe","mediapipe-hands","python","tracking"],"created_at":"2025-08-30T19:01:28.672Z","updated_at":"2026-05-20T05:13:18.614Z","avatar_url":"https://github.com/ollielarkins.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mediapipe-handtrackerv2\n# MediaPipe Hand Tracking Tool 🤲\n\nAn advanced hand tracking analysis tool that processes videos to detect, track, and analyze hand movements using Google's MediaPipe framework. Features real-time hand detection, 3D trajectory visualization, movement analytics, and comprehensive reporting.\n\n\nhttps://github.com/user-attachments/assets/79457fdb-9900-4082-a67b-96517a4f7a43\n\n\n## 📷 Images (@oliver.larkins on Instagram)\n\u003cimg width=\"1080\" height=\"1350\" alt=\"4\" src=\"https://github.com/user-attachments/assets/276146a4-ee11-482d-bb60-8707cd53a283\" /\u003e\n\u003cimg width=\"1080\" height=\"1350\" alt=\"3\" src=\"https://github.com/user-attachments/assets/1a7b7974-2690-4e03-a4e9-7ebc39869bf3\" /\u003e\n\u003cimg width=\"1080\" height=\"1350\" alt=\"2\" src=\"https://github.com/user-attachments/assets/492587f3-b1a5-497d-9980-cee42f799007\" /\u003e\n\u003cimg width=\"1080\" height=\"1350\" alt=\"1\" src=\"https://github.com/user-attachments/assets/e762a16c-6c56-4f92-84bd-4869e7b2e0e4\" /\u003e\n\n\n## ✨ Features\n\n### Core Functionality\n- **Multi-Hand Detection**: Track up to 4 hands simultaneously (left/right hand identification)\n- **YouTube Integration**: Download and process videos directly from YouTube URLs\n- **Real-time Processing**: Live hand tracking with visual overlay on video\n- **3D Trajectory Analysis**: Interactive 3D visualization of hand movement paths\n- **Movement Analytics**: Comprehensive statistical analysis of hand movements\n\n### Analysis \u0026 Visualization\n- **ASCII Heatmaps**: CLI-based movement heatmaps for quick analysis\n- **Interactive 3D Plots**: Browser-based 3D trajectory visualization using Plotly\n- **Movement Statistics**: Speed, distance, acceleration, and position analytics\n- **Comprehensive Reports**: Detailed text and visual reports\n\n### User Experience\n- **Rich CLI Interface**: Beautiful command-line interface with progress bars and tables\n- **Side-by-Side Playback**: Compare original and tracked videos simultaneously\n- **Automatic Cleanup**: Smart file management with automatic cleanup of temporary files\n- **URL Caching**: Remember downloaded videos to avoid re-downloading\n\n## 🛠️ Installation\n\n### Prerequisites\n- Python 3.7+ (Up to Python 3.11.9)\n- FFmpeg (for video processing)\n- Windows OS (current configuration)\n\n### Required Python Packages\n```bash\npip install opencv-python mediapipe yt-dlp rich numpy matplotlib plotly scipy\n```\n\n### FFmpeg Setup\n1. Download FFmpeg from [https://ffmpeg.org/download.html](https://ffmpeg.org/download.html)\n2. Extract to `C:\\ffmpeg\\ffmpeg-8.0-essentials_build\\`\n3. Update the paths in the script if your installation differs:\n   ```python\n   ffmpeg_path = r\"C:\\ffmpeg\\ffmpeg-8.0-essentials_build\\bin\\ffmpeg.exe\"\n   ffplay_path = r\"C:\\ffmpeg\\ffmpeg-8.0-essentials_build\\bin\\ffplay.exe\"\n   ```\n\n### Directory Structure\nThe tool automatically creates the following directory structure:\n```\nC:\\Users\\[username]\\Hand Tracking Mediapipe\\\n├── videos/           # Downloaded/input videos\n├── tracked/          # Temporarily processed videos\n├── csv_data/         # Hand tracking data exports\n├── reports/          # Analysis reports and visualizations\n└── url_cache.txt     # Cached video URLs\n```\n\n## 🚀 Usage\n\n### Quick Start\n1. Run the script:\n   ```bash\n   python hand_tracking_tool.py\n   ```\n\n2. Choose input method:\n   - **YouTube URL**: Enter any YouTube video URL\n   - **Local File**: Enter filename or select by number\n   - **Cached Video**: Reprocess previously downloaded videos\n\n3. The tool will:\n   - Download/process the video\n   - Perform hand tracking analysis\n   - Generate visualizations and reports\n   - Display results in your preferred format\n\n### Input Options\n- **YouTube URLs**: Direct video processing from YouTube\n- **Video Selection**: Choose from previously downloaded videos\n- **File Management**: Delete videos or clear cache as needed\n\n### Output Formats\n- **CSV Data**: Frame-by-frame hand tracking coordinates\n- **3D Trajectory**: Interactive HTML visualization\n- **Analysis Reports**: Comprehensive text reports\n- **Video Playback**: Side-by-side or tracked-only viewing\n\n## 📊 Analysis Features\n\n### Movement Statistics\n- **Distance Tracking**: Total distance traveled by each hand\n- **Speed Analysis**: Average, maximum, and minimum speeds\n- **Position Analytics**: Movement ranges and center of mass\n- **Detection Rates**: Frame-by-frame tracking success rates\n\n### Visualization Types\n1. **ASCII Heatmaps**: Quick CLI visualization of movement patterns\n2. **3D Trajectories**: Interactive browser-based 3D movement paths\n3. **Statistical Reports**: Detailed numerical analysis\n\n### Data Export\n- **CSV Format**: Frame, hand type, coordinates (x, y, z), landmark count\n- **HTML Reports**: Interactive 3D visualizations\n- **Text Reports**: Comprehensive statistical summaries\n\n## 🎯 Possible Advanced Use Cases with Tampering\n\n### Sports Analysis\n- Golf swing analysis\n- Tennis technique evaluation\n- Baseball pitching mechanics\n- Basketball shooting form\n\n### Medical \u0026 Therapy\n- Hand coordination assessment\n- Rehabilitation progress tracking\n- Motor skill evaluation\n- Tremor analysis\n\n### Research \u0026 Education\n- Gesture recognition research\n- Human-computer interaction studies\n- Sign language analysis\n- Movement pattern research\n\n### Entertainment \u0026 Art\n- Dance choreography analysis\n- Musical performance evaluation\n- Animation reference tracking\n- Creative movement studies\n\n## 📈 Technical Details\n\n### Hand Detection Specifications\n- **Framework**: Google MediaPipe\n- **Max Hands**: 4 simultaneous detections\n- **Confidence Threshold**: 0.5 (adjustable)\n- **Landmark Points**: 21 per hand\n- **Coordinate System**: Normalized 3D coordinates\n\n### Performance Optimizations\n- **Smart Caching**: Avoid re-downloading videos\n- **Efficient Processing**: Frame-by-frame analysis with progress tracking\n- **Memory Management**: Automatic cleanup of temporary files\n- **Batch Processing**: Handle multiple videos efficiently\n\n### Output Data Structure\n```csv\nframe,hand,wrist_x,wrist_y,wrist_z,num_landmarks\n1,Left,0.456,0.234,0.123,21\n1,Right,0.678,0.345,0.234,21\n```\n\n## 🔧 Configuration\n\n### Customizable Parameters\n```python\n# Hand tracking sensitivity\nmin_detection_confidence = 0.5\nmin_tracking_confidence = 0.5\n\n# Maximum hands to detect\nmax_num_hands = 4\n\n# Video processing quality\nscale_factor = \"iw/2:ih/2\"  # Resize for faster processing\n```\n\n### Path Configuration\nUpdate these paths based on your system setup:\n```python\nproject_folder = r\"C:\\Users\\ozzal\\Hand Tracking Mediapipe\"\nffmpeg_path = r\"C:\\ffmpeg\\ffmpeg-8.0-essentials_build\\bin\\ffmpeg.exe\"\n```\n\n## 🚨 Troubleshooting\n\n### Common Issues\n\n**FFmpeg Not Found**\n- Ensure FFmpeg is installed and paths are correct\n- Verify FFmpeg is in your system PATH\n\n**Video Download Fails**\n- Check internet connection\n- Verify YouTube URL is accessible\n- Try clearing URL cache with `clear cache` command\n\n**Low Detection Rates**\n- Ensure hands are clearly visible in video\n- Adjust `min_detection_confidence` parameter\n- Check video quality and lighting\n\n**Memory Issues**\n- Process shorter videos for testing\n- Increase system RAM if processing large files\n- Check available disk space\n\n### Performance Tips\n- Use lower resolution videos for faster processing\n- Ensure good lighting in source videos\n- Keep hands clearly visible and unobstructed\n- Process shorter clips for initial testing\n\n## 📋 Requirements\n\n### System Requirements\n- **OS**: Windows (current configuration)\n- **RAM**: 4GB+ recommended\n- **Storage**: 1GB+ free space for video processing\n- **CPU**: Multi-core processor recommended\n\n### Python Dependencies\n```txt\nopencv-python\u003e=4.5.0\nmediapipe\u003e=0.8.0\nyt-dlp\u003e=2023.1.6\nrich\u003e=12.0.0\nnumpy\u003e=1.21.0\nmatplotlib\u003e=3.5.0\nplotly\u003e=5.0.0\nscipy\u003e=1.7.0\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Areas for improvement:\n- Cross-platform compatibility (macOS/Linux)\n- Real-time webcam processing\n- Additional analysis metrics\n- Export format options\n- GUI interface development\n\n## 📝 License\n\nThis project is open source and available under the MIT License.\n\n## 🙏 Acknowledgments\n\n- **Google MediaPipe**: For the excellent hand tracking framework\n- **Rich Library**: For the beautiful CLI interface\n- **Plotly**: For interactive 3D visualizations\n- **yt-dlp**: For reliable video downloading\n\n## 📞 Support\n\nFor issues, questions, or contributions:\n1. Check the troubleshooting section above\n2. Review existing issues in the repository\n3. Create a detailed issue report with:\n   - System information\n   - Error messages\n   - Steps to reproduce\n   - Sample video (if applicable)\n\n---\n\n**Made with ❤️ for hand tracking analysis and movement research**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Follielarkins%2Fmediapipe-handtrackerv2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Follielarkins%2Fmediapipe-handtrackerv2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Follielarkins%2Fmediapipe-handtrackerv2/lists"}