xsukax OSM Downloader

A privacy-focused, client-side web application for downloading custom OpenStreetMap regions as high-resolution PNG images. Built with pure JavaScript and designed with a GitHub-inspired dark interface, this tool enables users to export map tiles without server-side processing or data collection.

Project Overview

xsukax OSM Downloader is a lightweight, browser-based application that allows users to select any rectangular region on an OpenStreetMap interface and export it as a high-quality PNG image. The application fetches map tiles directly from OpenStreetMap servers and processes them entirely within the user's browser using HTML5 Canvas API. For extremely large exports that exceed browser canvas limitations, the tool automatically splits the output into multiple PNG files, which can be seamlessly merged using the included Python utility.

Core Capabilities

• Interactive Map Selection: Click to place four corner points defining your export area with real-time polygon visualization
• Flexible Zoom Levels: Export maps at any zoom level from 0 (world view) to 19 (street level detail)
• Large Area Support: Automatically handles exports exceeding 8,192×8,192 pixels by splitting into manageable chunks
• Intelligent Tile Management: Batch loading with caching, timeout handling, and progress tracking
• Offline Processing: All image generation occurs client-side without uploading data to external servers
• Python Merger Tool: Companion script to reconstruct split images into single files

Security and Privacy Benefits

The xsukax OSM Downloader prioritizes user privacy and data security through its architecture and design principles:

• Complete Client-Side Processing: All tile fetching, image rendering, and file generation occur exclusively in your browser, ensuring no geographic data or export parameters are transmitted to third-party servers beyond the standard OSM tile requests.

• No User Tracking: The application does not implement analytics, cookies, or any tracking mechanisms. Your usage patterns, selected locations, and exported regions remain entirely private.

• No Account Required: Operate the tool anonymously without registration, login credentials, or personal information disclosure.

• Local Data Storage: Map tiles are cached in browser memory only during active sessions and are automatically cleared when you close the page or clear your points.

• Transparent Source Code: Fully open-source codebase enables independent security audits and verification of privacy claims.

• No Server Dependencies: After the initial page load, the application can function offline (except for tile downloads), reducing exposure to potential server-side vulnerabilities.

• Direct OSM Communication: Tiles are fetched directly from OpenStreetMap's public tile servers using standard HTTPS, eliminating intermediary services that could intercept or log requests.

Features and Advantages

User Experience

• Intuitive Interface: Clean, GitHub-inspired dark theme with responsive design for desktop and mobile devices
• Drag-and-Drop Points: Reposition selection corners interactively by dragging markers on the map
• Real-Time Feedback: Live progress bars, status messages, and tile loading counters keep you informed
• Error Resilience: Graceful handling of failed tile loads with automatic retry logic and informative error messages

Technical Capabilities

• Batch Tile Loading: Concurrent tile requests with configurable batch sizes to optimize download speed
• Smart Canvas Splitting: Automatic detection and division of oversized exports to respect browser limitations
• Memory Efficient: Tiles are cached strategically and released after rendering to minimize memory footprint
• Cross-Origin Support: Properly configured CORS handling for seamless tile loading from OSM servers

Output Quality

• Lossless Export: PNG format with 0.92 compression quality preserves map details
• Accurate Georeferencing: Exported images maintain precise tile alignment and coordinate accuracy
• Metadata Preservation: Filenames include zoom level and timestamp for easy organization

Companion Tools

• Python Merger Script: Automated reconstruction of split images with intelligent grid detection
• No Dependencies: Merger requires only Python 3 and Pillow library

Installation Instructions

Web Application Setup

Option 1: Direct Browser Usage (Recommended)

1. Clone the repository:

git clone https://github.com/xsukax/xsukax-OSM-Downloader.git
cd xsukax-OSM-Downloader

2. Open index.html in any modern web browser (Chrome, Firefox, Safari, Edge)

3. The application is ready to use immediately—no build process or dependencies required

Option 2: Local Web Server

For enhanced compatibility with certain browsers' CORS policies:

# Using Python 3
python -m http.server 8000

# Using Node.js (requires http-server package)
npx http-server

# Then navigate to http://localhost:8000

Python Merger Tool Setup

1. Ensure Python 3.7 or higher is installed:

python --version

2. Install the Pillow library:

pip install Pillow

3. Make the script executable (Linux/macOS):

chmod +x osm_merger.py

Usage Guide

Exporting Map Regions

flowchart TD
    A[Open index.html in Browser] --> B[Click Map to Place 4 Corner Points]
    B --> C{Points Valid?}
    C -->|No| B
    C -->|Yes| D[Select Zoom Level 0-19]
    D --> E[Click Generate PNG]
    E --> F[Wait for Tile Loading]
    F --> G{Size > 8192px?}
    G -->|No| H[Single PNG Generated]
    G -->|Yes| I[Multiple PNGs Generated]
    H --> J[Click Download PNG]
    I --> J
    J --> K[Files Saved to Downloads]
    K --> L{Multiple Files?}
    L -->|Yes| M[Run osm_merger.py]
    L -->|No| N[Complete]
    M --> N

Loading

Step-by-Step Workflow

1. Define Export Area

• Open the application in your browser
• Click on the map to place exactly 4 points defining the corners of your desired region
• Points automatically connect to form a translucent blue polygon
• Drag any marker to adjust the selection area

2. Configure Export Settings

• Set Zoom Level (0-19):
  • Lower values (0-10): Broader areas with less detail
  • Medium values (11-15): Balanced detail for city-scale maps
  • Higher values (16-19): Street-level detail, very large file sizes
• Monitor the Points Selected counter (must be 4/4)

3. Generate Image

• Click Generate PNG button
• Progress bar displays:
  • Tile calculation phase
  • Batch downloading progress
  • Cache statistics
• Wait for "Image ready!" confirmation message
• Large exports automatically split into multiple files

4. Download Files

• Click Download PNG button when enabled
• Files download automatically to your default downloads folder
• Naming convention:
  • Single file: osm_export_z15_1234567890.png
  • Split files: osm_export_z15_1234567890_part_1-1_of_2x3.png

Merging Split Images

When your export exceeds 8,192 pixels in either dimension, multiple PNG files are created. Merge them using the Python script:

# Basic usage
python osm_merger.py /path/to/download/folder

# Example
python osm_merger.py ~/Downloads

Merger Output:

Found 6 chunks in 2x3 grid
Creating merged image: 16384x12288px
✓ Merged image saved: osm_merged_z15_1234567890.png
  Size: 247.35 MB

Process Architecture

graph LR
    A[User Clicks Map] --> B[Store Coordinates]
    B --> C[Calculate Tile Range]
    C --> D[Batch Tile Loader]
    D --> E{Tile Available?}
    E -->|Yes| F[Cache Tile]
    E -->|No| G[Retry/Skip]
    F --> H[All Tiles Loaded?]
    G --> H
    H -->|No| D
    H -->|Yes| I[Create Canvas Chunks]
    I --> J[Render Tiles to Canvas]
    J --> K[Convert to PNG Blob]
    K --> L[Trigger Browser Download]
    L --> M{Multiple Files?}
    M -->|Yes| N[User Runs Merger]
    M -->|No| O[Complete]
    N --> O

Loading

Tips and Best Practices

Zoom Level Selection:

• Zoom 0-8: Continental/country-scale exports, minimal detail
• Zoom 9-13: Regional/city-scale exports, moderate detail
• Zoom 14-16: District/neighborhood-scale exports, high detail
• Zoom 17-19: Street-level exports, extreme detail (very large files)

Performance Optimization:

• Start with lower zoom levels to test your selected area
• Use wired internet connections for large exports
• Close unnecessary browser tabs to free memory
• Expect 5-15 minutes for exports with 5,000+ tiles

Troubleshooting:

• "No tiles loaded": Check internet connection and retry
• Browser freezing: Reduce zoom level or select smaller area
• Download fails: Ensure sufficient disk space (check status message for size estimate)
• Merger errors: Verify all split files are in the same folder

Advanced Usage

Clearing and Restarting:

• Click Clear All Points to remove selection and start over
• Cached tiles persist until you clear points or refresh the page

Partial Tile Loading:

• If some tiles fail to load, the application proceeds with available tiles
• Check the status message: "X/Y tiles loaded" indicates success rate

License

This project is licensed under the GNU General Public License v3.0.

---

Repository: https://github.com/xsukax/xsukax-OSM-Downloader

Map Data: © OpenStreetMap contributors

Developed by: xsukax