SXXXXXXX_GeoElevation/doc/English-Manual.md

User Manual: GeoElevation Tool (English - Updated)

1. Introduction

GeoElevation 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 Digital Elevation Model (DEM) data, an improved version of the SRTM data provided by NASA.

The application allows you to:

• Get the elevation for a single point.
• Automatically download necessary DEM data "tiles" and their corresponding "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.
• View the browse images of individual tiles or a composite mosaic of the downloaded area (static visualizations).
• View the elevation data of a single tile as an interactive 3D plot (static visualization).
• Explore elevation data and tiled maps interactively using a dedicated map viewer, with pan and zoom functionalities.

2. Prerequisites and Installation

Before using the application, ensure you have the following:

• Python: A recent version of Python 3.8 or higher installed on your system.
• Python Libraries: Install the required libraries using pip. For the full experience with the interactive map viewer and advanced visualizations, we recommend installing all of the following:

  pip install requests rasterio Pillow matplotlib numpy netrc opencv-python mercantile pyproj scipy
  

  • requests: For downloading data from the internet (Required).
  • rasterio: For reading DEM data (HGT files) (Required for elevation functionality).
  • Pillow (PIL): For image processing (browse, composites) and drawing overlays (Required for image visualizations and map viewer).
  • matplotlib: For displaying 2D images and 3D plots (Required for static visualizations).
  • numpy: Fundamental dependency for rasterio, matplotlib, scipy, and opencv-python (Required).
  • netrc: For handling Earthdata authentication (often pre-installed, required for protected NASADEM downloads).
  • opencv-python: For handling the interactive map viewer window and mouse events (Required for the map viewer).
  • mercantile: For Web Mercator map tile calculations (Required for the map viewer).
  • pyproj: For geodesic calculations (bounding boxes, distances) (Required for some map viewer utilities and helpful for deg<->dms).
  • scipy: For advanced features in 3D plots (smoothing/interpolation) (Optional for 3D visualizations).
• 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 need to create a file named .netrc in your home directory:
  • Location:
    • Windows: C:\Users\YourUsername\.netrc
    • Linux/macOS: /home/yourusername/.netrc (or /Users/yourusername/.netrc)
  • Content (use a simple 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 is crucial to set the correct permissions for security. Open a terminal and type: chmod 600 ~/.netrc

3. Graphical User Interface (GUI) 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): Initiates the elevation lookup for the specified point. Downloads necessary data (HGT and browse image) if not already in cache.
  • Result: Label displaying the found elevation (in meters), a "nodata" message, or an error.
  • Show Browse Image (2D) (Button): (Enabled after successful Get Elevation) Opens a separate Matplotlib window showing the browse image for the tile containing the point.
  • Show DEM Tile (3D) (Button): (Enabled after successful Get Elevation) Opens a separate Matplotlib window showing an interactive 3D plot of the DEM data for the tile.
  • View Point on Map (Button): (Enabled after successful Get Elevation, requires Map Viewer libraries) Opens or brings the interactive map viewer window to the foreground, centered on the specified point with an automatic zoom level to show the surrounding DEM tile.
• Pre-Download Tiles for Area:
  • Min Lat, Max Lat, Min Lon, Max Lon: Fields to define the geographic 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 Composite (2D) (Button): (Enabled after successful Download Area Tiles and if browse images are available) Opens a separate Matplotlib window showing a mosaic composite of the downloaded area's browse images, with a grid and tile labels.
  • View Area on Map (Button): (Enabled after successful Download Area Tiles, requires Map Viewer libraries) Opens or brings the interactive map viewer window to the foreground, displaying the area covered by the downloaded DEM tiles.
  • Status: Label displaying the status of the area download.
• Map Display Options: (Visible only if Map Viewer libraries are available)
  • Map Display Scale: Combobox to select a scaling factor for the displayed interactive map image. This affects the window size.
• Map Info: (Visible only if Map Viewer libraries are available)
  • This section displays information related to the point clicked on the interactive map or the currently displayed area.
  • Latitude (Dec): Latitude of the clicked point in decimal degrees (copyable).
  • Longitude (Dec): Longitude of the clicked point in decimal degrees (copyable).
  • Latitude (DMS): Latitude of the clicked point in Degrees, Minutes, Seconds format (copyable).
  • Longitude (DMS): Longitude of the clicked point in Degrees, Minutes, Seconds format (copyable).
  • Elevation: Estimated elevation at the clicked point on the map (in meters, "NoData", "Unavailable", or fetching status) (copyable).
  • Map Area Size: Approximate geographic dimensions (Width x Height in km) of the area currently displayed in the interactive map window, including the current zoom level (copyable).
• Interactive Map Viewer Window:
  • Opens when you click "View Point on Map" or "View Area on Map".
  • Displays tiled web maps (like OpenStreetMap) with potential overlays (DEM tile borders, click marker).
  • "Map Loading" Screen: A small progress window automatically appears and disappears above the main GUI during map tile fetching and stitching operations in the map viewer.

4. Detailed Functionality

• Get Elevation: (Existing description unchanged - refers to manual input and the "Result" label)
• Download Area: (Existing description unchanged - refers to downloading HGT/browse data to cache)
• Static Visualizations (Show Browse Image, Show DEM Tile, Show Area Composite): (Existing descriptions unchanged - refer to non-interactive Matplotlib windows with standard Matplotlib pan/zoom tools)
• Interactive Map Viewer (View on Map buttons):
  • Activates a separate window (based on OpenCV) that displays online map tiles.
  • When opened via "View Point on Map", the map is centered on the point and zoomed automatically to show the corresponding DEM tile (with a small buffer). The boundary of the DEM HGT tile is drawn in red.
  • When opened via "View Area on Map", the map displays the combined extent of all DEM tiles available (in cache) for the defined area. The boundary of the requested area (based on the input limits) is drawn in blue, and the boundaries of the individual available DEM HGT tiles are drawn in red with their labels.
  • The map window responds to mouse events:
    • Left Click (Standard):
      1. Identifies the geographic coordinates of the clicked pixel.
      2. Requests the elevation for that point from the ElevationManager.
      3. Updates the "Map Info" fields in the main GUI with the coordinates (Decimal and DMS), the found elevation ("NoData", "Unavailable", or meter value), and the displayed area size.
      4. Draws a temporary marker on the map at the clicked point.
      5. During elevation fetching (which might involve downloads), the "Map Loading" screen may briefly appear.
    • Ctrl + Left Click (Pan):
      1. Identifies the geographic coordinates of the clicked pixel.
      2. Updates the map view so the clicked point becomes the new center.
      3. The current zoom level is maintained.
      4. New map tiles are fetched and stitched for the new centered area.
      5. Updates the "Map Info" fields (new center, elevation N/A, displayed area size including zoom).
      6. During fetching/stitching, the "Map Loading" screen appears.
    • Right Click (Zoom Out + Recenter):
      1. Identifies the geographic coordinates of the clicked pixel.
      2. Updates the map view so the clicked point becomes the new center.
      3. Decreases the zoom level by 1 (clamped to a minimum of zoom 0).
      4. New map tiles are fetched and stitched for the new area and zoom level.
      5. Updates the "Map Info" fields (new center, elevation N/A, displayed area size including zoom).
      6. During fetching/stitching, the "Map Loading" screen appears.
    • Shift + Left Click (Zoom In + Recenter):
      1. Identifies the geographic coordinates of the clicked pixel.
      2. Updates the map view so the clicked point becomes the new center.
      3. Increases the zoom level by 1 (clamped to the maximum zoom level supported by the map service, e.g., 19 for OSM).
      4. New map tiles are fetched and stitched for the new area and zoom level.
      5. Updates the "Map Info" fields (new center, elevation N/A, displayed area size including zoom).
      6. During fetching/stitching, the "Map Loading" screen appears.

5. Common Use Cases

• Finding the Altitude of a Specific Location:
  1. Start the application.
  2. Enter the latitude and longitude of the location in the respective fields.
  3. Click "Get Elevation". Read the result in the "Result" label. (This ensures the DEM tile is available and activates buttons).
  4. Click "View Point on Map". The interactive map window will open centered on the point.
  5. (Optional) Click on any point on the map to get the precise elevation at that spot and see the coordinates and elevation update in the "Map Info" panel. A red marker will appear at the clicked location.
• Checking Elevation Offline (Data Already Downloaded):
  1. Start the application.
  2. Enter latitude and longitude of a point within an area whose DEM data has already been downloaded (into the geoelevation_dem_cache).
  3. Click "Get Elevation". The result will appear almost instantly as HGT data is read locally.
  4. Click "View Point on Map". The map will load using cached OpenStreetMap tiles (if available) or downloading if online, but elevation for a clicked point (step 5 from previous use case) will be fast if the DEM is cached.
• Preparing Data for an Area Before Going Offline:
  1. Start the application (with active internet connection).
  2. Identify the boundaries (min/max lat/lon) of your area of interest.
  3. Enter these boundaries in the "Pre-Download Tiles for Area" section.
  4. Click "Download Area Tiles". Wait for completion (monitor the "Status" label and console for logs). This may take time depending on area size and connection speed.
  5. (Optional) Click "Show Area Composite (2D)" to visually confirm which tiles were downloaded.
  6. You can now use the application offline to get quick elevations for any point within the downloaded DEM area and view the area in "View Area on Map" (the tiled map might not load offline if its tiles aren't cached, but the DEM boundaries will appear).
• Exploring an Area Visually on the Interactive Map:
  1. Ensure you have already downloaded the desired area using "Download Area Tiles".
  2. Click "View Area on Map". The interactive map window will open displaying the area of the downloaded DEM tiles. You will see the boundaries of the requested area (blue) and the boundaries of the individual available DEM tiles (red with labels).
  3. Use Ctrl + Left Click to move (pan) around the map while keeping the same zoom level.
  4. Use Shift + Left Click to zoom IN and recenter on a point.
  5. Use Right Click to zoom OUT and recenter on a point.
  6. Standard Left Click on a point to get its elevation and see the info in the "Map Info" panel.

6. Notes and Troubleshooting

• Download Errors: (Existing description unchanged)
• .netrc File: (Existing description unchanged)
• Missing Dependencies: If crucial libraries for the map viewer (Pillow, OpenCV, Mercantile, Pyproj) are missing, the "View on Map" buttons will be disabled and/or error messages will appear on startup. If libraries for static visualizations (Matplotlib, SciPy, Pillow) are missing, the corresponding "Show..." buttons will be disabled. Install missing libraries with pip.
• Performance:
  • Downloading very large areas can take time.
  • Rendering a full tile in 3D can be computationally intensive.
  • Fetching and stitching a large number of map tiles for the interactive viewer (at low zoom levels or for large view areas) can take time and memory; the "Map Loading" screen will appear in these cases.
• Separate Windows: Visualization windows (both static Matplotlib plots and the interactive OpenCV map) run in separate processes to avoid blocking the main GUI. They might appear in unexpected locations on your desktop.
• "Map Loading" Window: This window is set to always stay on top to help ensure you see it. Selecting the main GUI window or the map window will not hide it. On some operating systems or window managers, the "always on top" behavior might vary slightly.
• Logs: Always check the output in the console/terminal you used to launch the application for detailed log messages, especially in case of errors.