TRC Data Reader

A lightweight Python package for reading, processing, and writing track row column (TRC) motion capture data. It also includes interoperability with binary C3D files (via the c3d package), allowing for easy conversion between formats.

The TRCData object behaves like a standard Python dictionary, providing simple, direct access to all header metadata and time-series marker data.

Installation

pip install trc-data-reader

Usage

The TRCData object is the main entry point.

from trc import TRCData

# Create an instance.
mocap_data = TRCData()

1. Loading Data

You can load data from a TRC file, a C3D file, or parse it directly from a string.

Load from a .trc file:

mocap_data.load('path/to/my_data.trc')

Load from a .c3d file:

# Requires the 'c3d' package to be installed (pip install c3d)
mocap_data.import_from('path/to/my_data.c3d')

Parse from a multi-line string:

data_string = """PathFileType	4	(X/Y/Z)	filename.trc
DataRate	CameraRate	NumFrames	NumMarkers	Units	OrigDataRate	OrigDataStartFrame	OrigNumFrames
60.0	60.0	2	1	mm	60.0	1	2
Frame#	Time	Marker1
		X1	Y1	Z1
1	0.000	1.0	2.0	3.0
2	0.017	1.1	2.1	3.1
"""
mocap_data.parse(data_string)

2. Accessing Data

The object works like a dictionary. Header metadata is stored as top-level keys, as is marker data.

Accessing Header Metadata:

print(f"File: {mocap_data['FileName']}")
print(f"Total Frames: {mocap_data['NumFrames']}")
print(f"Data Rate: {mocap_data['DataRate']} Hz")
print(f"Available Markers: {mocap_data['Markers']}")

Accessing Marker Data (Time-Series):

This is the most common use case. Accessing a marker by its name gives you its complete time-series data.

# Get all [X, Y, Z] coordinates for the 'Marker1'
marker_data = mocap_data['Marker1']

# Get the coordinates for the first frame (index 0)
print(marker_data[0])
# Output: [1.0, 2.0, 3.0]

# Get the coordinates for the second frame (index 1)
print(marker_data[1])
# Output: [1.1, 2.1, 3.1]

Accessing Data by Frame:

You can also access all data for a specific frame by using the frame number as the key.

# Get all data for Frame 1
frame, (time, marker_list) = 1, mocap_data[1]

print(f"Frame: {frame}")
print(f"Time: {time}")
print(f"All Marker Coords: {marker_list}")
# Output:
# Frame: 1
# Time: 0.0
# All Marker Coords: [[1.0, 2.0, 3.0]]

3. Saving Data

You can save the loaded (or modified) data back to a TRC file.

# ...after loading or modifying data
mocap_data.save('path/to/output_file.trc')

Developing

To install for development, clone the repository and install in editable mode with test dependencies:

git clone https://github.com/hsorby/trc-data-reader.git
cd trc-data-reader
pip install -e ".[test]"

Run tests from the root directory:

python -m unittest discover -s tests

Run coverage analysis, from the same directory:

coverage run --source src -m unittest discover
coverage report -m

This project strives to maintain 100% code coverage. To help meet this goal, we would like for all pull requests to include tests for new functionality or bug fixes.

• New Features: Should include tests to validate the new behavior.

• Bug Fixes: Should include a regression test (one that fails without your fix and passes with it).

Pull requests that do not include tests that lower the overall code coverage will be asked for updates before being merged. Minor code improvements should not, in general, require any new tests in a pull request.