🏀 HoopScout

מערכת לניתוח וידאו של משחקי כדורסל: מזהה שחקנית ספציפית, עוקבת אחר הפעולות שלה, מציעה רגעים מועמדים לאישור אנושי, ומייצרת קליפים מקוצרים ודוח סיכום (פעולות חיוביות: סל, אסיסט, ריבאונד; שליליות: איבודים ועבירות).

ארכיטקטורה

שלב	מה קורה	טכנולוגיה
1. זיהוי + מעקב	זיהוי שחקנים וכדור בכל פריים, מעקב עם פיצוי מצלמה זזה	YOLO (ultralytics) + BoT-SORT
2. Re-ID	התאמת tracklets לשחקנית היעד לפי דמיון חזותי	OSNet x1.0 (torchreid), 512-d cosine
2b. מספר גופייה (אופציונלי)	OCR עם הצבעה על פני כל tracklet	easyocr
3. הצעת רגעים	החזקת כדור ליד השחקנית, ניסיונות זריקה (כדור גבוה עולה)	היוריסטיקות על ציר הזמן
4. אישור אנושי	תיוג בממשק/קובץ labels	Gradio / JSON
5. תוצרים	קליפים לכל פעולה מאושרת + דוח סיכום בעברית	ffmpeg

למה זיהוי היברידי? מצלמה מהיציע לא תמיד מראה מספרי גופייה או פנים בצורה קריאה. לכן הזיהוי הראשי הוא דמיון חזותי לתמונות ייחוס של השחקנית (crop), ומספר הגופייה משמש כרמז עזר כשהוא קריא.

התקנה

דורש Python ≥ 3.10 ו-ffmpeg על ה-PATH.

pip install -r requirements.txt
# אופציונלי, לקריאת מספרי גופייה:
# pip install easyocr

משקלי OSNet מורידים אוטומטית בריצה הראשונה ממאגר kaiyangzhou/osnet ב-Hugging Face (הגדרת המודל מוטמעת בקוד — אין צורך ב-torchreid, שהחבילה שלו ב-PyPI מיושנת וההתקנה מהגיט שלו נכשלת ב-Windows ללא כלי build). מודל YOLO מוריד אוטומטית בהתאם לפרמטר --model (ברירת מחדל yolo26s.pt; לחלופה קלה יותר: yolo11n.pt).

שימוש — CLI

# 1. ניתוח: מייצר tracklets, דירוג דמיון, וקליפי תצוגה מקדימה של רגעים מועמדים
python run_pipeline.py analyze \
  --video game.mp4 \
  --ref player_ref_1.jpg player_ref_2.jpg \
  --out run1 \
  --device cuda        # או cpu

# 2. בדקו את הקליפים ב-run1/previews/, וכתבו labels.json:
#    {"0": "basket", "3": "turnover", "7": "irrelevant"}
#    תוויות תקפות: basket / assist / rebound / turnover / foul / irrelevant

# 3. השלמה: קליפים סופיים + דוח
python run_pipeline.py finalize --run run1 --video game.mp4 --labels labels.json

התוצרים: run1/clips/*.mp4 (קליפ לכל פעולה מאושרת), run1/report.md (הדוח בעברית), run1/labels.json, וכן run1/tracklet_ranking.json לבדיקת איכות הזיהוי.

שימוש — ממשק גרפי

python -m hoopscout.app

ממשק Gradio עם שני טאבים: ניתוח (וידאו + תמונות ייחוס) ותיוג בטבלה עריכה, ואז יצירת קליפים ודוח בלחיצה.

מבנה הקוד

hoopscout/
├── hoopscout/
│   ├── detect_track.py   # שלב 1: YOLO + BoT-SORT
│   ├── reid.py           # שלב 2: OSNet embeddings + גלריית השחקנית
│   ├── jersey.py         # שלב 2b: OCR מספרי גופייה (אופציונלי)
│   ├── identify.py       # שלב 3: דירוג tracklets
│   ├── events.py         # שלב 4: הצעות רגעים מועמדים
│   ├── clips.py          # חיתוך קליפים עם ffmpeg
│   ├── report.py         # דוח סיכום בעברית
│   ├── pipeline.py       # אורקסטרציה end-to-end
│   └── app.py            # ממשק Gradio
├── run_pipeline.py       # CLI
└── requirements.txt

האצת ביצועים

על CPU הריצה איטית כי מריצים זיהוי על כל פריים. שלוש האצות מדורגות:

1. דילוג פריימים (ההאצה הגדולה) — --stride 3 מעבד כל פריים שלישי ומזער את הזמן פי ~3. בברירת מחדל stride=2. למשחקים ארוכים 3-4 בסדר גמור; ערך גבוה מדי יפגע במעקב בתנועות מהירות.
2. מודל קטן + רזולוציה נמוכה — --model yolo11n.pt --imgsz 480 נותן עוד ~2x על חשבון מעט דיוק בשחקנים מרוחקים.
3. GPU — אם יש NVIDIA, התקינו torch עם CUDA והריצו עם --device cuda (מהיר פי 5-10). בלי GPU: למשחק שלם שווה להריץ על מחשוב ענן.

שילוב מהיר מומלץ על CPU: python run_pipeline.py analyze --video game.mp4 --ref ref1.jpg --stride 3 --model yolo11n.pt --imgsz 480

מגבלות מוכרות (גרסה 0.1)

• ההצעות האוטומטיות הן היוריסטיות: עבירות ואיבודים לא מזוהים ישירות — הן מסומנות ידנית תוך צפייה ברגעי ההחזקה שהוצעו.
• Re-ID מהציע הצעה, לא ודאות: חשוב לבדוק את tracklet_ranking.json ולוודא שה-tracklets הנכונים סומנו (התאמה נופלת בחילופים, מסך צל, ושחקניות דומות באותה קבוצה).
• וידאו באיכות נמוכה/זוויות קיצוניות מפחיתים דיוק של כל השלבים.
• גרסאות החבילות ב-requirements.txt נבדקו מול מבני ה-API הנוכחיים של ultralytics ו-torchreid, אך לא הורצו עדיין בסביבה חיה — בעיית גרסה ראשונה מתוקנת בדרך כלל בהצמדת הגרסה החדשה ביותר.

רעיונות להמשך

• הפעלה ב-HF Space (שלב 2 של הפרויקט) — הממשק כבר כתוב ב-Gradio.
• OCR משופר למספרי גופייה עם PARSeq מכויל (mkoshkina/jersey-number-pipeline) או חיתוך פלג-גוף עליון מבוסס pose.
• מעבר מהיוריסטיקות למודל זיהוי פעולות (למשל על בסיס BARD/E-BARD).