- [1. Úvod](#1-úvod)
- [2. Struktura projektu](#2-struktura-projektu)
- [3. Instalace](#3-instalace)
- [4. Použití](#4-použití)
  - [4.1. Spuštění simulací všech komponent](#41-spuštění-simulací-všech-komponent)
  - [4.2. Spuštění simulací podle šablony v json](#42-spuštění-simulací-podle-šablony-v-json)
  - [4.3. Výsledky simulací](#43-výsledky-simulací)
    - [4.3.1. Jednoduché zobrazení výsledků](#431-jednoduché-zobrazení-výsledků)
    - [4.3.2. Pokročilé zobrazení výsledků](#432-pokročilé-zobrazení-výsledků)
      - [4.3.2.1. Exportování do CSV](#4321-exportování-do-csv)

# 1. Úvod

Nástroj RFTester je software pro automatické vyhodnocování efektivity zpětnovazebních učících algoritmů pro hledání známého objektu v databázi. K hledání využívá charakteristické rysy z hlubokých neuronových sítí.

# 2. Struktura projektu

 - Projekt *CEmbedSomDLL* obsahuje implementaci samoogranizujících se map, která je převzatá z [EmbedSOM](https://github.com/exaexa/EmbedSOM).
 - Adresář *data* obsahuje data pro nástroj jako například charakteristické rysy z neuronových sítí apod.
   - Obsahuje pouze podmnožinu **20 000** snímků z původního datasetu na kterých byly prezentovány výsledky. Celý původní dataset nemohl být přibalen z důvodu velikosti.
 - Adresář *docs* obsahuje dokumentaci k projektům *RFTester* a *RFTesterBackend*
 - Projekt *RFTest* obsahuje webovou nadstavbu pro práci s evaluačním frameworkem. Obsahuje:
   - *Models* - modely pro zobrazení na Razor pages.
   - *NancyModules* - moduly pro framework NancyFX. 
   - *Properties* - obsahuje `AssemblyInfo.cs`
   - *assets* - obsahuje podpůrné .js knihovny a kaskádové styly
   - *views* - obsahuje .cshtml soubory pro zobrazení na webu
 - Projekt *RFTesterBackend* obsahuje základní evaluační framework pro paralelní testování zpětnovazebních algoritmů. Obsahuje:
   - *DisplayGenerators* - rozhraní a implementace algoritmů pro generování displejů.
   - *Evaluator* - logika a podpůrné třídy pro vyhodnocení efektivity zpětnovazebních algoritmů pro hledání známého objektu
   - *Initializers* - rozhraní a implementace algoritmů pro inicializaci skóre relevancí
   - *KeywordFilters* - algoritmy pro aplikování klíčových slov
   - *Measurers* - rozhraní a implementace tříd pro vzdálenostní funkce
   - *Rankers* - rozhraní a implementace tříd pro aplikování zpětné vazby na skóre relevancí
   - *ResourceManagers* - správa statických dat a poskytnutí přístupu k funkcím v externím dll
   - *SimulatedUsers* - rozhraní a implementace simulovaných užívatelů
 - Skripty `UpdateConfigs.sh` a `UpdateConfigs.bat` připraví dll a konfigurační soubory na správné místa 

# 3. Instalace

Ke spuštění nástroje RFTester budete potřebovat Microsoft Visual studio 2017 (kompatibilita s VS 2019 neozkoušena).

Postup instalace a spuštění nástroje:
1. Rozbalit nebo stáhnout repozitář `https://gitlab.mff.cuni.cz/veselp/rftester`
2. Otevřít `RFTester.sln` v programu Visual studio
3. Změnit cílovou platformu na `x64`
4. Vybrat konfiguraci `Debug` nebo `Release`
5. Sestavit projekt `CEmbedSomDLL` (pravé tlačítko myši -> sestavit)
6. Spustit skript pro zanesení konfiguračních souborů do správných adresářů `UpdateConfigs.bat` nebo `UpdateConfigs.sh`
7. Vybrat projekt `RFTester` jako startovací
8. Spustit aplikaci tlačítkem `Start`

# 4. Použití

Po startu aplikace se otevře prohlížeč s úvodní obrazovkou. 
Doporučuji použít prohlížeč Mozilla Firefox nebo Google Chrome. 

Na první obrazovce můžeme nalézt (viz screenshot):
1. Správce zdrojů
    - V prvním sloupci je název správce
    - V druhém je stav (NOT_LOADED, LOADING, LOADED)
    - V posledním sloupci je možná akce (načíst jeho prostředky)
    - Typy správců:
      - Deep features - obstarává matici charakteristických rysů
      - Path to videos - obstarává názvy snímků
      - Query embeddings - obstarává textové dotazy
    - Ke správnému fungování aplikace je třeba načíst **všechny** zdroje
2. Evaluační engine
    - Zde je možné kontrolovat průběh simulací
    - Indikátor v sloupci "running" znázorňuje stav, zda se vyhodnocují evaluační úkoly
    - V sloupci "Occupancy" je počítadlo, kolik úkolů zbývá ve frontě (bez aktuálně se zpracovávaných)
    - Tlačítko Start/Stop změní stav výpočtů. Buď nastartuje nebo stopne další výpočty.
3. Ostatní akce
    - Tlačítko "Save Processes" uloží aktuální stav a výsledky všech procesů. 
    - Tlačítko "Brute Force Process" vytvoří evaluační proces pro všechny instance klíčových komponent evaluace. Viz [4.1. Spuštění simulací všech komponent](#41-spuštění-simulací-všech-komponent).
    - Tlačítko "Custom Process" vytvoří evaluační proces na základě šablony v json. Viz [4.2. Spuštění simulací podle šablony v json](#42-spuštění-simulací-podle-šablony-v-json).
4. Menu
    - Obsahuje položky "Dashboard" a "Evaluation analytics"

![Dashboard screenshot](/img/Dashboard.jpeg)


## 4.1. Spuštění simulací všech komponent

Pokud uživatel chce spustit simulace hledání pro všechny komponenty, tak toho může docílit stisknutí tlačítka "Brute Force Process" na obrazovce "Dashboard" a vybráním počtu hledaných snímků. 

Vytváření tohoto procesu probíhá tak, že se každý typ komponenty nakombinuje s každým typem zbylích komponent. Pro ukázku předpokládejme, že máme komponenty jen generátory displeje D1, D2, D3 a simulované uživatele U1 a U2. Po vytvoření bude mít tento proces třídy D1-U1, D2-U1, D3-U1, D1-U2, D2-U2 a D3-U2.

> Aby se začaly vyhodnocovat jednotlivé úkoly, tak musí být načteny všechny zdroje a musí být nastartovaná část vyhodnocující úkoly "Evaluation engine"

## 4.2. Spuštění simulací podle šablony v json

Pokud uživatel chce spustit simulace s různými komponenty nebo s rozdílnýma dodatečnýma parametrama, může k tomu využít možnost vytvoření procesu podle šablony v json. Cesta k šabloně je zadána do vstupního pole ve vyskakovacím okně.

Ukázka šablony `evaluation_template.json`:
```
{
  "Name": "Evaluation_Example_1",
  "MaxRounds": 10,
  "NumberOfTests": 0,
  "SingleTestRepeat": 1,
  "Initializers": [
    {"Name": "W2VVInitializer", "Pars": {"topn": 100000, "power": 25, "normalize": true} },
    {"Name": "UniformInitializer"}
  ],
  "Rankers": [
    {"Name": "BayesianIndepRanker", "Pars": {"sigma": 0.1}}, 
    {"Name": "BayesianIndepRanker", "Pars": {"sigma": 0.3}}, 
    {"Name": "BayesianIndepRanker", "Pars": {"sigma": 0.5}}
  ],
  "Displays": [
    {"Name": "SOMDisplayGenerator", "Pars": {"somx": 8, "somy": 8, "usecos": true, "forcerepre": true, "power": 1}},
    {"Name": "SOMWeightedDisplayGenerator", "Pars": {"somx": 8, "somy": 8, "usecos": true, "forcerepre": true, "power": 1}}, 
    {"Name": "RandomSampleGenerator", "Pars": {"nimages": 64, "power": 1}},
    {"Name": "TopNDisplayGenerator", "Pars": {"nimages": 64}}
  ],
  "Users": [
     {"Name": "SimpleIdealUser", "Pars": {"likes": 3}},
     {"Name": "RandomSampleUser", "Pars": {"likes": 3, "power": 12}},
  ],
  "Measurers": [{"Name": "CosineMeasurer"}]
}
```

Šablona se zkládá z:
- Názvu v atributu "Name". Za tento název bude dále přidáno časové razítko.
- Maximální počet kol "MaxRounds", které budou simulované. **Doporučuji** ponechat 10.
- Počet hledaných snímků "NumberOfTests". Pokud je vyplněno 0, tak se vezme maximální možný počet. Hledané snímky jsou určeny v souboru `data/annots_W2VV.20k.json`.
- Opakování jednoho hledaného snímku "NumberOfTests". Kolik bude pro jeden hledaný snímek vytvořeno úkolů.
- Inicializátory skóre "Initializers". Obsahuje pole objektů, kde položka "Name" musí odpovídat názvu třídy implementace dané komponenty a položka "Pars" obsahuje dodatečné parametry pro tuto komponentu.
- Implementace zpětnovazebního učení "Rankers". Komponenty musí být definované obdobně jako inicializátory.
- Implementace výběrů displeje "Displays". Komponenty musí být definované obdobně jako inicializátory.
- Implementace simulovaných uživatelů "Users". Komponenty musí být definované obdobně jako inicializátory.
- Implementace funkcí vzdáleností "Measurers". Komponenty musí být definované obdobně jako inicializátory.

Pro tyto komponenty zase každý s každým bude vytvořena jedna evaluační třída.

> Aby se začaly vyhodnocovat jednotlivé úkoly, tak musí být načteny všechny zdroje a musí být nastartovaná část vyhodnocující úkoly "Evaluation engine"

## 4.3. Výsledky simulací

K analýze výsledků evaluací využijeme obrazovku "Evaluation analytics", ke které se dostaneme přes tlačítko "Evaluation analytics" v postranním menu.

Zde je vidět seznam všech evaluačních procesů, které jsou uloženy v nástroji. Viz screenshot. V první sloupci je název procesu, v druhém je čas vytvoření a v třetím jsou tlačítka k zobrazení výsledku nebo oznámení, že výsledek ještě není připraven.

![Evaluation analytics screenshot](/img/Analytics.jpeg)

### 4.3.1. Jednoduché zobrazení výsledků

Jednoduché výsledky procesu se zobrazí po stisknutí tlačítka "Show detail".

Tyto výsledky jsou rozdělené do 3 kategorií podle toho, zda nás zajímá úspěšnost nalezení přesně hledaného snímku, scény nebo videa. Grafy zobrazují část úkolů, které byli vyřešeny do displeje na ose x. Popisky k barvám křivek jsou napravo.

![Evaluation detail screenshot](/img/Detail.jpeg)

### 4.3.2. Pokročilé zobrazení výsledků

Jednoduché zobrazení nemusí být vždy dostačující, když například testujeme velké množství typů uživatelů. K tomu slouží pokročilé zobrazení výsledků. Toto zobrazení se objeví po stisknutí tlačítka "Show grid".

Na této obrazovce je zde zobrazeno více grafů. V řádcích jsou grafy, kde uživatelé zadávali stejný počet relevantních snímků. V sloupcích jsou grafy, kde uživatelé měli stejnou "sílu".

![Evaluation grid screenshot](/img/Grid.jpeg)

#### 4.3.2.1. Exportování do CSV

Pokud anii pokročilé zobrazení není dostačující, může uživatel využít možnost exportovat výsledky do CSV. K tomu slouží tlačítka "Frame found CSV", "Shot found CSV", "Video found CSV", "Frame detail search CSV", "Shot detail search CSV" a "Video detail search CSV". První tři vyexportují data o tom, jak velká část úloh byla vyřešena do určitého displeje. Poslední tří tlačítka exportují pořadí hledaných objektů v databázi v průběhu hledání.
