Quick Start

This guide will help you get started with Pyehicle.

Data Format

Pyehicle expects trajectory data as pandas/polars DataFrames with columns:

Column	Type	Description
lat	float	Latitude in WGS84
lon	float	Longitude in WGS84
time	string/datetime	Timestamp (configurable)

Example CSV:

lat,lon,time
56.9496,24.1052,2023-01-01 10:00:00
56.9497,24.1053,2023-01-01 10:00:05
56.9498,24.1054,2023-01-01 10:00:10

Basic Usage

import pandas as pd
import pyehicle as pye

# Load GPS data
df = pd.read_csv('trajectory.csv')

# Preprocess
compressed = pye.preprocessing.spatio_temporal_compress(df)
matched = pye.preprocessing.leuven(compressed, lat_col='lat', lon_col='lon')
filtered = pye.preprocessing.kalman_aeqd_filter(matched, lat_col='lat', lon_col='lon', time_col='time')

# Load road network
road_network, geometries, spatial_index = pye.utilities.load_road_network(
    pbf_file_path='map.osm.pbf',
    bbox=(24.0, 56.9, 24.2, 57.0)
)

# Reconstruct trajectory
refined = pye.reconstructing.refine_trajectory(filtered, road_network, max_node_distance=10, time_col='time')
final = pye.reconstructing.curve_interpolation(refined, road_network, lower_threshold=20, upper_threshold=80, max_node_distance=10, time_col='time')

# Visualize
pye.utilities.visualization.single(final, name='Trajectory', show_in_browser=True)

Pipeline Overview

Raw GPS Data → Preprocessing → Reconstruction → Final Refined Trajectory
  (noisy)      (compress,      (combine,         (accurate, road-aligned)
                map-match,      refine,
                kalman)         curve_interp)