From 129debec7c86e5a16f5d3afd620398c005005b70 Mon Sep 17 00:00:00 2001 From: tomasz Date: Sat, 12 Sep 2020 15:57:45 +0200 Subject: [PATCH] Added docs --- README.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..f9e23a55 --- /dev/null +++ b/README.md @@ -0,0 +1,109 @@ +#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 + + + +``` \ No newline at end of file