GeoElevation Tool

(English Presentation Below)

IT | EN

GeoElevation Tool è un'applicazione versatile e una libreria Python progettata per interagire con i dati di elevazione digitale del terreno (DEM), principalmente utilizzando i dataset NASADEM HGT. Offre un'interfaccia grafica (GUI) completa per un facile utilizzo interattivo, un'interfaccia a riga di comando (CLI) per interrogazioni rapide e un'API di libreria per l'integrazione in altri progetti Python.

Permette agli utenti di:

• Ottenere l'Elevazione Puntuale: Sia tramite GUI, CLI o API, inserendo coordinate geografiche (latitudine e longitudine) per recuperare l'elevazione di un punto specifico.
• Scaricare Aree DEM (via GUI): Definire un'area geografica per scaricare automaticamente tutti i tile NASADEM HGT necessari.
• Visualizzare Dati DEM (via GUI):
  • Mostrare un'immagine di anteprima del tile DEM.
  • Generare e visualizzare una rappresentazione 3D interattiva del tile DEM, con opzioni per lo smoothing e l'interpolazione.
  • Creare e mostrare un'immagine composita delle anteprime per un'area definita.
• Esplorare Mappe e Dati di Elevazione Interattivamente (via GUI): Utilizzare un visualizzatore mappa dedicato per navigare mappe online, ottenere elevazioni al click e visualizzare overlay informativi sui tile DEM.

Lo strumento gestisce l'autenticazione con NASA Earthdata Login (tramite file .netrc), il download dei dati, l'estrazione e la conversione. Per informazioni dettagliate sull'utilizzo come libreria o da riga di comando, consultare le sezioni "Utilizzo da Riga di Comando" e "Utilizzo come Libreria Python".

Caratteristiche Principali

• Interfaccia utente grafica (GUI) intuitiva basata su Tkinter.
• Interfaccia a riga di comando (CLI) per il recupero rapido dell'elevazione puntuale.
• API Python per l'integrazione come libreria in altre applicazioni.
• Recupero dell'elevazione per coordinate specifiche.
• Download automatico e caching dei tile NASADEM HGT e delle immagini browse.
• Visualizzazione 2D di immagini di anteprima singole o composite (GUI).
• Visualizzazione 3D interattiva dei dati di elevazione DEM (GUI).
• Visualizzatore mappa interattivo integrato per l'esplorazione geografica.
• Funzionalità interattive sulla mappa:
  • Click Sinistro (Standard): Ottiene e mostra coordinate ed elevazione nel punto cliccato, disegna un marker.
  • Ctrl + Click Sinistro (Pan): Sposta la mappa centrata sul punto cliccato mantenendo il livello di zoom attuale.
  • Shift + Click Sinistro (Zoom In): Centra la mappa sul punto cliccato e aumenta il livello di zoom.
  • Click Destro (Zoom Out): Centra la mappa sul punto cliccato e diminuisce il livello di zoom.
• Pannello informativo in tempo reale nella GUI con coordinate del click (Decimali e DMS), elevazione e dettagli sull'area mappa visualizzata (dimensione, zoom).
• Indicatore visibile di caricamento ("Map Loading" screen) durante il fetch e lo stitching dei tile mappa.
• Gestione delle dipendenze opzionali (ad es. Map Viewer richiede OpenCV, Mercantile, Pyproj).

Requisiti

• Python 3.8+
• Tkinter (solitamente incluso con Python)
• Requests
• NumPy
• Matplotlib
• Pillow (PIL Fork)
• Rasterio (per la lettura dei file HGT)
• SciPy (per lo smoothing e l'interpolazione nella visualizzazione 3D)
• OpenCV-Python (per il visualizzatore mappa interattivo)
• Mercantile (per i calcoli sui tile mappa Web Mercator nel visualizzatore)
• Pyproj (per i calcoli geografici nel visualizzatore e utility come deg<->dms)

L'installazione di OpenCV-Python, Mercantile e Pyproj è necessaria per abilitare la funzionalità completa del visualizzatore mappa interattivo. Se non installati, la GUI si avvierà ma i pulsanti e le sezioni correlate alla mappa saranno disabilitati.

È necessario configurare un file .netrc nella propria directory home con le credenziali per urs.earthdata.nasa.gov per scaricare i dati DEM protetti.

Installazione

(Aggiungere istruzioni specifiche per l'installazione del pacchetto se pubblicato, o basate su requirements.txt e cloni GitHub.)

# Esempio ipotetico se pubblicato su PyPI con tutti gli extra
pip install geoelevation[full]

Utilizzo

Avvio dell'Interfaccia Grafica (GUI)

Per avviare l'interfaccia grafica, eseguire il modulo dalla directory principale del progetto (la cartella che contiene geoelevation/):

python -m geoelevation

Oppure, se è stato installato come pacchetto:

geoelevation_gui # (o il nome dell'entry point script se definito in setup.py)

L'applicazione si avvierà mostrando la finestra principale.

Utilizzo da Riga di Comando (CLI)

È possibile ottenere l'elevazione per un punto specifico direttamente dalla riga di comando:

python -m geoelevation --lat <latitudine> --lon <longitudine> [--show-progress] [--verbose]

Argomenti:

• --lat LATITUDINE: Latitudine del punto (es. 45.0). Richiesto per modalità CLI punto.
• --lon LONGITUDINE: Longitudine del punto (es. 7.0). Richiesto per modalità CLI punto.
• --gui: (Opzionale) Forza l'avvio della GUI anche se sono specificati --lat e --lon.
• --show-progress: (Opzionale) Mostra una semplice finestra di dialogo di avanzamento durante il recupero dei dati (solo per CLI punto).
• --verbose o -v: (Opzionale) Abilita output di logging più dettagliato.
• --help: Mostra il messaggio di aiuto con tutti gli argomenti.

Esempio:

python -m geoelevation --lat 40.7128 --lon -74.0060 --show-progress
```Output atteso:

Elevation: meters

oppure `Elevation: NODATA` o `Elevation: UNAVAILABLE`.

#### Utilizzo come Libreria Python

Il package `geoelevation` può essere importato nei tuoi script Python per recuperare programmaticamente i dati di elevazione.

La funzione principale esposta è `get_point_elevation`:

```python
from geoelevation import get_point_elevation
import logging

# Opzionale: configura il logging per vedere i messaggi da geoelevation
# logging.basicConfig(level=logging.INFO)

latitude = 45.0
longitude = 7.0

try:
    # Recupera l'elevazione, mostrando opzionalmente una finestra di progresso
    elevation = get_point_elevation(
        latitude,
        longitude,
        show_progress_dialog=True,
        progress_dialog_custom_message="Sto cercando l'elevazione per te..." # Messaggio personalizzato
    )

    if elevation is None:
        print(f"Impossibile recuperare l'elevazione per ({latitude}, {longitude}).")
    elif isinstance(elevation, float) and math.isnan(elevation):  # Controllo per NaN (Not a Number)
        print(f"Il punto ({latitude}, {longitude}) si trova su un'area NoData.")
    else:
        print(f"L'elevazione a ({latitude}, {longitude}) è: {elevation:.2f} metri.")

except RuntimeError as e:
    print(f"Errore durante l'inizializzazione della libreria GeoElevation: {e}")
except ValueError as e:
    print(f"Errore di valore nei parametri: {e}")
except Exception as e:
    print(f"Si è verificato un errore imprevisto: {e}")

Dettagli della funzione get_point_elevation:

• get_point_elevation(latitude: float, longitude: float, show_progress_dialog: bool = False, progress_dialog_custom_message: str = "Retrieving elevation data...") -> Optional[float]
  • latitude, longitude: Coordinate geografiche del punto.
  • show_progress_dialog: Se True, mostra una finestra di dialogo non bloccante con indicatore di avanzamento durante il recupero dei dati. Utile se la funzione viene chiamata da un'applicazione con una propria GUI per non sembrare bloccata. Richiede Tkinter.
  • progress_dialog_custom_message: Permette di personalizzare il messaggio visualizzato nella finestra di dialogo di progresso.
  • Restituisce: L'elevazione in metri come float, float('nan') se il punto è un'area NoData, o None se l'elevazione non può essere determinata, i dati sono non disponibili o si verifica un errore.
  • Solleva: RuntimeError se le dipendenze critiche (es. Rasterio) non sono disponibili o se ElevationManager non può essere inizializzato correttamente. ValueError per input di coordinate non validi.

(Aggiungere altre sezioni come Struttura Progetto, Screenshot, Limitazioni, Licenza, Contribuire come suggerito prima)

---

---

GeoElevation Tool

(Italian Presentation Above)

EN | IT

GeoElevation Tool is a versatile Python application and library designed for interacting with digital elevation model (DEM) data, primarily utilizing the NASADEM HGT datasets. It offers a comprehensive Graphical User Interface (GUI) for easy interactive use, a Command Line Interface (CLI) for quick queries, and a library API for integration into other Python projects.

It allows users to:

• Get Point Elevation: Via GUI, CLI, or API, by inputting geographic coordinates (latitude and longitude) to retrieve the elevation of a specific point.
• Download DEM Areas (via GUI): Define a geographical area to automatically download all necessary NASADEM HGT tiles.
• Visualize DEM Data (via GUI):
  • Display a browse image (preview) of the DEM tile.
  • Generate and display an interactive 3D representation of the DEM data, with options for smoothing and interpolation.
  • Create and show a composite browse image for a defined area.
• Explore Maps and Elevation Data Interactively (via GUI): Use a dedicated map viewer to navigate online maps, get elevations on click, and visualize informative overlays on DEM tiles.

The tool handles authentication with NASA Earthdata Login (via a .netrc file), data downloading, extraction, and conversion. For detailed information on using it as a library or from the command line, please refer to the "Command Line Interface (CLI) Usage" and "Using as a Python Library" sections.

Key Features

• Intuitive Tkinter-based Graphical User Interface (GUI).
• Command Line Interface (CLI) for quick point elevation retrieval.
• Python API for integration as a library into other applications.
• Elevation retrieval for specific coordinates.
• Automatic download and caching of NASADEM HGT tiles and browse images.
• 2D visualization of single browse images and composite images (GUI).
• Interactive 3D visualization of DEM elevation data (GUI).
• Integrated interactive map viewer for geographic exploration.
• Interactive map functionalities:
  • Left Click (Standard): Gets and displays coordinates and elevation at the clicked point, draws a marker.
  • Ctrl + Left Click (Pan): Centers the map on the clicked point while maintaining the current zoom level.
  • Shift + Left Click (Zoom In): Centers the map on the clicked point and increases the zoom level.
  • Right Click (Zoom Out): Centers the map on the clicked point and decreases the zoom level.
• Real-time information panel in the GUI with click coordinates (Decimal and DMS), elevation, and details about the displayed map area (size, zoom).
• Visible loading indicator ("Map Loading" screen) during map tile fetching and stitching.
• Handling of optional dependencies (e.g., Map Viewer requires OpenCV, Mercantile, Pyproj).

Requirements

• Python 3.8+
• Tkinter (usually included with Python)
• Requests
• NumPy
• Matplotlib
• Pillow (PIL Fork)
• Rasterio (for reading HGT files)
• SciPy (for smoothing and interpolation in 3D visualization)
• OpenCV-Python (for the interactive map viewer)
• Mercantile (for Web Mercator map tile calculations in the viewer)
• Pyproj (for geographic calculations in the viewer and utilities like deg<->dms)

Installation of OpenCV-Python, Mercantile, and Pyproj is required to enable the full interactive map viewer functionality. If not installed, the GUI will start but related map buttons and sections will be disabled.

A .netrc file in your home directory must be configured with credentials for urs.earthdata.nasa.gov to download protected DEM data.

Installation

(Add specific instructions for package installation if published, or based on requirements.txt and GitHub clones.)

# Hypothetical example if published on PyPI with all extras
pip install geoelevation[full]

Usage

Launching the Graphical User Interface (GUI)

To start the GUI, run the module from the project's root directory (the folder containing the geoelevation/ directory):

python -m geoelevation

Alternatively, if installed as a package:

geoelevation_gui # (or the entry point script name if defined in setup.py)

The application window will open.

Command Line Interface (CLI) Usage

You can get the elevation for a specific point directly from the command line:

python -m geoelevation --lat <latitude> --lon <longitude> [--show-progress] [--verbose] [--gui]

Arguments:

• --lat LATITUDE: Latitude of the point (e.g., 45.0). Required for point CLI mode.
• --lon LONGITUDE: Longitude of the point (e.g., 7.0). Required for point CLI mode.
• --gui: (Optional) Forces the GUI to launch, overriding --lat and --lon if present.
• --show-progress: (Optional) Displays a simple progress dialog window during data retrieval (point CLI only). Requires Tkinter.
• --verbose or -v: (Optional) Enables more detailed logging output.
• --help: Shows the help message with all arguments.

Example:

python -m geoelevation --lat 40.7128 --lon -74.0060 --show-progress

Expected output:

Elevation: <value> meters

or Elevation: NODATA or Elevation: UNAVAILABLE.

Using as a Python Library

The geoelevation package can be imported into your Python scripts to programmatically retrieve elevation data.

The primary function exposed is get_point_elevation:

from geoelevation import get_point_elevation
import logging
import math # Needed for math.isnan

# Optional: configure logging to see messages from geoelevation
# logging.basicConfig(level=logging.INFO)

latitude = 45.0
longitude = 7.0

try:
    # Retrieve elevation, optionally showing a progress window
    elevation = get_point_elevation(
        latitude,
        longitude,
        show_progress_dialog=True,
        progress_dialog_custom_message="Fetching elevation data for you..." # Custom message
    )

    if elevation is None:
        print(f"Could not retrieve elevation for ({latitude}, {longitude}).")
    elif isinstance(elevation, float) and math.isnan(elevation):  # Check for NaN (Not a Number)
        print(f"The point ({latitude}, {longitude}) is on a NoData area.")
    else:
        print(f"The elevation at ({latitude}, {longitude}) is: {elevation:.2f} meters.")

except RuntimeError as e:
    print(f"Error initializing GeoElevation library: {e}")
except ValueError as e:
     print(f"Value error in coordinates: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

get_point_elevation function details:

• get_point_elevation(latitude: float, longitude: float, show_progress_dialog: bool = False, progress_dialog_custom_message: str = "Retrieving elevation data...") -> Optional[float]
  • latitude, longitude: Geographic coordinates of the point.
  • show_progress_dialog: If True, displays a non-blocking dialog window with a progress indicator during data retrieval. Useful if the function is called from an application with its own GUI to prevent it from appearing frozen. Requires Tkinter.
  • progress_dialog_custom_message: Allows customization of the message displayed in the progress dialog.
  • Returns: The elevation in meters as a float, float('nan') if the point is a NoData area, or None if the elevation cannot be determined, data is unavailable, or an error occurs.
  • Raises: RuntimeError if critical dependencies (e.g., Rasterio) are unavailable or if the ElevationManager cannot be initialized correctly. ValueError for invalid coordinate inputs.

(Add other sections like Project Structure, Screenshots, Limitations, License, Contributing as suggested before)