INDEPENDENT_MODELS_MIGRATION.md

Independent Models Migration

Date: February 24, 2026

Summary

The system has been updated to use independently trained YOLOv5 models for player and ball detection instead of the combined models.

Changes Made

1. Config Files Updated

• back-end/configs/configs.py

  • PLAYER_DETECTOR_PATH: Changed from TEAM_MODEL_PATH → models/player_detector_v1.pt
  • BALL_DETECTOR_PATH: Changed from TEAM_MODEL_PATH → models/ball_detector_v1.pt

• back-end/app/config.py

  • player_detector_path: Updated from "models/nbl_v3_combined.pt" → "models/player_detector_v1.pt"
  • ball_detector_path: Updated from "models/nbl_v3_combined.pt" → "models/ball_detector_v1.pt"
  • team_model_path: Now uses "models/nbl_v4_combined.pt" (for team analysis)
  • personal_model_path: Still uses "models/nbl_v2_combined.pt" (for personal analysis)

• back-end/test_system.py

  • Model loader updated to use new independent model paths

2. Model Files in Production

back-end/models/
├── player_detector_v1.pt      (165 MB) - trained Feb 24 16:23
├── ball_detector_v1.pt        (165 MB) - trained Feb 24 17:10
├── court_keypoint_detector.pt (399 MB) - existing
├── nbl_v3_combined.pt         (165 MB) - kept for reference
└── nbl_v4_combined.pt         (5.3 MB) - for team analysis

3. Training Metrics

Player Detector (train5)

• Model: YOLOv5l6u
• Epochs: 100
• mAP50: 0.745
• mAP50-95: 0.381
• Per-class performance:
  • player: 0.851 (mAP50)
  • hoop: 0.836
  • referee: 0.802
  • basketball: 0.744
  • shot-clock: 0.518

Ball Detector (train6)

• Model: YOLOv5l6u
• Epochs: 100
• mAP50: 0.731
• mAP50-95: 0.403
• Per-class performance:
  • player: 0.865 (mAP50)
  • hoop: 0.909
  • referee: 0.780
  • basketball: 0.646
  • shot-clock: 0.454

4. System Components Affected

The following components now use independent models:

• trackers/player_tracker.py - loads player_detector_v1.pt
• trackers/ball_tracker.py - loads ball_detector_v1.pt
• All video analysis pipelines pass the correct model paths via config

5. Backward Compatibility

• Combined models are still available in models/ for reference
• team_analysis.py still uses team-oriented combined models for compatibility
• personal_analysis.py still uses personal analysis combined models

Benefits

1. Specialized Training: Each detector trained specifically for its object class
2. Better Performance: Dedicated models allow for task-specific optimization
3. Modular Architecture: Easier to update individual detectors without affecting others
4. Production Ready: Both models trained on identical NBL-6 dataset for consistency

Rollback Instructions

If needed, to revert to combined models:

# In back-end/configs/configs.py
PLAYER_DETECTOR_PATH = TEAM_MODEL_PATH  # = 'models/nbl_v4_combined.pt'
BALL_DETECTOR_PATH = TEAM_MODEL_PATH     # = 'models/nbl_v4_combined.pt'

Verification

All imports verified working:

from configs import PLAYER_DETECTOR_PATH, BALL_DETECTOR_PATH
# PLAYER_DETECTOR_PATH = 'models/player_detector_v1.pt' ✓
# BALL_DETECTOR_PATH = 'models/ball_detector_v1.pt' ✓