14. Data Formats

14.1. Video Data

_images/vid_folder_structure.png

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

_images/camera_image_axes.png

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 plain text and Vicon calibrations 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

_images/workspace_files.png

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. Pose (.c3d) Files

Pose (.c3d) files can be saved and used to perform post-processing analysis steps in Visual3D software. Use the Save Skeleton Poses SavePose 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.