utdfpy 0.1.1

Read and manipulate Universal Tracking Data Format (UTDF) satellite tracking data

UTDFpy

A Python library for reading and manipulating Universal Tracking Data Format (UTDF) satellite tracking data.

A direct conversion of https://github.com/trwyant/perl-Astro-UTDF. Thanks go to https://github.com/trwyant for creating the Perl module.

Binary Format

UTDF records are 75-byte big-endian binary structures. The library uses explicit big-endian unpacking (struct format >), so it produces identical results on any architecture (arm64, amd64, etc.).

Prerequisites

• Task (task runner)
• Docker (or Podman)

Development

All development tasks run inside a Docker container via Taskfile.yaml. To use Podman instead of Docker:

task tests CONTAINER_BIN=podman

Available tasks

task tests          # Run lint, format check, typecheck, then pytest
task tests:cov      # Run tests with coverage report
task lint           # Run ruff linter
task lint:fix       # Run ruff linter with auto-fix (modifies host files)
task format         # Run ruff formatter (modifies host files)
task format:check   # Check formatting without changes
task typecheck      # Run mypy type checking
task check          # Run all checks (lint, format, typecheck, tests)
task build          # Build distribution packages
task publish        # Build and publish package to PyPI
task utdfpy:install # Install utdfpy from PyPI into local venv
task clean          # Remove build artifacts and caches
task clean:all      # Remove everything including Docker image

Task dependency chain

tests depends on lint, format:check, and typecheck, each of which depends on docker:build. Running task tests will automatically build the Docker image, run the linter, check formatting, and run mypy before executing the test suite. publish depends on tests, so it runs the full check suite before uploading to PyPI.

Installation

pip install utdfpy

Or for development:

pip install -e '.[dev]'

Usage

from utdfpy import UTDFRecord

# Read all records from a UTDF file
records = UTDFRecord.slurp("tracking_data.utd")

for record in records:
    print(record.sic, record.vid, record.decode("measurement_time"))
    print(f"  azimuth:  {record.azimuth}")
    print(f"  elevation: {record.elevation}")
    print(f"  range:    {record.range}")

CLI tool

An interactive query tool is included:

query-utdf tracking_data.utd

Commands: load, count, select, next, list, or type any field name to inspect it.

CI/CD

• GitHub Actions (.github/workflows/ci.yaml): runs lint, tests, and typecheck on push/PR; publishes to PyPI on release.
• GitLab CI (.gitlab-ci.yaml): runs lint, tests (Python 3.10-3.13), and typecheck; publishes to PyPI on version tags.

License

Artistic-2.0 OR GPL-1.0-or-later (same as the original Perl module).

Architecture

classDiagram
    class UTDFRecord {
        -bytes _front
        -str _router
        -int _year
        -int _sic
        -int _vid
        -int _seconds_of_year
        -int _microseconds_of_year
        -float _transponder_latency
        -bool _enforce_validity
        -UTDFRecord _prior_record
        -float _factor_K
        -float _factor_M
        +azimuth() float
        +elevation() float
        +range_delay() float
        +doppler_count() float
        +doppler_shift() float
        +range() float
        +range_rate() float
        +measurement_time() float
        +transmit_frequency() int
        +raw_record() bytes
        +hex_record() str
        +clone() UTDFRecord
        +slurp(file) list~UTDFRecord~
        +iter_file(file) Iterator~UTDFRecord~
        +decode(field_name) str
    }

    class UTDFError {
        <<exception>>
    }

    class InvalidRecordError {
        <<exception>>
    }

    class FrequencyBand {
        <<IntEnum>>
        UNSPECIFIED
        VHF
        UHF
        S_BAND
        C_BAND
        X_BAND
        KU_BAND
        VISIBLE
    }

    class TransmissionType {
        <<IntEnum>>
        TEST
        SIMULATED
        RESUBMIT
        REAL_TIME
        PLAYBACK
    }

    class TrackingMode {
        <<IntEnum>>
        AUTOTRACK
        PROGRAM_TRACK
        MANUAL
        SLAVED
    }

    class TrackerType {
        <<IntEnum>>
        C_BAND_PULSE
        SRE
        SGLS
        TDRSS
    }

    class AntennaGeometry {
        <<IntEnum>>
        AZ_EL
        XY_SOUTH
        XY_EAST
        RA_DEC
        HR_DEC
    }

    Exception <|-- UTDFError
    UTDFError <|-- InvalidRecordError
    UTDFRecord --> UTDFRecord : prior_record
    UTDFRecord ..> InvalidRecordError : raises
    UTDFRecord ..> parsing : uses
    UTDFRecord ..> decode : uses