#Dokumentacja skryptów

## Implementacja yolov3 Pytorch
Użyta implementacja pochodzi z [repozytorium](https://github.com/ultralytics/yolov3) i została zmodyfikowana na potrzeby projektu

Użyty model sieci: **yolov3-spp**

W [katalogu](./cfg) znajdują się pliki konfiguracyjne dla poszczególnych modeli. W zależności od ilości klas
musza zostać one odpowiednio zmodyfikowana jak opisano [tutaj](https://github.com/ultralytics/yolov3/wiki/Train-Custom-Data)
dodatkowo jest tutaj również opisany sposób renowania modelu na dowolnych danych.


## Kod źródłowy

Głównie interesuje nas skrypt [run_yolov3_process_bayes.py](./our_scripts/run_yolov3_process_bayes.py)
Który wykonuje kolejno nastęjące zadania:

1. Trenowanie modelu na danych ([train.py](./train.py))
2. Tworzenie katalogu z eksperymentem zawierającym: 
    * najelpszy model
    * wyniki detekcji na zbiorze testowym (podzielone na błędnie sklasyfikowane i te poprawne)
    * użyty plik z nazwami klas
    * użyty plik konfiguracyjny `.yml`
3. Puszczanie skryptu wykonującego detekcje ([detect.py](./detect.py))
4. Puszczanie skryptu [generate-confusion-matrix.js](./our_scripts/generate-confusion-matrix.js) obliczającego tzw. "macierz pomyłek" _(ang. confussion matrix)_

Skrypt wykonuje również trenowanie modelu wraz z optymalizacją bayesowską.

Najważniejszym plikiem który nas interesuje to [config_bayes.yml](./our_scripts/config_bayes.yml)  oraz plik 
z rozszeżeniem `*.data` np. [widok_01_21.data](./data/widok_01_21/widok_01_21.data) który zawiera konfigurację 
modelu.
Parametry :
* `classes` - liczba klas wykrywanych przez model
* `train` - plik zawierający ścieżki do zdjeć uczących 
* `valid` - plik zawierający ścieżki do zdjęć testowych
* `names` - plik z etykietami, musi być ich tyle samo co klas


Kilka uwag dotyczących pliku konfiguracyjnego [config_bayes.yml](./our_scripts/config_bayes.yml)
 * Parametry mogą być typu:
    * `discrete` - dyskretne wtedy wartości jakie może on przyjmować trzeba wymienić w liście `values` :
    
        ```yaml
          batch-size:
            type: discrete
            values: [4]
        ```    
   
        albo określić przedział wartości np:
    
         ```yaml
            batch-size:
                type: discrete
                min: 1
                max: 5
                step: 1
        ```
    *  `continuous` - parametry ciągłe, wtedy należy określić zakres `min` i `max` (jako liczba zmiennoprzecinkowa)
        w jakim może mieścić się wartość parametru np:
        
        ```yaml
            giou:
              type: continuous
              min: 0.0
              max: 10.0
        ```
Jeśli chcemy aby optymalizacja bayesowska nie została wykonana to po prostu należy ustawić wszystkie parametry jako dyskretne z jedną wartością
w liście. W przypadku różnych kombinacji parametrów skrypt uruchamiający proces wykona optymalizację bayesowską.

## Uruchamianie detekcji

Puszczanie detekcji odbywa się za pomocą skryptu [detect.py](./detect.py)

Parametry wywołania (te które nas interesują):
* `source` - źródło danych (plik/folder ze zdjęciami/nagraniami), może też być plik txt zawierający ścieżki do nagrań/zdjeć
* `output` - folder do którego zostanią zapisane wyniki (musi być utworzony)
* `names` - plik `.names` z etykietami klas
* `weights` - plik `.pt` z wagami modelu, zazwyczaj będzie to plik `best.pt` zawierający wagi dla najlepszego modelu
* `test-img-size` - rozmiar obrazu na jakim odbędzie się detekcja
* `conf-thres` - próg prawdopodobieństwa, minimalna wartość stopnia "pewności" dla której model uzna że znalazł obiekt na zdjęciu/nagraniu
* `iou-thresh` - próg dla współczynnika IoU, (współczynnik Jaccarda), wykorzysywany przy non-max-supression
* `save-txt` - flaga określająca czy skrypt ma zapisać znalezione detekcje do pliku `.txt`
* `device` - numer karty graficznej wykorzystywanej do obliczeń, w przypadku braku tej flagi model odpali się na wszystkich dostępnych    
    
Przykładowe wywołanie:

```shell script
python detect.py
--source
/home/tomekb/yolov3/data/widok_01_21/widok_01_21_test_labels.txt
--output
/home/tomekb/yolov3/experiments/2020-09-01_06-39-29/output
--names
/home/tomekb/yolov3/experiments/2020-09-01_06-39-29/widok_01_21.names
--weights
/home/tomekb/yolov3/experiments/2020-09-01_06-39-29/best.pt
--test-img-size
1024
--conf-thres
0.45
--iou-thres
0.6
--save-txt
--device
1



```