Welcome to gpx-kml-converter

Welcome to the GPX KML Converter application, a versatile tool designed for processing geographical data files (GPX and KML). The application offers both an intuitive Graphical User Interface (GUI) and a robust command line interface for various file manipulation tasks.

Installation

Download from PyPI.

💾 For more installation options see install.

pip install gpx-kml-converter

Run GUI from command line

gpx-kml-converter-gui

Run CLI from command line

gpx-kml-converter-cli --help

2. Main Features 🚀

2.1. Graphical User Interface (GUI) 🖥️

The application features a comprehensive GUI that simplifies the process of managing and processing your geographical data.

• Dual File Lists: The GUI presents two distinct listboxes:

  • Input Files: Displays the files selected by the user for processing. 📁

  • Generated Files: Shows the output files produced after a successful processing operation. 📊

• File Information at a Glance: Both listboxes display not only the file names but also their respective file sizes in kilobytes, providing immediate feedback on file changes (e.g., after compression). 📏

• Interactive File Access: Files listed in both the input and generated file sections are clickable. Double-clicking a file will open it using your operating system's default application or launch the file explorer with the file selected. 🖱️📂

• Integrated Logging: A dedicated log output area provides real-time feedback on application operations, warnings, and errors. Directory paths mentioned in the logs are clickable, allowing direct navigation to the output folders. 📝🔗

2.2. GPX/KML File Processing Capabilities 🗺️

The core strength of the application lies in its ability to handle GPX and KML files with several powerful processing modes:

• Compression: Reduce the size of your track files by optimizing the number of track points and cleaning unnecessary metadata. 📉

• Merging: Combine multiple GPX/KML files into a single, consolidated GPX file, ideal for creating continuous routes from fragmented data. ➕

• POI Extraction: Automatically identify and extract the starting points of tracks and routes from your files, saving them as Waypoints (Points of Interest) in a new GPX file. 📍

3. Detailed Features 🔍

3.1. File Management 🗃️

• Adding Input Files: Use the "Open Files" button or the "File -> Open..." menu option to select one or multiple GPX, KML, or even ZIP archives containing GPX/KML files. The application intelligently extracts and lists valid geographical data files. ➕📂

• Removing Input Files:

  • "Remove Selected" Button: Select one or more files in the "Input Files" listbox and click this button to remove them from the processing queue. 🗑️

  • "Clear Input Files" Button: Remove all files from the "Input Files" list. 🧹

• Clearing Generated Files: The "Clear Generated Files" button allows you to empty the output list, useful for managing the display after multiple processing runs. ✨

3.2. Processing Logic 🧠

• Selective Processing: If you have selected specific files in the "Input Files" list, only those files will be processed when a "Compress," "Merge," or "Extract POIs" operation is initiated. If no files are selected, the application will process all files currently in the input list. ✅

• Output Directory Management: Generated files are saved into a new directory, automatically named with a timestamp (e.g., gpx_processed_YYYY-MM-DD_HHMMSS), ensuring clean organization of your outputs. This directory path is explicitly logged and made clickable. 📁📅

3.3. Data Optimization ⚙️

The underlying processing engine includes sophisticated optimization techniques:

• min_dist Parameter: During compression and merging, the application uses a configurable minimum distance parameter (min_dist). Track points closer than this distance are removed, reducing file size without significant loss of detail. 🤏

• Metadata Cleaning: Irrelevant metadata (e.g., time, extensions, comments, descriptions, symbols) is stripped from points, tracks, and routes to further reduce file size and declutter the data. 🧼

• Elevation Adjustment:

  • The application attempts to integrate SRTM (Shuttle Radar Topography Mission) elevation data to correct or enhance elevation values in your tracks and waypoints. ⛰️

  • If SRTM data cannot be initialized (e.g., due to network issues or library unavailability), the application gracefully falls back to using the original elevation data present in the GPX/KML files or defaults to zero, ensuring continued functionality. Warnings are logged if SRTM is unavailable. ⚠️

3.4. Logging and Configuration 🚦

• Real-time Logging: The "Log Output" pane provides detailed information about every operation, helping you monitor progress and troubleshoot issues. 🪵

• Configurable Log Level: Adjust the verbosity of the log output (DEBUG, INFO, WARNING, ERROR, CRITICAL) directly from the GUI, allowing you to control the level of detail displayed. 🎚️

• Settings Dialog: Access a comprehensive settings dialog from the "Options -> Settings" menu. Here, you can configure various application parameters, including min_dist, date formats, and other internal settings. Changes made here are saved to config.yaml for persistence across sessions. 🔧💾

4. Usage ▶️

To run the GUI application, execute the following command in your project's root directory:

Run with CLI from source

python -m gpx_kml_converter.cli [OPTIONS] path/to/file

Run with GUI from source

python -m gpx_kml_converter.gui

Once the GUI is launched, you can:

1. Open Files: Click "Open Files" to add GPX/KML files to the input list. ➕📁

2. Select Files (Optional): Click on files in the input list to select them for specific processing. If no files are selected, all loaded input files will be processed. ✅

3. Choose a Processing Mode: Click one of the processing buttons ("Compress," "Merge," "Extract POIs") to start the operation. ▶️

4. Monitor Progress: Observe the log output and the progress bar. ⏳

5. View Results: Check the "Generated Files" list for your processed outputs. Double-click an output file to open it or navigate to its containing directory. 🌟