# 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
git clone git@bitbucket.org:soccerwatch/swdl.git
cd swdl
sudo python setup.py install
```

# 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, to_md5
ds = DataService(username="MyUser",password_hashed=to_md5("mySuperSecretPW"))
match_list = ds.get_matches()
print(len(match_list))
```

## Download Single Match Info
You can get a specific #Match by passing the match id
```python
match = ds.get_matche(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 update 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.update_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 = label_data["events"][:]
labels = label_data["labels"][:]
status = label_data["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)
events[:, 2]        | which team caused the event (0 - home team; 1 - away team)


labels[n_labels, 7] | 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


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


