				#########################################
				#					#
				#	Face Recognition - UNIX		#
				#					#
				#########################################



===== [CONTENUTO] =============================================================================================

# face_encoder_cpu	versione Unix della prima parte del programma che utilizza il processore

La versione CPU è universale ed è abilitata al multicore.

# face_encoder_gpu	versione Unix della prima parte del programma che utilizza la scheda grafica

La versione GPU funziona solamente in un ambiente che dispone di una scheda grafica,
altrimenti il programma segnala l'errore e termina. Utilizza le librerie CUDA per maggiore precisione.

# face_matcher		versione Unix della seconda parte del programma



===== [ESEGUIRE FACE_ENCODER] =================================================================================

Avvia il terminale nella cartella del programma e lancia il comando

face_encoder_cpu [-h/--help] -i IMAGES/--images IMAGES [-o OUT/--out OUT] [-l LOG/--log LOG] [-r/--recursive] [-t/--include-tn] [-m/--multicore] [-s MIN/--min-size MIN] [-u/--upsample]
face_encoder_gpu [-h/--help] -i IMAGES/--images IMAGES [-o OUT/--out OUT] [-l LOG/--log LOG] [-r/--recursive] [-t/--include-tn] [-m/--multiprocess] [-s MIN/--min-size MIN] [-u/--upsample]

rispettivamente per la versione CPU o GPU.

----- <DESCRIZIONE> -------------------------------------------------------------------------------------------
--help		mostra la guida del programma

--images	imposta il percorso da cui leggere le immagini da codificare

--out		imposta il percorso in cui generare il file di encodings .pkl

Il programma accetta sia il percorso di un file da creare (es. "./output/gara2/face_encodings_gara2.pkl"),
sia quello di una cartella (es. "./output/gara2/") in cui verrà generato un file default "face_encodings_DATETIME.pkl".
Tutte le sottocartelle presenti nel percorso, se non esistenti, verranno create.
Se non impostato, di default il programma genererà il file al percorso "./output/face_encodings_DATETIME.pkl".

--log		imposta il percorso in cui generare il file di log .txt

Il programma accetta sia il percorso di un file da creare (es. "./output/gara2/encoder_log_gara2.txt"),
sia quello di una cartella (es. "./output/gara2/") in cui verrà generato un file default "encoder_log_DATETIME.txt".
Tutte le sottocartelle presenti nel percorso, se non esistenti, verranno create.
Se non impostato, di default il programma genererà il file al percorso "./output/encoder_log_DATETIME.txt".

--recursive	abilita la ricerca ricorsiva in tutte le sotto cartelle all'interno di "IMAGES"

Se non impostato, di default il programma ignorerà tutte le sottocartelle nel percorso indicato.

--include-tn	disabilita il filtro-tn, includendo nell'elaborazione anche le immagini thumbnail

Se non impostato, di default il programma abilita il filtro e ignora ciascuna immagine che inizia per "tn_".

--multicore	[!SOLO PER CPU!] imposta il livello di parallelismo con cui avviare l'elaborazione

Accetta valori {1, 2, 3, 4, 5} che corrispondono all'utilizzo di {1/8, 1/4, 1/2, 3/4, n-2} dei core.
Se non impostato, di default il programma imposterà il livello di multicore a 3 e utilizzerà dunque 1/2 dei core.

--multiprocess	[!SOLO PER GPU!] imposta il livello di parallelismo con cui la CPU fornisce le immagini da elaborare alla GPU

Accetta valori {1, 2, 3, 4, 5} che corrispondono all'utilizzo di {1/8, 1/4, 1/2, 3/4, n} dei worker utilizzabili.
Se non impostato, di default il programma imposterà il livello di multicore a 3 e utilizzerà dunque 1/2 dei worker.

--min-size	imposta la dimensione minima in pixel dei volti da codificare

Se non impostato, di default il programma imposterà la dimensione minima a 35px.

--upsample	abilita l'upsample, permettendo al programma di aumentare la risoluzione delle immagini prima dell'elaborazione

Aumentando la risoluzione delle immagini, il programma consumerà molte più risorse in termini di tempo e memoria ma
sarà in grado di trovare molti più volti, anche casi limite come volti piccoli, oscurati o coperti.
Fortemente consigliato per la versione CPU.
Se non impostato, di default il programma tiene l'upsample disabilitato.

----- <LEGENDA> -----------------------------------------------------------------------------------------------
[ ]		indica che il parametro è opzionale
/		indica che per impostare quel parametro puoi usare una delle due scritture
IMAGES		è il percorso della cartella contenente le immagini da elaborare e da codificare
OUT		è il percorso della cartella o del file di output contenente gli encodings in formato .pkl
LOG		è il percorso della cartella o del file di output contenente i log dell'esecuzione .txt
MIN		è il valore minimo in pixel dei volti da considerare
DATETIME	è la data nel formato "yyyyMMdd_hhmmss" in cui è stato generato il file



===== [ESEGUIRE FACE_MATCHER] =================================================================================

Avvia il terminale nella cartella del programma e lancia il comando

face_matcher [-h/--help] -i IMAGE/--image IMAGE -e ENCODINGS/--encodings ENCODINGS [-o OUT/--out OUT] [-l LOG/--log LOG] [-t/--tollerance TOL]

----- <DESCRIZIONE> -------------------------------------------------------------------------------------------
--help		mostra la guida del programma

--image		imposta il percorso da cui leggere il volto di cui fare il match

--encodings	imposta il percorso da cui leggere gli encodings con cui eseguire il match

--out		imposta il percorso in cui generare il file dei risultati .csv

Il programma accetta sia il percorso di un file da creare (es. "./output/gara2/result_gara2.csv"),
sia quello di una cartella (es. "./output/gara2/") in cui verrà generato un file default "result_DATETIME.csv".
Tutte le sottocartelle presenti nel percorso, se non esistenti, verranno create.
Se non impostato, di default il programma genererà il file al percorso "./output/result_DATETIME.csv".

--log		imposta il percorso in cui generare il file di log .txt

Il programma accetta sia il percorso di un file da creare (es. "./output/gara2/matcher_log_gara2.txt"),
sia quello di una cartella (es. "./output/gara2/") in cui verrà generato un file default "matcher_log_DATETIME.txt".
Tutte le sottocartelle presenti nel percorso, se non esistenti, verranno create.
Se non impostato, di default il programma genererà il file al percorso "./output/matcher_log_DATETIME.txt".

--tollerance	imposta il valore di tolleranza con cui eseguire il match

Il valore è vincolato tra due estremi (0.35, 0.75) per impedire di utilizzare una tolleranza priva di senso.
Una tolleranza più bassa aumenterà la restrittività del match e darà risultati più sicuri a scapito della quantità,
mentre una tolleranza più alta aumenterà la permissività del match permettendo di riconoscere più facilmente casi limite
come volti piccoli, oscurati o coperti a scapito però della precisione.
Se non impostato, di default il programma utilizza una tolleranza di 0.5.

----- <LEGENDA> -----------------------------------------------------------------------------------------------
[ ]		indica che il parametro è opzionale
/		indica che per impostare quel parametro puoi usare una delle due scritture
IMAGE		è il percorso dell'immagine contenente il volto di cui fare il match
ENCODINGS	è il percorso del file .pkl che contiene gli encodings delle foto con cui eseguire il match
OUT		è il percorso della cartella o del file di output contenente il risultato in formato .csv
LOG		è il percorso della cartella o del file di output contenente i log dell'esecuzione .txt
TOL		è il valore della tolleranza impostato per l'esecuzione del match
DATATIME	è la data nel formato "yyyyMMdd_hhmmss" in cui è stato generato il file
