Differences

This shows you the differences between two versions of the page.

--- visual3d:documentation:third-party:theia [2025/09/18 14:44] – wikisysop
+++ visual3d:documentation:third-party:theia [2026/07/23 13:49] (current) – Corrected version number for Theia3D Apex. richard
@@ Line 6: / Line 6: @@
 Each ROTATION signal consists of 17 float values per frame: sixteen values represent the 4×4 transformation matrix, and the seventeenth is a reliability metric. These signals are stored sequentially in the C3D file. This data type is used in practice because if a segment’s origin is defined at the proximal end, the ROTATION matrix provides a description of both the position and orientation of that segment. This eliminates the need for additional calculations to estimate pose and makes data management easier, since the pose is a single signal.
-This integration supports all Theia3D software versions including [[https://docs.theiamarkerless.com/|Theia Axiom v2025]], [[https://docs.theiamarkerless.com/version-2024.1.0|Theia Apollo v2024]], [[https://www.theiamarkerless.com/blog/theia-2023-patch-3| Theia 2023]], Theia 2022, and Theia 2021.
+This integration supports all Theia3D software versions including [[https://www.theiamarkerless.com/blog/theia3d-apex---the-next-generation-of-markerless-motion-capture-has-arrived|Theia Apex v2026]], [[https://docs.theiamarkerless.com/|Theia Axiom v2025]], [[https://docs.theiamarkerless.com/version-2024.1.0|Theia Apollo v2024]], [[https://www.theiamarkerless.com/blog/theia-2023-patch-3| Theia 2023]], Theia 2022, and Theia 2021.
+===== Automatic Model-building =====
-=== Merging Theia3D Files===
+Visual3D will automatically build a model for [[visual3d:documentation:c3d_signal_types:c3d_format|C3D files]] output by Theia3D. The model has 17 body segments, two lab coordinate systems (global and [[visual3d:tutorials:modeling:virtual_laboratory|virtual lab]], and 4 shadow segments. Visual3D also builds model segments for Theia's baseball bat and ball tracking.
-Typically, users want to merge Theia3D's motion capture output and analog signals such as force platform recordings.\\
-\\
-The [[visual3d:documentation:pipeline:pipeline_commands:manage_file_merge|Manage_File_Merge]] command is designed to merge multiple files that recorded data from the same motion capture trial. This command merges data types from each .c3d file into one trial in the Visual3D workspace. This command was originally called **Manage_Theia3D_Merge**, but since has been updated to be used for file types other than from Theia3D.
+|1. Lab |6. Right Toes |11. Thorax |16. Left Upper Arm |21. Left Foot (Shadow) |
+|2. Pelvis |7. Left Thigh |12. Head |17. Left Forearm | 22. Thorax/Ab (Shadow) |
+|3. Right Shank |8. Left Shank |13. Right Upper Arm |18. Left Hand | 23. Head (shadow)|
+|4. Right Thigh |9. Left Foot |14. Right Forearm |19. Virtual Lab | 24. Baseball Bat |
+|5. Right Foot |10. Left Toes |15. Right Hand |20. Right Foot (Shadow) |25. Baseball Ball |
+==== Kinetic But No Force Assignment ====
+For the automatic model built for Theia3D output data, and other similar markerless systems, force assignments at the feet are intentionally assigned to the toe segment rather than the foot segment. This is accomplished by defining the foot segment as "Kinetic with no force assignment" while the toe segment is defined as "Kinetic". This ensures that forces are assigned always assigned to the Right/Left Toes segments which are the most distal segments in the kinetic chain.
+The reason for this is that the Net Joint Moment and Joint Reaction Force at the ankle are identical regardless of which segment is assigned the force, as they are part of the kinetic chain, but if the force is assigned to the foot segment then the metatarsal moment cannot be computed.
+==== Shadow Segments ====
+The shadow segments defined to model Theia3D and their underlying purpose are:
+  * Right/Left Foot: Make joint angles easier to interpret
+  * Thorax/Ab: Invert proximal/distal; place origin at pelvis
+  * Head: Place origin at proximal head; account for CoM
+==== Version Requirements ====
+Theia releases newer, more advanced, models over time and users must make certain that their version of Visual3D supports automatic model-building for their version of Theia3D. Different versions of Theia will produce different model / segment definitions.
+^ Theia3D Version ^ Notes/Description ^ Visual3D Version ^
+| Apex (v2026.1.4) | Full release of Bat and Ball tracking | v2026.07.1 |
+| | Automatic model-builder supports sex-specific regression equations from de Leva (adjusted Zatsiorsky-Seluyanov) for segment inertial properties | |
+| v2025.2.2 | Added Ball Modelling to automatic model | v2026.04.1 |
+|  | Implemented Bat and Ball modelling using multiple subjects, allowing multiple balls and bats to be modelling within a single session |  |
+| v2025.2.0 | Introduced Bat Tracking feature | v2026.01.1 |
+| Axiom (v2025.1.0) | Separate inertial parameters for male and female participants | v2025.03.2 |
+| Apollo (v2024.1.0) | Introduction of new model | v2024.08.4 |
+|  | Model 10 | v2024.02.1 |
+|  | Initial Model | v2020.03.16 |
+===== Merging Theia3D Files=====
+Typically, users want to merge Theia3D's motion capture output and analog signals such as force platform recordings.
+The [[visual3d:documentation:pipeline:pipeline_commands:manage_file_merge|Manage_File_Merge]] command is designed to merge multiple files that recorded data from the same motion capture trial. This command merges data types from each .c3d file into one trial in the Visual3D workspace. This command was originally called **Manage_Theia3D_Merge**, but since has been updated to be used for file types other than from Theia3D.
 This pipeline command makes it simple to merge markerless motion capture files from Theia with marker-based motion capture files from [[https://www.qualisys.com/software/qualisys-track-manager/|Qualisys QTM]].\\
@@ Line 21: / Line 58: @@
-===Loading Theia C3D Files into Sift===
+===== Loading Theia C3D Files into Sift =====
+Users wanting to import Theia C3D files into Sift can use the Theia Builder to build CMZ files from the Theia3D outputs and merge these with analog data if desired. Sift's tutorials include a walkthrough of how to use the [[sift:build_cmz:load_c3ds_dialog#Build CMZ Dialog - Theia Builder|Theia Builder]] feature.
+===== Batch Reprocessing Theia Files =====
+If your reprocessing workflow involves going back to your raw video data and rerunning Theia's pose estimation, e.g., when a new model is released, then you can incorporate this into your Sift console script. The [[sift:command_line
+#-RunTheiaBatch / -RunTheia / -RTB|-RunTheiaBatch]] console command tells Sift to call to Theia3D with an instruction file for batch processing.
-If wanting to import Theia C3D files into Sift the Theia Builder will be needed to build CMZ files from the Theia3D outputs. Reference the tutorial here on how to use the Theia Builder: [[sift:build_cmz:load_c3ds_dialog#Build CMZ Dialog - Theia Builder|Theia Builder]]