wunderscout 0.1.2__tar.gz

wunderscout-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-n-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

wunderscout-0.1.2/.gitignore

@@ -0,0 +1,40 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv/
+.uv/
+
+# Env
+.env
+
+# Datasets
+football-players-detection-20/
+football-field-detection-15/
+
+# Output directories
+runs/
+data/
+
+# Research scripts
+research/
+
+# Models
+*.pt
+
+# Videos
+*.mp4
+
+# Mac
+.DS_Store
+
+# Large/Auto-generated data
+*.png
+*.json
+!pyproject.toml
+!package.json

wunderscout-0.1.2/.python-version

@@ -0,0 +1 @@
+3.11

wunderscout-0.1.2/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: wunderscout
+Version: 0.1.2
+Summary: Add your description here
+Requires-Python: >=3.11
+Requires-Dist: ipython>=9.5.0
+Requires-Dist: matplotlib>=3.10.6
+Requires-Dist: memory-profiler>=0.61.0
+Requires-Dist: more-itertools>=10.8.0
+Requires-Dist: networkx>=3.5
+Requires-Dist: numba>=0.58
+Requires-Dist: numpy>=2.3.2
+Requires-Dist: opencv-python>=4.11.0.86
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: plotly>=6.3.0
+Requires-Dist: protobuf>=6.32.1
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: roboflow>=1.2.7
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: sentencepiece>=0.2.1
+Requires-Dist: supervision>=0.26.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: transformers>=4.56.1
+Requires-Dist: ultralytics>=8.3.193
+Requires-Dist: umap-learn>=0.5.9.post2

wunderscout-0.1.2/context.md

@@ -0,0 +1,93 @@
+This project integrates two main data sources: StatsBomb Events Data and Metrica Sports Tracking Data. Both datasets provide complementary information useful for AI models analyzing soccer matches.
+
+---
+
+1. StatsBomb Events Data
+
+- Format: JSON (array of objects)
+
+- Granularity: Event-based (specific match events with contextual details)
+
+- Typical Event Example: "Starting XI", passes, shots, fouls, etc.
+
+Main fields:
+
+- id: Unique identifier of the event
+
+- index: Sequential index of the event
+
+- period: Match period (1 = first half, 2 = second half)
+
+- timestamp, minute, second: Time indicators
+
+- type: Event category (e.g., "Starting XI", "Pass", "Shot")
+
+- possession: Possession sequence ID
+
+- possession_team: Team in possession
+
+- play_pattern: Context of play (e.g., "Regular Play", "From Corner")
+
+- team: Team performing the event
+
+- duration: Duration of the event (float in seconds)
+
+- tactics: (only for Starting XI events) formation + list of players and their positions
+
+Example – "Starting XI" event:
+
+- Includes formation (e.g., 4-2-3-1)
+
+- lineup: Array of players
+
+  - Each player has:
+
+    - player.id, player.name
+
+    - position.id, position.name (e.g., Goalkeeper, Right Back)
+
+    - jersey_number
+
+This dataset is high-level, event-based and provides semantic information (who did what, when, and in which tactical context).
+
+---
+
+2. Metrica Sports Tracking Data
+
+- Format: CSV
+
+- Granularity: Frame-by-frame spatio-temporal tracking (player and ball positions)
+
+Structure:
+
+- Header row contains player identifiers (Player15, Player16, …, Player28) and columns for ball position
+
+- Each record represents a single frame in the match with timestamp
+
+Main fields:
+
+- Period: Match half (1 = first half, 2 = second half)
+
+- Frame: Frame number within the match video
+
+- Time [s]: Timestamp in seconds (float, high precision)
+
+- PlayerXX: X and Y coordinates of each player (two columns per player)
+
+  - Example: Player15_x, Player15_y
+
+- Ball: X and Y coordinates of the ball
+
+Example row:
+
+- Period = 1
+
+- Frame = 1
+
+- Time [s] = 0.04
+
+- Player positions given as normalized coordinates (0–1 scale) across the pitch
+
+- Ball position reported similarly
+
+This dataset is low-level, continuous tracking data giving spatial and temporal movement of all players and the ball throughout the match.

wunderscout-0.1.2/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "wunderscout"
+version = "0.1.2"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "ipython>=9.5.0",
+    "memory-profiler>=0.61.0",
+    "more-itertools>=10.8.0",
+    "numpy>=2.3.2",
+    "opencv-python>=4.11.0.86",
+    "plotly>=6.3.0",
+    "protobuf>=6.32.1",
+    "psutil>=7.0.0",
+    "python-dotenv>=1.1.1",
+    "roboflow>=1.2.7",
+    "scikit-learn>=1.7.2",
+    "sentencepiece>=0.2.1",
+    "tqdm>=4.67.1",
+    "transformers>=4.56.1",
+    "ultralytics>=8.3.193",
+    "umap-learn>=0.5.9.post2",
+    "numba>=0.58",
+    "supervision>=0.26.1",
+    "pandas>=2.3.2",
+    "matplotlib>=3.10.6",
+    "seaborn>=0.13.2",
+    "networkx>=3.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wunderscout"]

wunderscout-0.1.2/src/wunderscout/__init__.py

@@ -0,0 +1,6 @@
+from .vision import VisionEngine
+from .geometry import PitchMapper
+from .teams import TeamClassifier
+from .core import ScoutingPipeline
+
+__all__ = ["VisionEngine", "PitchMapper", "TeamClassifier", "ScoutingPipeline"]

wunderscout-0.1.2/src/wunderscout/core.py

@@ -0,0 +1,164 @@
+import cv2
+import supervision as sv
+import numpy as np
+from pathlib import Path
+from .vision import VisionEngine
+from .geometry import PitchMapper
+from .teams import TeamClassifier
+from .exporters import DataExporter
+
+
+class ScoutingPipeline:
+    def __init__(self, player_weights, field_weights):
+        self.engine = VisionEngine(player_weights, field_weights)
+        self.mapper = PitchMapper()
+        self.classifier = TeamClassifier()
+
+    def run(self, video_path, output_video_path):
+        # 1. Warm-up (Calibration)
+        print("WORKER: Calibrating teams...")
+        crops = self.engine.get_calibration_crops(video_path)
+        if len(crops) > 0:
+            embeddings = self.engine.get_embeddings(crops)
+            self.classifier.fit(embeddings)
+        else:
+            print("WARNING: No player crops found for calibration.")
+
+        # 2. Setup Video I/O
+        output_path_obj = Path(output_video_path)
+        output_path_obj.parent.mkdir(parents=True, exist_ok=True)
+        # ---------------------------------------------------------------------
+
+        cap = cv2.VideoCapture(video_path)
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+        out = cv2.VideoWriter(
+            output_video_path, cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height)
+        )
+
+        if not out.isOpened():
+            print(f"ERROR: Could not create video file at {output_video_path}")
+            return
+
+        tracker = sv.ByteTrack()
+        tracking_results = {}
+
+        # ID Constants
+        BALL_ID = 0
+        GOALKEEPER_ID = 1
+        PLAYER_ID = 2
+        REFEREE_ID = 3
+
+        # 3. Main Processing Loop
+        print(f"WORKER: Starting processing: {video_path}")
+        frame_generator = sv.get_video_frames_generator(video_path)
+
+        for frame_idx, frame in enumerate(frame_generator):
+            if frame_idx % 100 == 0:
+                print(f"WORKER: Processing frame {frame_idx}")
+
+            # --- A. DETECTION ---
+            all_dets = self.engine.detect_players(frame)
+            f_res = self.engine.detect_field(frame)
+
+            # --- B. FIELD HOMOGRAPHY ---
+            H = None
+            if f_res.keypoints is not None and len(f_res.keypoints.xy) > 0:
+                H = self.mapper.get_matrix(
+                    f_res.keypoints.xy[0].cpu().numpy(),
+                    f_res.keypoints.conf[0].cpu().numpy(),
+                )
+            else:
+                H = self.mapper.last_h
+
+            # --- C. SEPARATE BALL & OTHERS ---
+            ball_detections = all_dets[all_dets.class_id == BALL_ID]
+            ball_detections.xyxy = sv.pad_boxes(xyxy=ball_detections.xyxy, px=10)
+
+            other_detections = all_dets[all_dets.class_id != BALL_ID]
+            other_detections = other_detections.with_nms(threshold=0.5)
+
+            # --- D. TRACKING ---
+            tracked_objects = tracker.update_with_detections(other_detections)
+
+            # Split tracked objects
+            tracked_players = tracked_objects[tracked_objects.class_id == PLAYER_ID]
+            tracked_gks = tracked_objects[tracked_objects.class_id == GOALKEEPER_ID]
+            tracked_refs = tracked_objects[tracked_objects.class_id == REFEREE_ID]
+
+            # --- E. TEAM CLASSIFICATION ---
+
+            # 1. Players
+            if len(tracked_players) > 0:
+                p_crops = [sv.crop_image(frame, xyxy) for xyxy in tracked_players.xyxy]
+                p_pil = [sv.cv2_to_pillow(c) for c in p_crops]
+                p_embeddings = self.engine.get_embeddings(p_pil)
+
+                final_team_ids = []
+                for i, tid in enumerate(tracked_players.tracker_id):
+                    team_id = self.classifier.get_consensus_team(tid, p_embeddings[i])
+                    final_team_ids.append(team_id)
+
+                tracked_players.class_id = np.array(final_team_ids)
+
+            # 2. Goalkeepers
+            if len(tracked_gks) > 0 and len(tracked_players) > 0:
+                tracked_gks.class_id = self.classifier.resolve_goalkeepers_team_id(
+                    tracked_players, tracked_gks
+                )
+
+            # 3. Referees (Shift ID 3 -> 2)
+            if len(tracked_refs) > 0:
+                tracked_refs.class_id -= 1
+
+            # --- F. DATA STORAGE ---
+            tracking_results[frame_idx] = {"players": {}, "ball": None}
+            data_targets = sv.Detections.merge([tracked_players, tracked_gks])
+
+            if H is not None:
+                if len(data_targets) > 0:
+                    feet_coords = data_targets.get_anchors_coordinates(
+                        sv.Position.BOTTOM_CENTER
+                    )
+                    transformed_feet = self.mapper.transform(feet_coords, H)
+
+                    for i, tid in enumerate(data_targets.tracker_id):
+                        px, py = transformed_feet[i]
+                        tracking_results[frame_idx]["players"][tid] = (
+                            max(0.0, min(1.0, px)),
+                            max(0.0, min(1.0, py)),
+                        )
+
+                if len(ball_detections) > 0:
+                    ball_coords = ball_detections.get_anchors_coordinates(
+                        sv.Position.CENTER
+                    )
+                    transformed_ball = self.mapper.transform([ball_coords[0]], H)
+                    bx, by = transformed_ball[0]
+                    tracking_results[frame_idx]["ball"] = (
+                        max(0.0, min(1.0, bx)),
+                        max(0.0, min(1.0, by)),
+                    )
+
+            # --- G. DRAW & WRITE VIDEO ---
+            all_tracked = sv.Detections.merge(
+                [tracked_players, tracked_gks, tracked_refs]
+            )
+            annotated_frame = self.engine.draw_annotations(
+                frame, all_tracked, ball_detections
+            )
+            out.write(annotated_frame)
+
+        # 4. Cleanup
+        out.release()
+        cap.release()
+        print(f"WORKER: Video saved to {output_video_path}")
+
+        # Save CSVs
+        final_assignments = self.classifier.get_final_assignments()
+        csv_path = output_video_path.replace(".mp4", ".csv")
+        DataExporter.save_csvs(
+            tracking_results, final_assignments, frame_idx, fps, csv_path
+        )

wunderscout-0.1.2/src/wunderscout/exporters.py

@@ -0,0 +1,43 @@
+import csv
+from pathlib import Path
+
+
+class DataExporter:
+    @staticmethod
+    def save_csvs(tracking_data, team_assignments, total_frames, fps, output_path):
+        """
+        tracking_data: {frame_idx: {"ball": (x,y), "players": {id: (x,y)}}}
+        team_assignments: {tracker_id: team_id}
+        """
+        path_obj = Path(output_path)
+        path_obj.parent.mkdir(parents=True, exist_ok=True)
+        base_name = str(path_obj.with_suffix(""))
+        home_ids = [tid for tid, team in team_assignments.items() if team == 0]
+        away_ids = [tid for tid, team in team_assignments.items() if team == 1]
+
+        def write_file(filename, team_name, ids):
+            with open(filename, "w", newline="") as f:
+                writer = csv.writer(f)
+                writer.writerow(
+                    ["", "", ""] + [team_name for _ in ids for _ in (0, 1)] + ["", ""]
+                )
+                writer.writerow(
+                    ["", "", ""] + [str(pid) for pid in ids for _ in (0, 1)] + ["", ""]
+                )
+                writer.writerow(
+                    ["Period", "Frame", "Time [s]"]
+                    + [f"Player{pid}_{axis}" for pid in ids for axis in ("X", "Y")]
+                    + ["Ball_X", "Ball_Y"]
+                )
+
+                for f_idx in range(total_frames):
+                    data = tracking_data.get(f_idx, {"ball": None, "players": {}})
+                    row = [1, f_idx, f"{f_idx / fps:.2f}"]
+                    for tid in ids:
+                        coords = data["players"].get(tid, ("NaN", "NaN"))
+                        row.extend(coords)
+                    row.extend(data["ball"] if data["ball"] else ("NaN", "NaN"))
+                    writer.writerow(row)
+
+        write_file(f"{base_name}_Home.csv", "Home", sorted(home_ids))
+        write_file(f"{base_name}_Away.csv", "Away", sorted(away_ids))

wunderscout-0.1.2/src/wunderscout/geometry.py

@@ -0,0 +1,74 @@
+import cv2
+import numpy as np
+
+PITCH_CONFIG = {
+    # --- LEFT GOAL LINE ---
+    0: (0.000, 0.000),  # Top-Left Corner
+    1: (0.000, 0.204),  # Top Edge of Penalty Box
+    2: (0.000, 0.365),  # Top Edge of Goal Area
+    3: (0.000, 0.635),  # Bottom Edge of Goal Area
+    4: (0.000, 0.796),  # Bottom Edge of Penalty Box
+    5: (0.000, 1.000),  # Bottom-Left Corner
+    # --- LEFT PENALTY AREA ---
+    6: (0.052, 0.365),
+    7: (0.052, 0.635),
+    8: (0.105, 0.500),  # Penalty Spot (Left)
+    9: (0.157, 0.204),
+    10: (0.157, 0.392),
+    11: (0.157, 0.608),
+    12: (0.157, 0.796),
+    # --- MIDFIELD ---
+    13: (0.413, 0.500),
+    14: (0.500, 0.000),
+    15: (0.500, 0.365),
+    16: (0.500, 0.635),
+    17: (0.500, 1.000),
+    18: (0.587, 0.500),
+    # --- RIGHT PENALTY AREA ---
+    19: (0.843, 0.204),
+    20: (0.843, 0.392),
+    21: (0.843, 0.608),
+    22: (0.843, 0.796),
+    23: (0.895, 0.500),  # Penalty Spot (Right)
+    24: (0.948, 0.365),
+    25: (0.948, 0.635),
+    # --- RIGHT GOAL LINE ---
+    26: (1.000, 0.000),
+    27: (1.000, 0.204),
+    28: (1.000, 0.365),
+    29: (1.000, 0.635),
+    30: (1.000, 0.796),
+    31: (1.000, 1.000),
+}
+
+
+class PitchMapper:
+    def __init__(self, pitch_config=PITCH_CONFIG):
+        self.pitch_config = pitch_config
+        self.last_h = None
+
+    def get_matrix(self, keypoints_xy, keypoints_conf):
+        src_points = []
+        dst_points = []
+
+        for i, (xy, conf) in enumerate(zip(keypoints_xy, keypoints_conf)):
+            if conf > 0.5 and i in self.pitch_config:
+                src_points.append(xy)
+                dst_points.append(self.pitch_config[i])
+
+        if len(src_points) >= 4:
+            H, _ = cv2.findHomography(
+                np.array(src_points), np.array(dst_points), cv2.RANSAC
+            )
+            self.last_h = H
+
+        return self.last_h
+
+    def transform(self, points, H=None):
+        target_h = H if H is not None else self.last_h
+        if target_h is None or len(points) == 0:
+            return []
+
+        points_reshaped = np.array(points).reshape(-1, 1, 2).astype(np.float32)
+        projected = cv2.perspectiveTransform(points_reshaped, target_h)
+        return projected.reshape(-1, 2)

wunderscout-0.1.2/src/wunderscout/heatmap.py

@@ -0,0 +1,115 @@
+import pandas as pd
+import matplotlib.pyplot as plt
+import numpy as np
+import seaborn as sns
+import json
+from scipy.stats import gaussian_kde
+
+# === Load the raw tracking data CSV ===
+# NOTE: "header=2" → skip the first two rows (team/labels) and use row 3 as header
+df = pd.read_csv(
+    "./data/Sample_Game_1_RawTrackingData_Away_Team.csv",
+    header=2,
+)
+
+# === Clean column names so each player has _X and _Y ===
+cleaned_colums = []
+colnames = df.columns.tolist()
+i = 0
+while i < len(colnames):
+    col = colnames[i]
+    if col.startswith("Player") or col.startswith("Ball"):
+        cleaned_colums.append(f"{col}_X")
+        cleaned_colums.append(f"{col}_Y")
+        i += 2
+    else:
+        cleaned_colums.append(col)
+        i += 1
+df.columns = cleaned_colums
+
+print("Columns cleaned. First few rows:")
+print(df.head())
+
+# === Extract Player17 (drop NaN values where tracking failed) ===
+player17 = df[["Player17_X", "Player17_Y"]].dropna()
+x = player17["Player17_X"].to_numpy()
+y = player17["Player17_Y"].to_numpy()
+
+# === Detect scale (normalized [0,1] or real meters) ===
+if x.max() <= 1.5 and y.max() <= 1.5:
+    print("Scaling Player17 data from normalized [0,1] to meters...")
+    x = x * 105  # pitch length in meters
+    y = y * 68  # pitch width in meters
+else:
+    print("Data appears to already be in meters, leaving as is.")
+
+print("First 10 points:", list(zip(x[:10], y[:10])))
+
+# =============================================================================
+# 1. Scatter Plot (sanity check, raw positions)
+# =============================================================================
+fig, ax = plt.subplots(figsize=(10, 7))
+# Pitch outline
+ax.plot([0, 105, 105, 0, 0], [0, 0, 68, 68, 0], color="black")
+ax.plot([52.5, 52.5], [0, 68], color="black")  # halfway line
+# Player positions
+ax.scatter(x, y, s=1, alpha=0.3, color="blue")
+ax.set_xlim(0, 105)
+ax.set_ylim(0, 68)
+ax.set_title("Player17 Movement Scatter (raw positions)")
+plt.savefig("./heatmap/player17_scatter.png", dpi=150, bbox_inches="tight")
+
+# =============================================================================
+# 2. Histogram Heatmap (occupancy grid)
+# =============================================================================
+heatmap, xedges, yedges = np.histogram2d(x, y, bins=(50, 34), range=[[0, 105], [0, 68]])
+
+fig, ax = plt.subplots(figsize=(10, 7))
+extent = [xedges[0], xedges[-1], yedges[0], yedges[-1]]
+im = ax.imshow(
+    heatmap.T, origin="lower", extent=extent, cmap="Blues", alpha=0.7, aspect="auto"
+)
+ax.plot([0, 105, 105, 0, 0], [0, 0, 68, 68, 0], color="black")
+ax.plot([52.5, 52.5], [0, 68], color="black")
+fig.colorbar(im, ax=ax, label="Frames")
+ax.set_title("Player17 Heatmap (Histogram)")
+plt.savefig("./heatmap/player17_histogram.png", dpi=150, bbox_inches="tight")
+
+# === Export histogram data as JSON for three.js ===
+heatmap_data = {
+    "xedges": xedges.tolist(),
+    "yedges": yedges.tolist(),
+    "values": heatmap.T.tolist(),  # transpose so rows correspond to y-axis correctly
+}
+with open("./heatmap/player17_histogram.json", "w") as f:
+    json.dump(heatmap_data, f)
+
+# =============================================================================
+# 3. KDE Heatmap (smoothed density field)
+# =============================================================================
+values = np.vstack([x, y])
+kde = gaussian_kde(values)
+
+# Define mesh grid
+X, Y = np.meshgrid(np.linspace(0, 105, 100), np.linspace(0, 68, 68))
+Z = kde(np.vstack([X.ravel(), Y.ravel()])).reshape(X.shape)
+
+fig, ax = plt.subplots(figsize=(10, 7))
+sns.kdeplot(x=x, y=y, fill=True, cmap="Blues", alpha=0.7, thresh=0.05, levels=50, ax=ax)
+ax.plot([0, 105, 105, 0, 0], [0, 0, 68, 68, 0], color="black")
+ax.plot([52.5, 52.5], [0, 68], color="black")
+ax.set_xlim(0, 105)
+ax.set_ylim(0, 68)
+ax.set_title("Player17 Heatmap (KDE Smoothed)")
+plt.savefig("./heatmap/player17_kde.png", dpi=150, bbox_inches="tight")
+
+# === Export KDE density field for three.js ===
+kde_data = {
+    "x": X[0].tolist(),  # x grid coordinates
+    "y": Y[:, 0].tolist(),  # y grid coordinates
+    "values": Z.tolist(),  # density values
+}
+with open("./heatmap/player17_kde.json", "w") as f:
+    json.dump(kde_data, f)
+
+print("Outputs saved: scatter, histogram PNG+JSON, KDE PNG+JSON for Player17")