README

A PHP package for converting GPX, KMZ, and KML files to LineString format with distance calculations and route densification.

Features

Convert GPX, KMZ, and KML files to LineString format
Automatic file type detection
Densify LineString to have points at regular intervals (default: 100 meters)
Calculate total distance of the track
Calculate distance from start for each point
Compatible with Laravel and other PHP frameworks

Requirements

PHP 7.4 or 8.0+
SimpleXML extension
ZIP extension
Composer

Installation

composer require lachlanhickey/gps-track-converter

Or add this to your composer.json and run composer install:

{
    "require": {
        "lachlanhickey/gps-track-converter": "^1.0"
    }
}

Usage

Basic Usage

use App\GpsTrackConverter;

$converter = new GpsTrackConverter();
$result = $converter->convert('/path/to/track.gpx');

// Access results
$points = $result->points; // Array of point objects
$totalDistance = $result->totalDistance; // in meters

// Access start and finish locations directly
$startPoint = $result->start_location;
$finishPoint = $result->finish_location;

echo "Route starts at: {$startPoint->lat}, {$startPoint->lon}";
echo "Route ends at: {$finishPoint->lat}, {$finishPoint->lon}";
echo "Total distance: {$result->totalDistance} meters";

// Access individual point data
$firstPoint = $points[0];
echo "First point: Lat: {$firstPoint->lat}, Lon: {$firstPoint->lon}, " .
     "Elevation: {$firstPoint->elevation}, " .
     "Distance from start: {$firstPoint->distance_from_start} meters, " .
     "Distance from previous: {$firstPoint->distance_from_previous} meters";

// Calculate average segment length
$totalSegments = count($points) - 1;
$averageSegmentLength = 0;

if ($totalSegments > 0) {
    $totalSegmentLength = 0;
    foreach ($points as $point) {
        $totalSegmentLength += $point->distance_from_previous;
    }
    $averageSegmentLength = $totalSegmentLength / $totalSegments;
}

echo "Average segment length: {$averageSegmentLength} meters";

Laravel Controller Example

namespace App\Http\Controllers;

use App\GpsTrackConverter;
use Illuminate\Http\Request;

class GpsTrackController extends Controller
{
    public function convert(Request $request)
    {
        $request->validate([
            'file' => 'required|file|mimes:gpx,kml,kmz',
        ]);

        $file = $request->file('file');
        $filePath = $file->getPathname();
        $fileType = $file->getClientOriginalExtension();
        
        try {
            $converter = new GpsTrackConverter();
            $result = $converter->convert($filePath, $fileType);
            
            return response()->json([
                'success' => true,
                'data' => $result
            ]);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage()
            ], 400);
        }
    }
}

Return Format

The converter returns an object with the following structure:

stdClass Object (
    [points] => Array (
        [0] => stdClass Object (
            [lat] => 47.123456
            [lon] => 8.123456
            [elevation] => 1234.5
            [distance_from_start] => 0 // in meters
            [distance_from_previous] => 0 // First point has 0 distance from previous
        )
        [1] => stdClass Object (
            [lat] => 47.124567
            [lon] => 8.124567
            [elevation] => 1235.5
            [distance_from_start] => 100.0 // in meters
            [distance_from_previous] => 100.0 // in meters
        )
        // More points...
    )
    [totalDistance] => 12345.67 // Total distance in meters
    [originalPointCount] => 120
    [densifiedPointCount] => 245
    [start_location] => stdClass Object (
        [lat] => 47.123456
        [lon] => 8.123456
        [elevation] => 1234.5
        [distance_from_start] => 0
        [distance_from_previous] => 0
    )
    [finish_location] => stdClass Object (
        [lat] => 47.129876
        [lon] => 8.129876
        [elevation] => 1240.5
        [distance_from_start] => 12345.67
        [distance_from_previous] => 100.0
    )
)

Supported File Formats

GPX

Extracts coordinates from:

Track points (trkpt)
Route points (rtept)
Waypoints (wpt)

KML

Extracts coordinates from:

LineString elements
Point elements

KMZ

Automatically extracts and processes the KML file from the KMZ archive.

Densification

The package can densify routes to have points at regular intervals. This is useful for:

Creating smoother visualizations
Ensuring consistent data for analysis
Generating intermediate points for animations

By default, densification creates points every 100 meters along the route.

Error Handling

The converter throws exceptions for:

Unsupported file types
Files with no coordinates
Invalid file formats
KMZ files without a KML inside

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

lachlanhickey / gps-track-converter

Maintainers

Details