python.md

Python SDK

geotrace-sdk reads and writes .gtd files. MIT licensed. Requires Python 3.12+. Distributed as abi3 wheels (one cp312-abi3 wheel per platform, forward-compatible with newer CPython).

Install

uv add geotrace-sdk

Or

pip install geotrace-sdk

Prebuilt wheels:

• Linux: manylinux and musllinux, x86-64 / ARM64 / x86 / armv7 / s390x / ppc64le.
• macOS: x86-64, ARM64.
• Windows: x64, x86, ARM64.

A platform without a matching wheel builds from the source distribution, which requires a Rust toolchain.

Examples

In sdk/python/geotrace-py/examples/. Run with python <name>.py.

• write_basic: minimal write workflow: add fixes, finish, write to disk.
• read_file: read a .gtd file and print a content summary.
• with_satellites: pair each fix with a satellite visibility report.
• with_satellites_and_markers: satellite reports plus custom map annotations placed by interpolation.
• event_markers: write and read hierarchical event markers (variant_path).
• channels: attach scalar and vector sensor channels and read them back.
• event_markers_flat: typed markers via @event_kind, single-level paths.
• event_markers_nested: typed markers via @event_kind, nested paths.
• event_markers_skip: omit variants with event_kind.skip.
• from_csv: convert CSV rows into a .gtd file.
• from_multiple_sources: merge fixes and events from separate sources, interpolating event positions.
• gold_dataset: build the cross-SDK reference file from shared fixtures and verify the round-trip.