**Manuale Utente: GeoElevation Tool (Italiano - Aggiornato)**

**1. Introduzione**

GeoElevation 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 (visualizzazioni statiche).
*   Visualizzare i dati di elevazione di un singolo tile come plot 3D interattivo (visualizzazione statica).
*   **Esplorare dati di elevazione e mappe tiled interattivamente tramite un visualizzatore mappa dedicato, con funzionalità di pan e zoom.**

**2. Prerequisiti e Installazione**

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

*   **Python:** Una versione recente di Python 3.8 o superiore installata sul tuo sistema.
*   **Librerie Python:** Installa le librerie necessarie tramite `pip`. Per l'esperienza completa con il visualizzatore mappa e le visualizzazioni avanzate, raccomandiamo di installare tutte le seguenti:
    ```bash
    pip install requests rasterio Pillow matplotlib numpy netrc opencv-python mercantile pyproj scipy
    ```
    *   `requests`: Per scaricare dati da internet (richiesto).
    *   `rasterio`: Per leggere i dati DEM (file HGT) (richiesto per funzionalità elevazione).
    *   `Pillow` (PIL): Per elaborare immagini (browse, compositi) e disegnare overlay (richiesto per visualizzazioni immagine e map viewer).
    *   `matplotlib`: Per visualizzare immagini 2D e plot 3D (richiesto per visualizzazioni statiche).
    *   `numpy`: Dipendenza fondamentale per `rasterio`, `matplotlib`, `scipy` e `opencv-python` (richiesto).
    *   `netrc`: Per gestire l'autenticazione Earthdata (spesso già presente, richiesto per download NASADEM protetti).
    *   `opencv-python`: Per la gestione della finestra e degli eventi mouse del visualizzatore mappa interattivo (richiesto per il map viewer).
    *   `mercantile`: Per i calcoli sui tile mappa Web Mercator (richiesto per il map viewer).
    *   `pyproj`: Per calcoli geodetici (bounding boxes, distanze) (richiesto per alcune funzioni map viewer e utili come deg<->dms).
    *   `scipy`: Per funzionalità avanzate nei plot 3D (smoothing/interpolazione) (opzionale per visualizzazioni 3D).
*   **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 Grafica (GUI)**

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 Get Elevation) Apre una finestra Matplotlib separata con l'immagine di anteprima del tile DEM contenente il punto.
    *   `Show DEM Tile (3D)` (Pulsante): (Abilitato dopo successo Get Elevation) Apre una finestra Matplotlib separata con un plot 3D interattivo dei dati DEM del tile.
    *   `View Point on Map` (Pulsante): (Abilitato dopo successo Get Elevation, richiede librerie Map Viewer) Apre o porta in primo piano la finestra del visualizzatore mappa interattivo, centrata sul punto specificato con uno zoom automatico per mostrare il tile DEM circostante.
*   **Pre-Download Tiles for Area:**
    *   `Min Lat`, `Max Lat`, `Min Lon`, `Max Lon`: Campi per definire i limiti di un'area rettangolare.
    *   `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 Composite (2D)` (Pulsante): (Abilitato dopo successo Download Area Tiles e se sono disponibili immagini browse) Apre una finestra Matplotlib separata con un mosaico delle immagini di anteprima dei tile scaricati, con una griglia e etichette.
    *   `View Area on Map` (Pulsante): (Abilitato dopo successo Download Area Tiles, richiede librerie Map Viewer) Apre o porta in primo piano la finestra del visualizzatore mappa interattivo, mostrando l'area coperta dai tile DEM scaricati.
    *   `Status`: Etichetta che mostra lo stato del download dell'area.
*   **Map Display Options:** (Visibile solo se le librerie del Map Viewer sono disponibili)
    *   `Map Display Scale`: Combobox per selezionare un fattore di scala per l'immagine della mappa visualizzata nella finestra interattiva. Questo cambia la dimensione della finestra.
*   **Map Info:** (Visibile solo se le librerie del Map Viewer sono disponibili)
    *   Questa sezione mostra informazioni relative al punto cliccato sulla mappa interattiva o all'area visualizzata.
    *   `Latitude (Dec)`: Latitudine del punto cliccato in gradi decimali (copiabile).
    *   `Longitude (Dec)`: Longitudine del punto cliccato in gradi decimali (copiabile).
    *   `Latitude (DMS)`: Latitudine del punto cliccato in formato Gradi, Minuti, Secondi (copiabile).
    *   `Longitude (DMS)`: Longitudine del punto cliccato in formato Gradi, Minuti, Secondi (copiabile).
    *   `Elevation`: Elevazione stimata nel punto cliccato sulla mappa (in metri, "NoData", "Unavailable", o stato di fetch) (copiabile).
    *   `Map Area Size`: Dimensioni approssimative (Larghezza x Altezza in km) dell'area geografica visualizzata nella finestra mappa interattiva, con indicato il livello di zoom corrente (copiabile).
*   **Finestra Visualizzatore Mappa Interattivo:**
    *   Si apre quando si clicca su "View Point on Map" o "View Area on Map".
    *   Mostra mappe tiled (come OpenStreetMap) con potenziali overlay (bordi tile DEM, marker click).
    *   **Schermata "Map Loading":** Una piccola finestra di progresso appare e scompare automaticamente sopra la GUI principale durante il caricamento o l'aggiornamento dei tile nella finestra mappa.

**4. Funzionalità Dettagliate**

*   **Ottenere Elevazione (Get Elevation):** (Descrizione esistente invariata - si riferisce all'input manuale e al risultato nell'etichetta "Result")
*   **Scaricare Area (Download Area Tiles):** (Descrizione esistente invariata - si riferisce al download dei dati DEM HGT/browse nella cache)
*   **Visualizzazioni Statiche (Show Browse Image, Show DEM Tile, Show Area Composite):** (Descrizioni esistenti invariate - si riferiscono alle finestre Matplotlib non interattive per pan/zoom con strumenti standard di Matplotlib)
*   **Visualizzatore Mappa Interattivo (View on Map buttons):**
    *   Attiva una finestra separata (basata su OpenCV) che visualizza mappe online.
    *   Quando aperto tramite "View Point on Map", la mappa è centrata sul punto e zoomata automaticamente per mostrare il tile DEM corrispondente (con un leggero buffer). Il bordo del tile DEM HGT è disegnato in rosso.
    *   Quando aperto tramite "View Area on Map", la mappa mostra l'intera estensione combinata di tutti i tile DEM disponibili (nella cache) per l'area definita. Il bordo dell'area richiesta (secondo i limiti inseriti) è disegnato in blu, e i bordi dei singoli tile DEM HGT disponibili sono disegnati in rosso con le loro etichette.
    *   La finestra mappa risponde agli eventi mouse:
        *   **Click Sinistro (Standard):**
            1.  Identifica le coordinate geografiche del punto cliccato.
            2.  Richiede all'ElevationManager l'elevazione per quel punto.
            3.  Aggiorna i campi "Map Info" nella GUI principale con le coordinate (Decimali e DMS), l'elevazione trovata ("NoData", "Unavailable", o valore in metri), e la dimensione dell'area visualizzata.
            4.  Disegna un marker sulla mappa nel punto cliccato.
            5.  Durante il fetch dell'elevazione (che potrebbe richiedere download), la schermata "Map Loading" potrebbe apparire brevemente.
        *   **Ctrl + Click Sinistro (Pan):**
            1.  Identifica le coordinate geografiche del punto cliccato.
            2.  Aggiorna la vista mappa in modo che il punto cliccato diventi il nuovo centro.
            3.  **Il livello di zoom corrente viene mantenuto.**
            4.  Vengono fetched e stitched i nuovi tile mappa necessari per la nuova area centrata.
            5.  Aggiorna i campi "Map Info" (nuovo centro, elevazione N/A, dimensione area visualizzata e zoom).
            6.  Durante il fetch/stitching, appare la schermata "Map Loading".
        *   **Click Destro (Zoom Out + Recenter):**
            1.  Identifica le coordinate geografiche del punto cliccato.
            2.  Aggiorna la vista mappa in modo che il punto cliccato diventi il nuovo centro.
            3.  **Diminuisce il livello di zoom di 1** (con limite minimo a zoom 0).
            4.  Vengono fetched e stitched i nuovi tile mappa necessari per la nuova area e il nuovo zoom.
            5.  Aggiorna i campi "Map Info" (nuovo centro, elevazione N/A, dimensione area visualizzata e zoom).
            6.  Durante il fetch/stitching, appare la schermata "Map Loading".
        *   **Shift + Click Sinistro (Zoom In + Recenter):**
            1.  Identifica le coordinate geografiche del punto cliccato.
            2.  Aggiorna la vista mappa in modo che il punto cliccato diventi il nuovo centro.
            3.  **Aumenta il livello di zoom di 1** (con limite massimo al zoom supportato dal servizio mappa, es. 19 per OSM).
            4.  Vengono fetched e stitched i nuovi tile mappa necessari per la nuova area e il nuovo zoom.
            5.  Aggiorna i campi "Map Info" (nuovo centro, elevazione N/A, dimensione area visualizzata e zoom).
            6.  Durante il fetch/stitching, appare la schermata "Map Loading".

**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". Leggi il risultato nell'etichetta "Result". (Questo garantisce che il tile DEM sia disponibile e attiva i pulsanti).
    4.  Clicca "View Point on Map". Si aprirà la finestra mappa interattiva centrata sul punto.
    5.  (Opzionale) Clicca su un punto qualsiasi della mappa per ottenere l'elevazione precisa in quel punto e vedere le coordinate e l'elevazione aggiornarsi nel pannello "Map Info". Un marker rosso apparirà nel punto cliccato.
*   **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 DEM sono già stati scaricati (nella cache `geoelevation_dem_cache`).
    3.  Clicca "Get Elevation". Il risultato apparirà quasi istantaneamente perché i dati HGT vengono letti localmente.
    4.  Clicca "View Point on Map". La mappa si caricherà utilizzando i tile mappa OpenStreetMap dalla cache locale (se disponibili) o scaricandoli se online, ma l'elevazione per il punto cliccato (passo 5 del caso d'uso precedente) sarà rapida se il DEM è in cache.
*   **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". Attendi il completamento (monitora l'etichetta "Status" e la console).
    5.  Ora puoi usare l'applicazione offline per ottenere elevazioni rapide per qualsiasi punto all'interno dell'area DEM scaricata e visualizzare l'area in "View Area on Map" (la mappa tiled potrebbe non caricarsi offline se i suoi tile non sono in cache, ma i bordi DEM appariranno).
*   **Esplorare Visivamente un'Area sulla Mappa Interattiva:**
    1.  Assicurati di aver già scaricato l'area desiderata usando "Download Area Tiles".
    2.  Clicca "View Area on Map". Si aprirà la finestra mappa interattiva mostrando l'area dei tile DEM scaricati. Vedrai i bordi dell'area richiesta (blu) e i bordi dei singoli tile DEM disponibili (rossi con etichette).
    3.  Usa **Ctrl + Click Sinistro** per spostarti (pan) sulla mappa mantenendo lo zoom.
    4.  Usa **Shift + Click Sinistro** per zoommare IN e ricentrare su un punto.
    5.  Usa **Click Destro** per zoommare OUT e ricentrare su un punto.
    6.  Clicca Sinistro standard su un punto per ottenere l'elevazione e vedere le info nel pannello "Map Info".

**6. Note e Risoluzione Problemi**

*   **Errori di Download:** (Descrizione esistente invariata)
*   **File `.netrc`:** (Descrizione esistente invariata)
*   **Dipendenze Mancanti:** Se mancano librerie cruciali per il visualizzatore mappa (Pillow, OpenCV, Mercantile, Pyproj), i pulsanti "View on Map" saranno disabilitati e/o appariranno messaggi di errore all'avvio. Se mancano librerie per le visualizzazioni statiche (Matplotlib, SciPy, Pillow), i relativi pulsanti "Show..." saranno disabilitati. Installa le librerie mancanti con `pip`.
*   **Performance:**
    *   Il download di aree molto grandi può richiedere tempo.
    *   Il rendering 3D di un tile completo può essere intensivo.
    *   Il fetch e lo stitching di un gran numero di tile mappa per la visualizzazione interattiva (a livelli di zoom bassi o per aree estese) può richiedere tempo e memoria; la schermata "Map Loading" apparirà in questi casi.
*   **Finestre Sepate:** Le finestre di visualizzazione (sia Matplotlib statiche che OpenCV interattiva) sono eseguite in processi separati per non bloccare la GUI principale. Potrebbero apparire in posizioni inaspettate sul tuo desktop.
*   **Finestra "Map Loading":** Questa finestra è impostata per rimanere sempre in primo piano per garantire che tu la veda. Selezionando la finestra principale della GUI o la finestra mappa non la nasconderà. Su alcuni sistemi operativi o gestori di finestre, il comportamento "always on top" potrebbe variare leggermente.
*   **Log:** Controlla sempre l'output nella console/terminale da cui hai avviato l'applicazione per messaggi di log dettagliati.

---