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) 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.
• 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.
• Scaricare Aree DEM (via GUI): Definire un'area geografica per scaricare automaticamente tutti i tile NASADEM HGT necessari.
• Visualizzare Aree Scaricate (via GUI): Creare e mostrare un'immagine composita delle anteprime per un'area definita.

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 la sezione "Utilizzo Avanzato" di seguito.

Caratteristiche Principali

• Interfaccia utente grafica (GUI) intuitiva basata su Tkinter.
• Interfaccia a riga di comando (CLI) per il recupero rapido dell'elevazione.
• API Python per l'integrazione come libreria in altre applicazioni.
• Recupero dell'elevazione per coordinate specifiche.
• Download automatico e caching dei tile NASADEM.
• Visualizzazione 2D delle immagini di anteprima (GUI).
• Visualizzazione 3D interattiva dei dati di elevazione con opzioni avanzate (GUI).
• Download di tile DEM per aree geografiche (GUI).
• Creazione di immagini composite per aree (GUI).
• Feedback visivo opzionale (finestra di progresso) durante le operazioni di recupero dati quando usato come libreria.

Requisiti

• Python 3.x
• 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)

È 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 se necessario, es. pip install geoelevation se pubblicato, o istruzioni per requirements.txt)

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)

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).
• --lon LONGITUDINE: Longitudine del punto (es. 7.0).
• --show-progress: (Opzionale) Mostra una semplice finestra di dialogo di avanzamento durante il recupero dei dati.
• --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: <valore> 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:

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_message="Sto cercando l'elevazione per te..." # Messaggio personalizzato
    )

    if elevation is None:
        print(f"Impossibile recuperare l'elevazione per ({latitude}, {longitude}).")
    elif elevation != 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 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_message: str = "Messaggio di default...") -> Optional[float]
  • latitude, longitude: Coordinate geografiche del punto.
  • show_progress_dialog: Se True, mostra una finestra di dialogo non bloccante durante il recupero dei dati. Utile se la funzione viene chiamata da un'applicazione con una propria GUI che potrebbe altrimenti sembrare bloccata.
  • progress_dialog_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 o si verifica un errore.
  • Solleva: RuntimeError se le dipendenze critiche (es. Rasterio) non sono disponibili o se ElevationManager non può essere inizializzato.

(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 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.
• Visualize DEM Data (via GUI):
  • Display a browse image (preview) of the DEM tile.
  • Generate and display an interactive 3D representation of the DEM tile, with options for smoothing and interpolation.
• Download DEM Areas (via GUI): Define a geographical area to automatically download all necessary NASADEM HGT tiles.
• Visualize Downloaded Areas (via GUI): Create and show a composite browse image for a defined area.

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 "Advanced Usage" section below.

Key Features

• Intuitive Tkinter-based Graphical User Interface (GUI).
• Command Line Interface (CLI) for quick elevation retrieval.
• Python API for integration as a library into other applications.
• Elevation retrieval for specific coordinates.
• Automatic download and caching of NASADEM tiles.
• 2D visualization of tile browse images (GUI).
• Interactive 3D visualization of elevation data with advanced options (GUI).
• DEM tile download for defined geographical areas (GUI).
• Composite image creation for areas (GUI).
• Optional visual feedback (progress window) during data retrieval operations when used as a library.

Requirements

• Python 3.x
• Tkinter (usually included with Python)
• Requests
• NumPy
• Matplotlib
• Pillow (PIL Fork)
• Rasterio (for reading HGT files)
• SciPy (for smoothing and interpolation in 3D visualization)

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

Installation

(Add if needed, e.g., pip install geoelevation if published, or requirements.txt instructions)

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)

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]

Arguments:

• --lat LATITUDE: Latitude of the point (e.g., 45.0).
• --lon LONGITUDE: Longitude of the point (e.g., 7.0).
• --show-progress: (Optional) Displays a simple progress dialog window during data retrieval.
• --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

# 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_message="Fetching elevation data for you..." # Custom message
    )

    if elevation is None:
        print(f"Could not retrieve elevation for ({latitude}, {longitude}).")
    elif elevation != 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 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_message: str = "Default progress message...") -> Optional[float]
  • latitude, longitude: Geographic coordinates of the point.
  • show_progress_dialog: If True, displays a non-blocking dialog window during data retrieval. Useful if the function is called from an application with its own GUI that might otherwise appear to freeze.
  • progress_dialog_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 or an error occurs.
  • Raises: RuntimeError if critical dependencies (e.g., Rasterio) are unavailable or if the ElevationManager cannot be initialized.

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