VisuAnalytics

Einleitung

Im Rahmen der Veranstaltung Softwaretechnik-Praktikum im Sommersemester 2020 wurde dieses Projekt zum Thema Data Analytics durchgeführt.

Die Veranstaltung gehört zum Curriculum der Bachelorstudiengänge der Informatik an der Technischen Hochschule Mittelhessen.

Die Aufgabe war es, Informationen über verschiedene Schnittstellen zu erfassen, diese automatisiert zu verarbeiten und daraus ein Video zu generieren, welches die Informationen in Bild und Ton präsentiert.

Aktuell gibt es vier mögliche Videos, welche automatisiert erstellt werden können:

• Deutschlandweiter Wetterbericht
• Ortsbezogener Wetterbericht
• Bundesliga-Ergebnisse
• Twitter-Wordcloud

Neue Schnittstellen sollen schnell zu ergänzen sein, sodass weitere Videos mit anderen Themen erstellt werden können.

Zudem wurde ein Frontend entwickelt mit welchem es möglich ist Videos in Auftrag zu geben und diese zu festgelegten Zeitpunkten automatisch zu generieren. Dies ist auch durch ein Wordpress-Plugin möglich.

Die Software soll nach der Fertigstellung auf der Website https://biebertal.mach-mit.tv/ eingesetzt werden. Biertal.Mach-Mit.TV ist ein Kooperationsprojekt der Gemeinde Biebertal und dem Fachbereich MNI der Technischen Hochschule Mittelhessen.

Programm Verwenden

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.

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, wir fanden diese aber hilfreicher. 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

• Konfigurations-Dateien 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)

Um die Option h264_nvenc (siehe config.json) zu verwenden, müssen diverse Einstellungen vorgenommen werden. Eine gute 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.

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 Backendserver 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):

• keep_count(optional):

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 Audio-Generierung 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 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

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 in dem Format %y-%m-%d 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.

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.

Alle hier beschriebenen Konfigurationen sind optional und werden notfals mit default-Werten initalisiert.

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

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

Spieltag-Bericht für die 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

 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

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.