Ezc3d: An Open Source Library Based on C++

ezc3d: A Powerful Tool for Biomechanical Data Processing

In biomechanical research, data storage and processing are crucial steps. The C3D file format, as a widely used standard, is specifically designed for storing biomechanical data, such as three-dimensional motion capture data and force platform data. However, for a long time, the biomechanics field has lacked a simple, free, and open-source library to read, modify, and write C3D files. The emergence of ezc3d perfectly addresses this issue.

What is ezc3d?

ezc3d is an open-source library written in C++ specifically for processing C3D files. It not only provides functionality for reading and writing C3D files but also supports modifications to the file content. Additionally, ezc3d offers bindings for Python and MATLAB, making it convenient for users in different programming environments. The goal of ezc3d is to provide biomechanical researchers with a lightweight and comprehensive tool to efficiently process and analyze data.

Main Features of ezc3d

1. Reading and Writing C3D Files: ezc3d provides a simple and easy-to-use API for quickly reading and writing C3D files. Whether reading data from a file or writing processed data to a new file, it can be accomplished with just a few lines of code.
2. Modifying C3D File Content: Users can easily modify data within C3D files, such as adding or removing marker points and changing the sampling rate. This makes ezc3d not just a data reading tool but also a powerful data processing tool.
3. Force Platform Data Processing: The force platform data format stored in C3D files is relatively complex, and ezc3d provides a dedicated force platform analysis module. This module can convert force and moment data into more common reference frames, such as global or center of mass reference frames. This allows users to directly use this data for further analysis.
4. Cross-Platform Support: ezc3d supports multiple operating systems, including Windows, Linux, and macOS. Whether using C++, Python, or MATLAB, users can seamlessly use ezc3d across different platforms.

Using ezc3d

The usage of ezc3d is very straightforward. Below is an example code written in C++ that demonstrates how to create an empty C3D file and add some data:

#include "ezc3d/ezc3d_all.h"

int main() {
    // Create an empty C3D file
    ezc3d::c3d c3d_empty;

    // Set sampling rate
    ezc3d::ParametersNS::GroupNS::Parameter pointRate("RATE");
    pointRate.set(std::vector<float>{100}, {1});
    c3d_empty.parameter("POINT", pointRate);

    ezc3d::ParametersNS::GroupNS::Parameter analogRate("RATE");
    analogRate.set(std::vector<float>{1000}, {1});
    c3d_empty.parameter("ANALOG", analogRate);

    // Add marker points and analog channels
    c3d_empty.point("new_marker1");
    c3d_empty.point("new_marker2");
    c3d_empty.analog("new_analog1");
    c3d_empty.analog("new_analog2");

    // Fill data
    ezc3d::DataNS::Frame f;
    std::vector<std::string> labels(c3d_empty.parameters().group("POINT").parameter("LABELS").valuesAsString());
    int nPoints(c3d_empty.parameters().group("POINT").parameter("USED").valuesAsInt()[0]);
    ezc3d::DataNS::Points3dNS::Points pts;
    for (size_t i = 0; i < static_cast<size_t>(nPoints); ++i) {
        ezc3d::DataNS::Points3dNS::Point pt;
        pt.name(labels[i]);
        pt.x(1.0);
        pt.y(2.0);
        pt.z(3.0);
        pts.point(pt);
    }
    ezc3d::DataNS::AnalogsNS::Analogs analog;
    ezc3d::DataNS::AnalogsNS::SubFrame subframe;
    for (size_t i = 0; i < c3d_empty.header().nbAnalogs(); ++i) {
        ezc3d::DataNS::AnalogsNS::Channel c;
        c.data(i + 1);
        subframe.channel(c);
    }
    for (size_t i = 0; i < c3d_empty.header().nbAnalogByFrame(); ++i)
        analog.subframe(subframe);

    // Add data to the frame
    f.add(pts, analog);
    c3d_empty.frame(f);
    c3d_empty.frame(f);

    // Print C3D file content
    c3d_empty.print();

    return 0;
}
</size_t></std::string></float></float>

Installing ezc3d

For Python users, ezc3d can be quickly installed via pip or Anaconda. Enter the following command in the terminal to complete the installation:

pip install ezc3d

Or:

conda install conda-forge::ezc3d

For MATLAB users, precompiled binaries can be downloaded from the Release page on GitHub.

Conclusion

With its ease of use, powerful features, and cross-platform support, ezc3d has become the preferred tool for processing C3D files in the biomechanics field. Whether you are a biomechanical researcher, sports scientist, or developer in related fields, ezc3d can help you efficiently process and analyze biomechanical data.

If you find it useful, please follow, like, and share. Mark the public account with a five-pointed star to receive updates promptly.