**Manuale Utente: Elevation Tool**


**1. Introduzione**

Elevation Tool è un'applicazione desktop progettata per ottenere dati di elevazione (altitudine) per specifiche coordinate geografiche (latitudine e longitudine) sulla superficie terrestre. Utilizza i dati DEM (Digital Elevation Model) NASADEM, una versione migliorata dei dati SRTM forniti dalla NASA.

L'applicazione permette di:

*   Ottenere l'elevazione per un singolo punto.
*   Scaricare automaticamente i "tile" (mattonelle) di dati DEM necessari e le relative immagini di anteprima ("browse images") da server remoti.
*   Mantenere una cache locale dei dati scaricati per un accesso offline veloce e per ridurre download ripetuti.
*   Pre-scaricare i dati per un'intera area geografica.
*   Visualizzare le immagini di anteprima dei singoli tile o un mosaico dell'area scaricata.
*   Visualizzare i dati di elevazione di un singolo tile come plot 3D interattivo.

**2. Prerequisiti e Installazione**

Prima di utilizzare l'applicazione, assicurati di avere quanto segue:

*   **Python:** Una versione recente di Python 3 installata sul tuo sistema.
*   **Librerie Python:** Installa le librerie necessarie tramite `pip`:
    ```bash
    pip install requests rasterio Pillow matplotlib numpy netrc opencv-python
    ```
    *   `requests`: Per scaricare dati da internet.
    *   `rasterio`: Per leggere i dati DEM (file HGT).
    *   `Pillow`: Per elaborare le immagini di anteprima.
    *   `matplotlib`: Per visualizzare le immagini 2D e i plot 3D.
    *   `numpy`: Dipendenza fondamentale per `rasterio` e `matplotlib`.
    *   `netrc`: Per gestire l'autenticazione (spesso già presente).
    *   `opencv-python`: (Attualmente non usata nella versione finale, ma potrebbe essere utile per future elaborazioni 2D).
*   **Account NASA Earthdata Login:** I dati NASADEM richiedono un account gratuito. Registrati su: [https://urs.earthdata.nasa.gov/users/new](https://urs.earthdata.nasa.gov/users/new)
*   **File `.netrc` per Autenticazione:** Per permettere all'applicazione di scaricare i dati protetti, devi creare un file chiamato `.netrc` nella tua directory home:
    *   **Posizione:**
        *   Windows: `C:\Users\TuoNomeUtente\.netrc`
        *   Linux/macOS: `/home/tuonomeutente/.netrc` (o `/Users/tuonomeutente/.netrc`)
    *   **Contenuto** (usa un editor di testo semplice):
        ```
        machine urs.earthdata.nasa.gov
        login TUA_USERNAME_EARTHDATA
        password TUA_PASSWORD_EARTHDATA
        ```
        Sostituisci `TUA_USERNAME_EARTHDATA` e `TUA_PASSWORD_EARTHDATA` con le tue credenziali reali.
    *   **Permessi (Linux/macOS):** È cruciale impostare i permessi corretti per sicurezza. Apri un terminale e digita: `chmod 600 ~/.netrc`

**3. Panoramica dell'Interfaccia**

L'applicazione presenta una singola finestra principale divisa in sezioni:

*   **Get Elevation for Point:**
    *   `Latitude`: Campo per inserire la latitudine (gradi decimali, es. 45.0).
    *   `Longitude`: Campo per inserire la longitudine (gradi decimali, es. 7.0).
    *   `Get Elevation` (Pulsante): Avvia la ricerca dell'elevazione per il punto specificato. Scarica i dati necessari (HGT e browse image) se non presenti in cache.
    *   `Result`: Etichetta che mostra l'elevazione trovata (in metri), un messaggio di "nodata" o un errore.
    *   `Show Browse Image (2D)` (Pulsante): (Abilitato dopo successo) Apre una finestra separata (usando Matplotlib) mostrando l'immagine di anteprima del tile contenente il punto, con nome e fonte sovraimpressi. Permette zoom e pan.
    *   `Show DEM Tile (3D)` (Pulsante): (Abilitato dopo successo) Apre una finestra separata (usando Matplotlib) mostrando un plot 3D interattivo dei dati di elevazione del tile contenente il punto. Permette rotazione, zoom e pan.
*   **Pre-Download Tiles for Area:**
    *   `Min Lat`, `Max Lat`, `Min Lon`, `Max Lon`: Campi per definire i limiti di un'area rettangolare da scaricare.
    *   `Download Area Tiles` (Pulsante): Avvia il download (in background) di tutti i dati HGT (estratti) e delle immagini browse per tutti i tile che intersecano l'area specificata.
    *   `Show Area Browse Images (2D)` (Pulsante): (Abilitato dopo successo download area) Apre una finestra separata (usando Matplotlib) mostrando un mosaico delle immagini di anteprima dei tile dell'area scaricata, con una griglia rossa e il nome di ogni tile. Permette zoom e pan.
    *   `Status`: Etichetta che mostra lo stato del download dell'area (Idle, Downloading, Complete, Error).

**4. Funzionalità Dettagliate**

*   **Ottenere Elevazione (Get Elevation):**
    1.  Inserisci Latitudine e Longitudine valide.
    2.  Clicca "Get Elevation".
    3.  L'applicazione determina il tile DEM 1x1 grado necessario.
    4.  Controlla se il file HGT estratto esiste nella cache locale (`elevation_cache/hgt_tiles/`).
    5.  **Se non esiste:**
        *   Si connette al server NASA usando le credenziali `.netrc`.
        *   Scarica il file `.zip` contenente i dati HGT.
        *   Estrae il file `.hgt` nella cache locale (`hgt_tiles`).
        *   Tenta di scaricare l'immagine browse `.jpg` pubblica nella cache locale (`browse_images`).
    6.  **Se esiste (o dopo download):**
        *   Apre il file `.hgt` locale.
        *   Legge il valore di elevazione per le coordinate esatte.
        *   Mostra il risultato nell'etichetta "Result".
        *   Abilita i pulsanti "Show Browse Image (2D)" e "Show DEM Tile (3D)".
*   **Scaricare Area (Download Area Tiles):**
    1.  Inserisci i limiti geografici dell'area.
    2.  Clicca "Download Area Tiles".
    3.  L'applicazione calcola quali tile 1x1 grado sono necessari.
    4.  Per ogni tile necessario:
        *   Controlla se il file HGT estratto esiste già in cache.
        *   Se non esiste, esegue i passi 5a-5c di "Ottenere Elevazione".
        *   Indipendentemente dal fatto che l'HGT esistesse già, controlla se l'immagine browse esiste in cache e tenta di scaricarla se manca.
    5.  L'operazione avviene in background per non bloccare l'interfaccia. Lo stato è mostrato nell'etichetta "Status".
    6.  Al termine, un messaggio riassume quanti tile sono stati processati e quanti file HGT sono stati effettivamente scaricati/estratti. Il pulsante "Show Area Browse Images (2D)" viene abilitato.
*   **Visualizzazione 2D (Browse Image - Singolo Tile):**
    1.  Ottieni l'elevazione per un punto con successo.
    2.  Clicca "Show Browse Image (2D)".
    3.  L'applicazione cerca l'immagine browse corrispondente nella cache (`browse_images`).
    4.  Se trovata, carica l'immagine, aggiunge il nome del tile e la fonte come overlay.
    5.  Mostra l'immagine in una nuova finestra Matplotlib interattiva.
*   **Visualizzazione 3D (DEM Tile):**
    1.  Ottieni l'elevazione per un punto con successo.
    2.  Clicca "Show DEM Tile (3D)".
    3.  L'applicazione cerca il file HGT corrispondente nella cache (`hgt_tiles`).
    4.  Se trovato, legge i dati di elevazione come array NumPy.
    5.  Genera un plot 3D della superficie usando Matplotlib (con sottocampionamento per performance).
    6.  Mostra il plot in una nuova finestra Matplotlib interattiva.
*   **Visualizzazione 2D (Area - Mosaico Browse):**
    1.  Scarica un'area con successo usando "Download Area Tiles".
    2.  Clicca "Show Area Browse Images (2D)".
    3.  L'applicazione cerca tutte le immagini browse corrispondenti ai tile dell'area richiesta nella cache (`browse_images`).
    4.  Carica le immagini trovate.
    5.  Crea un'immagine composita "cucendo" insieme le immagini disponibili (usa placeholder grigi se un'immagine manca).
    6.  Disegna una griglia rossa per separare i tile e aggiunge l'etichetta con il nome a ciascun tile.
    7.  Mostra l'immagine composita in una nuova finestra Matplotlib interattiva.

**5. Casi d'Uso Comuni**

*   **Trovare l'Altitudine di un Luogo Specifico:**
    1.  Avvia l'applicazione.
    2.  Inserisci la latitudine e la longitudine del luogo nei campi appositi.
    3.  Clicca "Get Elevation".
    4.  Leggi il risultato nell'etichetta "Result". Il primo accesso potrebbe richiedere qualche secondo per il download.
    5.  (Opzionale) Clicca "Show Browse Image (2D)" per vedere l'aspetto generale dell'area dal satellite/radar.
    6.  (Opzionale) Clicca "Show DEM Tile (3D)" per esplorare il rilievo del terreno in 3D.
*   **Verificare l'Elevazione Offline (Dati Già Scaricati):**
    1.  Avvia l'applicazione.
    2.  Inserisci latitudine e longitudine di un punto all'interno di un'area i cui dati sono già stati scaricati (nella cache `elevation_cache`).
    3.  Clicca "Get Elevation".
    4.  Il risultato apparirà quasi istantaneamente perché i dati vengono letti localmente.
*   **Preparare Dati per un'Area Prima di Andare Offline:**
    1.  Avvia l'applicazione (con connessione internet attiva).
    2.  Identifica i limiti (min/max lat/lon) dell'area di interesse.
    3.  Inserisci questi limiti nella sezione "Pre-Download Tiles for Area".
    4.  Clicca "Download Area Tiles".
    5.  Attendi il completamento (monitora l'etichetta "Status" e la console per i log). Potrebbe richiedere tempo a seconda della dimensione dell'area e della velocità di connessione.
    6.  (Opzionale) Clicca "Show Area Browse Images (2D)" per confermare visivamente quali tile sono stati scaricati.
    7.  Ora puoi usare l'applicazione offline per ottenere elevazioni rapide per qualsiasi punto all'interno dell'area scaricata.
*   **Esplorare Visivamente un Singolo Tile:**
    1.  Inserisci le coordinate di un punto qualsiasi all'interno del tile che ti interessa.
    2.  Clicca "Get Elevation" (anche se conosci già l'elevazione, questo assicura che il tile sia disponibile e i pulsanti si attivino).
    3.  Clicca "Show Browse Image (2D)" o "Show DEM Tile (3D)".
*   **Ottenere una Visione d'Insieme di un'Area:**
    1.  Assicurati di aver già scaricato l'area desiderata usando "Download Area Tiles".
    2.  Clicca "Show Area Browse Images (2D)".
    3.  Esplora l'immagine composita usando gli strumenti di zoom/pan di Matplotlib per vedere la disposizione dei tile e l'aspetto generale della regione.

**6. Note e Risoluzione Problemi**

*   **Errori di Download:**
    *   **401/403 (Unauthorized/Forbidden):** Problema con le credenziali Earthdata Login nel file `.netrc`. Verifica username, password e il nome `machine urs.earthdata.nasa.gov`.
    *   **404 (Not Found):** Il file richiesto (HGT zip o browse jpg) non esiste all'URL specificato. Potrebbe indicare una lacuna nei dati NASA per quell'area o un problema nella costruzione dell'URL (controlla le costanti URL nel codice `elevation_manager.py`).
    *   **Errori di Rete/Timeout:** Problemi temporanei di connessione. Lo script tenta un breve retry, ma errori persistenti richiedono una connessione stabile.
*   **File `.netrc`:** Assicurati che sia nella directory corretta e che i permessi siano restrittivi (Linux/macOS).
*   **Dipendenze Mancanti:** Se mancano librerie (Rasterio, Pillow, Matplotlib), l'applicazione mostrerà messaggi di avviso all'avvio e/o errori quando tenti di usare le funzionalità associate. Installa le librerie mancanti con `pip`.
*   **Performance 3D:** Il rendering 3D di un tile completo può essere intensivo. Il sottocampionamento (`subsample`) aiuta, ma per aree molto complesse potrebbe comunque essere lento.
*   **Finestre Bloccanti:** Le finestre di visualizzazione Matplotlib (sia 2D che 3D) sono eseguite in processi separati per non bloccare la GUI principale, ma la finestra Matplotlib stessa attenderà la chiusura da parte dell'utente.
*   **Log:** Controlla sempre l'output nella console/terminale da cui hai avviato l'applicazione per messaggi di log dettagliati, specialmente in caso di errori.