CALIA VULKAN UPSCALER — BETA 3.0
================================

Guida di installazione e utilizzo per Linux x86-64.

CHE COS'È
---------
Calia Vulkan Upscaler è un'interfaccia grafica per l'upscaling locale di immagini
tramite Real-ESRGAN NCNN/Vulkan.

Le immagini vengono elaborate sul computer dell'utente. L'app non le invia
automaticamente a servizi cloud.

AVVIO RAPIDO — UBUNTU / DEBIAN
------------------------------
Metodo consigliato: installare il pacchetto .deb fornito insieme a questa release.

1. Fare doppio clic sul file:
   calia-vulkan-upscaler_0.3.0-beta_amd64.deb

2. Aprirlo con il gestore applicazioni/pacchetti della propria distribuzione.

3. Installare il pacchetto.

4. Cercare nel menu applicazioni:
   Calia Vulkan Upscaler

In alternativa da terminale:
   sudo apt install ./calia-vulkan-upscaler_0.3.0-beta_amd64.deb

Il gestore pacchetti installerà anche le dipendenze dichiarate disponibili nei
repository della distribuzione.

AVVIO RAPIDO — PACCHETTO PORTABILE
----------------------------------
1. Estrarre l'archivio:
   Calia-Vulkan-Upscaler-Beta-3.0-Linux-x86_64.tar.xz

2. Entrare nella cartella estratta.

3. Eseguire:
   ./VERIFICA_SISTEMA.sh

4. Se il controllo è positivo, eseguire:
   ./AVVIA.sh

Requisiti del pacchetto portabile:
- Linux x86-64
- Python 3
- Tkinter per Python 3
- Vulkan loader e driver Vulkan funzionanti
- xdg-open consigliato per il pulsante "Apri risultati"

Su Ubuntu/Debian, se mancano le dipendenze:
   sudo apt update
   sudo apt install python3 python3-tk libvulkan1 libgomp1 xdg-utils vulkan-tools

REQUISITI GRAFICI
-----------------
È necessaria una GPU o un dispositivo grafico con supporto Vulkan e driver
correttamente installati.

Sono normalmente utilizzabili GPU AMD, NVIDIA o Intel compatibili con Vulkan.
Le prestazioni dipendono dalla GPU, dalla memoria video, dai driver e dalla
dimensione delle immagini.

Controllo facoltativo:
   vulkaninfo --summary

Se compare soltanto "llvmpipe", Vulkan sta usando un renderer software sulla CPU:
il programma può risultare molto lento.

COSA NON SERVE
--------------
Per il motore NCNN/Vulkan NON servono:
- PyTorch
- CUDA
- ambiente virtuale Python per Real-ESRGAN
- repository Python completo di Real-ESRGAN

Il pacchetto contiene già:
- realesrgan-ncnn-vulkan
- modelli NCNN necessari
- interfaccia Calia Vulkan Upscaler

NOTA: la versione portabile usa Python/Tkinter del sistema. Il pacchetto .deb
dichiara queste dipendenze. Una futura AppImage realmente autosufficiente dovrà
includere anche il runtime Python/Tkinter.

GUIDA RAPIDA ALL'APP
--------------------
1. Premere "Apri immagine" per un singolo file oppure "Apri cartella" per un gruppo.

2. Scegliere:
   - Modello
   - Ingrandimento 2x, 3x o 4x
   - Formato PNG, JPG o WEBP

3. Per l'uso normale:
   - Tile = 0
   - TTA = disattivato

4. Premere "Avvia upscaling".

5. Attendere il completamento.

6. Premere "Apri risultati".

I pulsanti "?" nell'interfaccia spiegano le principali opzioni.

MODELLI
-------
Foto / immagini reali:
   realesrgan-x4plus

È il modello consigliato per fotografie, scansioni, frame video e immagini
realistiche.

Anime / illustrazioni:
   realesrgan-x4plus-anime

È disponibile per illustrazioni e linee grafiche. Non è necessario per le foto.

INGRANDIMENTO
-------------
2x = larghezza e altezza raddoppiate
3x = larghezza e altezza triplicate
4x = larghezza e altezza quadruplicate

Esempio:
800 x 600 a 4x -> 3200 x 2400

Attenzione: un 4x sulle due dimensioni produce 16 volte il numero di pixel.

FORMATO DI USCITA
-----------------
PNG
- senza perdita
- indicato per archiviazione e grafica
- file generalmente più grandi

JPG
- compressione con perdita
- spesso più compatto
- indicato soprattutto per fotografie

WEBP
- buon compromesso tra qualità e dimensioni
- molto adatto al web

TILE
----
Tile controlla la suddivisione dell'immagine in blocchi durante l'elaborazione.

0   = automatico / nessun valore forzato
256 = può ridurre l'uso di memoria video
128 = usa ancora meno memoria, ma può rallentare

Lasciare 0 salvo errori di memoria su immagini molto grandi.

GPU
---
Il numero GPU è l'ID del dispositivo Vulkan.

0 = primo dispositivo
1 = secondo dispositivo
ecc.

Non indica la potenza della GPU. L'ordine dipende dal computer.

Per visualizzare i dispositivi:
   vulkaninfo --summary

Evitare un renderer software come llvmpipe quando è disponibile una vera GPU.

TTA
---
TTA significa Test-Time Augmentation.

Disattivato:
- più veloce
- consigliato per uso normale

Attivato:
- elabora più trasformazioni della stessa immagine
- può migliorare leggermente alcuni dettagli
- può richiedere molto più tempo

TTA non addestra il modello.

BARRA DI AVANZAMENTO
--------------------
Singola immagine:
Il motore NCNN non fornisce una percentuale interna affidabile. L'app mostra
quindi una barra animata "in corso" senza inventare una percentuale.

Cartella:
La percentuale è calcolata sui file completati, ad esempio 7/20 = 35%.

PRIVACY
-------
L'elaborazione è locale:
immagine -> computer dell'utente -> GPU Vulkan -> risultato

L'applicazione non richiede automaticamente un account online e non invia
automaticamente le immagini a un server esterno.

LIMITI DELL'UPSCALING
---------------------
L'upscaling non recupera magicamente informazioni assenti nell'originale.

Real-ESRGAN genera dettagli plausibili sulla base dell'immagine disponibile.
Un risultato più definito non equivale necessariamente alla ricostruzione esatta
di una fotografia originale ad alta risoluzione.

TESTO NELLE IMMAGINI
--------------------
Real-ESRGAN non è un OCR e non è un correttore ortografico.

Se una scritta nell'immagine originale è molto piccola, deformata o errata,
l'upscaler può renderla più grande, ma non garantisce che diventi testo corretto.

RISOLUZIONE DEI PROBLEMI
------------------------
1. L'app non parte
   Eseguire:
      ./VERIFICA_SISTEMA.sh

2. Python manca
   Ubuntu/Debian:
      sudo apt install python3

3. Tkinter manca
   Ubuntu/Debian:
      sudo apt install python3-tk

4. Vulkan manca
   Ubuntu/Debian:
      sudo apt install libvulkan1 vulkan-tools

   Verificare poi:
      vulkaninfo --summary

5. L'elaborazione è molto lenta
   Controllare che non venga usato llvmpipe e che sia selezionata una GPU Vulkan
   hardware.

6. Errore di memoria
   Provare Tile = 256.
   Se necessario, Tile = 128.

7. "Apri risultati" non funziona
   Ubuntu/Debian:
      sudo apt install xdg-utils

DIAGNOSTICA
-----------
Eseguire:
   ./VERIFICA_SISTEMA.sh

Il controllo mostra:
- architettura
- Python
- Tkinter
- Vulkan loader
- vulkaninfo, se presente
- disponibilità del motore
- disponibilità dei modelli
- librerie dinamiche mancanti

DISINSTALLAZIONE
----------------
Pacchetto .deb:
   sudo apt remove calia-vulkan-upscaler

Il programma non elimina automaticamente le immagini elaborate dall'utente.

LICENZE E COMPONENTI OPEN SOURCE
--------------------------------
Consultare la cartella:
   LICENSES/

Calia Vulkan Upscaler è un'interfaccia separata e non è il progetto originale
Real-ESRGAN.

Motore:
- Real-ESRGAN
- ncnn / Vulkan

Prima di una distribuzione pubblica definitiva è raccomandato verificare i
license notice della precisa versione binaria inclusa.

SUPPORTO / VERSIONE
-------------------
Consultare VERSION.txt quando si segnala un problema.

Nome versione:
Calia Vulkan Upscaler — Beta 3.0
