telemachus

Python SDK for the Telemachus open telematics format — read, validate, convert, and introspect high-frequency GNSS+IMU datasets.

pip install telemachus

Try it in 5 minutes: the AEGIS demo notebook (open in Colab) downloads a real Zenodo dataset, loads it, and plots one trip.

Read a dataset

import telemachus as tele

df = tele.read("path/to/manifest.yaml")   # → pandas DataFrame
print(tele.sensor_profile(df))             # → "gps+imu+gyro"

Sensor introspection

tele.has_gps(df)       # True if lat, lon, speed_mps non-NaN
tele.has_imu(df)       # True if ax, ay, az non-NaN
tele.has_gyro(df)      # True if gx, gy, gz present
tele.has_magneto(df)   # True if mx, my, mz present
tele.has_obd(df)       # True if speed_obd or rpm present
tele.has_io(df)        # True if ignition or voltage present
tele.is_full_imu(df)   # accel + gyro
tele.is_gps_only(df)   # GPS but no IMU

Validate

report = tele.validate(df, profile="imu")
print(report)
# ValidationReport(PASS, profile=imu, level=basic, errors=0, warnings=0)

report = tele.validate_dataset("path/to/dataset/", level="full")

Three profiles adapt validation to hardware capabilities:

Convert Open datasets

tele convert aegis /path/to/aegis/csvs -o datasets/aegis/
tele convert pvs /path/to/pvs/trips -o datasets/pvs/ --placement dashboard
tele convert stride /path/to/stride/road_data -o datasets/stride/ --category driving

Supported Open datasets:

CLI

tele validate path/to/manifest.yaml          # validate manifest
tele validate path/to/dataset/ --level full   # validate dataset
tele info path/to/manifest.yaml               # dataset summary
tele convert aegis /data/aegis -o out/        # convert Open dataset

Telemachus record format

A Telemachus record is a flat Parquet row with 7 functional groups:

Full specification: SPEC-01 | SPEC-02 | SPEC-03

Development

git clone https://github.com/telemachus3/telemachus
cd telemachus/python-sdk
pip install -e .[dev]
pytest                  # 31 tests

License

AGPL-3.0