# ReadMe

<div id="bkmrk-%23-mytools---gps-file"><div>\# MyTools - GPS File Processing Suite</div>  
<div>A comprehensive Docker-based toolkit for GPS and mapping file processing, featuring two powerful applications for converting and extracting GPS data.</div>  
<div>\## 🌟 Applications</div>  
<div>\### 📍 Google GPX Converter (Port 6010)</div><div>Convert Google My Maps (.kmz) files to standard GPX format with a client-side web interface.</div>  
<div>**Features:**</div><div>- 🔄 Convert Google My Maps to GPX format</div><div>- 🌐 Client-side processing (no data uploaded to servers)</div><div>- 📱 Responsive web interface</div><div>- ⚡ Fast, browser-based conversion</div><div>- 🔒 Complete privacy - all processing local</div>  
<div>\### 🚀 Extract GPX Parts (Port 6020)</div><div>Extract and separate components (waypoints, tracks, routes) from GPX container files.</div>  
<div>**Features:**</div><div>- 📦 Extract waypoints, tracks, and routes from GPX files</div><div>- 🖥️ Web interface with drag-drop upload</div><div>- 💾 Batch download as ZIP archives</div><div>- 🔍 File preview and content inspection</div><div>- 📊 Processing statistics and summaries</div><div>- 🗂️ Persistent storage with automatic cleanup</div>  
<div>\## 🚀 Quick Start</div>  
<div>\### Prerequisites</div><div>- Docker with Compose plugin</div><div>- 8GB+ available disk space</div><div>- Ports 6010 and 6020 available</div>  
<div>\### Installation</div>  
<div>1. **Clone the repository:**</div><div>```bash</div><div>git clone https://github.com/your-username/mytools-gps-suite.git</div><div>cd mytools-gps-suite</div><div>```</div>  
<div>2. **Deploy with Docker Compose:**</div><div>```bash</div><div>cd /opt/containerd/myTools</div><div>./deploy.sh</div><div>```</div>  
<div>3. **Access Applications:**</div><div>- **Google GPX Converter:** http://localhost:6010</div><div>- **Extract GPX Parts:** http://localhost:6020</div>  
<div>\## 📂 Directory Structure</div>  
<div>```</div><div>myTools/</div><div>├── docker-compose.yml # Main deployment configuration</div><div>├── deploy.sh # Deployment script</div><div>├── google-gpx-converter/ # Google Maps to GPX converter</div><div>│ ├── Dockerfile</div><div>│ ├── .copilot-instructions.md</div><div>│ ├── index.html</div><div>│ ├── script.js</div><div>│ ├── styles.css</div><div>│ └── url-expander.js</div><div>├── extract-gpx-parts/ # GPX component extractor</div><div>│ ├── Dockerfile</div><div>│ ├── .copilot-instructions.md</div><div>│ ├── gpx_extractor.py # CLI extraction tool</div><div>│ ├── data/ # Persistent storage</div><div>│ │ ├── uploads/ # User uploaded files</div><div>│ │ └── processed/ # Extracted components</div><div>│ └── web/ # Flask web application</div><div>│ ├── app.py</div><div>│ ├── requirements.txt</div><div>│ ├── templates/</div><div>│ └── static/</div><div>└── README.md # This file</div><div>```</div>  
<div>\## 🛠️ Usage</div>  
<div>\### Google GPX Converter</div>  
<div>1. **Open** http://localhost:6010 in your browser</div><div>2. **Upload** a Google My Maps (.kmz) file via drag-drop or file selection</div><div>3. **Convert** - processing happens instantly in your browser</div><div>4. **Download** the resulting GPX file</div>  
<div>**Supported Input Formats:**</div><div>- Google My Maps (.kmz files)</div><div>- Google Maps shared URLs</div>  
<div>**Output Format:**</div><div>- Standard GPX 1.1 format compatible with GPS devices and mapping software</div>  
<div>\### Extract GPX Parts</div>  
<div>1. **Open** http://localhost:6020 in your browser</div><div>2. **Upload** a GPX file containing multiple components</div><div>3. **Review** extracted components in the results table</div><div>4. **Select** individual files or use batch selection</div><div>5. **Download** selected files individually or as a ZIP archive</div>  
<div>**Supported Input:**</div><div>- GPX 1.0 and 1.1 files</div><div>- Large GPS tracks (tested with 900+ waypoints, 28+ tracks)</div><div>- Complex route files with multiple segments</div>  
<div>**Output:**</div><div>- Separate GPX files for waypoints, tracks, and routes</div><div>- Preserved metadata and naming conventions</div><div>- ZIP archives for batch downloads</div>  
<div>\## 🔧 Management Commands</div>  
<div>\### Container Management</div><div>```bash</div><div>\# Start services</div><div>docker compose up -d</div>  
<div>\# Stop services</div><div>docker compose down</div>  
<div>\# View logs</div><div>docker compose logs -f</div>  
<div>\# Restart services</div><div>docker compose restart</div>  
<div>\# Rebuild containers</div><div>docker compose up -d --build</div><div>```</div>  
<div>\### File Management</div><div>```bash</div><div>\# View uploaded files</div><div>ls -la /opt/containerd/myTools/extract-gpx-parts/data/uploads/</div>  
<div>\# View processed files</div><div>ls -la /opt/containerd/myTools/extract-gpx-parts/data/processed/</div>  
<div>\# Clean up old files (optional - auto-cleanup after 1 hour)</div><div>find /opt/containerd/myTools/extract-gpx-parts/data/ -type f -mtime +1 -delete</div><div>```</div>  
<div>\## 🔒 Security &amp; Privacy</div>  
<div>\### Google GPX Converter</div><div>- **100% Client-Side:** No data transmitted to external servers</div><div>- **Browser Processing:** All conversion happens in your browser</div><div>- **No Storage:** Files are not stored after conversion</div><div>- **Open Source:** Transparent processing logic</div>  
<div>\### Extract GPX Parts</div><div>- **Local Processing:** Files processed on your own server</div><div>- **Automatic Cleanup:** Temporary files removed after 1 hour</div><div>- **Secure Upload:** File validation and sanitization</div><div>- **Isolated Environment:** Docker container isolation</div>  
<div>\## 🐛 Troubleshooting</div>  
<div>\### Common Issues</div>  
<div>**Port Conflicts:**</div><div>```bash</div><div>\# Check if ports are in use</div><div>sudo netstat -tlnp | grep -E ':601[0-9]'</div>  
<div>\# Stop conflicting services</div><div>sudo fuser -k 6010/tcp 6020/tcp</div><div>```</div>  
<div>**Container Build Failures:**</div><div>```bash</div><div>\# Clean Docker cache</div><div>docker system prune -a</div>  
<div>\# Rebuild from scratch</div><div>docker compose down</div><div>docker compose up -d --build</div><div>```</div>  
<div>**Permission Issues:**</div><div>```bash</div><div>\# Fix directory permissions</div><div>sudo chown -R gerald:docker /opt/containerd/myTools</div><div>sudo chmod -R 775 /opt/containerd/myTools</div><div>```</div>  
<div>**Storage Issues:**</div><div>```bash</div><div>\# Check disk space</div><div>df -h /opt/containerd/</div>  
<div>\# Clean old files manually</div><div>sudo find /opt/containerd/myTools/extract-gpx-parts/data/ -type f -mtime +1 -delete</div><div>```</div>  
<div>\## 🧪 Development</div>  
<div>\### Local Development Setup</div>  
<div>1. **Google GPX Converter** (Static files):</div><div>```bash</div><div>cd google-gpx-converter</div><div>python -m http.server 8080</div><div>\# Access at http://localhost:8080</div><div>```</div>  
<div>2. **Extract GPX Parts** (Flask development):</div><div>```bash</div><div>cd extract-gpx-parts/web</div><div>python -m venv venv</div><div>source venv/bin/activate</div><div>pip install -r requirements.txt</div><div>python app.py</div><div>```</div>  
<div>\### Testing</div>  
<div>**Test Google GPX Converter:**</div><div>- Download sample .kmz files from Google My Maps</div><div>- Test with various map types (points, routes, areas)</div><div>- Verify GPX output in GPS software</div>  
<div>**Test Extract GPX Parts:**</div><div>- Use provided S.gpx test file (909 waypoints, 28 tracks)</div><div>- Test with various GPX file structures</div><div>- Verify component separation accuracy</div>  
<div>\## 📖 API Documentation</div>  
<div>\### Extract GPX Parts API Endpoints</div>  
<div>- `GET /` - Main upload interface</div><div>- `POST /upload` - Upload and process GPX file</div><div>- `GET /download/&lt;directory&gt;/&lt;filename&gt;` - Download individual file</div><div>- `POST /download-selected` - Download selected files as ZIP</div><div>- `GET /preview/&lt;directory&gt;/&lt;filename&gt;` - Preview file content</div>  
<div>\## 🤝 Contributing</div>  
<div>1. **Fork** the repository</div><div>2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)</div><div>3. **Commit** your changes (`git commit -m 'Add amazing feature'`)</div><div>4. **Push** to the branch (`git push origin feature/amazing-feature`)</div><div>5. **Open** a Pull Request</div>  
<div>\### Development Guidelines</div><div>- Follow existing code style and patterns</div><div>- Add tests for new functionality</div><div>- Update documentation as needed</div><div>- Ensure Docker compatibility</div>  
<div>\## 📄 License</div>  
<div>This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.</div>  
<div>\## 🙏 Acknowledgments</div>  
<div>- **ElementTree** - XML processing for GPX files</div><div>- **Flask** - Web framework for Python applications</div><div>- **JSZip** - JavaScript ZIP file handling</div><div>- **Docker** - Containerization platform</div><div>- **Nginx** - Web server for static file serving</div>  
<div>\## 📞 Support</div>  
<div>For issues, questions, or contributions:</div>  
<div>- **Issues:** Create an issue on GitHub</div><div>- **Discussions:** Use GitHub Discussions for questions</div><div>- **Documentation:** Check `.copilot-instructions.md` in each application directory</div>  
<div>---</div>  
<div>**Made with ❤️ for the GPS and mapping community**</div></div>