# Rozpoznávání znakového jazyka
Rozpoznávání znakového jazyka na slovní úrovni z dynamické pózy rukou a obličeje člověka. Subprojekt projektu [Interpretace znakové řeči](../README.md). Součástí projektu je automatická anotace dat, definice modelů rekurentních neuronových sítí (RNN) sloužící jako klasifikátory, jejich naučení a evaluace.

Rozpoznávání znakové řeči je pojato jako klasifikace dynamického pohybu rukou a obličeje v čase, popsanými svými klíčovými body, jinými slovy svou pózou. V rámci projektu je implementováno rozpoznávání amerického znakového jazyka (ASL). Jako dataset je použit dataset [Word-Level American Sign Language - WLASL](https://dxli94.github.io/WLASL/), který obsahuje 2000 znaků interpretovaných různými interprety v různých dialektech.

Adresářová struktura projektu je složená ze skriptů, knihoven, dat a vah. Spustitelné skripty jsou umístěny v adresářovém kořenu, knihovny, data a váhy jsou umístěny v samostatných adresářích `./modules/`, `./data/` a `./weights/`.

## Spustitelné skripty
Stručný popis funkcionality jednotlivých skriptů, podrobnější informace jsou uvedeny přímo ve skriptech.

### `annotate_data.py`
Automatická anotace `WLASL` datasetu klíčovými body rukou a obličeje interpreta ve všech časových krocích. K anotaci jsou použity [detektory](../detection/README.md), [estimátory pózy](../pose_estimation/README.md) a [tracker](../tracking/README.md) vyvinuté v rámci dalších subprojektů. Vzhledem k funkčnosti trackeru, je každý datový vzorek anotován dopředným a zpětným průchodem trackeru, tedy jsou analyzované sekvence `[t(0), t(1), ..., t(N-1)]` a `[t(N-1), t(N-2), ..., t(0)]`. Obsahuje hlavní funkce:
- `map_classes()` - vytvoří soubor mapující názvy znaků na identifikační čísla tříd
- `annotate_wlasl()` - automatická anotace datasetu klíčovými body

### `construct_tfrecords.py`
Skript pro konverzi datasetu do serializovaného formátu `TFRecord` pro účely efektivního podávání dat modelům při procesu učení a evaluace. Dataset je rozdělený do sub-datasetů podle počtu znaků, které obsahují - 100, 300, 1000 a 2000.

### `visualize_dataset.py`
Skript pro vizualizaci datasetu a vytvořených anotací přímo ze zdrojových adresářů datasetu nebo čtením generovaných `TFRecord` souborů. Obsahuje hlavní funkce:
- `wlasl_from_files()` - Vizualizace datasetu ze zdrojových adresářů
- `wlasl_from_tfrecords(n_classes)` - Vizualizace datasetu z vytvořených `TFRecord` souborů. Argument `n_classes` určuje, který sub-dataset je vizualizován - jedno z `{100, 300, 1000, 2000}`.

### `vocabulary.py`
Skript pro vyhledávání videí v datasetu podle názvu znaku.

### `train.py`
Skript pro naučení definovaných modelů. Argumentem hlavní funkce je počet tříd sub-setu, který bude použit pro naučení sítě - jedno z `{100, 300, 1000, 2000}`.

### `evaluate.py`
Evaluace naučených klasifikátorů definovanou metrikou. Argumenty hlavní funkce jsou flagy `to_file` a `only_test`. Flag `to_file` definuje, zda budou výsledky evaluace zaneseny do `.csv` souboru pro další zpracování a flag `only_test` definuje, zda má být provedena evaluace pouze na testovaích subsetech nebo i na trénovacích a validačních množinách.

### `performance.py`
Skript pro měření FLOPs (*floating point operations*), počet parametrů a latence inference jednotlivých modelů. Latence je měřena průměrnou latencí z 50-ti inferenčních průchodů.

### `visualize_model.py`
Skript pro vizualizaci vstupních a výstupních vah naučených modelů a vizualizaci odezvy modelu na vzorky z testovacích subsetů. Obsahuje hlavní funkce:
- `check_wlasl_input_weights()` - Vizualizace vstupních vah modelů
- `check_wlasl_output_weights()` - Vizualizace výstupních vah modelů
- `visualize_outputs()` - Vizualizace odezvy modelů na vzorky z testovacích subsetů

## Vlastní knihovny
Stručný popis vlastně vytvořených knihoven, podrobnější popis funkcionality je uveden přímo ve zdrojových souborech. Všechny knihovny jsou umístěny v adresáři `./modules/`.

- `config.py` - Konfigurační soubor obsahující primárně informace o adresářové struktuře a umístění jednotlivých souborů. Obsahuje také parametry pro učení a inferenci modelů.
- `wlasl_utils.py` - Knihovna obsahující nástroje pro práci s `WLASL` datasetem.
- `dataset_utils.py` - Knihovna obsahující nástroje pro práci s daty na projektové úrovni.
- `inference_utils.py` - Knihovna obsahující nástroje pro inferenci modelů.
- `model.py` - Knihovna obsahující definici modelů RNN pro rozpoznávání znakové řeči.
- `metrics.py` - Knihovna obsahující definici metrik použitých k evaluaci naučených modelů.

## Doporučený postup pro replikaci výsledků

### Předpokládaný adresářový strom a prerekvizity
Prerekvizitou je stažení použitého datasetu [WLASL: A large-scale dataset for Word-Level American Sign Language](https://github.com/dxli94/WLASL).

Pozn.: Autoři datasetu nepublikují kompletní dataset, ale pouze nástroje pro automatické stažení použitých videozáznamů z internetu. Vzhledem k tomu, že některá videa již nejsou veřejně dostupná, je touto metodou možné získat nekompletní dataset. Pro přístup ke kompletnímu datasetu je potřeba o data zažádat přímo od autorů podle [návodu uvedeného na oficiálním repozitáři](https://github.com/dxli94/WLASL#requesting-missing--pre-processed-videos).

Předpokládaný adresářový strom pro stažená data je pak ve tvaru:
```
translation
├── data
│   ├── WLASL
│   │   ├── videos
│   │   │   ├──  <>.mp4
│   │   │   └──  ...
│   │   └──  WLASL_v0.3.json
│   └── ...
├── ...
```

### 1. Anotace `WLASL` datasetu
Ve skriptu `annotate_data.py` povolte volání obou hlavních funkcí, pro konstrukci mapy tříd a spuštění samotné anotace.
```python
if __name__ == '__main__':
    map_classes()
    annotate_wlasl()
```
```
$ python ./translation/annotate_data.py
```
Výsledkem je vytvoření anotačního souboru pro každé video v datasetu
```
translation
├── data
│   ├── WLASL
│   │   ├── annotations
│   │   │   ├──  <>.json
│   │   │   └──  ...
│   │   └──  ...
│   └── ...
├── ...
```

### 2. Konstrukce `TFRecord` souborů
```
$ python ./translation/construct_tfrecords.py
```
Výsledkem je vytvoření `TFRecord` souborů pro jednotlivé subsety datasetů
```
translation
├── data
│   ├── tfrecords
│   │   ├── wlasl100_train.tfrecord
│   │   ├── wlasl100_val.tfrecord
│   │   ├── wlasl100_test.tfrecord
│   │   ├── wlasl300_train.tfrecord
│   │   ├── wlasl300_val.tfrecord
│   │   ├── wlasl300_test.tfrecord
│   │   ├── wlasl1000_train.tfrecord
│   │   ├── wlasl1000_val.tfrecord
│   │   ├── wlasl1000_test.tfrecord
│   │   ├── wlasl2000_train.tfrecord
│   │   ├── wlasl2000_val.tfrecord
│   │   └── wlasl2000_test.tfrecord
│   └── ...
├── ...
```

### 3. Naučení modelů
Ve skriptu `train.py` povolte volání učení modelů pro datasety o chtěné velikosti slovní zásoby, např. pro naučení všech modelů:
```python
if __name__ == '__main__':
    train_classifier(100)
    train_classifier(300)
    train_classifier(1000)
    train_classifier(2000)
```
```
$ python ./translation/train.py
```
Výsledkem jsou naučené váhy modelů
```
translation
├── weights
│   ├── wlasl100.tf.index
│   ├── wlasl100.tf.data-00000-of-00001
│   ├── wlasl300.tf.index
│   ├── wlasl300.tf.data-00000-of-00001
│   ├── wlasl1000.tf.index
│   ├── wlasl1000.tf.data-00000-of-00001
│   ├── wlasl2000.tf.index
│   ├── wlasl2000.tf.data-00000-of-00001
│   └── ...
├── ...
```

### 4. Evaluace naučených modelů
Ve skriptu `evaluate.py` je volitelné povolení uložení výsledků evaluace do souboru společně s evaluací na trénovací a vlidační množině pro následnou lidskou analýzu:
```python
if __name__ == '__main__':
    eval_wlasl(to_file=True, only_test=False)
    # eval_wlasl(to_file=False, only_test=True)  # pro čistou evaluaci na test subsetech
```
```
$ python ./translation/evaluate.py
```
Výstupem jsou výsledky evaluací v konzoli a v případě zápisu výsledků do souboru je vytvořen výstupní soubor
```
translation
├── data
│   ├── WLASL
│   │   ├── eval_metrics.csv
│   │   └──  ...
│   └── ...
├── ...
```
