Installation

Programm starten

Mit Docker

Benötigte Software:

• Docker

Unter Windows muss ggf. noch ein Windows Subsystem for Linux installiert werden. Weitere Informationen hier.

Docker-Container starten:

Die Pfade hinter -v müssen durch Pfade zu den Dateien, welche in Konfiguration beschrieben werden

• bzw. durch den Pfad zum Output-Ordner - ersetzt werden.

Linux:

docker run -t \
  -v /home/user/out:/out \
  -v /home/user/config.json:/config.json \
  -p 8000:8000 \
  visuanalytics/visuanalytics

Windows:

docker run -t ^
  -v C:\Users\user\out:/out  ^
  -v C:\Users\user\config.json:/config.json ^
  -p 8000:8000 ^
  visuanalytics/visuanalytics

Falls man nur das Wordpress-Plugin verwenden will (siehe hier) kann man auch eine Docker-Container starten, der das Frontend nicht enthält. Hierfür muss man nur anstelle von
visuanalytics/visuanalytics
im obigen Befehl
visuanalytics/visuanalytics:latest-wordpress eingeben.

Der Server kann nun unter http://localhost:8000 erreicht werden.

Bemerkung

Wenn man die Option h264_nvenc (siehe config.json) verwenden will, kann man beim Starten noch die Option`–runtime=“nvidia“(oder–gpus all`) angeben. Dafür muss man vorher ein paar Konfigurationen und Installationen vornehmen. Eine Anleitung dafür finden Sie hier (Dies ist nicht die offizielle Dokumentation. Die Dokumentation von Docker zu dem Thema befindet sich hier).

Ohne Docker (Development)

Benötigte Software:

• python >=3.6

• pip

• FFmpeg

• npm

In den src-Ordner wechseln: cd src

Pakete installieren:

• pip install -r visuanalytics/requirements.txt

• Konfigurationsdateien anlegen bzw. anpassen (diese werden unter Konfiguration beschrieben):

  • Die Datei config.json muss sich im Ordner visuanalytics/instance befinden.

In den frontend-Ordner wechseln:

• cd ./frontend

Frontend Dependencies installieren:

• npm i

• npm install react-scripts@3.4.1 -g

Programm starten:

• Backend & Frontend starten: npm run start:all

• Nur Frontend starten: npm run start

• Nur Backend starten: npm run start:server

• Backend ohne npm starten: python -m visuanalytics (dafür muss man sich im src-Ordner befinden)

Bemerkung

Um die Option h264_nvenc (siehe config.json) zu verwenden, müssen diverse Einstellungen vorgenommen werden. Eine Anleitung finden Sie hier.

Wordpress-Plugin verwenden

Nicht nur der Backend-Server kann das Frontend ausliefern. Das Frontend kann auch als Wordpress-Plugin verwendet werden.

Um das Wordpress-Plugin zu erstellen, sind folgende Schritte nötig:

Benötigte Software:

• python >=3.6

• npm

In den frontend-Ordner wechseln:

• cd src/frontend

Frontend Dependencies installieren:

• npm i

• npm install react-scripts@3.4.1 -g

In den wordpress-Ordner wechseln:

• cd ../wordpress (wenn man im frontend-Ordner ist, ansonsten cd src/wordpress)

Wordpress-Plugin erstellen:

• python build.py

Im build-Ordner befindet sich eine .zip-Datei, die sich einfach über die Wordpress-Oberfläche installieren lässt.

Warnung

Damit das Plugin vollständig funktioniert, muss das Backend laufen (siehe hier oder hier). Um vom Plugin Requests an das Backend zu senden, muss ein Reverse Proxy eingerichtet werden. Dieser sollte dann alle Requests, die mit /visuanalytics anfangen an den Backend-Server weiterleiten.

Konfiguration

config.json

Die Konfigurationsdatei für das Programm hat folgendes Format:

{
  "api_keys": {
    "weatherbit": "APIKey"
  },
  "steps_base_config": {
    "testing": false,
    "h264_nvenc": false,
    "thumbnail": false
  },
  "testing": false,
  "audio": {}
}

api_keys:

Die API-Keys für die verwendeten APIs:

• weatherbit: API-Key für weatherbit.io

• twitter: API-Key für Twitter

steps_base_config(optional):

Die Konfiguration, die für jeden Job gelten soll. (Die Konfigurationen, die im Frontend angegeben werden, sind höherwertig.)

• testing(optional):

  Wenn testing aktiviert ist, werden keine API-Abfragen gemacht. Zur Generierung des Videos werden in dem Fall Beispieldaten verwendet. (Diese sind nur für die vordefinierten Themen vorhanden.)

• h264_nvenc(optional):

  Wenn h264_nvenc aktiviert ist, wird diese Option bei FFmpeg verwendet. Diese aktiviert die Hardware-Beschleunigung bei Nvidia-Grafikkarten. Damit dies funktioniert, müssen diverse Sachen beachtet werden (weitere Informationen unter Mit Docker sowie Ohne Docker).

• thumbnail(optional):

  Wenn thumbnail aktiviert ist, wird zu jedem Video ein Thumbnail generiert. Der Name des Thumbnails hat das Format: {video_name}_thumbnail.png (wobei {video_name} dem Namen des Videos entspricht).

• fix_names(optional):

  fix_names kann dazu verwendet werden, um den Output-Videos feste Namen zu geben. Hierzu kann man entweder names verwenden (hier gibt man dann einfach eine Liste mit Namen an)
  oder man verwendet count. Bei count werden die Videos durchnumeriert, d.h. das neueste Video bekommt _1. Sollte man z.B. count=3 wählen, so liegen im out-Ordner immer die 3 neuesten Videos. Das neueste Video hat den Bezeichner _1 und das älteste Video _3. Sobald ein neues Video generiert wird, wird das Video mit _3 gelöscht und das _2-Video in _3 umbenannt etc.
  Die einzige Ausnahme ist, wenn count = 1 gesetzt wurde. In diesem Fall wird kein _1 verwendet, sondern bei jeder neuen Videogenerierung heißt das Video gleich dem Jobnamen.

• keep_count(optional):

  keep_count gibt an wie viele Videos maximal im out-Ordner von einem Task vorhanden sein sollen. Sobald es zu viele gibt, wird das älteste Video gelöscht.

testing(optional):

Wenn testing aktiviert ist, wird die logging Ausgabe auf das „Info“-Level gesetzt, wodurch mehr Informationen in den Log eingetragen werden.

audio(optional):

Hier kann die Konfiguration für die Audiogenerierung angegeben werden. Eine Erklärung dafür befindet sich hier.

console_mode(optional):

Falls man das Programm ohne Frontend verwenden will, kann man diese Option auf true setzen. Dann kann man die zu erstellenden Jobs in der Datei jobs.json angeben (diese liegt ab unter src\visuanalytics\resources, eine Erklärung des Formats befindet sich hier). Diese Option funktioniert nur, wenn man das Programm ohne Docker ausführt.

jobs.json

Wenn man den console_mode (siehe hier) aktiviert hat, kann man die Jobs in der Datei jobs.json wie folgt definieren:

{
  "jobs": [
    {
      "name": "Wetter in Biebertal",
      "id": 0,
      "steps": "weather_single",
      "schedule": {
        "time": "12:00",
        "daily": true
      },
      "config": {
        "city_name": "Biebertal",
        "p_code": "35444"
      }
    }
  ]
}

name: Name des Jobs

id: ID des Jobs (sollte einzigartig sein)

steps: Thema, zu welchem ein Video generiert werden soll

Aktuelle Optionen:

• "weather_germany": Deutschlandweiter Wetterbericht

• "weather_single": Ortsbezogener Wetterbericht

• "football": Spieltag- und Tabellenbericht für die 1. und 2. Fußball-Bundesliga

• "twitter": Twitter-Wordcloud

schedule: Hier kann der Zeitplan für die Generierung der Videos festgelegt werden.

Hierzu gibt es vier mögliche Einträge:

• time:

  Uhrzeit der Ausführung. Die Uhrzeit muss im Format "%H:%M" angegeben werden.

  Beispiel: 10:00

Warnung

Die Uhrzeit muss immer angegeben werden.

• daily:

  Wenn dieser Wert true ist, wird der Job jeden Tag ausgeführt.

• date:

  Ist ein Datum angegeben, so wird der Job einmalig und nur an diesem Datum ausgeführt. Das Datum muss im Format %y-%m-%d (YYYY-MM-DD) angegeben werden.

  Beispiel: 2020-06-09

• weekdays:

  Enthält die Wochentage, an welchen der Job ausgeführt werden soll. Die Wochentage werden als Array von Zahlen angegeben, wobei 0 ~ Montag, 1 ~ Dienstag usw.

  Beispiel: [0, 5, 6] => Der Job wird montags, samstags und sonntags ausgeführt.

Warnung

Die Optionen daily, date und weekdays schließen sich gegenseitig aus. Es muss also genau eine Option ausgewählt werden.

config: Hier können die Konfigurationen für die Jobs festgelegt werden.

Bemerkung

Alle hier beschriebenen Konfigurationen sind optional und werden notfalls mit default-Werten initialisiert.

Mögliche Konfigurationen für die verschiedenen Themen:

Deutschlandweiter Wetterbericht (steps: "weather_germany"):

• Alle Einstellungen, die auch in der config.json unter steps_base_config zur Verfügung stehen.

Ortsbezogener Wetterbericht (steps: "weather_single"):

• Alle Einstellungen, die auch in der config.json unter steps_base_config zur Verfügung stehen

• city_name: str - Name des Ortes

• p_code: str - Postleitzahl des Ortes

• speech_app_temp_2: bool - Ob eine Audiodatei zu den gefühlten Temperaturen bei der 2-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_wind_2: bool - Ob eine Audiodatei zu Windgeschwindigkeit und -richtung bei der 2-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_sun_2: bool - Ob eine Audiodatei zu Sonnenauf- und -untergang bei der 2-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_rh_2: bool - Ob eine Audiodatei zur relativen Luftfeuchtigkeit bei der 2-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_pop_2: bool - Ob eine Audiodatei zur Regenwahrscheinlichkeit bei der 2-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_app_temp_3: bool - Ob eine Audiodatei zu den gefühlten Temperaturen bei der 3-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_wind_3: bool - Ob eine Audiodatei zu Windgeschwindigkeit und -richtung bei der 3-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_sun_3: bool - Ob eine Audiodatei zu Sonnenauf- und -untergang bei der 3-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_rh_3: bool - Ob eine Audiodatei zur relativen Luftfeuchtigkeit bei der 3-Tage-Übersicht erstellt und im Video abgespielt werden soll

• speech_pop_3: bool - Ob eine Audiodatei zur Regenwahrscheinlichkeit bei der 2-Tage-Übersicht erstellt und im Video abgespielt werden soll

Bemerkung

Aktuell lassen sich nur Wettervorhersagen für Städte in Deutschland generieren.

Spieltag-Bericht für die 1. und 2. Fußball-Bundesliga (steps: "football"):

• Alle Einstellungen, die auch in der config.json unter steps_base_config zur Verfügung stehen

• liga-name: str - Spielklasse (1 ~ 1. Liga, 2 ~ 2. Liga, 3 ~ 3. Liga)

Twitter Wordcloud (steps: "twitter"):

• Alle Einstellungen, die auch in der config.json unter steps_base_config zur Verfügung stehen

• normalize_words: bool - Ob die Wörter normalisiert werden sollen und Doppelungen bei der Zählung der Häufigkeiten zu vermeiden (Beispiel: Bundesliga, bundesliga und BUNDESLIGA (wird einzeln gezählt: je 1x)-> Bundesliga, Bundesliga, Bundesliga (insgesamt: 3x)

• colormap_words: str - Die Farben der Wörter in der Wordcloud

• color_func: bool - Ob für den Farbverlauf der Wörter in der Wordcloud ein bestimmter Farbverlauf anstelle einer Colormap verwendet werden soll

• color_func_words: str - Farbe des gewünschten Farbverlaufs der Wörter in der Wordcloud (nur wenn color_func auf true gesetzt wurde)

• figure: str - Form der Wordcloud (aktuell nur Kreis und Quadrat möglich)

• size_wordcloud: str - Größe der Wordcloud (verschiedene Größen möglich)

Tests ausführen

Mit Docker

Benötigte Software:

• Docker

Unter Windows muss ggf. noch ein Windows Subsystem for Linux installiert werden. Weitere Informationen hier.

In den src-Ordner wechseln: cd src

Tests ausführen:

• docker-compose -f visuanalytics/docker-compose.test.yml up

Ohne Docker

Benötigte Software:

• python >=3.6

• pip

In den src-Ordner wechseln: cd src

Pakete installieren:

• pip install -r visuanalytics/requiraments.txt

Tests ausführen:

• python python3 -m unittest discover visuanalytics

Bemerkung

Unter Linux kann es sein, dass pip3 und python3 verwendet werden müssen.

Dokumentation generieren

Für die Dokumentation wird das Python-Paket Sphinx verwendet.

Installation

Benötigte Software:

• python >=3.6

• pip

1. dev-dependencies installieren: pip install -r src/visuanalytics/requirements-dev.txt

Bemerkung

Unter Linux kann es sein, dass pip3 und python3 verwendet werden müssen.

HTML generieren

1. in den Dokumentationsordner wechseln: cd Docs

2. Dokumentation generieren: make html

Die Dokumentation befindet sich dann im Ordner _build/html.