Added docs

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
+
+
+
+```