pixtrail 2.3.1

Extract GPS data from photos and create GPX files

PixTrail

PixTrail is a simple yet powerful tool that extracts the GPS information stored in your photos' EXIF metadata and converts it into standard GPX format that can be used in various mapping applications, allowing you to visualize and share your journeys.

The Story Behind PixTrail

As an avid photographer, I've always enjoyed using the Photos app on iOS and macOS to organize and relive my journeys. While these tools are great for managing photos, I found myself wishing for a way to reconstruct the routes I had taken during day trips or longer journeys based on the photos I captured along the way.

I wanted to see the path I wandered through a city, the trails I hiked in the mountains, or the roads I traveled during a vacation - all visualized on a map using the GPS data already embedded in my photos. This desire to connect my photographic memories with their geographic context led to the creation of PixTrail.

Features

Core Functionality

• GPS Data Extraction: Extract GPS coordinates and timestamps from EXIF metadata in photos
• Route Generation: Create GPX files with waypoints and tracks for use in mapping applications
• OpenStreetMap Integration: Visualize routes directly on interactive maps

Processing Capabilities

• Hybrid Processing Approach:
  • JPEG/TIFF files are processed directly in your browser for faster performance
  • RAW/PNG and other formats are processed on the server with full metadata extraction
• Wide Format Support:
  • Standard Formats: JPG, PNG, TIFF, BMP
  • Professional RAW Formats: CR2, NEF, ARW, ORF, RW2, PEF, SRW, DNG (Canon, Nikon, Sony, Olympus, Panasonic, Pentax, Samsung, digital negative)
• Automated File Management: Automatic cleanup of temporary files to save disk space

User Interface

• Multiple Access Methods:
  • Command-line interface for quick scripting and batch operations
  • Web interface for browser-based visual operation
• Advanced File Management:
  • Directory selection with recursive processing support
  • Intuitive drag & drop interface for files and directories
  • Batch processing of multiple photo collections

Advanced Visualization Features

• Heat Map Visualization: See where you spent the most time on your journey with color-coded intensity maps
• Marker Clustering: Group nearby photos for cleaner map displays with adjustable radius
• Statistical Analysis: View distance, elevation, speed, and time metrics for your journey
• Interactive Charts: Visualize elevation profiles and speed variations throughout your route

Privacy

PixTrail processes all photo metadata locally on your device. No data is uploaded to any server, shared with third parties, or sent anywhere outside your computer. Your location data and photos remain completely private and under your control at all times.

When using the web interface:

• JPEG/TIFF files are processed entirely in your browser - only extracted GPS coordinates are sent to the local server
• RAW/PNG files are temporarily cached (local) during processing and automatically deleted afterward
• Only the generated GPX files are stored (local)

Installation

Basic Installation

pip install pixtrail

Installation with Web Interface

pip install pixtrail[web]

Install from Source

git clone https://github.com/sukitsubaki/pixtrail.git
cd pixtrail
pip install -e .

Usage

Command Line

# Basic usage
pixtrail -i /path/to/photos

# Specify output file
pixtrail -i /path/to/photos -o /path/to/output.gpx

# Search recursively in subdirectories
pixtrail -i /path/to/photos -r

# Enable verbose output
pixtrail -i /path/to/photos -v

# Batch process multiple directories
pixtrail -b /path/to/photos1 /path/to/photos2 /path/to/photos3

# Batch process with a common output directory
pixtrail -b /path/to/photos1 /path/to/photos2 -d /path/to/gpx_output

# Start the web interface
pixtrail -w

# Start the web interface on a specific host and port
pixtrail -w --host 0.0.0.0 --port 8080

# Start the web interface without automatically opening a browser
pixtrail -w --no-browser

Web Interface

The web interface provides a user-friendly way to upload photos, extract GPS data, visualize routes on a map, and download GPX files:

1. Start the web interface:

   pixtrail -w
   

2. Your browser will automatically open to the PixTrail interface

3. Select photos using one of the following methods:

   • Click "Select Photos" to choose individual files
   • Click "Select Directory" to choose an entire folder
   • Drag and drop images directly into the interface

4. For directory processing, you can enable recursive subdirectory scanning

5. PixTrail will process the photos and display the route on a map

6. Use the map controls to:

   • Toggle the heatmap to visualize dwell time
   • Enable clustering for better visibility of dense photo areas
   • View statistics and charts for distance, elevation, and speed

7. Download the GPX file for use in other applications

Python API

from pixtrail.core import PixTrail

# Create a PixTrail object
pt = PixTrail()

# Process a directory of images
gps_data = pt.process_directory("/path/to/photos", recursive=True)

# Generate a GPX file
pt.generate_gpx("/path/to/output.gpx")

# Or do both in one step
pt.process_and_generate("/path/to/photos", "/path/to/output.gpx", recursive=True)

Requirements

• Python 3.6 or newer
• exifread
• gpxpy
• Pillow
• Flask (for web interface)
• Chart.js (automatically included in web interface)

Example

After running PixTrail on a directory of geotagged photos, you'll get a GPX file that can be imported into mapping software like:

• OpenStreetMap
• Google Earth
• GPX viewers
• Mapping applications on smartphones and GPS devices

Documentation

The PixTrail documentation is available in several formats:

• Online Documentation: Visit the documentation website
• Local Documentation: Build the documentation locally by installing the development dependencies and running:

  # Install development dependencies
  pip install -e ".[dev]"
  
  # Build documentation
  python build_docs.py
  
  # OR serve locally with live reloading
  python build_docs.py --serve
  

• Source Documentation: Browse the documentation in the docs directory:
  • User Guide
  • Web Interface
  • API Reference

Future Roadmap

Here are some features we're planning to add in future releases:

• Time-based Filtering: Process only photos within specific time windows
• Route Smoothing: Algorithm to reduce GPS inaccuracies
• Custom Map Styles: Support for different map providers and styles
• Video Support: Extract GPS data from video files
• Offline Map Functionality: Preloadable maps for use without internet connection
• Multilingual Support: Internationalization of the user interface
• Interactive Web Export: Share routes as standalone HTML pages with embedded photos
• Map Screenshot Export: Save the current map view as an image file
• Map Enhancements:
  • Support for multiple map providers
  • Customizable map styles
  • More detailed route information

Contributing

Contributions and suggestions for additional features are welcome! Here's how you can help:

• Bug Reports: If you encounter any issues, please open an issue on GitHub with details about the problem, including steps to reproduce it.
• Feature Requests: Have an idea for a new feature? Feel free to create an issue describing your suggestion.
• Code Contributions: Want to contribute code? Fork the repository, make your changes, and submit a pull request.
• Documentation: Help improve the documentation by fixing errors or adding examples.

Please follow these guidelines when contributing:

• Follow the existing code style
• Add tests for new functionality
• Update documentation as needed
• Keep pull requests focused on a single change

Development Setup

# Clone the repository
git clone https://github.com/sukitsubaki/pixtrail.git
cd pixtrail

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev,web]"

# Run tests
pytest

License

• This project is licensed under the MIT License by Suki Tsubaki.
• The example photos are licensed under CC BY 4.0 by Anil Öztas.