SXXXXXXX_GeoElevation/README.md

## GeoElevation Tool

**(English Presentation Below)**

**IT** | [EN](#english-presentation)

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/`):

```bash
python -m geoelevation
```
Oppure, se è stato installato come pacchetto:
```bash
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:

```bash
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:
```bash
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`:

```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_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-1)

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):

```bash
python -m geoelevation
```
Alternatively, if installed as a package:
```bash
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:

```bash
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:
```bash
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`:

```python
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)*