Model Zoo and Documentation updates

README.md

@@ -78,6 +78,9 @@ Use it as the main entry point to find:
 - extracted features
 - pretrained models and checkpoints
 
+See the [Model Zoo](docs/model-zoo.md) for available pretrained models,
+reported scores, datasets, and loading snippets.
+
 --
 
 ## Quickstart
@@ -96,7 +99,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 my_model.train(
@@ -112,7 +115,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(
@@ -143,7 +146,7 @@ from opensportslib.apis import LocalizationModel
 
 my_model = LocalizationModel(
     config="/path/to/localization.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(

docs/model-zoo.md

@@ -0,0 +1,77 @@
+# Model Zoo
+
+This page lists the pretrained OpenSportsLib models published on Hugging Face.
+Use the model repository ID with `load_weights(...)` to load a checkpoint into an
+OpenSportsLib model.
+
+## Available Models
+
+| Model | Task | Dataset trained on | Backbone / architecture | Classes / label set | Scores | Hugging Face link | Load weights snippet |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `OSL-cls-action-mvitv2` | Action / Event Classification | SoccerNet - MVFouls classification subset | MViT v2 | Not reported on model card | Accuracy: 0.57<br>Balanced Accuracy: 0.40<br>Top-2: 0.78 | [OpenSportsLab/OSL-cls-action-mvitv2](https://huggingface.co/OpenSportsLab/OSL-cls-action-mvitv2) | `myModel.load_weights(weights="OpenSportsLab/OSL-cls-action-mvitv2")` |
+| `OSL-loc-snbas-2023-e2e` | Action Spotting / Localization | SoccerNet - Ball Action Spotting 2023 | E2E, DALI backend | PASS, DRIVE | tight mAP: 71.48<br>loose mAP: 85.62 | [OpenSportsLab/OSL-loc-snbas-2023-e2e](https://huggingface.co/OpenSportsLab/OSL-loc-snbas-2023-e2e) | `myModel.load_weights(weights="OpenSportsLab/OSL-loc-snbas-2023-e2e")` |
+| `OSL-loc-snbas-2025-e2e` | Action Spotting / Localization | SoccerNet - Ball Action Spotting 2025 | E2E, DALI backend | PASS, DRIVE, HEADER, HIGH PASS, OUT, CROSS, THROW IN, SHOT, BALL PLAYER BLOCK, PLAYER SUCCESSFUL TACKLE, FREE KICK, GOAL | tight mAP: 47.98<br>loose mAP: 58.35 | [OpenSportsLab/OSL-loc-snbas-2025-e2e](https://huggingface.co/OpenSportsLab/OSL-loc-snbas-2025-e2e) | `myModel.load_weights(weights="OpenSportsLab/OSL-loc-snbas-2025-e2e")` |
+
+## OSL-cls-action-mvitv2
+
+**Intended use:** video-based soccer action / event classification.
+
+**Dataset/training source:** SoccerNet - MVFouls classification subset, using
+video clips.
+
+**Reported metrics:**
+
+| Metric | Score |
+| --- | --- |
+| Accuracy | 0.57 |
+| Balanced Accuracy | 0.40 |
+| Top-2 | 0.78 |
+
+**Hugging Face:** [OpenSportsLab/OSL-cls-action-mvitv2](https://huggingface.co/OpenSportsLab/OSL-cls-action-mvitv2)
+
+```python
+myModel.load_weights(weights="OpenSportsLab/OSL-cls-action-mvitv2")
+```
+
+## OSL-loc-snbas-2023-e2e
+
+**Intended use:** video-based soccer action spotting / localization.
+
+**Dataset/training source:** SoccerNet - Ball Action Spotting 2023, using video
+clips at 224p resolution. The model card reports two classes: `PASS` and
+`DRIVE`.
+
+**Reported metrics:**
+
+| Metric | Score |
+| --- | --- |
+| tight mAP | 71.48 |
+| loose mAP | 85.62 |
+
+**Hugging Face:** [OpenSportsLab/OSL-loc-snbas-2023-e2e](https://huggingface.co/OpenSportsLab/OSL-loc-snbas-2023-e2e)
+
+```python
+myModel.load_weights(weights="OpenSportsLab/OSL-loc-snbas-2023-e2e")
+```
+
+## OSL-loc-snbas-2025-e2e
+
+**Intended use:** video-based soccer action spotting / localization.
+
+**Dataset/training source:** SoccerNet - Ball Action Spotting 2025, using video
+clips at 224p resolution. The model card reports twelve classes: `PASS`,
+`DRIVE`, `HEADER`, `HIGH PASS`, `OUT`, `CROSS`, `THROW IN`, `SHOT`,
+`BALL PLAYER BLOCK`, `PLAYER SUCCESSFUL TACKLE`, `FREE KICK`, and `GOAL`.
+
+**Reported metrics:**
+
+| Metric | Score |
+| --- | --- |
+| tight mAP | 47.98 |
+| loose mAP | 58.35 |
+
+**Hugging Face:** [OpenSportsLab/OSL-loc-snbas-2025-e2e](https://huggingface.co/OpenSportsLab/OSL-loc-snbas-2025-e2e)
+
+```python
+myModel.load_weights(weights="OpenSportsLab/OSL-loc-snbas-2025-e2e")
+```

docs/tni/config-guide.md

@@ -8,6 +8,7 @@ Main config files in the repo:
 
 - `opensportslib/config/classification.yaml`
 - `opensportslib/config/localization.yaml`
+- `opensportslib/config/localization-e2e-ocv.yaml`
 - `opensportslib/config/localization-json_netvlad++_resnetpca512.yaml`
 - `opensportslib/config/localization-json_calf_resnetpca512.yaml`
 - `opensportslib/config/sngar-tracking.yaml`
@@ -40,7 +41,7 @@ Defines which task pipeline is used.
 - `classification`: clip-level classification pipeline.
 - `localization`: spotting/localization pipeline.
 
-If `TASK` does not match the selected API (`model.classification` / `model.localization`), behavior can be incorrect or fail.
+If `TASK` does not match the selected API (`ClassificationModel` / `LocalizationModel`), behavior can be incorrect or fail.
 
 ### `DATA`
 
@@ -121,7 +122,7 @@ This avoids duplication and keeps paths consistent.
 | Key | Type | Example | Meaning |
 |---|---|---|---|
 | `DATA.dataset_name` | string | `mvfouls` | Dataset identifier |
-| `DATA.data_dir` | path | `/.../SoccerNet/mvfouls` | Dataset root directory |
+| `DATA.data_dir` | path | `/.../OSL-XFoul/224p` | Dataset root directory |
 | `DATA.data_modality` | string | `video` | Input modality for loader |
 | `DATA.view_type` | string | `multi` | Single-view or multi-view processing |
 | `DATA.num_classes` | int | `8` | Number of target classes |
@@ -139,7 +140,7 @@ Each split (`train`, `valid`, `test`) has:
 | Key | Type | Example | Meaning |
 |---|---|---|---|
 | `DATA.<split>.video_path` | path | `${DATA.data_dir}/train` | Video root for split; relative media paths in annotations are resolved from here |
-| `DATA.<split>.path` | path | `.../annotations-train.json` | Annotation file |
+| `DATA.<split>.path` | path | `${DATA.train.video_path}/train.json` | Annotation file |
 | `DATA.<split>.dataloader.batch_size` | int | `8` | Batch size |
 | `DATA.<split>.dataloader.shuffle` | bool | `true` | Shuffle data each epoch |
 | `DATA.<split>.dataloader.num_workers` | int | `4` | Data loading worker count |
@@ -214,7 +215,7 @@ Each split (`train`, `valid`, `test`) has:
 | Key | Type | Example | Meaning |
 |---|---|---|---|
 | `DATA.dataset_name` | string | `SoccerNet` | Dataset identity |
-| `DATA.data_dir` | path | `/.../annotations` | Data root |
+| `DATA.data_dir` | path | `/.../OSL-SNBAS/224p-2024` | Data root |
 | `DATA.classes` | list[string] | `PASS, DRIVE, ...` | Event class set |
 | `DATA.epoch_num_frames` | int | `500000` | Frames sampled per epoch |
 | `DATA.mixup` | bool | `true` | Mixup augmentation |