Crate tracematch 

Route Matcher

High-performance GPS route matching library for fitness applications.

This library provides:

• GPS route matching using Average Minimum Distance (AMD)
• Route grouping and clustering algorithms
• Frequent section detection (multi-scale)
• Activity heatmap generation
• Modular route engine with persistence support
• Parallel processing for batch operations

Features

• parallel - Enable parallel processing with rayon
• persistence - Enable SQLite persistence for route engine
• ffi - Enable FFI bindings for mobile platforms (iOS/Android)

Quick Start

use tracematch::{GpsPoint, RouteSignature, MatchConfig, compare_routes};

// Create route signatures from GPS points
let route1 = vec![
    GpsPoint::new(51.5074, -0.1278),
    GpsPoint::new(51.5080, -0.1290),
    GpsPoint::new(51.5090, -0.1300),
];

let route2 = route1.clone(); // Same route

let sig1 = RouteSignature::from_points("activity-1", &route1, &MatchConfig::default());
let sig2 = RouteSignature::from_points("activity-2", &route2, &MatchConfig::default());

if let (Some(s1), Some(s2)) = (sig1, sig2) {
    if let Some(result) = compare_routes(&s1, &s2, &MatchConfig::default()) {
        println!("Match: {}% ({})", result.match_percentage, result.direction);
    }
}

Re-exports

pub use error::OptionExt;

pub use error::Result;

pub use error::RouteMatchError;

pub use union_find::UnionFind;

pub use matching::compare_routes;

pub use grouping::group_incremental;

pub use grouping::group_signatures_parallel;

pub use grouping::group_signatures_parallel_with_matches;

pub use grouping::group_signatures;

pub use grouping::group_signatures_with_matches;

pub use grouping::should_group_routes;

pub use engine::ActivityData;

pub use engine::ActivityStore;

pub use engine::ModularEngineStats;

pub use engine::ModularRouteEngine;

pub use engine::RouteGrouper;

pub use engine::SignatureStore;

pub use engine::SpatialIndex;

pub use persistence::GroupSummary;

pub use persistence::PERSISTENT_ENGINE;

pub use persistence::PersistentEngineStats;

pub use persistence::PersistentRouteEngine;

pub use persistence::SectionDetectionHandle;

pub use persistence::SectionSummary;

pub use persistence::with_persistent_engine;

pub use sections::DetectionStats;

pub use sections::FrequentSection;

pub use sections::MultiScaleSectionResult;

pub use sections::PotentialSection;

pub use sections::ScalePreset;

pub use sections::SectionConfig;

pub use sections::SectionMatch;

pub use sections::SectionPortion;

pub use sections::SplitResult;

pub use sections::detect_sections_from_tracks;

pub use sections::detect_sections_multiscale;

pub use sections::find_sections_in_route;

pub use sections::recalculate_section_polyline;

pub use sections::split_section_at_index;

pub use sections::split_section_at_point;

pub use heatmap::ActivityHeatmapData;

pub use heatmap::CellQueryResult;

pub use heatmap::HeatmapBounds;

pub use heatmap::HeatmapCell;

pub use heatmap::HeatmapConfig;

pub use heatmap::HeatmapResult;

pub use heatmap::RouteRef;

pub use heatmap::generate_heatmap;

pub use heatmap::query_heatmap_cell;

pub use http::ActivityFetcher;

pub use http::ActivityMapResult;

pub use http::MapBounds;

Modules

algorithms

Algorithm Toolbox

engine

Modular Route Engine

error

Unified error handling for the tracematch library.

ffi

FFI bindings for mobile platforms (iOS/Android).

geo_utils

Geographic Utilities

grouping

Route grouping algorithms.

heatmap

Heatmap generation with route intelligence.

http

HTTP client for intervals.icu API with rate limiting.

matching

Route matching algorithms using Average Minimum Distance (AMD).

persistence

Persistent Route Engine

sections

Adaptive Consensus Section Detection

union_find

Union-Find (Disjoint Set Union) data structure.

Structs

ActivityMatchInfo

Match info for an activity within a route group. Stores how well the activity matches the representative route.

ActivityMetrics

Activity metadata for performance calculations. Stores the non-GPS data needed for performance comparison.

Bounds

Bounding box for a route.

CustomSection

A user-created custom section definition.

CustomSectionMatch

A match between a custom section and an activity.

CustomSectionMatchConfig

Configuration for custom section matching.

GpsPoint

A GPS coordinate with latitude and longitude.

GroupingResult

Result from grouping signatures, including per-activity match info.

MatchConfig

Configuration for route matching algorithms.

MatchResult

Result of comparing two routes.

RouteBounds

Bounding box for a route (used for spatial indexing).

RouteGroup

A group of similar routes.

RoutePerformance

A single performance point for route comparison.

RoutePerformanceResult

Complete route performance result.

RouteSignature

A simplified route signature for efficient matching.

SectionLap

A single lap of a section.

SectionPerformanceRecord

Section performance record for an activity.

SectionPerformanceResult

Complete section performance result.

Functions

elapsed_ms

Helper to calculate elapsed milliseconds from an Instant