| Title: | Read and Write C3D Motion Capture Files |
|---|---|
| Description: | A wrapper for the ‘EZC3D’ library to work with C3D motion capture data. |
| Authors: | Simon Nolte [aut, cre] (ORCID: <https://orcid.org/0000-0003-1643-1860>), Benjamin Michaud [cph] (Author of included EZC3D library), German Sport University Cologne [fnd] (ROR: <https://ror.org/0189raq88>), Aymeric Stamm [rev] (reviewed the package (v. 0.1.0) for rOpenSci, see <https://github.com/ropensci/software-review/issues/686>), July Pilowsky [rev] (reviewed the package (v. 0.1.0) for rOpenSci, see <https://github.com/ropensci/software-review/issues/686>) |
| Maintainer: | Simon Nolte <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.1 |
| Built: | 2025-05-04 13:47:47 UTC |
| Source: | https://github.com/ropensci/c3dr |
Get the analog data of a c3d object in a data frame.
c3d_analog(x)c3d_analog(x)
x |
A c3d object, as imported by |
The analog data of imported c3d objects in c3dr is saved as a list of
lists. This is good for internal handling, but for analysis a table format (a
data frame) is often more convenient.c3d_analog() returns the analog data
from an imported c3d object as a data frame.
A data.frame with with n rows and m columns, where n is the number of frames recorded times the number of analog subframes per frame, and m as the number of recorded analog channels.
# Import example data d <- c3d_read(c3d_example()) # get analog data a <- c3d_analog(d) head(a)# Import example data d <- c3d_read(c3d_example()) # get analog data a <- c3d_analog(d) head(a)
Convert between different representations of point data in c3d files.
c3d_convert(data, format)c3d_convert(data, format)
data |
A data frame of class |
format |
Either |
A data frame of class c3d_data in the format specified by the
format argument.
The wide format has three numeric columns per point (x, y, z). The column
names have the structure pointname_type, so for example the x-coordinate of
a point named C7 has the name C7_x. Each row corresponds to one recording
frame.
The long format has one column per point. The column names correspond to the
names of the points. Each recording frame corresponds to three rows of data
(x, y, z). In additional to the point columns containing numeric data there
are two additional columns: One that indicates the frame number (frame,
numeric) and one that indicates the coordinate type (type, either x, y, or
z, as a character).
The longest format has one data column (value, numeric). The other columns
indicate the frame number (frame, numeric), the coordinate type (type,
either x, y, or z, as a character), and the point name (point, character).
Thus, each row of the data frame corresponds to one data entry.
# Import example data d <- c3d_read(c3d_example()) # get point data in wide format w <- c3d_data(d, format = "wide") # convert to long data l <- c3d_convert(w, "long") head(l)# Import example data d <- c3d_read(c3d_example()) # get point data in wide format w <- c3d_data(d, format = "wide") # convert to long data l <- c3d_convert(w, "long") head(l)
Get the point data of an c3d object in a data frame.
c3d_data(x, format = "wide")c3d_data(x, format = "wide")
x |
A c3d object, as imported by |
format |
Either |
The point data of imported c3d objects in c3dr is saved as a list of lists.
This is good for internal handling, but for analysis a table format (a data
frame) is often more convenient.c3d_data() returns the point data from an
imported c3d object as a data frame.
Analyses of data frames may require them to have different formats. For
c3d_data output, different data formats ("wide", "long", "longest")
are available. See the section below for more details. You can convert
between different formats with c3d_convert().
A data frame of class c3d_data with the c3d point data. The
structure of the data frame depends on the 'format' argument.
The wide format has three numeric columns per point (x, y, z). The column
names have the structure pointname_type, so for example the x-coordinate of
a point named C7 has the name C7_x. Each row corresponds to one recording
frame.
The long format has one column per point. The column names correspond to the
names of the points. Each recording frame corresponds to three rows of data
(x, y, z). In additional to the point columns containing numeric data there
are two additional columns: One that indicates the frame number (frame,
numeric) and one that indicates the coordinate type (type, either x, y, or
z, as a character).
The longest format has one data column (value, numeric). The other columns
indicate the frame number (frame, numeric), the coordinate type (type,
either x, y, or z, as a character), and the point name (point, character).
Thus, each row of the data frame corresponds to one data entry.
# Import example data d <- c3d_read(c3d_example()) # wide format (default) w <- c3d_data(d) head(w) # long format l <- c3d_data(d, format = "long") head(l) # longest format ll <- c3d_data(d, format = "longest") head(ll)# Import example data d <- c3d_read(c3d_example()) # wide format (default) w <- c3d_data(d) head(w) # long format l <- c3d_data(d, format = "long") head(l) # longest format ll <- c3d_data(d, format = "longest") head(ll)
Return the file path for an example data files within the c3dr package.
c3d_example()c3d_example()
The test data file contains a short recording of human walking using a full-body model. The test data includes analog channels (e.g., EMG) and data from two force platforms. The recording was made with a Qualisys motion capture system.
The file is taken from https://github.com/pyomeca/ezc3d-testFiles under a GPL-3.0 license.
A character vector with the absolute file path of the example file.
c3d_example()c3d_example()
Import a c3d file using the C++ ezc3d library.
c3d_read(file)c3d_read(file)
file |
A string with the path of a c3d file. |
This function reads a c3d file with biomechanical data. It returns a c3d object, which is a list of all imported data.
The resulting c3d object has the following entries:
header: A list with header parameters containing general
meta data for the recording. nframes is the total number of frames
recorded. npoints is the total number of points recorded. nanalogs is
the number of analog channels. analogperframe is the rate of analog
frames per point recording frame. framerate is the number of point frames
per second. nevents is the number of recorded events.
parameters: A list with meta data of the recording. The parameters are organized in groups, similarly to the original structure in the c3d file.
data: A list with the point data of the recording. Each element in the
list corresponds to one frame. Use c3d_data() to convert the data to a
data frame.
analog: A list with the analog data of the recording. Each element of
the list corresponds to one frame of the point recording and contains a
matrix with all analog channels (as columns) for all subframes (as rows).
Use c3d_analog() to convert the data to a data frame.
forceplatform: A list with force platform data, if available. Each
element in the list corresponds to one force platform. Each force platform
is another list with the following elements: forces is a matrix of the
forces. moments is a matrix of the moments. tz is a matrix of the
moments on the center of pressure. meta is a list with further meta data
of the force platform recording (frames, funit unit of force, munit
unit of moments, punit unit of center of pressure position, calmatrix
calibration matrix, corners position of the corners, origin position of
the origin).
A list of class c3d.
# get example data path path <- c3d_example() d <- c3d_read(path) str(d)# get example data path path <- c3d_example() d <- c3d_read(path) str(d)
Set new data to an existing c3d object.
c3d_setdata(x, newdata = NULL, newanalog = NULL)c3d_setdata(x, newdata = NULL, newanalog = NULL)
x |
A |
newdata |
The new point data that should be written to the |
newanalog |
The new analog data that should be written to the |
This is a basic helper function to allow the modification of data within the
c3dr package for later export. The function call updates the data (point
and/or analog) and the appropriate parameters and header sections. Note that
not all parameters can be updated based on insufficient information. For
example, when using c3d_setdata() for updating the point data, the point
label parameter gets updated (based on the column headers), but the point
label descriptions will be unmodified. This can create minor inconsistencies
in the resulting c3d object, which in the worst case can lead to corrupt data
after export with c3d_write(). If you plan heavy modifications of the data
before export make sure to manually check and update all relevant parameters
as well as the residual data after calling c3d_setdata().
The modified c3d object.
# Import example data d <- c3d_read(c3d_example()) # remove last frame from point data and analog data (10 subframes for analog) d_cut <- c3d_data(d)[-340, ] a_cut <- c3d_analog(d)[-(3391:3400), ] # write the new c3d object d_new <- c3d_setdata(d, newdata = d_cut, newanalog = a_cut) d_new# Import example data d <- c3d_read(c3d_example()) # remove last frame from point data and analog data (10 subframes for analog) d_cut <- c3d_data(d)[-340, ] a_cut <- c3d_analog(d)[-(3391:3400), ] # write the new c3d object d_new <- c3d_setdata(d, newdata = d_cut, newanalog = a_cut) d_new
Write a c3d file using the C++ ezc3d library.
c3d_write(x, file)c3d_write(x, file)
x |
A c3d object. |
file |
A string with the file path to write to. |
This function takes an c3d object in R and writes it to a c3d file. The function creates a new c3d file from scratch and inserts all point data, analog data and parameters in the file. Note that the resulting file will show minor discrepancies compared to the original file (e.g., in terms of file structure). During import and export minor rounding errors can occur.
Force platform data export is currently not supported. The header parameters will not be exported but recreated based on the parameter section. If you want to change the header you should change the appropriate parameters instead.
Be cautious when writing a modified c3d object to an c3d file, as internal
inconsistencies may lead to corrupt files. c3d_write and the underlying
ezc3d function perform some basic checks but may fail if, for example,
parameters and data are inconsistent. You can use the helper function
c3d_setdata() for modifying point or analog data of a c3d object. Larger
modifications may requires expert knowledge of the c3d file structure and
parameters.
Returns its input invisible.
# read an example file d <- c3d_read(c3d_example()) # create a temporary file tmp <- tempfile() on.exit(unlink(tmp)) # write c3d file c3d_write(d, tmp)# read an example file d <- c3d_read(c3d_example()) # create a temporary file tmp <- tempfile() on.exit(unlink(tmp)) # write c3d file c3d_write(d, tmp)
Formatting method for c3d objects
## S3 method for class 'c3d' format(x, ...)## S3 method for class 'c3d' format(x, ...)
x |
A |
... |
empty argument, currently not used. |
A character string with basic information for the c3d object.
# Import example data d <- c3d_read(c3d_example()) format(d)# Import example data d <- c3d_read(c3d_example()) format(d)
Printing method for c3d objects
## S3 method for class 'c3d' print(x, ...)## S3 method for class 'c3d' print(x, ...)
x |
A |
... |
empty argument, currently not used. |
Prints c3d objects by calling format.c3d().
The function prints basic information for the c3d object and returns it invisibly.
# Import example data d <- c3d_read(c3d_example()) print(d)# Import example data d <- c3d_read(c3d_example()) print(d)