MG-KI_Flaechenanalyse/README.md

# Drohnen KI

Dieses Projekt widmet sich der Erkennung von Flächenbelägen auf Drohnenbildern.

## Installation

Die Installation einer virtuellen Umgebung lässt sich durch folgende Zeilen Konsolencode bewerkstelligen.

```shell
python3 -m venv venv
source venv/bin/activate
pip install 'git+https://github.com/facebookresearch/detectron2.git'
pip install -r requirements.txt
```

Da sich Detectron2 nicht in den Standard pip-Bibliotheken verfügbar ist, muss dieses Modul separat installiert werden.

Nach Abschluss dieser Befehle ist die virtuelle Umgebung einsatzbereit.
Durch Ansprechen des Befehls `deactivate` gelangt man wieder aus der Umgebung heraus.
Um eine erneute Nutzung dieser virtuellen Umgebung durchzuführen, reicht es, den Befehl `source venv/bin/activate`
auszuführen.

## Nutzung

Dieser Abschnitt geht davon aus, dass die Umgebung korrekt installiert ist.

### Vorverarbeitung der GIS-Daten

Da die Daten aus dem stadteigenen GIS nicht direkt von der KI erstanden werden, benötigt es einer Vorverarbeitung.
Diese passiert in der Datei [`belag.py`](preprocessing/belag.py).

Voraussetzung hierfür ist, dass eine Datei `Fleachenbelaege.json` und eine `Referenzpunkte.csv` vorhanden sind.
Sollten die Namen oder Pfade abweichen, kann dies in der Datei `belag.py` angepasst werden.

In der Datei `Flaechenbelaege.json` werden Flächendefinitionen im [GeoJSON](https://geojson.org/)-Format erwartet.
Diese Datei enthält alle Flächen, die zum Training verwendet werden sollen.

Die Datei `Referenzpunkte.csv` gibt in den ersten 4 Reihen die Eckpunkte des zu verarbeitenden Bildes aus.
Diese werden verwendet, um die Koordinaten aus der Flächenbeschreibung den Pixel-Koordinaten im Bild zuzuweisen.

Sobald alle Dateien vorhanden sind, kann das Skript mit folgendem Befehl ausgeführt werden:

```shell
python belag.py
```

Das Resultat daraus ist zum einen ein Ordner mit allen 1000x1000 Pixel großen Bildern und zum anderen eine
Datei `belaege.json`.
Diese beiden Dateien können anschließend zum Training genutzt werden.

### Erkennung

Zur Erkennung einzelner Bilder kann die Datei `predict.py` verwendet werden.

```shell
python predict.py \
    --source data/images/westend/cropped \
    --output_dir data/images/Markierungen
```

Die Parameter können beliebig angepasst und in allen Kombinationen übergeben werden.

| Parameter     | Standardwert          | Beschreibung                                                            |
|---------------|-----------------------|-------------------------------------------------------------------------|
| category_json |                       | Falls andere Klassen verwendet werden, können sie hier übergeben werden |
| source        | data/images/original  | Ein Ordner, in dem sich alle zu bearbeitenden Bilder befinden           |
| output_dir    | data/images/predicted | Ein Ordner in dem alle erkannten Bilder abgelegt werden                 |

### Training

Zur Nutzung des Trainingsskripts wird eine GPU empfohlen.

Das Training lässt sich über die Datei `train.py` starten.
Dazu dient folgender Befehl:

```shell
python train.py --data_json data/json/train_data.json
```

Der Pfad `data/json/train_data.json` kann hierbei durch eine andere Trainingsdatei ersetzt werden.
Zur Anpassung weiterer Einstellungen (wie die Anzahl der zu trainierenden Epochen) stehen Konfigurationsoptionen direkt
in der `train.py`-Datei bereit.

#### Trainingsdaten

Die Trainingsdaten werden im folgenden JSON-Format erwartet:

```JSON
{
  "train_images": [],
  "test_images": [],
  "categories": []
}
```

Der Bereich `categories` ist ein Array von Strings.
Dies sind die Namen der Klassen, auf die in den image-Objekten referenziert werden.
Beispiel:

```JSON
[
  "Baumbestand",
  "Festweg",
  "Pflaster",
  "Wiese",
  "Wasser",
  "Gullydeckel"
]
```

Sowohl `train_images`, als auch `test_images` halten Bilddaten in dem folgenden Format vor:

```JSON
{
  "image_id": 0,
  "width": 1000,
  "height": 1000,
  "file_name": "data/images/westend/cropped/WestendDOP2_0_9000.tif",
  "annotations": []
}
```

Der Parameter `annotations` ist eine Liste aus Objekten:

```JSON
{
  "category_name": "Gullydeckel",
  "ignore": 0,
  "iscrowd": 0,
  "area": 1256.6370614359173,
  "bbox": [
    878.0,
    526.0,
    918.0,
    566.0
  ],
  "bbox_mode": 0,
  "segmentation": [
    [
      918.0,
      546.0,
      917.61571,
      549.90181,
      916.47759,
      553.65367,
      914.62939,
      557.1114,
      912.14214,
      560.14214,
      909.1114,
      562.62939,
      905.65367,
      564.47759,
      901.90181,
      565.61571,
      898.0,
      566.0,
      894.09819,
      565.61571,
      890.34633,
      564.47759,
      886.8886,
      562.62939,
      883.85786,
      560.14214,
      881.37061,
      557.1114,
      879.52241,
      553.65367,
      878.38429,
      549.90181,
      878.0,
      546.0,
      878.38429,
      542.09819,
      879.52241,
      538.34633,
      881.37061,
      534.8886,
      883.85786,
      531.85786,
      886.8886,
      529.37061,
      890.34633,
      527.52241,
      894.09819,
      526.38429,
      898.0,
      526.0,
      901.90181,
      526.38429,
      905.65367,
      527.52241,
      909.1114,
      529.37061,
      912.14214,
      531.85786,
      914.62939,
      534.8886,
      916.47759,
      538.34633,
      917.61571,
      542.09819
    ]
  ],
  "category_id": 5
}
```

`segmentation` folgt dem xyxy-Muster. Das bedeutet, dass ein Objekt, welches von (0, 10) über (0, 50) zu (20, 30) geht,
diese Liste generieren würde:

```JSON
[
  0,
  10,
  0,
  50,
  20,
  30
]
```

## Contributors
Dieses Projekt wurde entwickelt von [Masasana AI](https://masasana.ai) in Zusammenarbeit mit dem Smart City Team der Stadt
Mönchengladbach.