HAS-Motion Software Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Build Normal Database ======

This tutorial begins by assuming that you have a [[Visual3D:Documentation:Definitions:File_Formats:CMZ_Format_|CMZ]] file for each subject.session from [[Visual3D:Visual3D_Overview|Visual3D]]. If necessary you can use our [[Sift:Tutorials:OpenBiomechanics_Project:Build_CMZ_Files|build CMZ feature]] or work through the Visual3D tutorial for [[Visual3D:Tutorials:Pipeline:Generic_Pipeline_to_Create_CMZ|building a CMZ file]].

===== Data =====

This tutorial can be completed with any CMZ file. This tutorial will be using the data set from a Visual3D Workshop at a recent ASB meeting: [[https://www.has-motion.com/download/examples/V3D_Workshop.zip|V3D Workshop @ ASB]].\\
**Supporting files for this tutorial if using ABS workshop data:** [[https://has-motion.com/download/Tut-buildNDs.zip|download here]]
  * **GPS_GDI_Joint_Angles.v3s** - Visual3D Pipeline Script for GPS and GDI required Joint Angles
  * **BuildND_Queries.q3d** - Sift Query Definition File to query normalized joint angles to be summarized and saved in the Normal Database

===== 1. Load Library =====

{{ :sift_load_page.png?700}}
To start, you need to load the data into Sift. After opening Sift:

  - Click the {{:sift_library_load.png?20}}**Load Library** on the toolbar or the top left of the [[Sift:Application:Load_Page|load page]]:
    - Click {{:sift_browser.png?20}}**Browse** to open a dialog that allows you to select a file path
    - Select the top level folder/root directory which contains the CMZ file NOTE: the CMZ file's associated CMX file must also be present for Sift to be able to load the library;
    - Click **Select Folder**
  - Click **Load**
  - One the library is loaded, you will be able to do initial exploration on the [[Sift:Application:Load_Page|Load page]]:
    - Verify which CMZ file have been loaded in the 3D Viewer, as well as which C3D files are associated with each CMZ;

----

===== 2. Run External Script =====

In this specific tutorial, we are building a Normal Database to be used in a [[sift:tutorials:compute_GPS_and_GDI|tutorial]] for the [[Sift:gait_measures:gait_profile_score|Gait Profile Score]] and [[Sift:gait_measures:gait_deviation_index|Gait Deviation Index]] calculations. Therefore, we need to make sure we have the correct joint angles computed in our CMZ workspaces. To do so, we are going to run a Visual3D pipeline script (.v3s file) against the loaded library. \\

==== Pipeline Script ====
A sample of this pipeline script can be seen here:\\
**Note**: this pipeline was derived for the sample workspace associated with this tutorial. If running this against your own data, make sure to verify the Link_Model_Based calculations with the GPS definitions to insure you have the correct angles. \\

  !/////////////////////////////////////////////////////////////////////////////////////////////////
  !		Compute LEFT Joint Angles
  !/////////////////////////////////////////////////////////////////////////////////////////////////

  ! Left Angles are calculated in accordance to the GPS score

  ! Left Ankle
  Compute_Model_Based_Data
  /RESULT_NAME=L_Ankle_Angle
  /SUBJECT_TAG=ALL_SUBJECTS
  /FUNCTION=JOINT_ANGLE
  /SEGMENT=LMF
  /REFERENCE_SEGMENT=LSK
  /RESOLUTION_COORDINATE_SYSTEM=
  ! /USE_CARDAN_SEQUENCE=FALSE
  ! /NORMALIZATION=FALSE
  ! /NORMALIZATION_METHOD=
  ! /NORMALIZATION_METRIC=
  ! /NEGATEX=FALSE
  ! /NEGATEY=FALSE
  ! /NEGATEZ=FALSE
  ! /AXIS1=X
  ! /AXIS2=Y
  ! /AXIS3=Z
  ! /TREADMILL_DATA=FALSE
  ! /TREADMILL_DIRECTION=UNIT_VECTOR(0,1,0)
  ! /TREADMILL_SPEED=0.0
  ;

  ! Left Knee
  Compute_Model_Based_Data
  /RESULT_NAME=L_Knee_Angle
  /SUBJECT_TAG=ALL_SUBJECTS
  /FUNCTION=JOINT_ANGLE
  /SEGMENT=LSK
  /REFERENCE_SEGMENT=LTH
  /RESOLUTION_COORDINATE_SYSTEM=
  ! /USE_CARDAN_SEQUENCE=FALSE
  ! /NORMALIZATION=FALSE
  ! /NORMALIZATION_METHOD=
  ! /NORMALIZATION_METRIC=
  ! /NEGATEX=FALSE
  ! /NEGATEY=FALSE
  ! /NEGATEZ=FALSE
  ! /AXIS1=X
  ! /AXIS2=Y
  ! /AXIS3=Z
  ! /TREADMILL_DATA=FALSE
  ! /TREADMILL_DIRECTION=UNIT_VECTOR(0,1,0)
  ! /TREADMILL_SPEED=0.0
  ;
\\
==== Run V3D Engine Dialog ====

  - To run this script, the [[Sift:application:run_v3d_engine_dialog|Run V3D Engine Dialog]] can be accessed through the {{:sift_run_v3d.png?30}} button on the [[Sift:Application:Toolbar|toolbar]].\\
  - Add the .v3s script downloaded from this tutorial and select **"Run Scripts"**.\\
  - Wait for the CMZs to update and the library to load.\\



===== 3. Define Queries =====
{{ :sift:tutorials:buildNDQueries.png?850}}


To select which signals from our CMZ workspaces we want to summarize and include in the Normal Database, we first need to query them. These signals will be L or R specific (not grouped sides), and will be normalized to 101 points. For this sample dataset and it's existing events in the CMZ workspaces, all left signals will be normalized to LHS-LHS and right signals will be normalized to RHS-RHS.\\

  - Open the [[sift:application:query_builder_dialog|Query Builder Dialog]] {{:sift_query_builder.png?30}}\\
  - Define [[sift:documentation:query|queries]] based on your own dataset using the [[sift:application:query_builder_dialog|Query Builder]] **OR**
    - *select **Load Query Definitions** and load the .q3d file downloaded for this tutorial (if following with the sample data)\\
  - Once your own queries are defined, or the query definitions have been loaded from the .q3d file, select **"Calculate All Queries"** \\
  - Exit the [[sift:application:query_builder_dialog|Query Builder Dialog]] \\

----
===== 4. Build Normal Database =====

Now that we have queried the signals, we can see our [[sift:application:groups_and_workspaces|groups and workspaces]] on the [[sift:application:Explore_Page|Explore Page]].\\

  - Look through your groups and workspaces by using the [[sift:application:explore_page#plot_controls|plot controls]] to examine and verify your signals and/or metrics on the [[sift:application:explore_page#plot_viewer|plot viewer]]
  - Here for example, we have created a 5x4 grid using the [[sift:application:general_options_dialog|options dialog]], and have plotted different groups to check that we are happy with the joint angle, normalization, and quality of the data
  - If you wish to clean your data, see this tutorial [[sift:tutorials:clean_your_data|here]]\\

{{sift:tutorials:checkNDQueries.png}}

==== Build Normal Database Dialog ====

{{ :sift:tutorials:buildNDDlg.png?800}}

 4. On the [[Sift:application:explore_page|Explore Page]], select on the BuildND button\\

The Build ND Dialog has 3 main sections: **Query Groups**,**Meta Data & Summary Statistics**, and **Summary Level**.\\

 5. Select file path and name for resulting ND file. The file path of the ND directs Sift to save the resulting ND .sift file to a path of the users choice\\

 6. If you cleaned and excluded data and wish to still use those traces in the ND, check the "Use Excluded Data"\\

----
==== Query Groups ====

 7. Select all of the queries you wish to include in the ND. Following with the sample data, we will select all queries\\

==== Meta Data & Summary Statistics ====

The Meta Data & Summary Statistics widget of this dialog is populated with all of the available statistics that Sift offers. From this list, you can select as many summary results as you wish to be calculated for all selected Query Groups. A full list of available summary statistics can be found [[Sift:build_nds:ND_Summary_Statistics|here]].\\

 8. For this tutorial, we will select to calculate the **Mean**

==== Summary Level ====

The summary level options allow users to choose how broad or detailed they would like their summaries:
  *Library summary – a comprehensive overview of an entire project across all participants and motion capture sessions. The summary values are over all traces in all workspaces and all trials in the ND library.
  *Workspace summary – a more granular summary for each motion capture session; this can also line up with each participant. The summary values are taken over all trials within each workspace, and stored as a summary signal or metric per workspace.
  *Trial summary – a detailed summary of individual trials performed by each of your participants. The summary values are taken over all traces within each trial, and stored as a summary signal or metric per trial in each workspace.\\

 9. Following this tutorial, we will summarize across the **Library** and **Workspace** levels\\

==== Generate Normal Database ====

 10. Once you are happy with the dialog settings, select **"Generate Normal Database"**\\
 11. The .sift file will be generated and automatically loaded into Sift

==== View the Normal Database ====

 12. On the [[Sift:application:Load_Page|Load Page]] you will see a summary of the ND you just generated. Here you can see a summary of the files that were used to generate the ND, the summary statistics calculated across the data set, and the summary levels.

{{:sift:tutorials:NDLoadedTutorial.png?1000}}

===== 5. Use the Normal Database in Sift =====
\\
The generated ND file is a .sift workspace that can be loaded into Sift anytime with the [[sift:build_nds:building_normal_databases#loading_nds|Load ND]] button on the [[sift:application:Explore_Page|Explore Page]].\\

Within Sift, users have the flexibility to query, plot, and run any of our analysis tools or statistical tests across ND queries.\\

To see how we can continue with this specific Normal Database file to compute Gait Scores, follow the next tutorial [[sift:tutorials:compute_gps_and_gdi|here]].