GPX Interpolate - TypeScript

TypeScript/Node.js implementation of GPX interpolation using piecewise cubic Hermite splines.

中文文档 | 快速开始

Features

- 📍 Insert intermediate points between GPX track points
- 🎯 Smooth interpolation using PCHIP (Piecewise Cubic Hermite Interpolating Polynomial)
- 📏 Distance-based interpolation resolution (specify meters between points)
- ⏱️ Preserve and interpolate timestamp information
- 📈 Optional speed calculation and saving
- 🔄 Automatically remove duplicate track points
- 🚫 Gap detection for GPS signal loss
- 📊 Track statistics (distance, duration, elevation gain, etc.)

Installation

``bash
npm install gpx-interpolator
`

Or for development:

`bash
git clone
cd gpx-interpolator
npm install
npm run build
`

CLI Usage

`bash


Basic usage (default 1 meter resolution)

gpx-interpolator your-track.gpx

Specify resolution in meters

gpx-interpolator -r 5 your-track.gpx

Specify output point count

gpx-interpolator -n 1000 your-track.gpx

Only interpolate segments > 100 meters

gpx-interpolator -r 5 -m 100 your-track.gpx

Split track at GPS gaps > 500 meters

gpx-interpolator -r 5 -g 500 your-track.gpx

Custom output file

gpx-interpolator -r 5 -o output.gpx your-track.gpx

Verbose mode with statistics

gpx-interpolator -v your-track.gpx

Show statistics only (no interpolation)

gpx-interpolator --stats-only your-track.gpx

Dry run (preview without saving)

gpx-interpolator --dry-run -r 5 your-track.gpx

Save speed information

gpx-interpolator -s your-track.gpx

Process multiple files

gpx-interpolator *.gpx
`

$3

| Option | Description |
| ----------------------------- | ------------------------------------------------------ |
| -r, --resolution | Interpolation resolution in meters (default: 1.0) |
| -n, --num | Force exact point count in output |
| -m, --min-distance | Only interpolate segments longer than this |
| -g, --max-gap | Split track at gaps larger than this (GPS signal loss) |
| -o, --output | Output file name (single file only) |
| -s, --speed | Save interpolated speed in output |
| -v, --verbose | Verbose output with statistics |
| --dry-run | Preview what would be done without writing files |
| --stats-only | Only show track statistics, don't interpolate |

Module Usage

`typescript
import {
gpxRead,
gpxWrite,
gpxInterpolate,
interpolateTrack,
gpxCalculateStatistics,
gpxDataToPoints,
pointsToGpxData,
} from "gpx-interpolator";

// Read GPX file
const gpxData = gpxRead("input.gpx");

// Basic interpolation (1 meter resolution)
const interpolated = gpxInterpolate(gpxData, 1.0);

// Advanced interpolation with options
const result = interpolateTrack(gpxData, {
resolution: 5, // 5 meters between points
minDistance: 100, // Only interpolate segments > 100m
maxGap: 500, // Split at gaps > 500m
onProgress: (percent) => console.log(${percent}%),
});

// Get statistics
const stats = gpxCalculateStatistics(gpxData);
console.log(Distance: ${stats.totalDistance}m);
console.log(Duration: ${stats.totalDuration}s);
console.log(Elevation gain: ${stats.elevationGain}m);

// Convert between formats
const points = gpxDataToPoints(gpxData); // GPXData -> GPXPoint[]
const data = pointsToGpxData(points); // GPXPoint[] -> GPXData

// Save result
gpxWrite("output.gpx", result);
`

API Reference

$3

#### gpxInterpolate(gpxData, options)

Interpolate GPX data using piecewise cubic Hermite splines.

`typescript
// Simple usage (backward compatible)
gpxInterpolate(gpxData, 1.0); // 1 meter resolution
gpxInterpolate(gpxData, 5.0, 1000); // 5m resolution, force 1000 points

// With options object
gpxInterpolate(gpxData, {
resolution: 5, // meters between points (default: 1.0)
numPoints: null, // force exact point count (overrides resolution)
minDistance: 0, // only interpolate segments > this (default: 0)
maxGap: Infinity, // split at gaps > this (default: Infinity)
preserveOriginal: false, // keep original points (default: false)
onProgress: (p) => {}, // progress callback (0-100)
});
`

#### interpolateTrack(gpxData, options)

Alias for gpxInterpolate with options object. Recommended for new code.

$3

#### gpxRead(filename)

Read GPX data from file.

#### gpxWrite(filename, gpxData, writeSpeed?)

Write GPX data to file.

$3

#### gpxCalculateStatistics(gpxData, maxGap?)

Calculate track statistics:

- totalDistance - Total distance in meters
- totalDuration - Duration in seconds (null if no timestamps)
- pointCount - Number of track points
- avgSpeed / maxSpeed - Speed in m/s
- elevationGain / elevationLoss - Elevation changes
- minElevation / maxElevation - Elevation range
- bounds - Bounding box (minLat, maxLat, minLon, maxLon)
- segmentCount - Number of segments (based on maxGap)

#### gpxDataToPoints(gpxData)

Convert internal GPXData format to user-friendly GPXPoint[] array.

#### pointsToGpxData(points, tzinfo?)

Convert GPXPoint[] array to internal GPXData format.

#### gpxCalculateDistance(gpxData, useEle?)

Calculate distance between consecutive points (Haversine formula).

#### gpxCalculateSpeed(gpxData)

Calculate speed between consecutive points.

#### detectSegments(gpxData, maxGap)

Detect track segments separated by gaps larger than maxGap.

#### haversineDistance(lat1, lon1, lat2, lon2)

Calculate distance between two coordinates in meters.

#### formatDistance(meters) / formatDuration(seconds)

Format values for display.

$3

`typescript
interface GPXData {
lat: number[]; // Latitude array
lon: number[]; // Longitude array
ele: number[] | null; // Elevation array (meters)
tstamp: number[] | null; // Unix timestamps (seconds)
tzinfo: string | null; // Timezone info
}

interface GPXPoint {
lat: number;
lon: number;
ele?: number;
time?: Date;
speed?: number;
}

interface InterpolateOptions {
resolution?: number; // meters between points
numPoints?: number | null;
minDistance?: number;
maxGap?: number;
preserveOriginal?: boolean;
onProgress?: (percent: number) => void;
}

interface TrackStatistics {
totalDistance: number;
totalDuration: number | null;
pointCount: number;
avgSpeed: number | null;
maxSpeed: number | null;
elevationGain: number | null;
elevationLoss: number | null;
minElevation: number | null;
maxElevation: number | null;
bounds: { minLat; maxLat; minLon; maxLon };
segmentCount: number;
}
`

How It Works

1. Read: Parse GPX file and extract lat, lon, elevation, and timestamps
2. Clean: Remove duplicate track points
3. Distance: Calculate distances using Haversine formula (Earth curvature)
4. Segment: Detect gaps (GPS signal loss) and split track if needed
5. Interpolate: Use PCHIP algorithm to smoothly interpolate each dimension
6. Generate: Create new points based on resolution or point count
7. Output: Save to new GPX file or return data structure

Project Structure

`
gpx-interpolator/
├── src/
│ ├── types.ts # TypeScript type definitions
│ ├── pchip.ts # PCHIP interpolation algorithm
│ ├── gpx-utils.ts # GPX utility functions
│ ├── gpx-io.ts # File I/O
│ ├── interpolate.ts # Main interpolation function
│ ├── index.ts # Module exports
│ └── cli.ts # CLI tool
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
``

License

MIT