Upload scripts/push_to_huggingface.py with huggingface_hub

scripts/push_to_huggingface.py

@@ -0,0 +1,423 @@
+#!/usr/bin/env python3
+"""
+Push soccer ball detection project to Hugging Face Hub.
+Includes code, configs, and trained model checkpoints.
+"""
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+try:
+    from huggingface_hub import HfApi, create_repo, login
+    from huggingface_hub.utils import HfHubHTTPError
+    HF_AVAILABLE = True
+except ImportError:
+    HF_AVAILABLE = False
+    print("Error: huggingface_hub not installed. Install with: pip install huggingface_hub")
+    sys.exit(1)
+
+
+def get_files_to_upload(project_root: Path, exclude_patterns: List[str] = None) -> List[Path]:
+    """Get list of files to upload, excluding patterns."""
+    if exclude_patterns is None:
+        exclude_patterns = [
+            '__pycache__',
+            '.git',
+            '.gitignore',
+            'venv',
+            'env',
+            '.venv',
+            '.env',
+            '.env.local',
+            'mlruns',
+            'logs',
+            '*.log',
+            '.DS_Store',
+            'Thumbs.db',
+            'data/raw',
+            'data/output',
+            'datasets',
+            '*.tar.gz',
+            '*.tar',
+            '*.zip',
+        ]
+    
+    files_to_upload = []
+    
+    # Files/directories to include
+    include_patterns = [
+        '*.py',
+        '*.yaml',
+        '*.yml',
+        '*.md',
+        '*.txt',
+        '*.json',
+        '*.html',
+        '*.sh',
+        '*.dockerfile',
+        'Dockerfile',
+        'docker-compose*.yml',
+        'configs/',
+        'src/',
+        'scripts/',
+        'models/checkpoints/*.pth',  # Include model checkpoints
+    ]
+    
+    def should_include(file_path: Path) -> bool:
+        """Check if file should be included."""
+        rel_path = file_path.relative_to(project_root)
+        rel_str = str(rel_path)
+        
+        # Check exclude patterns
+        for pattern in exclude_patterns:
+            if pattern in rel_str or file_path.name.startswith('.'):
+                # Special handling for .gitkeep files
+                if file_path.name == '.gitkeep':
+                    return True
+                return False
+        
+        # Check include patterns
+        for pattern in include_patterns:
+            if pattern.endswith('/'):
+                # Directory pattern
+                if rel_str.startswith(pattern[:-1]):
+                    return True
+            elif '*' in pattern:
+                # Wildcard pattern
+                import fnmatch
+                if fnmatch.fnmatch(file_path.name, pattern):
+                    return True
+            else:
+                # Exact match
+                if file_path.name == pattern or rel_str == pattern:
+                    return True
+        
+        return False
+    
+    # Walk through project directory
+    for root, dirs, files in os.walk(project_root):
+        root_path = Path(root)
+        
+        # Filter directories to skip
+        dirs[:] = [d for d in dirs if not any(pattern in d for pattern in exclude_patterns)]
+        
+        # Check files
+        for file in files:
+            file_path = root_path / file
+            if should_include(file_path):
+                files_to_upload.append(file_path)
+    
+    return sorted(files_to_upload)
+
+
+def create_hf_readme(project_root: Path, repo_id: str) -> str:
+    """Create README content for Hugging Face."""
+    readme_content = f"""---
+license: mit
+tags:
+- computer-vision
+- object-detection
+- soccer
+- ball-detection
+- detr
+- rf-detr
+- pytorch
+datasets:
+- custom
+metrics:
+- mAP
+- precision
+- recall
+---
+
+# Soccer Ball Detection with RF-DETR
+
+Automated soccer ball detection pipeline using RF-DETR (Roboflow DETR) optimized for tiny object detection (<15 pixels).
+
+## Model Details
+
+### Architecture
+- **Model**: RF-DETR Base
+- **Backbone**: ResNet-50
+- **Classes**: Ball (single class detection)
+- **Input Resolution**: 1120x1120 (optimized for memory)
+- **Precision**: Mixed Precision (FP16/FP32) training, FP16 inference
+
+### Performance
+Based on training evaluation report (Epoch 39):
+- **mAP@0.5:0.95**: 0.682 (68.2%)
+- **mAP@0.5**: 0.990 (99.0%)
+- **Small Objects mAP**: 0.598 (59.8%)
+- **Training Loss**: 3.073
+- **Validation Loss**: 3.658
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+### Usage
+
+```python
+from src.perception.local_detector import LocalDetector
+from pathlib import Path
+
+# Initialize detector
+detector = LocalDetector(
+    model_path="models/checkpoints/latest_checkpoint.pth",
+    config_path="configs/default.yaml"
+)
+
+# Detect ball in image
+results = detector.detect(image_path)
+```
+
+### Process Video
+
+```bash
+python main.py --video path/to/video.mp4 --config configs/default.yaml --output data/output
+```
+
+## Training
+
+### Train from Scratch
+
+```bash
+python scripts/train_ball.py \\
+    --config configs/training.yaml \\
+    --dataset-dir datasets/combined \\
+    --output-dir models \\
+    --epochs 50
+```
+
+### Resume Training
+
+```bash
+python scripts/train_ball.py \\
+    --config configs/resume_20_epochs.yaml \\
+    --dataset-dir datasets/combined \\
+    --output-dir models \\
+    --resume models/checkpoints/latest_checkpoint.pth \\
+    --epochs 50
+```
+
+## Project Structure
+
+```
+soccer_cv_ball/
+├── main.py                 # Main orchestrator
+├── configs/               # Configuration files
+├── src/
+│   ├── perception/        # Detection, tracking
+│   ├── analysis/         # Event detection
+│   ├── visualization/    # Dashboard
+│   └── training/         # Training utilities
+├── scripts/               # Training and utility scripts
+├── models/               # Model checkpoints
+└── data/                 # Dataset (not included)
+```
+
+## Configuration
+
+Key configuration files:
+- `configs/training.yaml` - Main training configuration
+- `configs/default.yaml` - Inference configuration
+- `configs/resume_*.yaml` - Resume training configurations
+
+## Datasets
+
+This model was trained on:
+- SoccerSynth-Detection (synthetic data)
+- Open Soccer Ball Dataset
+- Custom validation sets
+
+## Precision Strategy
+
+- **Training**: Mixed Precision (FP16/FP32) - RF-DETR default
+- **Inference**: FP16 (half precision) for ~3x speedup
+- **Future**: INT8 via QAT (Quantization-Aware Training) for edge devices
+
+## Citation
+
+If you use this model, please cite:
+
+```bibtex
+@software{{soccer_ball_detection,
+  title={{Soccer Ball Detection with RF-DETR}},
+  author={{Your Name}},
+  year={{2026}},
+  url={{https://huggingface.co/{repo_id}}}
+}}
+```
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Acknowledgments
+
+- RF-DETR by Roboflow
+- SoccerSynth-Detection dataset
+- Open Soccer Ball Dataset
+"""
+    return readme_content
+
+
+def push_to_huggingface(
+    repo_id: str,
+    project_root: Path,
+    token: Optional[str] = None,
+    private: bool = False,
+    include_models: bool = True
+):
+    """Push project to Hugging Face Hub using HTTP API."""
+    
+    project_root = Path(project_root).resolve()
+    
+    print(f"📦 Preparing to push to Hugging Face: {repo_id}")
+    print(f"   Project root: {project_root}")
+    
+    # Initialize API
+    api = HfApi(token=token)
+    
+    # Verify login
+    try:
+        user_info = api.whoami()
+        print(f"🔐 Logged in as: {user_info.get('name', 'unknown')}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        print("   Please provide a valid token with --token argument")
+        sys.exit(1)
+    
+    # Create repository
+    print(f"📁 Creating repository: {repo_id}")
+    try:
+        api.create_repo(repo_id, private=private, exist_ok=True, repo_type="model")
+        print("✅ Repository created/exists")
+    except HfHubHTTPError as e:
+        if "already exists" in str(e).lower():
+            print("✅ Repository already exists")
+        else:
+            print(f"⚠️  Repository creation warning: {e}")
+    
+    # Get files to upload
+    print("🔍 Finding files to upload...")
+    files_to_upload = get_files_to_upload(project_root)
+    print(f"   Found {len(files_to_upload)} files")
+    
+    # Filter out model files if not including models
+    if not include_models:
+        files_to_upload = [f for f in files_to_upload if not str(f).endswith('.pth')]
+        print(f"   Excluding model files: {len(files_to_upload)} files remaining")
+    
+    # Create README
+    print("📝 Creating README.md...")
+    readme_path = project_root / "README.md"
+    readme_content = create_hf_readme(project_root, repo_id)
+    with open(readme_path, 'w') as f:
+        f.write(readme_content)
+    print("✅ README.md created")
+    
+    # Upload files
+    print("📤 Uploading files to Hugging Face Hub...")
+    uploaded = 0
+    failed = 0
+    
+    for file_path in files_to_upload:
+        try:
+            rel_path = file_path.relative_to(project_root)
+            # Convert to forward slashes for HF
+            path_in_repo = str(rel_path).replace('\\', '/')
+            
+            # Skip if it's the original README (we'll upload our generated one)
+            if path_in_repo == "README.md" and file_path != readme_path:
+                continue
+            
+            # Upload file
+            api.upload_file(
+                path_or_fileobj=str(file_path),
+                path_in_repo=path_in_repo,
+                repo_id=repo_id,
+                repo_type="model",
+                token=token
+            )
+            uploaded += 1
+            if uploaded % 10 == 0:
+                print(f"   Uploaded {uploaded}/{len(files_to_upload)} files...")
+        except Exception as e:
+            failed += 1
+            print(f"   ⚠️  Failed to upload {file_path.name}: {e}")
+    
+    # Upload the generated README
+    try:
+        api.upload_file(
+            path_or_fileobj=str(readme_path),
+            path_in_repo="README.md",
+            repo_id=repo_id,
+            repo_type="model",
+            token=token
+        )
+        print("✅ README.md uploaded")
+    except Exception as e:
+        print(f"⚠️  Failed to upload README.md: {e}")
+    
+    print(f"\n✅ Upload complete!")
+    print(f"   Uploaded: {uploaded} files")
+    if failed > 0:
+        print(f"   Failed: {failed} files")
+    print(f"   View at: https://huggingface.co/{repo_id}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Push soccer ball detection project to Hugging Face Hub"
+    )
+    parser.add_argument(
+        "--repo-id",
+        type=str,
+        required=True,
+        help="Hugging Face repository ID (e.g., 'username/soccer-ball-detection')"
+    )
+    parser.add_argument(
+        "--project-root",
+        type=str,
+        default=".",
+        help="Project root directory (default: current directory)"
+    )
+    parser.add_argument(
+        "--token",
+        type=str,
+        default=None,
+        help="Hugging Face API token (or use huggingface-cli login)"
+    )
+    parser.add_argument(
+        "--private",
+        action="store_true",
+        help="Create private repository"
+    )
+    parser.add_argument(
+        "--no-models",
+        action="store_true",
+        help="Exclude model checkpoint files (.pth)"
+    )
+    
+    args = parser.parse_args()
+    
+    push_to_huggingface(
+        repo_id=args.repo_id,
+        project_root=Path(args.project_root),
+        token=args.token,
+        private=args.private,
+        include_models=not args.no_models
+    )
+
+
+if __name__ == "__main__":
+    main()