swdl 1.11.10
Soccerwatch Data Library
Requires Python: >=3.8

# Soccerwatch Data Library

This is a small tool to access socccerwatch data with a simple python interface

# Requirements

Additional to a python installation you will need ffmpeg to download videos

# Installation

```bash
sudo pip install swdl
```

# Using the Library

For now the Documentation is quite sparse but here is a short overview about the given Functions

## Access Data Service

The DataService is a class that provide access to all of the data

```python
from swdl.swrest import DataService
ds = DataService(username="MyUser",password="mySuperSecretPW")
match_list = ds.get_matches()
# This take a lot of time
for m in match_list:
    print(m)
```

## Save credentials

To store your credentials we provide a helper script which stores username and password in plain text under ~/.swdlrc.
After login you do not need to pass any credentials into the DataService constructor

```bash
swdl-login
```

## Download Single Match Info

You can get a specific #Match by passing the match id

```python
match = ds.get_match(1300)
print match
-------------------OUTPUT
Match[	id:		1300,
	camera:		51,
	name:		FC Borussia Droeschede-DJK VfL Billerbeck,
	location:	Kunstrasenplatz, ESO-Stadion Auf der Emst, Am Suedenberg 36a, 58644 Iserlohn
	state:		done
	video:		https://xfiles100.blob.core.windows.net/1300/720p/1300.m3u8
	grid:		https://xfiles100.blob.core.windows.net/1300/Grid/1300.m3u8]
```

## Update Match Information

To sync the match information with the server you can use the two pull methods. One is for updating the match information and one is for updating the labels.
NOTE: The labels will only be downloaded by pull_labels request:

```python
match.pull_info()
match.pull_labels()
```

## Download Video

There are functions to download the videos of the match. User stream refers to the video after processed by the AI. Grid is a 3x2 Grid video of all 6 cameras.
This functions requieres ffmpeg to be installed on your system

```python
match.download_user_stream()
match.download_grid_stream()
```

## Save Labels

To save labels to disc you will need to get an match, update the labels and call the save function

```python
match = ds.get_match(1300)
match.pull_labels()
match.labels.save("labels.h5")
```

## Load Labels

To load the labels you can call the read function

```python
match = ds.get_match(1300)
label_data = match.labels.from_file()
```

# Data Explaination

The data contains on the one side the video material in form of grid or user stream and on the other side of a labels dataset which is includes information obout camera positions and special events.

## Grid Stream Video

The Grid stream is a 2x3 grid video showing all 6 cameras of the Soccerwatch camerasystems. In the table below you can find the positioning for each camera:

| left-column  | right-column  |
| ------------ | ------------- |
| top-left     | top-mid-right |
| top-mid-left | top-right     |
| top-mid      | bottom-fishey |

The Grid Stream has a resolution of 3296x3712, ~25 FPS and is H.265 coded.

## User Stream Video

The user stream video is generated by stiching the 6 cameras from the Grid Stream to a panorama and applying the AI to select the scene-of-interest. Typically the User Stream is saved in 720p format (1280x720, ~ 25 FPS, H.264 coded).

## Labels

The label dictionary containes three entries "events", "labels" and "status", which you can access using

```python
events = match.labels.events
labels = match.labels.postions
status = match.labels.status
```

The resulting arries contain following information:

| events[n_events, 3] | description                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| events[:, 0]        | position of the event (in seconds)                                                                                      |
| events[:, 1]        | event type (0 - goal; 1 - kickoff; 2 - corner; 3 - throw in; 4 - penalty; 5 - foul; 6 - score opportunity; 8 - whistle) |
| events[:, 2]        | which team caused the event (0 - home team; 1 - away team)                                                              |

| labels[n_labels, 8] | description               |
| ------------------- | ------------------------- |
| labels[:, 0]        | timepoint in milliseconds |
| labels[:, 1]        | target x position         |
| labels[:, 2]        | target y position         |
| labels[:, 3]        | target zoom               |
| labels[:, 4]        | actual x position         |
| labels[:, 5]        | actual y position         |
| labels[:, 6]        | actual zoom               |
| labels[:, 7]        | automatically created     |

| status[11,] | timepoint (in milliseconds) where...           |
| ----------- | ---------------------------------------------- |
| status[0]   | game status changed to before game             |
| status[1]   | game status changed to first half              |
| status[2]   | game status changed to half time               |
| status[3]   | game status changed to second half             |
| status[4]   | game status changed to after regular game      |
| status[5]   | game status changed to first half overtime     |
| status[6]   | game status changed to half time overtime      |
| status[7]   | game status changed to second half overtime    |
| status[8]   | game status changed to after overtime          |
| status[9]   | game status changed to penalty shoot-out       |
| status[10]  | game status changed to after penalty shoot-out |