geotrace-sdk 0.3.0

Python bindings for geotrace-sdk - read and write .gtd navigation data files

geotrace-sdk

Python bindings for the GeoTrace SDK: read and write .gtd GNSS/GPS navigation data files.

.gtd is the open binary recording format used by GeoTrace, a desktop application for visualizing GPS/GNSS navigation data: position traces on a map, satellite signal quality, event markers, and filtering.

MIT licensed. Requires Python 3.12+.

Install

uv add geotrace-sdk

Or

pip install geotrace-sdk

Distributed as abi3 wheels (one cp312-abi3 wheel per platform, forward-compatible with newer CPython) for Linux (manylinux and musllinux), macOS, and Windows. A platform without a matching wheel builds from the source distribution, which requires a Rust toolchain.

Write a track

from datetime import datetime, timezone
from geotrace_sdk import NavFileBuilder, NavFix

builder = NavFileBuilder()
builder.add(NavFix(
    lat=51.5074,
    lon=-0.1278,
    gps_time=datetime(2024, 1, 15, 9, 0, 0, tzinfo=timezone.utc),
    heading=90.0,
))
builder.finish().write_to_file("track.gtd")

add() also accepts satellite reports, map annotations, and event markers.

Read a file

from geotrace_sdk import NavFile

nav_file = NavFile.open("track.gtd")
print(len(nav_file.points), "points,", len(nav_file.markers), "markers")
for point in nav_file.points:
    print(point.lat, point.lon, point.gps_time)

Examples

Runnable examples are in sdk/python/geotrace-py/examples:

• write_basic: minimal write workflow.
• read_file: read a .gtd file and print a content summary.
• with_satellites: pair each fix with a satellite visibility report.
• event_markers: write and read hierarchical event markers.
• from_csv: convert CSV rows into a .gtd file.
• from_multiple_sources: merge fixes and events from separate sources.
• gold_dataset: build the cross-SDK reference file and verify the round-trip.

Full list and per-platform notes: docs/sdk/python.md.

Links

• Source and issues: https://github.com/CramBL/geotrace
• Changelog: https://github.com/CramBL/geotrace/blob/trunk/CHANGELOG_SDK.md