activereader

activereader

Python library for reading Garmin TCX and GPX running activity files.

Example

activereader provides the Tcx and Gpx file reader classes.

TCX and GPX files can be exported from Garmin Connect.

Use Tcx to read and access data from a TCX file:

import pandas as pd

from activereader import Tcx

reader = Tcx.from_file('tests/testdata.tcx')

# Build a DataFrame using only trackpoints (as records).
initial_time = reader.activity_start_time
records = [
  {
    'time': int((tp.time - initial_time).total_seconds()),
    'lat': tp.lat,
    'lon': tp.lon,
    'distance': tp.distance_m,
    'elevation': tp.altitude_m,
    'heart_rate': tp.hr,
    'speed': tp.speed_ms,
    'cadence': tp.cadence_rpm,
  } for tp in reader.trackpoints
]

df = pd.DataFrame.from_records(records)

Background

This project originated as the file-reading part of my heartandsole package. Lately, I've been interested in keeping my work in more self-contained modules with lighter dependencies, so I split it out.

The idea is to provide a simple API for accessing data from Garmin files, similar to the way python-fitparse provides access to Garmin's impenetrable .fit files. I don't aim to do everything, though; I want to just focus on activity files that represent runs (and maybe walks/hikes) for now. When I try to cover all cases, the schemas and profiles quickly grow out of control. Garmin seems to have a reputation for making their files indecipherable, and I like solving puzzles, so I will focus on translating Garmin's language into human language. This is in opposition to waiting for Garmin to document all the features of all its files.

Tangent time: when I was working on picking apart Garmin's.fit file structure with my own device's files, there were a number of undocumented, indecipherable fields. Add to that, Garmin does not seem to keep documentation online for its older .fit SDKs, so if your device uses an older one, you might just be out of luck trying to decipher it. I would rather keep my own separate source of truth, than count on Garmin's being forthcoming with info.

Dependencies and Installation

lxml and python-dateutil are required.

The package is available on PyPi and can be installed with pip:

$ pip install activereader

License

This project is licensed under the MIT License. See LICENSE file for details.

Project Status

The project has reached a stable point and I don't expect to be changing much for now - future versions will likely build on what's here. But sometimes I change my mind and tear everything apart, so who knows. This package will remain focused on extracting data from GPX and TCX files...of that I feel sure.

Complete

• Develop capability to read running tcx and gpx files.

Current Activities

• Handle pauses and laps in files (things I avoid in my own workouts because they complicate and obscure the DATA!). The body keeps the score, but the watch keeps the stats.

Future Work

• Expand capability to read running activity files

  • .pwx (is this Garmin?)

• Make a project wiki so I can be as verbose as I please. (You mean this isn't you being verbose?)

Contact

Reach out to me at one of the following places!

• Website: trailzealot.com
• LinkedIn: linkedin.com/in/aarondschroeder
• Twitter: @trailzealot
• Instagram: @trailzealot
• GitHub: github.com/aaron-schroeder