SXXXXXXX_GeoElevation/doc/English-Manual.md

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

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