Professional Pose Estimation using MediaPipe
A modern, extensible Python application for detecting human poses in videos and images using Google's MediaPipe framework. Built with best software engineering practices including SOLID principles, comprehensive testing, and modular architecture.
- Multi-format Support: Process videos, single images, or entire directories of images
- High-Quality Pose Detection: Leverages MediaPipe's state-of-the-art pose estimation models
- Multiple Output Formats: Export results as JSON and CSV with comprehensive metadata
- Visual Outputs: Generate frame-by-frame images and pose overlay visualizations
- Performance Monitoring: Built-in profiling and progress tracking
- Configurable Detection: Adjustable confidence thresholds and model complexity
- Modern CLI: Rich terminal interface with progress bars and colored output
- Comprehensive Logging: Structured logging with multiple verbosity levels
- Robust Error Handling: Graceful error handling with detailed error messages
- Extensible Architecture: Modular design following SOLID principles
- Python 3.12 or higher
- uv package manager (recommended)
-
Install uv if you haven't already:
# On macOS and Linux curl -LsSf https://astral.sh/uv/install.sh | sh # On Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
-
Clone the repository:
git clone https://github.com/your-username/pipedetect.git cd pipedetect -
Install dependencies:
uv sync
-
Activate the virtual environment:
# On Unix/macOS source .venv/bin/activate # On Windows .venv\Scripts\activate
git clone https://github.com/your-username/pipedetect.git
cd pipedetect
pip install -e .Use the convenient quick start scripts in the scripts/ directory:
# On Unix/macOS
./scripts/quick_start.sh
# On Windows
scripts\quick_start.bat# Process a video file
python src/detect.py video.mp4
# Process a single image
python src/detect.py image.jpg
# Process all images in a directory
python src/detect.py /path/to/images/
# Specify custom output directory
python src/detect.py video.mp4 --output-dir results/# High-precision detection with heavy model
python src/detect.py video.mp4 \
--model-complexity 2 \
--detection-confidence 0.8 \
--tracking-confidence 0.7
# Custom output filenames
python src/detect.py video.mp4 \
--json my_poses.json \
--csv my_poses.csv
# Enable segmentation and disable frame saving
python src/detect.py video.mp4 \
--segmentation \
--no-frames
# Verbose logging with log file
python src/detect.py video.mp4 \
--verbose --verbose \
--log-file pose_detection.logRun comprehensive examples using the provided scripts:
# On Unix/macOS
./scripts/run_examples.sh
# On Windows
scripts\run_examples.batPipeDetect generates comprehensive outputs organized in the outputs/ directory:
outputs/
├── pose_video_20231201_143022.json # Detailed JSON results
├── pose_video_20231201_143022.csv # Tabular CSV data
├── frames_video_20231201_143022/ # Original video frames
│ ├── frame_000001.jpg
│ ├── frame_000002.jpg
│ └── ...
└── overlay_video_20231201_143022/ # Frames with pose overlays
├── overlay_000001.jpg
├── overlay_000002.jpg
└── ...
{
"metadata": {
"export_timestamp": "2023-12-01T14:30:22",
"total_frames": 1000,
"processed_frames": 950,
"success_rate": 0.95,
"processing_time_seconds": 45.2,
"fps": 21.0
},
"results": [
{
"frame_id": 0,
"timestamp": 0.033,
"confidence": 0.92,
"source_file": "video.mp4",
"landmarks": [
{
"x": 0.5,
"y": 0.3,
"z": 0.1,
"visibility": 0.9,
"presence": 0.8
}
]
}
]
}Contains frame-by-frame data with columns for each of the 33 pose landmarks:
- Basic info:
frame_id,timestamp,confidence,source_file - Landmarks:
landmark_0_x,landmark_0_y,landmark_0_z,landmark_0_visibility,landmark_0_presence, ...
--model-complexity: 0 (light), 1 (full), 2 (heavy) - Default: 1--detection-confidence: Minimum detection confidence (0.0-1.0) - Default: 0.5--tracking-confidence: Minimum tracking confidence (0.0-1.0) - Default: 0.5--segmentation: Enable pose segmentation (slower but more detailed)--no-smooth: Disable landmark smoothing
--output-dir: Custom output directory - Default: "outputs"--json: Custom JSON filename--csv: Custom CSV filename--no-frames: Skip saving individual frames--no-overlays: Skip saving overlay frames
--verbose/-v: Increase verbosity (use -vv for debug)--quiet/-q: Suppress console output--no-progress: Hide progress bar--log-file: Save logs to file
Run the comprehensive test suite:
# Run all tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src/pipedetect --cov-report=html
# Run specific test files
uv run pytest tests/test_core_models.py
uv run pytest tests/test_validators.py -vPipeDetect follows modern software engineering principles:
pipedetect/
├── src/ # Source code
│ ├── detect.py # Main entry point
│ └── pipedetect/ # Main package
│ ├── core/ # Core business logic
│ │ ├── models.py # Data models (Pydantic)
│ │ └── exceptions.py # Custom exceptions
│ ├── detection/ # MediaPipe integration
│ │ ├── pose_detector.py # High-level detector
│ │ └── mediapipe_wrapper.py # MediaPipe wrapper
│ ├── io/ # Input/Output handling
│ │ ├── exporters.py # JSON/CSV exporters
│ │ ├── validators.py # Input validation
│ │ └── file_manager.py # File operations
│ ├── visualization/ # Rendering and progress
│ │ ├── overlay_renderer.py # Pose visualization
│ │ └── progress_tracker.py # Progress display
│ ├── utils/ # Utilities
│ │ ├── logging_config.py # Logging setup
│ │ └── performance.py # Performance profiling
│ └── cli/ # Command-line interface
│ ├── main.py # CLI entry point
│ └── processor.py # Main orchestrator
├── scripts/ # Automation scripts
│ ├── quick_start.sh # Quick start for Unix/macOS
│ ├── quick_start.bat # Quick start for Windows
│ ├── run_examples.sh # Examples for Unix/macOS
│ └── run_examples.bat # Examples for Windows
├── docs/ # Documentation
│ ├── INSTALLATION.md # Installation guide
│ ├── USAGE.md # Usage guide
│ ├── PROJECT_SUMMARY.md # Project overview
│ └── FINAL_PROJECT_STRUCTURE.md # Architecture details
├── tests/ # Comprehensive test suite
├── data/ # Sample data and videos
└── pyproject.toml # Project configuration
- Single Responsibility: Each class has one clear purpose
- Open/Closed: Easy to extend without modifying existing code
- Dependency Inversion: Abstractions don't depend on details
- DRY: No code duplication
- Comprehensive Error Handling: Graceful failure with detailed messages
- Performance Monitoring: Built-in profiling and metrics
# Clone and setup
git clone https://github.com/your-username/pipedetect.git
cd pipedetect
uv sync --all-extras
# Install pre-commit hooks
uv run pre-commit install
# Run code formatting
uv run black src/ tests/
uv run isort src/ tests/
# Type checking
uv run mypy src/- Exporters: Extend
BaseExporterinio/exporters.py - Validators: Add methods to
InputValidatorinio/validators.py - Visualizations: Extend
OverlayRendererinvisualization/overlay_renderer.py - CLI Options: Add to
cli/main.pyand updateprocessor.py
PipeDetect is optimized for performance:
- Efficient Processing: Streaming video processing with minimal memory usage
- Parallel Operations: Multi-threaded resource monitoring
- Progress Tracking: Real-time FPS and ETA calculations
- Memory Management: Automatic cleanup of temporary resources
- Video Processing: ~15-30 FPS on modern hardware
- Image Batch: ~10-50 images/second depending on size
- Memory Usage: ~200-500MB for typical video processing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes and add tests
- Run the test suite (
uv run pytest) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- MediaPipe for the excellent pose estimation models
- uv for modern Python package management
- Rich for beautiful terminal interfaces
- Typer for the CLI framework
Built with care for the computer vision community