GeoPulse Map Download Documentation

Overview

GeoPulse is a web-based tool that allows authenticated users to select a geographic area, configure map settings (such as zoom levels and tile sources), and download map tiles for offline use in GIS software or mapping applications. The application supports multiple tile sources (e.g., OpenStreetMap, satellite imagery) and two export formats: MBTiles and ZIP.

Getting Started

1. Sign In: Access the GeoPulse application and sign in using your credentials. If you don't have an account, register through the provided sign-up page. Upon signing in, you'll be directed to the dashboard.
2. Dashboard Overview:
   • Navigation Bar: Displays your user information and a sign-out option.
   • Map Interface: A dynamic map where you can select a target area.
   • Control Panel: Allows you to configure zoom levels, tile sources, and export formats.
   • Status and Progress Displays: Show real-time updates on map generation.
   • Usage Stats: View your download history and usage statistics by clicking "Show Stats."

Using the Map Interface

The map interface is powered by Leaflet and allows you to select a geographic area for downloading map tiles.

1. Loading the Map: The map loads automatically upon accessing the dashboard. If it fails to load, click the "Retry Loading" button.
2. Navigating the Map:
   • Zoom: Use the zoom controls (+/-) in the top-right corner to adjust the map's zoom level.
   • Pan: Click and drag to move the map.
   • Search by Coordinates:
     • Enter latitude (-90 to 90) and longitude (-180 to 180) in the input fields near the map.
     • Click the Search button to center the map at the specified coordinates.
3. Selecting a Target Area:
   • Click the target selector button (🎯) in the top-right corner to enable area selection.
   • Click and drag on the map to draw a rectangular area.
   • A green rectangle with a dashed border will appear, and a popup will display the selected area's size in square kilometers.
   • To modify the selection, click the target selector button again and redraw the area.

Configuring Map Download Settings

The control panel on the left side of the dashboard allows you to customize your map download.

1. Zoom Levels:
   • Minimum Zoom: Set the lowest zoom level (e.g., 12 for city-level detail).
   • Maximum Zoom: Set the highest zoom level (e.g., 15 for street-level detail).
   • Ensure the minimum zoom is less than or equal to the maximum zoom, and both are between 1 and 22.
2. Tile Source:
   • Choose from available tile sources: OpenStreetMap (osm), Satellite, Topographic, Hiking, Terrain, Cycling, Trekking, Outdoor.
   • The selected tile source updates the map preview in real-time.
3. Export Format:
   • MBTiles: A single SQLite database file compatible with many GIS applications (e.g., QGIS, TileServer GL).
   • Tiles (ZIP): A ZIP file containing individual PNG tiles in a tiles/z/x/y.png structure, along with a README.txt and manifest.json.
4. Tile Estimate:
   • After selecting an area, the control panel displays:
   • Total Tiles: Estimated number of tiles to download.
   • Estimated Size: Approximate file size in MB (assuming ~50KB per tile).
   • Estimated Time: Approximate download time in seconds.
   • If the tile count exceeds 5,000, a confirmation prompt will appear before proceeding.

Downloading Map Tiles

1. Initiate Download:
   • Click the Generate button in the control panel.
   • If no area is selected, an error message will prompt you to select a target area.
   • If libraries (JSZip or SQL.js) are still loading, wait until they are ready.
2. Monitor Progress:
   • The progress display shows the number of tiles downloaded and the current zoom level being processed.
   • The status display provides updates (e.g., "Initializing map generation…", "Generation complete!").
3. Download the File:
   • Upon completion, the file (MBTiles or ZIP) is automatically downloaded to your device.
   • The filename includes the tile source and timestamp (e.g., geopulse_osm_20251011T1141.mbtiles).
   • Check the status display for details like file size and tile count.

Using Downloaded Files

1. MBTiles:
   • Use with GIS software like QGIS, TileServer GL, or MapProxy.
   • Load the .mbtiles file as a raster layer or XYZ tile source.
   • The file includes metadata (e.g., bounds, zoom levels, attribution) for compatibility.
2. ZIP (Tiles):
   • Extract the ZIP to access the tiles/ folder, README.txt, and manifest.json.
   • Point your mapping software to the tiles/ directory, which follows the standard tiles/z/x/y.png structure.
   • Compatible with OpenLayers, Leaflet, QGIS, and most GIS applications.
   • Refer to README.txt for usage instructions and manifest.json for metadata.

Troubleshooting

• Map Fails to Load:
  • Ensure a stable internet connection.
  • Click "Retry Loading" if the map interface fails to initialize.
  • Refresh the page if the issue persists.
• Invalid Coordinates Error:
  • Verify that latitude is between -90 and 90, and longitude is between -180 and 180.
  • Use decimal format (e.g., 28.6139, not 28°36'50.04"N).
• Generation Fails:
  • Check if an area is selected on the map.
  • Ensure zoom levels are valid (1–22, min ≤ max).
  • Wait for libraries to load (check the status display).
  • If tiles fail to download, verify your internet connection and try a smaller area or fewer zoom levels.
• Large Tile Count Warning:
  • If the tile count exceeds 5,000, confirm the operation to proceed, as it may consume significant bandwidth and time.
• Authentication Issues:
  • If redirected to the login page, your session may have expired. Sign in again.
  • Contact support if you encounter persistent authentication errors.

FAQs