View source for iPi Biomech Add-on

=== Introduction ===

'''iPi Biomech Add-on''' is a convenient tool for in-depth biomechanical analysis of human motions. It includes visualization of tracking data and its export to various formats. It can be used for:
* Export of point cloud from multiple Kinect sensors for animation or research
* Gait analysis and rehabilitation
* Sports motion analysis
* Research in 3D human kinematics
Markerless tracking technology does not require clumsy suits, and work in real-life environments like regular office. 

With '''iPi Biomech Add-on''' you can:
[[Image:iPi-Biomech-1-1.jpg|thumb|600px|]]
* Get '''Linear and Angular Quantities''' for selected bones, including
** Linear coordinate, velocity, acceleration
** [http://en.wikipedia.org/wiki/Euler_angles Euler angles], [http://en.wikipedia.org/wiki/Angular_velocity angular velocity] and [http://en.wikipedia.org/wiki/Angular_acceleration angular acceleration]
** [http://en.wikipedia.org/wiki/Quaternion Quaternions] and [http://en.wikipedia.org/wiki/Rotation_matrix Rotation matrices]
* Select convenient '''coordinate systems'''
** Linear: Absolute (relative to floor), Relative to parent bone, Relative to center of mass
** Angular: Absolute (relative to floor), Relative to parent bone
* Select '''[http://en.wikipedia.org/wiki/Euler_angles#Conventions Euler angles system]'''
* '''Plot''' values of selected '''Quantities''' for selected bones
* '''Export''' bones motion data to file
** [http://en.wikipedia.org/wiki/Tab-separated_values Tab-separated text] format (for Excel)
** [http://www.mathworks.com/help/pdf_doc/matlab/matfile_format.pdf MATLAB] format

* '''Export point clouds''' obtained from depth sensors to file
**[http://www.mathworks.com/help/pdf_doc/matlab/matfile_format.pdf MATLAB],  [http://pointclouds.org/documentation/tutorials/pcd_file_format.php PCD], XYZ formats convenient for research
**[http://www.thinkboxsoftware.com/krak-prt-11-file-format/ Krakatoa PRT], [http://en.wikipedia.org/wiki/PLY_(file_format) PLY], [http://en.wikipedia.org/wiki/Wavefront_.obj_file OBJ], Leika PTS formats convenient for animation

{{Note| '''iPi Biomech Add-on''' requires separate license key, which you need to activate in addition to [[iPi Mocap Studio]] license key. 30-days free trial provided.}}

=== Glossary ===

;Bone: skeleton segment between two joints

;Linear quantities: Quantities derived from linear coordinate of the joint which connects bone to it's parent bone, including:
::* Coordinate
::* Velocity 
::* Acceleration

;Angular quantities: Quantities derived from bones's Euler angle, including:
::* [http://en.wikipedia.org/wiki/Euler_angles Euler angle]
::* [http://en.wikipedia.org/wiki/Angular_velocity Angular velocity]
::* [http://en.wikipedia.org/wiki/Angular_acceleration Angular acceleration]
::* [http://en.wikipedia.org/wiki/Quaternion Quaternions]
::* [http://en.wikipedia.org/wiki/Rotation_matrix Rotation matrices]

;Linear coordinate system: Coordinate system used for '''linear quantities''', can be:
[[Image:iPi-Biomech-1-2.png|thumb|]]
::* Absolute (relative to ground)
::**Axes are shown by selecting Move tool;
::**Y axis is vertical
::**XZ plane is floor
::**Center and X, Z axes directions are automatically set during calibration
::**''Recenter Coordinates on Character'' button on ''Scene'' tab before tracking will align coordinate system with actor in T-pose
::***Y is vertical axis passing through center of mass
::***XZ plane is floor
::***X is directed along left arm in T-pose
::* Relative to center of mass 
::**Axes directions are the same as Absolute coordinate system described above; 
::**Center is in the actor model's center of mass
::* Relative to parent joint
::**Axes directions are the same as Absolute coordinate system described above; 
::**Center coincides with the coordinates of the parent joint 

;Angular coordinate system: Coordinate system used for '''angular quantities''', can be:
::* Absolute (relative to ground) &mdash; in this system rotations are defined relative to ground
::* Local (Relative to parent bone) &mdash; in this system rotations are defined relative to the parent bone

;Euler angles system: Set of rotations which defines Euler angles, see [http://en.wikipedia.org/wiki/Euler_angles#Conventions here]

;Unit: Measurement unit of physical quantity (feet or meter, etc.)

=== License and Trial ===

'''iPi Biomech Add-on''' requires separate license key, which you need to activate in addition to [[iPi Mocap Studio]] license key. You can order your license [https://ipisoft.com/software/biomech-add-on/ here], or activate 30-days free trial. Follow the steps below to start working with '''iPi Biomech Add-on'''
# Switch to '''Biomech''' tab.
# Press '''Activate''' button
# Press '''Start 30-days Free Trial Period''' or '''Enter Biomech License Key''' and follow further on-screen instructions
#:[[Image:iPi-Biomech-2-1.png|600px|]]

{{Note|If you do not have [[iPi Mocap Studio]] license key, you can order it [https://ipisoft.com/store here] or activate 30-days free trial. If your Studio trial has expired, you will not be able to export biomech data as well as animation. But you can still plot biomech data.}}

=== Joint Positions Caclulation in iPi Mocap Studio ===
* For tracking of human motion we use [[Animation_Export#Default_iPi_Character_Rig|Default iPi Character Rig]] optimized for tracking purposes.
* The default rig is much simplified compared to real skeleton, but it is still a good approximation and allow to track body and limbs motions with good accuracy
* Accuracy much depends on the particular research task and kind of motion. According to our internal estimations, accuracy is within 0.01 meter range in most cases.
** This page contains links to papers on research made with the use of iPi Motion Capture. Papers contain accuracy estimations for particular research tasks.
* Tracking algorithms are stochastic, so residual noise always present in motion data
** To remove the noise, [[User_Guide_for_Multiple_PS_Eye_Cameras_Configuration#Post-processing:_Trajectory_Filtering|Trajectory Filtering]] is applied after tracking, refine and jitter removal
** To get maximum accuracy, we recommend to do tracking, refine and jitter removal before exporting data
==== Center of Mass Calculation ====
For center of mass calculation we use anthropometric data from the book ''David A Winter "Biomechanics and Motor Control of Human Movement", Chapter 4 "Scope of Anthropomentry in Movement Biomechanics"''. Each body segment has its mass (percent of the whole body mass, and center of mass position). 

Actor's mass index does not affect center of mass position, as well as Chest, Bust, Waist, Hips, Belly adjustment settings. These settings only affect skin (surface) of the model, but do not change body segments.
But the rest of adjustments (Arms Length, Legs Length, Shoulders Width, Head Size, Feet Size) do affect body of mass position.

{| class="wikitable"
|-
! Joint Name !! Body Mass Portion !! Proximal Distance of Mass Center
|-
| Hip || style="text-align:right; padding-right: 10px;" | 14.20% || 0.614224
|-
| MiddleSpine || style="text-align:right; padding-right: 10px;" | 13.90% || 0.585650749
|-
| Chest || style="text-align:right; padding-right: 10px;" | 21.6% || 0.68964662
|-
| Head || style="text-align:right; padding-right: 10px;" | 8.10% || 0.35
|-
| LShoulder / RShoulder || style="text-align:right; padding-right: 10px;" | 2.80% || 0.436
|-
| LForearm / RForearm || style="text-align:right; padding-right: 10px;" | 1.60% || 0.43
|-
| LHand / RHand || style="text-align:right; padding-right: 10px;" | 0.60% || 0.506
|-
| LThigh / RThigh || style="text-align:right; padding-right: 10px;" | 10.00% || 0.433
|-
| LShin / RShin || style="text-align:right; padding-right: 10px;" | 4.65% || 0.433
|-
| LFoot / RFoot || style="text-align:right; padding-right: 10px;" | 1.45% || 0.5
|}

=== Select Data for Analysis ===
First you need to select data that you will analyze
# Select bones
#* (1) Check corresponding bones to include them in analysis
#:{{Note|On the top of the list you can see "special" bones &mdash; ''Center of mass'', ''Center of mass projection to the ground''. The rest of the list are the bones from the internal iPi rig.}}
#* (2) You can include finger bones into analysis by expanding hand bone (RHand and / or LHand). However, fingers are not tracked due to insufficient resolution of off-the-shelf cameras, so they just keep attached to hand joint (RHand or LHand), remaining in default position related to hand
#* (3) You can select all bones by clicking to the checkbox in the header. Fingers will be included only if the hand bone is expanded.
#* (4) You can change bones listbox height using splitter at the bottom.
#:[[Image:iPi-Biomech-2-2.png]]
# Select '''linear quantities''' for analysis
# Select output '''units''' for each quantity
# Select '''linear coordinate system'''
# Select '''angular quantities''' for analysis
# Select output '''units''' for each quantity
# Select '''angular coordinate system'''
# Select '''Euler angles system'''
#:[[Image:iPi-Biomech-2-3.png]]

=== Plot Data ===
You can plot values of the selected '''quantities''' for the selected bones within the ''Region-of-Interest'' (except Quaternions and Rotation matrices, as it makes no sense to see them on plots due to their physical meaning).
# Select the ''Region-of-Interest''
# Press '''Plot Selected Data''' button
#: Plot window will be opened. If it is already opened it's contents will be updated. In the Plot window you see bones in rows and '''quantities''' in columns. Plot controls:
# '''Plot controls''' button shows plot control keys (focus should be set to '''Plot''' window).
#:'''Mouse wheel''' &mdash; zoom in / out for the horizontal axis
#:''''Page Up' key''' &mdash; zoom in for the horizontal axis
#:''''Page Down' key''' &mdash; zoom out for the horizontal axis
#:'''Right mouse button drag over plots''' &mdash; horizontal shift of all plots                               
#:'''Left mouse button drag over table header title''' &mdash; change columns order
#:''''Right arrow' key''' &mdash; shift all plots to the left
#:''''Left arrow' key''' &mdash; shift all plots to the right
#:'''Left mouse key click''' &mdash; show plot values for particular frame
#:''''A' key''' &mdash; cancel zoom and shift, restore initial state of all plots
# '''Reload plot data''' reloads plot's data. Useful when selection of bones, '''quantities''', ''Region-of-Interest'' changed or any tracking / refined / filtering applied to motion data. You will get the same effect if you press '''Plot''' button.
# '''Scroll to current frame''' button shifts all plots along horizontal axis, in order to make current frame visible in the plot area. Nothing happens, if current frame is already visible on plots.
# '''Show / hide series''' button allows to select particular components of the corresponding '''quantity''' that will be shown on graph.
#:[[Image:iPi-Biomech-2-4.png|700px]]

=== Export Motion Data ===
To export values of the selected '''quantities''' for the selected bones within the ''Region-of-Interest'':
# Select the ''Region-of-Interest''
# Press '''Export Selected Data''' button
# Select export option:
#* ''Tab-separated text file'': text format easily importable to Excel. Header will contain information on parameters such as '''coordinate systems''' and '''units'''
#* ''Copy to clipboard / paste to Excel'': text data will be copied to clipboard. You just need to open empty Excel sheet and paste data to it. Information on parameters such as '''coordinate systems''' and '''units''' will be in the top rows.
#* ''MATLAB file'': binary file in [http://www.mathworks.com/help/pdf_doc/matlab/matfile_format.pdf MATLAB] format.
#:[[Image:iPi-Biomech-2-5.png]]

=== Export Point Cloud ===
To export point cloud captured with depth sensors within the ''Region-of-Interest'':
# Select the ''Region-of-Interest''
# Select the cameras you want to export point cloud from (if you select several cameras, you will get one aggregate point cloud)
# Turn on / off background subtraction (if checked, background will not be included in point cloud)
# Turn on / off RGB export (if checked, color information will be added to points)
# Select export format
# Press '''Export Selected Data''' button
# Select export option:
#* ''One point cloud from current frame'': export single point cloud from the current frame to file
#* ''All frames of ROI'': export multiple point clouds (one point cloud from each frame of the ''Region-of-Interest'') to single or multiple files depending of export format
#: [[Image:iPi-Biomech-2-6.png]]

==== Import of Point Cloud to 3d Packages ====

Point cloud data can be useful as video reference in 3d packages like 3ds Max, Maya and others.

* [http://www.thinkboxsoftware.com/krak-prt-11-file-format/ Krakatoa PRT] format is recognized by Krakatoa PRT Loader for [http://www.thinkboxsoftware.com/krak-prt-loader 3ds Max] and [http://www.thinkboxsoftware.com/krakatoa-my-prt-loader/ Maya]. It can load to multiple frames from multiple files.

* [http://en.wikipedia.org/wiki/Wavefront_.obj_file OBJ] format is natively supported in 3ds Max

* [http://en.wikipedia.org/wiki/PLY_(file_format) PLY] format can be imported to Max with this free [http://www.guruware.at/main/plyImp/index.html plugin]

=== Biomech Export Profile  ===
You can save all interface settings '''<span style="color: red">(1)</span>''' to an XML file, and later load them from the file '''<span style="color: red">(2)</span>'''. It is useful if you work with several projects that require to analyze different bones and / or '''quantities'''. The following settings are stored:
* Selected bones, bones list view height
* Selected '''quantities''', '''coordinate systems''', '''euler angles system''', '''units'''
* Settings of point cloud export
* Plot window settings (order on columns, visible series, window size and position)
:[[Image:iPi-Biomech-2-7.png]]