# ReadMe

<div id="bkmrk-%23-gpx-parts-extracto"><div>\# GPX Parts Extractor</div>  
<div>A Python tool for extracting different components from a GPX file (waypoints, tracks, routes) into separate files for easier management and analysis.</div>  
<div>\## Overview</div>  
<div>This tool takes a single GPX file containing multiple components and splits them into individual files:</div><div>- **Waypoints** → Single file with all waypoints</div><div>- **Tracks** → Individual files for each track</div><div>- **Routes** → Individual files for each route (if present)</div>  
<div>\## Features</div>  
<div>- ✅ **Namespace-aware parsing** - Handles GPX files with XML namespaces correctly</div><div>- ✅ **Metadata preservation** - Maintains original metadata in extracted files</div><div>- ✅ **Smart file naming** - Uses track/route names for descriptive filenames</div><div>- ✅ **Progress reporting** - Shows detailed extraction progress</div><div>- ✅ **Summary generation** - Creates a summary of all extracted files</div><div>- ✅ **Error handling** - Graceful failure handling with clear error messages</div>  
<div>\## Requirements</div>  
<div>- Python 3.6+</div><div>- Standard library only (no external dependencies)</div>  
<div>\## Installation</div>  
<div>Simply download or clone the `gpx_extractor.py` file to your local machine.</div>  
<div>\## Usage</div>  
<div>\### Basic Usage</div>  
<div>```bash</div><div>python3 gpx_extractor.py input.gpx</div><div>```</div>  
<div>This extracts all components to a directory named `{filename}_extracted` in the same location as the input file.</div>  
<div>\### Custom Output Directory</div>  
<div>```bash</div><div>python3 gpx_extractor.py input.gpx /path/to/output/directory</div><div>```</div>  
<div>\### Examples</div>  
<div>```bash</div><div>\# Extract from your GPS device data</div><div>python3 gpx_extractor.py my_vacation_trip.gpx</div>  
<div>\# Extract to a specific location</div><div>python3 gpx_extractor.py route_collection.gpx ./separated_routes/</div>  
<div>\# Extract the example file</div><div>python3 gpx_extractor.py S.gpx</div><div>```</div>  
<div>\## Output Structure</div>  
<div>After extraction, you'll get:</div>  
<div>```</div><div>output_directory/</div><div>├── filename_waypoints.gpx # All waypoints in one file</div><div>├── filename_track_01_trackname.gpx # Individual track files</div><div>├── filename_track_02_trackname.gpx</div><div>├── ...</div><div>├── filename_route_01_routename.gpx # Individual route files (if any)</div><div>├── ...</div><div>└── filename_extraction_summary.txt # Summary of extraction</div><div>```</div>  
<div>\## Example Output</div>  
<div>When you run the tool on a GPX file like `S.gpx`, you'll see output like this:</div>  
<div>```</div><div>✓ Loaded GPX file: S.gpx</div><div>✓ Root namespace: http://www.topografix.com/GPX/1/1</div>  
<div>Extracting components from S.gpx...</div><div>Output directory: S_extracted</div><div>------------------------------------------------------------</div><div>✓ Extracted 909 waypoints to: S_extracted/S_waypoints.gpx</div><div>✓ Extracted track 1: 'TET_S-01_20260102' (4557 points) to: S_extracted/S_track_01_TET_S-01_20260102.gpx</div><div>✓ Extracted track 2: 'TET_S-02_20260102' (4501 points) to: S_extracted/S_track_02_TET_S-02_20260102.gpx</div><div>...</div><div>✓ Extracted track 28: 'TET_S-28_20260102' (2123 points) to: S_extracted/S_track_28_TET_S-28_20260102.gpx</div><div>ℹ No routes found</div><div>✓ Created extraction summary: S_extracted/S_extraction_summary.txt</div><div>------------------------------------------------------------</div><div>✓ Extraction complete! Created 29 files.</div>  
<div>🎉 All done! Check the output directory for extracted files.</div><div>```</div>  
<div>\## Use Cases</div>  
<div>\### 1. **GPS Device Data Management**</div><div>When your GPS device exports a single large GPX file with multiple tracks from different trips, extract them into individual files for better organization.</div>  
<div>\### 2. **Route Planning**</div><div>Separate waypoints (POIs) from tracks (actual routes) to use them independently in different mapping applications.</div>  
<div>\### 3. **Data Analysis**</div><div>Extract individual tracks for statistical analysis, elevation profiling, or performance comparison.</div>  
<div>\### 4. **Sharing Specific Routes**</div><div>Share only specific tracks from a collection without exposing all your GPS data.</div>  
<div>\### 5. **Application Compatibility**</div><div>Some GPS applications work better with individual track files rather than combined collections.</div>  
<div>\## File Naming Convention</div>  
<div>The tool creates descriptive filenames based on the content:</div>  
<div>- **Waypoints**: `{original_filename}_waypoints.gpx`</div><div>- **Tracks**: `{original_filename}_track_{number:02d}_{track_name}.gpx`</div><div>- **Routes**: `{original_filename}_route_{number:02d}_{route_name}.gpx`</div>  
<div>Track and route names are sanitized to be filesystem-safe (spaces become underscores, special characters removed).</div>  
<div>\## Metadata Handling</div>  
<div>Each extracted file maintains:</div><div>- Original GPX version and namespace declarations</div><div>- Preserved metadata from the source file</div><div>- Updated timestamp reflecting the extraction time</div><div>- Description indicating the extraction source</div>  
<div>\## Error Handling</div>  
<div>The tool provides clear error messages for common issues:</div><div>- File not found</div><div>- Invalid GPX format</div><div>- Permission errors</div><div>- XML parsing errors</div>  
<div>\## Testing</div>  
<div>The tool has been tested with:</div><div>- ✅ Large GPX files (164,000+ lines)</div><div>- ✅ Multiple namespaced XML elements</div><div>- ✅ Complex track structures</div><div>- ✅ Files with 900+ waypoints</div><div>- ✅ Files with 28+ individual tracks</div><div>- ✅ Garmin device exports</div><div>- ✅ Various GPS application formats</div>  
<div>\## Example: S.gpx Results</div>  
<div>The included `S.gpx` test file demonstrates the tool's capabilities:</div>  
<div>**Input**: `S.gpx` (164,775 lines, 20+ MB)</div><div>**Results**:</div><div>- 909 waypoints extracted</div><div>- 28 individual tracks extracted (ranging from 703 to 9,934 track points each)</div><div>- Total of 136,000+ track points processed</div><div>- Complete extraction in under 30 seconds</div>  
<div>\## Command Line Options</div>  
<div>```</div><div>usage: gpx_extractor.py [-h] [--verbose] gpx_file [output_dir]</div>  
<div>Extract waypoints, tracks, and routes from a GPX file into separate files</div>  
<div>positional arguments:</div><div>gpx_file Input GPX file to extract from</div><div>output_dir Output directory (default: same as input file)</div>  
<div>optional arguments:</div><div>-h, --help show this help message and exit</div><div>--verbose, -v Enable verbose output</div><div>```</div>  
<div>\## Troubleshooting</div>  
<div>\### Common Issues</div>  
<div>1. **"No waypoints/tracks found"**</div><div>- Check if your GPX file uses XML namespaces</div><div>- Verify the file is a valid GPX format</div>  
<div>2. **Permission denied**</div><div>- Ensure you have write permissions to the output directory</div><div>- Try running with appropriate permissions</div>  
<div>3. **Large file processing**</div><div>- The tool handles large files efficiently</div><div>- For very large files (&gt;100MB), expect longer processing times</div>  
<div>\### Validation</div>  
<div>To verify successful extraction:</div><div>1. Check the extraction summary file</div><div>2. Verify file counts match expectations</div><div>3. Open extracted files in your preferred GPS application</div><div>4. Compare total point counts with the original file</div>  
<div>\## License</div>  
<div>This tool is provided as-is for educational and practical use. Feel free to modify and distribute according to your needs.</div>  
<div>\## Contributing</div>  
<div>Suggestions and improvements are welcome! Common enhancement areas:</div><div>- Route support improvements</div><div>- Additional output formats</div><div>- GUI interface</div><div>- Batch processing capabilities</div>  
<div>---</div>  
<div>**Created for the extract-gpx-parts project**</div><div>*Making GPX file management easier, one extraction at a time.*</div></div>