Interpolate GPX track points based on distance intervals
npm install gpx-interpolatorTypeScript/Node.js implementation of GPX interpolation using piecewise cubic Hermite splines.
- 📍 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.)
``bash`
npm install gpx-interpolator
Or for development:
`bash`
git clone
cd gpx-interpolator
npm install
npm run build
`bashBasic usage (default 1 meter resolution)
gpx-interpolator your-track.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
``MIT