ktk.read_c3d

Contents

ktk.read_c3d#

read_c3d(filename, *, convert_point_unit=None, include_event_context=False, **kwargs)[source]#

Read point, analog and rotation data from a C3D file.

If available, point positions are returned in output[“Points”] as a TimeSeries, where each point corresponds to a data key. Each point position is expressed as an Nx4 point series:

[
    [x0, y0, z0, 1.0],
    [x1, y1, z1, 1.0],
    [x2, y2, z2, 1.0],
    ...,
]

If available, analog data is returned in output[“Analogs”] as a TimeSeries, where each analog signal is expressed as a unidimensional array of length N.

If available, transform matrices are returned in output[“Rotations”] as a TimeSeries, where each matrix series is expressed as an Nx4x4 series.

Some applications store calculated values such as angles, forces, moments, powers, etc. into the C3D file. Storing these data is application-specific and is not standardized in the C3D file format (https://www.c3d.org). This function reads these values as points regardless of their nature.

Parameters:

  • filename (str) – Path of the C3D file

  • convert_point_unit (bool | None) – Optional. True to convert the point units to meters, if they are expressed in other units such as mm in the C3D file. False to keep points as is. When unset, if points are stored in a unit other than meters, then a warning is issued. See caution note below.

  • include_event_context (bool) – Optional. True to include the event context, for C3D files that use this field. If False, the events in the output TimeSeries are named after the events names in the C3D files, e.g.: “Start”, “Heel Strike”, “Toe Off”. If True, the events in the output TimeSeries are named using this scheme “context:name”, e.g.,: “General:Start”, “Right:Heel strike”, “Left:Toe Off”. The default is False.

Returns:

A dict of TimeSeries, with keys being, if available: “Points”, “Analogs” and/or “Rotations”.

Return type:

dict[ktk.TimeSeries]

Caution

If, for a given C3D file, points are expressed in another unit than meters (e.g., mm), and that this file also contains calculated points such as angles, powers, etc., then you need to be cautious with the convert_point_unit parameter:

  • Setting convert_point_unit to False reads the file as is, but you then need to manually convert the points to meters. This can be done easily using ktk.geometry.scale.

  • Setting convert_point_unit to True scales all points to meters, but also scales every calculated angle, power, etc. as they are read as any other point.

For these special cases, we recommend to set convert_point_unit to False, and then scale the points manually.

Warning

This function, which has been introduced in version 0.9, is still experimental and its behaviour or API may change slightly in the future.

See also

ktk.write_c3d, ktk.geometry.scale

Notes

  • This function relies on ezc3d, which is installed by default using conda, but not using pip. Please install ezc3d before using read_c3d. pyomeca/ezc3d

  • As for any instrument, please check that your data loads correctly on your first use (e.g., sampling frequency, position unit). It is possible that read_c3d misses some corner cases.

Contents