add manual

This commit is contained in:
VALLONGOL 2025-04-28 15:43:31 +02:00
parent d0b6cdee39
commit bcb2bf3fdc
2 changed files with 311 additions and 0 deletions

155
Manual.md Normal file
View File

@ -0,0 +1,155 @@
**(English Version)**
**User Manual: Elevation Tool**
**1. Introduction**
Elevation Tool is a desktop application designed to retrieve elevation data (altitude) for specific geographic coordinates (latitude and longitude) on the Earth's surface. It utilizes NASADEM DEM (Digital Elevation Model) data, an improved version of SRTM data provided by NASA.
The application allows you to:
* Get the elevation for a single point.
* Automatically download the necessary DEM data "tiles" and their corresponding preview ("browse") images from remote servers.
* Maintain a local cache of downloaded data for fast offline access and to reduce repeated downloads.
* Pre-download data for an entire geographic area.
* Visualize browse images of individual tiles or a mosaic of the downloaded area.
* Visualize the elevation data of a single tile as an interactive 3D plot.
**2. Prerequisites and Installation**
Before using the application, ensure you have the following:
* **Python:** A recent version of Python 3 installed on your system.
* **Python Libraries:** Install the required libraries using `pip`:
```bash
pip install requests rasterio Pillow matplotlib numpy netrc opencv-python
```
* `requests`: For downloading data from the internet.
* `rasterio`: For reading DEM data (HGT files).
* `Pillow`: For processing preview images.
* `matplotlib`: For displaying 2D images and 3D plots.
* `numpy`: A fundamental dependency for `rasterio` and `matplotlib`.
* `netrc`: For handling authentication (often already present).
* `opencv-python`: (Currently unused in the final version, but potentially useful for future 2D processing).
* **NASA Earthdata Login Account:** NASADEM data requires a free account. Register at: [https://urs.earthdata.nasa.gov/users/new](https://urs.earthdata.nasa.gov/users/new)
* **`.netrc` File for Authentication:** To allow the application to download protected data, you must create a file named `.netrc` in your system's home directory:
* **Location:**
* Windows: `C:\Users\YourUsername\.netrc`
* Linux/macOS: `/home/yourusername/.netrc` (or `/Users/yourusername/.netrc`)
* **Content** (use a plain text editor):
```
machine urs.earthdata.nasa.gov
login YOUR_EARTHDATA_USERNAME
password YOUR_EARTHDATA_PASSWORD
```
Replace `YOUR_EARTHDATA_USERNAME` and `YOUR_EARTHDATA_PASSWORD` with your actual credentials.
* **Permissions (Linux/macOS):** It's crucial to set the correct permissions for security. Open a terminal and type: `chmod 600 ~/.netrc`
**3. Interface Overview**
The application features a single main window divided into sections:
* **Get Elevation for Point:**
* `Latitude`: Field to enter latitude (decimal degrees, e.g., 45.0).
* `Longitude`: Field to enter longitude (decimal degrees, e.g., 7.0).
* `Get Elevation` (Button): Starts the elevation lookup for the specified point. Downloads necessary data (HGT and browse image) if not found in the cache.
* `Result`: Label displaying the found elevation (in meters), a "nodata" message, or an error.
* `Show Browse Image (2D)` (Button): (Enabled after success) Opens a separate window (using Matplotlib) showing the preview image of the tile containing the point, with the name and source overlaid. Allows zooming and panning.
* `Show DEM Tile (3D)` (Button): (Enabled after success) Opens a separate window (using Matplotlib) showing an interactive 3D plot of the elevation data from the tile containing the point. Allows rotation, zooming, and panning.
* **Pre-Download Tiles for Area:**
* `Min Lat`, `Max Lat`, `Min Lon`, `Max Lon`: Fields to define the boundaries of a rectangular area to download.
* `Download Area Tiles` (Button): Starts the background download of all HGT data (extracted) and browse images for all tiles intersecting the specified area.
* `Show Area Browse Images (2D)` (Button): (Enabled after successful area download) Opens a separate window (using Matplotlib) showing a mosaic of the preview images for the tiles in the downloaded area, with a red grid and tile names overlaid. Allows zooming and panning.
* `Status`: Label showing the status of the area download (Idle, Downloading, Complete, Error).
**4. Detailed Functionality**
* **Get Elevation:**
1. Enter valid Latitude and Longitude.
2. Click "Get Elevation".
3. The application determines the required 1x1 degree DEM tile.
4. Checks if the extracted HGT file exists in the local cache (`elevation_cache/hgt_tiles/`).
5. **If not exists:**
* Connects to the NASA server using `.netrc` credentials.
* Downloads the `.zip` file containing HGT data.
* Extracts the `.hgt` file into the local cache (`hgt_tiles`).
* Attempts to download the public `.jpg` browse image into the local cache (`browse_images`).
6. **If exists (or after download):**
* Opens the local `.hgt` file.
* Reads the elevation value for the exact coordinates.
* Displays the result in the "Result" label.
* Enables the "Show Browse Image (2D)" and "Show DEM Tile (3D)" buttons.
* **Download Area:**
1. Enter the geographic boundaries of the area.
2. Click "Download Area Tiles".
3. The application calculates which 1x1 degree tiles are needed.
4. For each required tile:
* Checks if the extracted HGT file already exists in the cache.
* If not, performs steps 5a-5c of "Get Elevation".
* Independently of whether the HGT existed, checks if the browse image exists in the cache and attempts to download it if missing.
5. The operation runs in the background to keep the interface responsive. Status is shown in the "Status" label.
6. Upon completion, a message summarizes how many tiles were processed and how many HGT files were actually downloaded/extracted. The "Show Area Browse Images (2D)" button is enabled.
* **2D Visualization (Browse Image - Single Tile):**
1. Successfully get the elevation for a point.
2. Click "Show Browse Image (2D)".
3. The application looks for the corresponding browse image in the cache (`browse_images`).
4. If found, it loads the image and adds the tile name and source as an overlay.
5. Displays the image in a new interactive Matplotlib window.
* **3D Visualization (DEM Tile):**
1. Successfully get the elevation for a point.
2. Click "Show DEM Tile (3D)".
3. The application looks for the corresponding HGT file in the cache (`hgt_tiles`).
4. If found, it reads the elevation data as a NumPy array.
5. Generates a 3D surface plot using Matplotlib (with subsampling for performance).
6. Displays the plot in a new interactive Matplotlib window.
* **2D Visualization (Area - Browse Mosaic):**
1. Successfully download an area using "Download Area Tiles".
2. Click "Show Area Browse Images (2D)".
3. The application looks for all browse images corresponding to the tiles in the requested area within the cache (`browse_images`).
4. Loads the found images.
5. Creates a composite image by "stitching" together the available images (uses gray placeholders if an image is missing).
6. Draws a red grid to separate tiles and adds the name label to each tile.
7. Displays the composite image in a new interactive Matplotlib window.
**5. Common Use Cases**
* **Finding the Altitude of a Specific Location:**
1. Launch the application.
2. Enter the location's latitude and longitude into the respective fields.
3. Click "Get Elevation".
4. Read the result in the "Result" label. The first access might take a few seconds for the download.
5. (Optional) Click "Show Browse Image (2D)" to see the general appearance of the area from satellite/radar.
6. (Optional) Click "Show DEM Tile (3D)" to explore the terrain relief in 3D.
* **Checking Elevation Offline (Data Already Downloaded):**
1. Launch the application.
2. Enter the latitude and longitude of a point within an area whose data has already been downloaded (in the `elevation_cache`).
3. Click "Get Elevation".
4. The result will appear almost instantly as data is read locally.
* **Preparing Data for an Area Before Going Offline:**
1. Launch the application (with an active internet connection).
2. Identify the boundaries (min/max lat/lon) of the area of interest.
3. Enter these boundaries in the "Pre-Download Tiles for Area" section.
4. Click "Download Area Tiles".
5. Wait for completion (monitor the "Status" label and console logs). This may take time depending on the area size and connection speed.
6. (Optional) Click "Show Area Browse Images (2D)" to visually confirm which tiles were downloaded.
7. You can now use the application offline to get quick elevations for any point within the downloaded area.
* **Visually Exploring a Single Tile:**
1. Enter the coordinates of any point within the tile you are interested in.
2. Click "Get Elevation" (even if you know the elevation, this ensures the tile is available and enables the buttons).
3. Click "Show Browse Image (2D)" or "Show DEM Tile (3D)".
* **Getting an Overview of a Region:**
1. Ensure you have already downloaded the desired area using "Download Area Tiles".
2. Click "Show Area Browse Images (2D)".
3. Explore the composite image using Matplotlib's zoom/pan tools to see the tile layout and the general appearance of the region.
**6. Notes and Troubleshooting**
* **Download Errors:**
* **401/403 (Unauthorized/Forbidden):** Problem with Earthdata Login credentials in your `.netrc` file. Check username, password, and the machine name `urs.earthdata.nasa.gov`.
* **404 (Not Found):** The requested file (HGT zip or browse jpg) does not exist at the specified URL. This could indicate a gap in NASA's data for that area or an issue with the URL construction (check URL constants in `elevation_manager.py`).
* **Network Errors/Timeouts:** Temporary connection issues. The script attempts a short retry, but persistent errors require a stable connection.
* **`.netrc` File:** Ensure it's in the correct directory and has restricted permissions (Linux/macOS).
* **Missing Dependencies:** If libraries (Rasterio, Pillow, Matplotlib) are missing, the application will show warning messages on startup and/or errors when trying to use associated features. Install missing libraries with `pip`.
* **3D Performance:** Rendering a full 3D tile can be intensive. Subsampling helps, but it might still be slow for very complex areas or less powerful machines.
* **Blocking Windows:** The Matplotlib visualization windows (2D and 3D) are run in separate processes to avoid blocking the main GUI, but the Matplotlib window itself will wait for user interaction or closure.
* **Logs:** Always check the output in the console/terminal where you launched the application for detailed log messages, especially if errors occur.

156
Manuale.md Normal file
View File

@ -0,0 +1,156 @@
**Manuale Utente: Elevation Tool**
**1. Introduzione**
Elevation 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.
* Visualizzare i dati di elevazione di un singolo tile come plot 3D interattivo.
**2. Prerequisiti e Installazione**
Prima di utilizzare l'applicazione, assicurati di avere quanto segue:
* **Python:** Una versione recente di Python 3 installata sul tuo sistema.
* **Librerie Python:** Installa le librerie necessarie tramite `pip`:
```bash
pip install requests rasterio Pillow matplotlib numpy netrc opencv-python
```
* `requests`: Per scaricare dati da internet.
* `rasterio`: Per leggere i dati DEM (file HGT).
* `Pillow`: Per elaborare le immagini di anteprima.
* `matplotlib`: Per visualizzare le immagini 2D e i plot 3D.
* `numpy`: Dipendenza fondamentale per `rasterio` e `matplotlib`.
* `netrc`: Per gestire l'autenticazione (spesso già presente).
* `opencv-python`: (Attualmente non usata nella versione finale, ma potrebbe essere utile per future elaborazioni 2D).
* **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**
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) Apre una finestra separata (usando Matplotlib) mostrando l'immagine di anteprima del tile contenente il punto, con nome e fonte sovraimpressi. Permette zoom e pan.
* `Show DEM Tile (3D)` (Pulsante): (Abilitato dopo successo) Apre una finestra separata (usando Matplotlib) mostrando un plot 3D interattivo dei dati di elevazione del tile contenente il punto. Permette rotazione, zoom e pan.
* **Pre-Download Tiles for Area:**
* `Min Lat`, `Max Lat`, `Min Lon`, `Max Lon`: Campi per definire i limiti di un'area rettangolare da scaricare.
* `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 Browse Images (2D)` (Pulsante): (Abilitato dopo successo download area) Apre una finestra separata (usando Matplotlib) mostrando un mosaico delle immagini di anteprima dei tile dell'area scaricata, con una griglia rossa e il nome di ogni tile. Permette zoom e pan.
* `Status`: Etichetta che mostra lo stato del download dell'area (Idle, Downloading, Complete, Error).
**4. Funzionalità Dettagliate**
* **Ottenere Elevazione (Get Elevation):**
1. Inserisci Latitudine e Longitudine valide.
2. Clicca "Get Elevation".
3. L'applicazione determina il tile DEM 1x1 grado necessario.
4. Controlla se il file HGT estratto esiste nella cache locale (`elevation_cache/hgt_tiles/`).
5. **Se non esiste:**
* Si connette al server NASA usando le credenziali `.netrc`.
* Scarica il file `.zip` contenente i dati HGT.
* Estrae il file `.hgt` nella cache locale (`hgt_tiles`).
* Tenta di scaricare l'immagine browse `.jpg` pubblica nella cache locale (`browse_images`).
6. **Se esiste (o dopo download):**
* Apre il file `.hgt` locale.
* Legge il valore di elevazione per le coordinate esatte.
* Mostra il risultato nell'etichetta "Result".
* Abilita i pulsanti "Show Browse Image (2D)" e "Show DEM Tile (3D)".
* **Scaricare Area (Download Area Tiles):**
1. Inserisci i limiti geografici dell'area.
2. Clicca "Download Area Tiles".
3. L'applicazione calcola quali tile 1x1 grado sono necessari.
4. Per ogni tile necessario:
* Controlla se il file HGT estratto esiste già in cache.
* Se non esiste, esegue i passi 5a-5c di "Ottenere Elevazione".
* Indipendentemente dal fatto che l'HGT esistesse già, controlla se l'immagine browse esiste in cache e tenta di scaricarla se manca.
5. L'operazione avviene in background per non bloccare l'interfaccia. Lo stato è mostrato nell'etichetta "Status".
6. Al termine, un messaggio riassume quanti tile sono stati processati e quanti file HGT sono stati effettivamente scaricati/estratti. Il pulsante "Show Area Browse Images (2D)" viene abilitato.
* **Visualizzazione 2D (Browse Image - Singolo Tile):**
1. Ottieni l'elevazione per un punto con successo.
2. Clicca "Show Browse Image (2D)".
3. L'applicazione cerca l'immagine browse corrispondente nella cache (`browse_images`).
4. Se trovata, carica l'immagine, aggiunge il nome del tile e la fonte come overlay.
5. Mostra l'immagine in una nuova finestra Matplotlib interattiva.
* **Visualizzazione 3D (DEM Tile):**
1. Ottieni l'elevazione per un punto con successo.
2. Clicca "Show DEM Tile (3D)".
3. L'applicazione cerca il file HGT corrispondente nella cache (`hgt_tiles`).
4. Se trovato, legge i dati di elevazione come array NumPy.
5. Genera un plot 3D della superficie usando Matplotlib (con sottocampionamento per performance).
6. Mostra il plot in una nuova finestra Matplotlib interattiva.
* **Visualizzazione 2D (Area - Mosaico Browse):**
1. Scarica un'area con successo usando "Download Area Tiles".
2. Clicca "Show Area Browse Images (2D)".
3. L'applicazione cerca tutte le immagini browse corrispondenti ai tile dell'area richiesta nella cache (`browse_images`).
4. Carica le immagini trovate.
5. Crea un'immagine composita "cucendo" insieme le immagini disponibili (usa placeholder grigi se un'immagine manca).
6. Disegna una griglia rossa per separare i tile e aggiunge l'etichetta con il nome a ciascun tile.
7. Mostra l'immagine composita in una nuova finestra Matplotlib interattiva.
**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".
4. Leggi il risultato nell'etichetta "Result". Il primo accesso potrebbe richiedere qualche secondo per il download.
5. (Opzionale) Clicca "Show Browse Image (2D)" per vedere l'aspetto generale dell'area dal satellite/radar.
6. (Opzionale) Clicca "Show DEM Tile (3D)" per esplorare il rilievo del terreno in 3D.
* **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 sono già stati scaricati (nella cache `elevation_cache`).
3. Clicca "Get Elevation".
4. Il risultato apparirà quasi istantaneamente perché i dati vengono letti localmente.
* **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".
5. Attendi il completamento (monitora l'etichetta "Status" e la console per i log). Potrebbe richiedere tempo a seconda della dimensione dell'area e della velocità di connessione.
6. (Opzionale) Clicca "Show Area Browse Images (2D)" per confermare visivamente quali tile sono stati scaricati.
7. Ora puoi usare l'applicazione offline per ottenere elevazioni rapide per qualsiasi punto all'interno dell'area scaricata.
* **Esplorare Visivamente un Singolo Tile:**
1. Inserisci le coordinate di un punto qualsiasi all'interno del tile che ti interessa.
2. Clicca "Get Elevation" (anche se conosci già l'elevazione, questo assicura che il tile sia disponibile e i pulsanti si attivino).
3. Clicca "Show Browse Image (2D)" o "Show DEM Tile (3D)".
* **Ottenere una Visione d'Insieme di un'Area:**
1. Assicurati di aver già scaricato l'area desiderata usando "Download Area Tiles".
2. Clicca "Show Area Browse Images (2D)".
3. Esplora l'immagine composita usando gli strumenti di zoom/pan di Matplotlib per vedere la disposizione dei tile e l'aspetto generale della regione.
**6. Note e Risoluzione Problemi**
* **Errori di Download:**
* **401/403 (Unauthorized/Forbidden):** Problema con le credenziali Earthdata Login nel file `.netrc`. Verifica username, password e il nome `machine urs.earthdata.nasa.gov`.
* **404 (Not Found):** Il file richiesto (HGT zip o browse jpg) non esiste all'URL specificato. Potrebbe indicare una lacuna nei dati NASA per quell'area o un problema nella costruzione dell'URL (controlla le costanti URL nel codice `elevation_manager.py`).
* **Errori di Rete/Timeout:** Problemi temporanei di connessione. Lo script tenta un breve retry, ma errori persistenti richiedono una connessione stabile.
* **File `.netrc`:** Assicurati che sia nella directory corretta e che i permessi siano restrittivi (Linux/macOS).
* **Dipendenze Mancanti:** Se mancano librerie (Rasterio, Pillow, Matplotlib), l'applicazione mostrerà messaggi di avviso all'avvio e/o errori quando tenti di usare le funzionalità associate. Installa le librerie mancanti con `pip`.
* **Performance 3D:** Il rendering 3D di un tile completo può essere intensivo. Il sottocampionamento (`subsample`) aiuta, ma per aree molto complesse potrebbe comunque essere lento.
* **Finestre Bloccanti:** Le finestre di visualizzazione Matplotlib (sia 2D che 3D) sono eseguite in processi separati per non bloccare la GUI principale, ma la finestra Matplotlib stessa attenderà la chiusura da parte dell'utente.
* **Log:** Controlla sempre l'output nella console/terminale da cui hai avviato l'applicazione per messaggi di log dettagliati, specialmente in caso di errori.