TCXReader.jl -- A parser for TCX files

✨ Detailed insights • 📦 Installation • 🚀 Usage • 🐳 Command line and Docker • 📖 Documentation • 🗃️ Datasets • 🔗 Related packages/frameworks • 🔑 License

TCXReader.jl reads Training Center XML (.tcx) workout files produced by Garmin and other fitness devices. It exposes author, device, activity, lap, and track-point data as Julia structs, calculates common activity summaries, and can export track points to CSV. The package API, command-line interface, and container use the same parser.

✨ Detailed insights

• TCXAuthor stores information about the application that created the file, including its name, build version, language, and part number.
• TCXActivity provides the sport, activity timestamp, recording device, laps, and calculated time, distance, heart-rate, cadence, speed, elevation, and power summaries.
• TCXLap stores lap metadata and its ordered track points.
• TCXTrackPoint stores timestamped position, altitude, distance, heart rate, cadence, speed, and power samples. Values absent from the TCX file are represented by nothing.
• Sparse metadata and documents without activities are supported. A malformed individual track point is warned about and skipped so the remaining workout can still be read.

📦 Installation

TCXReader.jl requires Julia 1.10 or later. From the Julia package prompt, run:

pkg> add TCXReader

🚀 Usage

using TCXReader: loadTCXFile

author, activities = loadTCXFile("activity.tcx")

println("Created by: ", author.name)
for activity in activities
    println(activity.sport, ": ", activity.total_distance, " m in ",
            activity.total_time, " s")
end

Pass a second path to write CSV while loading:

author, activities = loadTCXFile("activity.tcx", "trackpoints.csv")

The CSV contains one row per track point and repeats the corresponding author, activity, and lap metadata on each row. Missing optional track-point values become empty cells; laps without track points do not create rows. The column names and order are documented in the usage guide.

The repository also includes a runnable example for its bundled sample files:

julia --project=. examples/reader_demo.jl

🐳 Command line and Docker

Run the dependency-free CLI from a checkout:

julia --project=. bin/tcxreader.jl activity.tcx
julia --project=. bin/tcxreader.jl --csv trackpoints.csv activity.tcx
julia --project=. bin/tcxreader.jl --help

Released images use the CLI as their entrypoint.

docker run --rm -v "$PWD:/data:ro" tilenhlis/tcxreader /data/activity.tcx
docker run --rm -v "$PWD:/data" tilenhlis/tcxreader \
    --csv /data/trackpoints.csv /data/activity.tcx

To open Julia instead of the CLI, override the entrypoint:

docker run --rm -it --entrypoint julia tilenhlis/tcxreader

📖 Documentation

The full manual covers installation and usage, calculation semantics, and the API reference. Release notes are recorded in the changelog.

🗃️ Datasets

Datasets available and used in the examples on the following links: DATASET1, DATASET2, DATASET3.

🔗 Related packages/frameworks

[1] tcxreader: Python reader/parser for Garmin's TCX file format.

[2] sport-activities-features: A minimalistic toolbox for extracting features from sports activity files written in Python

[3] tcxread: A parser for TCX files written in Ruby

[4] TCX2Graph.jl: Building Property Graphs from TCX Files

🔑 License

This package is distributed under the MIT License. This license can be found online at http://www.opensource.org/licenses/MIT.

Disclaimer

This framework is provided as-is, and there are no guarantees that it fits your purposes or that it is bug-free. Use it at your own risk!