feat: publish Whistle project and poster

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+media/whistle-poster.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+
+__pycache__/
+*.py[cod]
+

README.md

@@ -0,0 +1,36 @@
+# Whistle
+
+![Whistle official poster](media/whistle-poster.png)
+
+**Whistle** is developed and owned by [Assem Sabry](https://assem.one/).
+
+Whistle يحوّل فيديو مباراة كرة القدم إلى بيانات زمنية قابلة للفحص: detections وtracks وملفات JSON/CSV وفيديو مرئي. لا يحدد أسماء اللاعبين أو مراكزهم أو أرقام قمصانهم، ولا يحتوي على مهمة تقييم للاعبين.
+
+## الحالة الحالية
+
+الإصدار `0.0.1` يوفّر:
+
+- قراءة manifest للفيديو والتحقق من الملف.
+- schema ثابت للـ frames وdetections وtracks.
+- CLI يستقبل MP4 ويكتب manifest ونتيجة JSON أولية قابلة لإعادة التشغيل.
+- طبقة detector/tracker قابلة للاستبدال دون ربطها بمكتبة بعينها.
+
+لا توجد أوزان أو بيانات فيديو موزعة مع المستودع. يجب تسجيل provenance والترخيص قبل إضافة أي dataset أو checkpoint.
+
+## التشغيل
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+whistle inspect path\to\match.mp4 --output outputs\match
+pytest
+```
+
+## مراحل المنتج
+
+Core ثم Pitch ثم Ball ثم Events الأساسية ثم Analytics. لن تظهر السرعة أو المسافة عند فشل معايرة الكاميرا أو انخفاض الثقة.
+
+## الترخيص
+
+الكود الأصلي Apache-2.0. رخصة الأوزان والبيانات منفصلة وتُراجع قبل النشر؛ لا تُضمّن فيديوهات المباريات أو مشتقاتها دون حق إعادة التوزيع.

configs/detector_yolo26x.yaml

@@ -0,0 +1,9 @@
+# Ultralytics dataset config. Replace paths only after licensing/provenance review.
+path: /mnt/opet-data/whistle/datasets/detection
+train: images/train
+val: images/val
+test: images/test
+names:
+  0: player
+  1: referee
+  2: football

docs/architecture.md

@@ -0,0 +1,56 @@
+# Whistle Architecture
+
+Whistle is a modular post-match football video analysis system owned and developed by Assem Sabry. It does not identify player names, positions, or jersey numbers, and it has no player-rating task.
+
+```text
+MP4
+ |
+ v
+Video Ingest + Shot Segmentation
+ | frames, timestamps, shot_id
+ v
+Whistle Detector (YOLO26x pretrained -> football fine-tune)
+| player / referee / football boxes + confidence
+ v
+Whistle Tracker (motion + appearance, ByteTrack adapter)
+ | stable track_id + trajectories
++-----------------------+
+ |
+ v
+Pitch Calibration
+(segmentation/keypoints + homography + gates)
+ | XY metres
+ v
+Ball State + Possession (football detector + motion filter + temporal probability)
+             |
+             v
+Events (rules first, temporal model second)
+             |
+             v
+Analytics (deterministic metrics + uncertainty propagation)
+             |
+             v
+MP4 overlay + JSON + CSV + Parquet + 2D pitch map + report
+```
+
+## Model contracts
+
+| Module | Input | Output | First training target |
+| --- | --- | --- | --- |
+| Detector | RGB frames/crops | boxes, class, confidence | player, referee, football |
+| Tracker | detections + frame timestamps | track IDs and trajectories | HOTA/IDF1 stability |
+| Pitch | frames + pitch landmarks | camera state, homography, XY metres | JaC@5 and reprojection error |
+| Ball/Possession | football detections + tracks | ball state, owner probability | ball recall and possession F1 |
+| Events | tracks, ball state, temporal windows | event type, actors, time, confidence | event mAP/F1 |
+| Analytics | trusted state/events | distance, speed, KPIs | deterministic regression tests |
+| Quality gates | calibration + track coverage | valid/invalid metric flags | false-metric rate |
+
+## 48-hour execution target
+
+The 48-hour target is a reproducible baseline: environment, data schemas, YOLO26 detector fine-tuning on an available licensed/public sample, tracker integration, visualizer, metrics, and one end-to-end MP4 run. A production-quality Whistle still depends on licensed match data, annotation volume, and validation that cannot honestly be guaranteed before those inputs exist.
+
+## Ownership
+
+Project name: **Whistle**  
+Developer and owner: **Assem Sabry**  
+Website: https://assem.one/

pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "whistle"
+version = "0.0.1"
+description = "Open-source football video analysis pipeline"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "Apache-2.0"}
+authors = [{name = "Whistle contributors"}]
+dependencies = []
+
+[project.optional-dependencies]
+video = ["opencv-python>=4.8", "numpy>=1.24"]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+whistle = "whistle.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["whistle*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tests/test_schemas.py

@@ -0,0 +1,16 @@
+from whistle.core.schemas import Detection, Track
+
+
+def test_detection_serializes_bbox_as_json_array():
+    item = Detection(3, "player", (1.0, 2.0, 10.0, 20.0), 0.9)
+    assert item.to_dict() == {
+        "frame_id": 3,
+        "class_name": "player",
+        "bbox_xyxy": [1.0, 2.0, 10.0, 20.0],
+        "confidence": 0.9,
+    }
+
+
+def test_track_serializes_stable_fields():
+    item = Track(7, 3, "referee", (0.0, 1.0, 2.0, 3.0), 0.8)
+    assert item.to_dict()["track_id"] == 7

tests/test_video_inspect.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+import pytest
+
+from whistle.video.inspect import inspect_video
+
+
+def test_missing_video_is_explicit(tmp_path: Path):
+    with pytest.raises(FileNotFoundError, match="Video not found"):
+        inspect_video(tmp_path / "missing.mp4")

whistle/__init__.py

@@ -0,0 +1,3 @@
+"""Whistle football video analysis."""
+
+__version__ = "0.0.1"

whistle/cli.py

@@ -0,0 +1,26 @@
+"""Command line entry point for the first Whistle pipeline."""
+
+import argparse
+import json
+from pathlib import Path
+from typing import List, Optional
+
+from whistle.video.inspect import inspect_video
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="whistle")
+    commands = parser.add_subparsers(dest="command", required=True)
+    inspect = commands.add_parser("inspect", help="inspect a video and write a manifest")
+    inspect.add_argument("path", type=Path)
+    inspect.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args(argv)
+
+    if args.command == "inspect":
+        manifest = inspect_video(args.path)
+        args.output.mkdir(parents=True, exist_ok=True)
+        destination = args.output / "video_manifest.json"
+        destination.write_text(json.dumps(manifest.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        print(destination)
+        return 0
+    return 2

whistle/core/__init__.py

@@ -0,0 +1 @@
+"""Stable data contracts and shared utilities."""

whistle/core/schemas.py

@@ -0,0 +1,44 @@
+"""Small, dependency-free schemas for pipeline interchange."""
+
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class VideoManifest:
+    path: str
+    width: Optional[int]
+    height: Optional[int]
+    fps: Optional[float]
+    frame_count: Optional[int]
+    duration_ms: Optional[int]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class Detection:
+    frame_id: int
+    class_name: str
+    bbox_xyxy: Tuple[float, float, float, float]
+    confidence: float
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = asdict(self)
+        result["bbox_xyxy"] = list(self.bbox_xyxy)
+        return result
+
+
+@dataclass(frozen=True)
+class Track:
+    track_id: int
+    frame_id: int
+    role: str
+    bbox_xyxy: Tuple[float, float, float, float]
+    confidence: float
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = asdict(self)
+        result["bbox_xyxy"] = list(self.bbox_xyxy)
+        return result

whistle/training/__init__.py

@@ -0,0 +1 @@
+"""Training entry points."""

whistle/training/train_detector.py

@@ -0,0 +1,40 @@
+"""Train the Whistle detector from an Ultralytics YOLO dataset YAML."""
+
+import argparse
+from pathlib import Path
+
+
+def train(data: str, epochs: int, imgsz: int, batch: int, device: str, project: str):
+    from ultralytics import YOLO
+
+    model = YOLO("yolo26x.pt")
+    return model.train(
+        data=data,
+        epochs=epochs,
+        imgsz=imgsz,
+        batch=batch,
+        device=device,
+        project=project,
+        name="whistle-detector-yolo26x",
+        pretrained=True,
+        amp=True,
+        exist_ok=True,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data", default="configs/detector_yolo26x.yaml")
+    parser.add_argument("--epochs", type=int, default=80)
+    parser.add_argument("--imgsz", type=int, default=1280)
+    parser.add_argument("--batch", type=int, default=-1)
+    parser.add_argument("--device", default="0")
+    parser.add_argument("--project", default="/mnt/opet-data/whistle/outputs/training")
+    args = parser.parse_args()
+    Path(args.project).mkdir(parents=True, exist_ok=True)
+    train(args.data, args.epochs, args.imgsz, args.batch, args.device, args.project)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

whistle/video/__init__.py

@@ -0,0 +1 @@
+"""Video input and metadata helpers."""

whistle/video/inspect.py

@@ -0,0 +1,35 @@
+"""Video inspection with an optional OpenCV dependency."""
+
+from pathlib import Path
+from typing import Union
+
+from whistle.core.schemas import VideoManifest
+
+
+def inspect_video(path: Union[str, Path]) -> VideoManifest:
+    video_path = Path(path).expanduser().resolve()
+    if not video_path.is_file():
+        raise FileNotFoundError(f"Video not found: {video_path}")
+
+    try:
+        import cv2
+    except ImportError:
+        return VideoManifest(str(video_path), None, None, None, None, None)
+
+    capture = cv2.VideoCapture(str(video_path))
+    try:
+        if not capture.isOpened():
+            raise ValueError(f"Could not open video: {video_path}")
+        fps = float(capture.get(cv2.CAP_PROP_FPS)) or None
+        frames = int(capture.get(cv2.CAP_PROP_FRAME_COUNT)) or None
+        duration_ms = int(frames * 1000 / fps) if fps and frames else None
+        return VideoManifest(
+            str(video_path),
+            int(capture.get(cv2.CAP_PROP_FRAME_WIDTH)) or None,
+            int(capture.get(cv2.CAP_PROP_FRAME_HEIGHT)) or None,
+            fps,
+            frames,
+            duration_ms,
+        )
+    finally:
+        capture.release()