14. Data Formats¶

14.1. Video Data¶

Example structure of video data.

The video data for a single trial must be contained in its own folder, and each video file must be in its own subfolder. The name of each subfolder must be the ID of the corresponding camera. There are no requirements on the structure of the names of the video files, but the names must be unique and videos must be .avi or .mp4 format. For example, the figure above shows video data for a walking trial collected using four cameras with IDs 21375, 21379, 21380, and 21381.

Organizing your videos in this format can be achieved using the Organize Videos tool.

It is also best practice to keep the associated extrinsic calibration file nested within the trial folder and beside the camera ID folders. This can be achieved using the Assign Calibration Files tool.

14.2. Camera Calibration¶

Camera and image coordinate system conventions.

The camera calibration file contains the calibrations for all of the cameras using a structure similar to XML. An example calibration file is provided with the sample data. Key elements and attributes of the calibration file are outlined here. Note that Qualisys calibrations exported from QTM as .txt files and Vicon calibrations (.xcp) can also be used.

<calibration>	Top level element with no attributes.
<cameras>	Grouping element that holds <camera> child elements. It has no attributes.
<camera>	Element that holds the calibration information for a single camera. Required attributes are: active, serial, and viewrotation. Required child elements are: <transform> and <intrinsic>. active: 1 if the camera is used, 0 if unused. serial: The camera ID. Must be unique to the camera and match the camera ID used to name the video subfolders. viewrotation: Rotation of the camera. 0 if upright, 180 if upside down, 90 or 270 if sideways. This is calculated from the rotation matrix of the calibration.
<transform>	Translation and rotation components of the transformation from global to camera coordinates \((\vec{p}_{cam}=R\vec{p}_{global}+\vec{t})\). Required attributes are x, y, z and r11 through r33. x, y, z: Elements of the translation component \((\vec{t})\) of the transformation. Expressed in mm. rij: Elements of row i and column j of the rotation component \((R)\) of the transformation.
<intrinsic>	Intrinsic camera parameters. Required attributes are: focallength, sensorMinU, sensorMaxU, sensorMinV, sensorMaxV, focalLengthU, focalLengthV, centerPointU, centerPointV, skew, radialDistortion1-3, and tengentialDistortion1-2. focallength: Focal length of the lens in mm. sensorMinU: Minimum u coordinate of the sensor in pixels. sensorMaxU: Maximum u coordinate of the sensor in pixels. sensorMinV: Minimum v coordinate of the sensor in pixels. sensorMaxV: Maximum v coordinate of the sensor in pixels. focalLengthU: Focal length along the u axis in pixels. focalLengthV: Focal length along the v axis in pixels. centerPointU: Principal point u coordinate in pixels. centerPointV: Principal point v coordinate in pixels. skew: Skew coefficient. Non-zero if the image axes are not perpendicular. Note that non-zero skew is currently unsupported. radialDistortion1-3: Radial distortion coefficients. tangentialDistortion1-2: Tangential distortion coefficients.

14.3. Theia3D Workspaces¶

Example files that make up a single Theia3D workspace.

A workspace folder contains the video and data files of a saved workspace. The video files are named according to their unique camera ID. The .t3d and .p3d files contain the analysis results. It is important that the contents of the workspace folder are not modified, including moving files in or out of the folder.

Theia3D workspaces can be used to save data at various stages of analysis, but are most useful for saving analyzed data that will be reviewed later. When a fully analyzed movement trial is saved as a Theia3D workspace, the saved data includes the 2D videos, calibration file, and all data associated with the analysis. Therefore, when a saved workspace is loaded, you can immediately review the analyzed data in the 2D and 3D viewers.

14.4. C3D Files¶

Pose (.c3d) files can be saved and used to perform post-processing analysis steps in Visual3D software. Use the Save Skeleton Poses button to save skeleton pose .c3d files, or navigate to Save Skeleton Poses under the File Menu. Saved pose .c3d files can be opened in Visual3D, and a subject-specific model will automatically be applied to the Theia3D data in Visual3D without requiring the model to be defined.

The movement of each tracked individual is conveyed within the .c3d file using ROTATION signals, which are 4x4 pose (position and orientation) matrices for each segment’s local segment coordinate system, for every frame of data. A description of the ROTATION data type is available from Visual3D documentation. Raw tracked landmarks are not included as signals in any output files from Theia3D.

14.5. FBX Files¶

Pose files can also be saved as .fbx file formats for use in animation and other software tools that utilize this file format. Use the Save Skeleton Poses button to save skeleton pose .fbx files, or navigate to Save Skeleton Poses under the File Menu.

FBX file outputs can be saved with a variety of different segment coordinate system conventions for your convenience.

14.6. JSON Files¶

Movement data for tracked people from a processed trial can also be exported to .json file format for more open-ended use in scripting environments and as an easily readable file output format. Use the Save Skeleton Poses button to save .json output files, or navigate to Save Skeleton Poses under the File Menu.

Output .json files contain:

Theia3D version number, engines, and kinematic model information
Trial frame rate
Preferences used during process, such as start/end frame, max people, smoothing frequency, etc.
Tracking data for each tracked individual, including ID number, segment names and 4x4 pose matrices, and parameters such as segment length.