### Install Dependencies using Conda

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Installs project dependencies using Conda, creating a dedicated environment. Sets up PyTorch with CUDA support and installs mmcv.

```bash
conda create -n tracklab pip python=3.9 pytorch==1.13.1 torchvision==0.14.1 pytorch-cuda=11.7 -c pytorch -c nvidia -y
conda activate tracklab
cd sn-gamestate
pip install -e .
mim install mmcv==2.0.1
```

--------------------------------

### Install Dependencies using UV

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Installs the project dependencies and mmcv using the UV package manager. Requires Python 3.9.

```bash
cd sn-gamestate
uv venv --python 3.9
uv pip install -e .
uv run mim install mmcv==2.0.1
```

--------------------------------

### Get Help for Tracklab (Bash)

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Displays all available configuration groups for the Tracklab command-line interface. This is useful for understanding the different parameters and options that can be used to customize the execution.

```bash
uv run tracklab --help
```

--------------------------------

### Update Repositories and Rerun Installation

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Updates both the sn-gamestate and tracklab repositories and then reinstalls dependencies. This ensures the project is up-to-date.

```bash
git pull
git -C ../tracklab pull
# Rerun installation based on your environment manager (uv or pip)
```

--------------------------------

### Download SoccerNet-gamestate Dataset

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Downloads the SoccerNet-gamestate dataset for training, validation, testing, and challenge splits using the SoccerNetDownloader. Assumes the SoccerNet package is installed.

```python
from SoccerNet.Downloader import SoccerNetDownloader
mySoccerNetDownloader = SoccerNetDownloader(LocalDirectory="data/SoccerNetGS")
mySoccerNetDownloader.downloadDataTask(task="gamestate-2024",
                                       split=["train", "valid", "test", "challenge"])
```

--------------------------------

### Add Local Tracklab to sn-gamestate

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Adds a local installation of the Tracklab library to the sn-gamestate project's environment. This allows sn-gamestate to use the local version of Tracklab for development.

```bash
cd sn-gamestate
uv add ../tracklab
```

--------------------------------

### Manipulate Python sys.path for Tracklab

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Provides an alternative method to integrate Tracklab by manipulating the Python `sys.path` via a `.pth` file. This is useful when working on slow drives or for specific environment setups.

```bash
echo "/absolute/path/to/tracklab" > .venv/lib/python3.9/site-packages/tracklab_dev.pth
```

--------------------------------

### Run TVCalib Optimization

Source: https://github.com/soccernet/sn-gamestate/blob/main/plugins/calibration/tvcalib/README.md

Executes the iterative optimization process for camera parameter estimation using TVCalib. Requires a configuration file for hyperparameters and specifies an output directory for results. Supports device selection (CPU/GPU).

```bash
python -m tvcalib.optimize --hparams configs/val_main_center_gt.json --output_dir ./experiments --device cuda
```

--------------------------------

### Clone sn-gamestate Repository

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Clones the SoccerNet game state repository to the local machine. This is the first step in setting up the project.

```bash
git clone https://github.com/SoccerNet/sn-gamestate.git
```

--------------------------------

### Configure Tracklab Reinstallation in pyproject.toml

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Configures the `pyproject.toml` file for sn-gamestate to ensure that Tracklab is reinstalled when changes are made. This is useful for watching live changes during development.

```toml
[tool.uv]
reinstall-package = ["tracklab"]
```

--------------------------------

### Clone Tracklab Repository

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Clones the Tracklab repository from GitHub to set up a local version for development or adaptation. This is a prerequisite for contributing to or modifying Tracklab's behavior.

```bash
git clone https://github.com/TrackingLaboratory/tracklab.git
```

--------------------------------

### Load and Prepare SoccerNet Game State Data (Python)

Source: https://github.com/soccernet/sn-gamestate/blob/main/plugins/calibration/tvcalib/visualize_per_sample_output.ipynb

Loads hyperparameters and per-sample output from JSON files using pandas. It initializes a 3D object representation of a soccer pitch and reads camera calibration data. Handles lens distortion based on hyperparameters.

```python
import json
from argparse import Namespace
from pathlib import Path
import pandas as pd
import matplotlib.pyplot as plt
from PIL import Image
import torchvision.transforms as T


from tvcalib.cam_modules import SNProjectiveCamera
from tvcalib.utils.objects_3d import SoccerPitchSNCircleCentralSplit, SoccerPitchLineCircleSegments
from tvcalib.inference import get_camera_from_per_sample_output, load_annotated_points
from tvcalib.utils import visualization_mpl_min as viz

args = Namespace(
    file_hparams=Path("configs/wc14-test/extrem-pred.json"),
    per_sample_output=Path("experiments/wc14-test/extrem-pred/per_sample_output.json"),
    dir_images=Path("data/datasets/wc14-test"),
    output_dir=Path("tmp"),
)


object3d = SoccerPitchLineCircleSegments(device="cpu", base_field=SoccerPitchSNCircleCentralSplit())

with open(args.file_hparams) as fr:
    hparams = json.load(fr)
    lens_dist = False
    if hparams["lens_distortion"] == True:
        lens_dist = True

df_cam = pd.read_json(args.per_sample_output, orient="records", lines=True).set_index(
    "image_ids", drop=False
)
df_cam.head(5)
```

--------------------------------

### Update Environment with uv run

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Updates the project environment by running `uv` commands to ensure Tracklab and the current project are up to date. This is a common troubleshooting step after version upgrades.

```bash
uv run -U tracklab -cn soccernet
uv pip install -e .
```

--------------------------------

### TVCalib Configuration File Structure

Source: https://github.com/soccernet/sn-gamestate/blob/main/plugins/calibration/tvcalib/README.md

Defines the configuration for the TVCalib optimization process. Includes parameters for temporal and batch dimensions, dataset paths, object properties, lens distortion models, image dimensions, and optimization steps.

```json
{
    "temporal_dim": 1,
    "batch_dim": 256,
    "sigma_scale": 1.96,
    "object3d": "SoccerPitchLineCircleSegments",
    "dataset": {
        "file_match_info": "data/datasets/sncalib-test/match_info.json",
        "extremities_annotations": "data/segment_localization/np4_r4_md30/test",
        "extremities_prefix": "extremities_",
        "num_points_on_line_segments": 4,
        "num_points_on_circle_segments": 8,
        "filter_cam_type": null,
        "remove_invalid": true
    },
    "lens_distortion": false,
    "image_width": 960,
    "image_height": 540,
    "optim_steps": 1000
}
```

--------------------------------

### Run SoccerNet Game State Baseline (Bash)

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Executes the SoccerNet Game State Reconstruction baseline. This command automatically downloads the dataset and model weights on the first run. It processes a validation sequence, saves results to a video file, and prints performance metrics.

```bash
uv run tracklab -cn soccernet
```

--------------------------------

### TVCalib Optimization Output Structure

Source: https://github.com/soccernet/sn-gamestate/blob/main/plugins/calibration/tvcalib/README.md

Represents the output structure for a single sample after TVCalib optimization. Includes batch information, image IDs, time, masking of lines and circles, various loss metrics, and estimated camera intrinsic and extrinsic parameters.

```json
{
    "batch_idx":"experiments\/wc14-test_full_gt\/batch_0.pt",
    "image_ids":"1.jpg",
    "time_s":1.8033202589,
    "mask_lines":[[[false,false,false],[true,true,false],[true,true,true],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[true,true,true],[false,false,false],[true,true,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false],[false,false,false]]],
    "mask_circles":[[[false,false,false,false,false,false,false,false],[true,true,true,true,true,true,true,true],[false,false,false,false,false,false,false,false]]],
    "loss_ndc_lines_distances_raw":[[[0.0,0.0,0.0],[0.010469364,0.0019166876,0.0],[0.0086851967,0.0050904173,0.0100935074],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0040892977,0.0009114548,0.0050593293],[0.0,0.0,0.0],[0.0000008759,0.0016332311,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0]]],
    "loss_ndc_lines":0.0047949357,
    "loss_ndc_circles_distances_raw":[[[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0],[0.0100957388,0.0031360432,0.0003662109,0.0027729045,0.004986987,0.0026938571,0.0051269531,0.002303218],[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]]],
    "loss_ndc_circles":0.0039352393,
    "loss_ndc_total":0.008730175,
    "loss_ndc_lines_distances_max":0.010469364,
    "loss_ndc_circles_distances_max":0.0100957388,
    "loss_ndc_total_max":0.010469364,
    "league":"Fifa WorldCup",
    "season":"2014",
    "match":"None",
    "date":"None",
    "pan_degrees":-17.578212738,
    "tilt_degrees":80.8040008545,
    "roll_degrees":-0.1310900003,
    "position_meters":[-7.7424321175,57.8480377197,-11.1651697159],
    "aov_radian":0.4283054769,
    "aov_degrees":24.540096283,
    "x_focal_length":2942.6950683594,
    "y_focal_length":2942.6950683594,
    "principal_point":[640.0,360.0],
    "radial_distortion":[0.0,0.0,0.0,0.0,0.0,0.0],
    "tangential_distortion":[0.0,0.0],
    "thin_prism_distortion":[0.0,0.0,0.0,0.0],
    "stadium":"None"
}
```

--------------------------------

### Extremities Annotation File Format

Source: https://github.com/soccernet/sn-gamestate/blob/main/plugins/calibration/tvcalib/README.md

Specifies the format for extremity annotations used in the TVCalib dataset. It's a JSON file where keys represent semantic class names, and values are lists of points (x, y coordinates) associated with those classes.

```json
{
     "semantic_class_name_1" : [{"x": x1,"y": y1}, {"x": x2,"y": y2}],
     "semantic_class_name_2": [{"x": x3,"y": y3}, {"x": x4,"y": y4}]
      ...
}
```

--------------------------------

### Unzip SoccerNet-gamestate Dataset

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Unzips the downloaded SoccerNet-gamestate dataset files. This command assumes you are in the data/SoccerNetGS directory.

```bash
cd data/SoccerNetGS
unzip gamestate-2024/train.zip -d train
unzip gamestate-2024/valid.zip -d valid
unzip gamestate-2024/test.zip -d test
unzip gamestate-2024/challenge.zip -d challenge
cd ../..
```

--------------------------------

### Visualize Undistorted Points and Camera Reprojection (Python)

Source: https://github.com/soccernet/sn-gamestate/blob/main/plugins/calibration/tvcalib/visualize_per_sample_output.ipynb

Processes a single game state sample, retrieves camera parameters, loads annotated points, and visualizes them. If lens distortion is enabled, it undistorts the image and points before drawing. The visualization includes image, camera reprojection, and annotated points, saving the output in PDF, SVG, and PNG formats.

```python
sample = df_cam.iloc[10]

image_id = Path(sample.image_ids).stem
print(f"{image_id=}")
image = Image.open(args.dir_images / sample.image_ids).convert("RGB")
image = T.functional.to_tensor(image)

cam = get_camera_from_per_sample_output(sample, lens_dist)
print(cam, cam.str_lens_distortion_coeff(b=0) if lens_dist else "")
points_line, points_circle = load_annotated_points(hparams, image_id, object3d)

if args.lens_dist:
    # we visualize annotated points and image after undistortion
    image = cam.undistort_images(image.unsqueeze(0).unsqueeze(0)).squeeze()
    # print(points_line.shape) # expected: (1, 1, 3, S, N)
    points_line = SNProjectiveCamera.static_undistort_points(points_line.unsqueeze(0).unsqueeze(0), cam).squeeze()
    points_circle = SNProjectiveCamera.static_undistort_points(points_circle.unsqueeze(0).unsqueeze(0), cam).squeeze()
else:
    psi = None


fig, ax = viz.init_figure(hparams["image_width"], hparams["image_height"])
ax = viz.draw_image(ax, image)
ax = viz.draw_reprojection(ax, object3d, cam)
ax = viz.draw_selected_points(
    ax,
    object3d,
    points_line,
    points_circle,
    kwargs_outer={
        "zorder": 1000,
        "rasterized": False,
        "s": 500,
        "alpha": 0.3,
        "facecolor": "none",
        "linewidths": 3,
    },
    kwargs_inner={
        "zorder": 1000,
        "rasterized": False,
        "s": 50,
        "marker": ".",
        "color": "k",
        "linewidths": 4.0,
    },
)
dpi = 50
plt.savefig(args.output_dir / f"{image_id}.pdf", dpi=dpi)
plt.savefig(args.output_dir / f"{image_id}.svg", dpi=dpi)
plt.savefig(args.output_dir / f"{image_id}.png", dpi=dpi)
```

--------------------------------

### TrackLab Citation

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

BibTeX entry for citing the TrackLab project. This provides academic reference for the TrackLab library.

```bibtex
@misc{Joos2024Tracklab,
	title = {{TrackLab}},
	author = {Joos, Victor and Somers, Vladimir and Standaert, Baptiste},
	journal = {GitHub repository},
	year = {2024},
	howpublished = {\url{https://github.com/TrackingLaboratory/tracklab}}
}
```

--------------------------------

### SoccerNet Game State Reconstruction Citation

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

BibTeX entry for citing the SoccerNet Game State Reconstruction paper. This provides academic reference for the project's contributions.

```bibtex
@inproceedings{Somers2024SoccerNetGameState,
        title = {{SoccerNet} Game State Reconstruction: End-to-End Athlete Tracking and Identification on a Minimap},
        author = {Somers, Vladimir and Joos, Victor and Giancola, Silvio and Cioppa, Anthony and Ghasemzadeh, Seyed Abolfazl and Magera, Floriane and Standaert, Baptiste and Mansourian, Amir Mohammad and Zhou, Xin and Kasaei, Shohreh and Ghanem, Bernard and Alahi, Alexandre and Van Droogenbroeck, Marc and De Vleeschouwer, Christophe},
        booktitle = cvsports,
	shortjournalproceedings = {2024 IEEE/CVF Conf. Comput. Vis. Pattern Recognit. Work. (CVPRW)},
        month = Jun,
        year = {2024},
        address = city-seattle,
}
```

--------------------------------

### PRTReid Citation

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

BibTeX entry for citing the PRTReid paper. This provides academic reference for the PRTReid contribution.

```bibtex
@inproceedings{Mansourian2023Multitask,
	title = {Multi-task Learning for Joint Re-identification, Team Affiliation, and Role Classification for Sports Visual Tracking},
	author = {Mansourian, Amir M. and Somers, Vladimir and De Vleeschouwer, Christophe and Kasaei, Shohreh},
	booktitle = mmsports,
	shortjournalproceedings = {Proc. 6th Int. Work. Multimedia Content Anal. Sports},
	pages = {103–112},
	month = Oct,
	day = {26},
	year = {2023},
	publisher = {ACM},
	address = city-ottawa,
	doi = {10.1145/3606038.3616172},
	url = {https://doi.org/10.1145/3606038.3616172}
}
```

--------------------------------

### GS-HOTA Similarity Formulation

Source: https://github.com/soccernet/sn-gamestate/blob/main/README.md

Defines the GS-HOTA similarity score, which combines localization and identification similarities. LocSim uses a Gaussian kernel with a tolerance parameter \(\\tau\), while IdSim checks for matching attributes (role, team, jersey number).

```latex
Sim_{\text{GS-HOTA}}(P, G) = \text{LocSim}(P, G) \times \text{IdSim}(P, G)
```

```latex
\text{with LocSim}(P, G) = e^{\ln(0.05)\frac{\|P - G\|_2^2}{\\tau^2}}
```

```latex
\text{and IdSim}(P, G) = 
\begin{cases} 
1 & \text{if all attributes match,} \\
0 & \text{otherwise.} 
\end{cases}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.