SXXXXXXX_GeoElevation/doc/Italian-Manual.md

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:

  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
• 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.

---