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.
=====Manage_File_Merge=====

====Overview====
The **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 command can be found in the [[visual3d:documentation:pipeline:pipeline_overview|Pipeline Workshop Dialog]] under [[visual3d:documentation:pipeline:pipeline_commands:pipeline_control_commands|Pipeline Control]]. 

Manage_File_Merge can be used to combine motion capture files from the same recording session. A popular use case for this command would be to merge force plate recordings from a QTM file with a Theia3D motion capture file. The analog signals from the QTM .c3d file would be merge into the Theia3D .c3d file. 

This command requires data files to be stored in a particular folder structure to match .c3d files appropriately. Please carefully review the [[visual3d:documentation:pipeline:pipeline_commands:manage_file_merge#Notes| Notes]] section of this page for more details.

====Pipeline Command====
Below is the full pipeline command and parameters for Manage_File_Merge
<code>
Manage_File_Merge
! /ROOT_FOLDER=
! /HMX_INDEX_MASK=
! /USE_HMX_INDEX=FALSE
! /ACTION=
! /TAGS=ACTION
! /IMPORT_ANALOG_FILES=FALSE
! /MERGE_PRIMARY_FILES=FALSE
! /MERGE_PRIMARY_AND_OTHER_FILES=FALSE
! /MERGE_EVENT_LABELS=FALSE
! /PRIMARY_SESSION_FOLDER=
! /PRIMARY_FILE_MASK=*.c3d
! /PRIMARY_FILE_MASK_FOR_MODEL=
! /THEIA3D_PREFIX=
! /THEIA3D_SUBJECT_TAG=
! /PRIMARY_COLOR=
! /PRIMARY_SEX=UNKNOWN
! /CREATE_MODEL_FOR_EACH_C3D_FILE=FALSE
! /OTHER_SESSION_FOLDER=
! /OTHER_FILE_MASK=
! /OTHER_MODEL_MASK=
! /OTHER_MODEL_TEMPLATE_MASK=
! /OTHER_PREFIX=
! /OTHER_SUBJECT_TAG=
! /OTHER_COLOR=
! /NUMBER_OF_SESSION_FILES_ALLOWED=
! /SAVE_DEFAULT_CMZ_FILES=TRUE
! /DEFAULT_CMZ_NAME=<SESSION>
! /OPEN_CMZ_LIBRARY=FALSE
! /VIRTUAL_LAB=
! /INPUT_DATA_FOLDER_PRIMARY=DEFAULT
! /INPUT_DATA_FOLDER_SECONDARY=DEFAULT
! /INPUT_STATIC_DATA_FOLDER=DEFAULT
! /KINETIC_THORAX=RTA
! /ANALOG_FILTER_CUTOFF=12
! /TARGET_FILTER_CUTOFF=12
! /FP_AUTO_BASELINE=DO_NOT_COMPUTE
! /VISUAL3D_PIPELINE_POST_MERGE=
! /VISUAL3D_PIPELINE_PREMERGE=
;
</code>


====Command Parameters====
The following table shows the command parameters and descriptions:

|**Parameter**   |**Description**|
|**! /ROOT_FOLDER=**| The directory root search containing all C3D files that contain the information relevant for analysis.|
|**! /HMX_INDEX_MASK=**|file mask for Theia .hmx file (if applicable).|
|**! /USE_HMX_INDEX=FALSE**|If you would like to use a .hmx file to supersede this information.|
|**! /ACTION=**|...|
|**! /TAGS=ACTION**|If/how file tags should be added onto the files by. Default is to the Action.|
|**! /IMPORT_ANALOG_FILES=FALSE**|Merge primary files with analog files, such as force plate data (mutually exclusive).|
|**! /MERGE_PRIMARY_FILES=FALSE**|Merge primary files into other files (mutually exclusive)|
|**! /MERGE_PRIMARY_AND_OTHER_FILES=FALSE**|Merge primary files with other data, such as marker-based files (mutually exclusive).|
|**! /MERGE_EVENT_LABELS=FALSE**|Merge event labels between Primary and Secondary .c3d files.|
|**! /PRIMARY_SESSION_FOLDER=**|Folder mask for primary session files (directory within top level directory to search for primary files).|
|**! /PRIMARY_FILE_MASK=*.c3d**|File name mask for primary files. Can include wildcards.|
|**! /PRIMARY_FILE_MASK_FOR_MODEL=**|File name mask for model file. If blank it will select the first file as the model file. Can include wildcards.|
|**! /THEIA3D_PREFIX=**|Subject Prefixes for Primary files.|
|**! /THEIA3D_SUBJECT_TAG=**|Subject tags for Primary files.|
|**! /PRIMARY_COLOR=**|The color of the Primary file skeleton.|
|**! /PRIMARY_SEX=UNKNOWN**|Sex of the primary file.|
|**! /CREATE_MODEL_FOR_EACH_C3D_FILE=FALSE**|For automated model building for Theia3D files, creating a new model for each .c3d. |
|**! /OTHER_SESSION_FOLDER=**|Folder mask for merged files (directory within top level directory to search for merged files).|
|**! /OTHER_FILE_MASK=**|File name mask for merged files. Can include wildcards.|
|**! /OTHER_MODEL_MASK=**|File name mask for static merged files. Can include wildcards.|
|**! /OTHER_MODEL_TEMPLATE_MASK=**|File name mask for model files (if needed). Can include wildcards.|
|**! /OTHER_PREFIX=**|Subject prefixes for merged files.|
|**! /OTHER_SUBJECT_TAG=**|Subject tags for merged files.|
|**! /OTHER_COLOR=**|The color of the secondary data files.|
|**! /NUMBER_OF_SESSION_FILES_ALLOWED=**|Restricts the number of session files used.|
|**! /SAVE_DEFAULT_CMZ_FILES=TRUE**|Automatically save default CMZ file with specified name.|
|**! /DEFAULT_CMZ_NAME=<SESSION>**|The name that CMZ file should be saved as, related to the hierarchy of the folder structure (either Session or Group+Session).|
|**! /OPEN_CMZ_LIBRARY=FALSE**|Open CMZ Library after processing.|
|**! /VIRTUAL_LAB=**|Set virtual lab ("None" if not desired).|
|**! /INPUT_DATA_FOLDER_PRIMARY=DEFAULT**| Method by which primary data is stored. DEFAULT is |
|**! /INPUT_DATA_FOLDER_SECONDARY=DEFAULT**|Method by which secondary data is stored. DEFAULT is |
|**! /INPUT_STATIC_DATA_FOLDER=DEFAULT**|Method by which static secondary data is stored. DEFAULT is |
|**! /KINETIC_THORAX=RTA**|Choice of Kinetic Thorax for automated model with Theia3D specific files.|
|**! /ANALOG_FILTER_CUTOFF=12**|The lowpass filter cutoff for the analog files.|
|**! /TARGET_FILTER_CUTOFF=12**|The lowpass filter cutoff for the target files.|
|**! /FP_AUTO_BASELINE=DO_NOT_COMPUTE**|Method by which forceplate data was collected.|
|**! /VISUAL3D_PIPELINE_POST_MERGE=**|Visual 3D pipeline to run after the merge occurs.|
|**! /VISUAL3D_PIPELINE_PREMERGE=**|Visual 3D pipeline to run before the merge occurs.|

====Dialog====
The command can be edited in a text editor or in a dialog form. To edit in the dialog pop up form either click on the **Edit** button in the pipeline workshop or double-click on the pipeline command. The dialog is shown below.
There are a variety of inputs that can be used to generate CMZs from Theia3D files:

{{ visual3d:documentation:pipeline:pipeline_commands:manage_file_merge_dialog.png}}
  * **Root path to search:** The directory root to search for all of the Files.
  * **Open CMZ Library After Processing:** 
  * **Automatically save default CMZ files:** How the CMZ file should be saved as.
  * **Use Index Theia Files (.hmx):** If you would like to use a .hmx file to supersede Theia3D files information.
  * **File Tags:** If/how file tags should be added onto the files by.

**Primary Files:**
  * **Primary Data Folder:** Method by which Primary data is stored.
  * **Primary Session Folder Mask:** Folder mask for Primary files (directory within top level directory to search for Primary files).
  * **Primary File Mask:** File name mask for Primary files. Can include wildcards.
  * **Primary File Mask for Model:** File name mask for model file. If blank it will select the first file as the model file. Can include wildcards.
  * **Theia3D Subject Tags:** Subject tags for Theia3D Primary files.
  * **Theia Prefixes:** Subject prefixes for Theia3D Primary files.
  * **Theia Color:** The color of the Primary skeleton.
  * **Sex:** The sex of the Primary file for model inertial properties.
  * **Choose Kinetic Thorax:** Choose which type of thorax to model.

  * **Merge Primary Files:** Merge primary files into other primary files (mutually exclusive).
  * **Import Analog Files:** Merge primary files with analog files, such as force plate data (mutually exclusive).
  * **Merge Primary Files and Other Files:** Merge primary files with other data, such as marker-based files (mutually exclusive).
  * **Treat Session Files as Independent:** ...

**Secondary Files:**
  * **Secondary Data Folder:** Method by which secondary data is stored.
  * **Static Data Folder:** Method by which static secondary data is stored.
  * **Other Session Folder Mask:** Folder mask for merged files (directory within top level directory to search for merged files).
  * **Other File Mask:** File name mask for merged files. Can include wildcards.
  * **Other Static File Mask:** File name mask for static merged files. Can include wildcards.
  * **Other Model Template Mask:** File name mask for model files (if needed). Can include wildcards.
  * **Other Subject Tags:** Subject tags for merged files.
  * **Other Prefixes:** Subject prefixes for merged files.
  * **Other Color:** The color of the secondary data files.
  * **Analog Filter Cutoff:** The lowpass filter cutoff for the analog files.
  * **Target Filter Cutoff:** The lowpass filter cutoff for the target files.
  * **FP_Auto_Baseline:** Method by which forceplate data was collected.

  * **Restrict Number of Session Files:** Restricts the number of session files used.
  * **Visual3D Pipeline Pre-Merge:** Visual 3D pipeline to run before the merge occurs.
  * **Visual3D Pipeline Post-Merge:** Visual 3D pipeline to run after the merge occurs.

|[IMAGE]
|
====Examples====
===Merge QTM and Theia===



===Merge Multiple QTM Files===



=====Notes=====
==== Folder Structure ====
There is an assumed basic directory structure for this command's input data that aligns with some useful concepts from the experiments that produced the data. This directory structure organizes the [[Visual3D:Documentation:Definitions:File_Formats:CMZ_Format_|CMZ files]] and [[Visual3D:Documentation:C3D_Signal_Types:C3D_Format|C3D files]] that contain the information relevant for analysis. This structure has 5 levels, from root folder to deepest leaf they are:

|**1. Study**|Although the name of this directory level suggests that the data it contains is only used for one study, this is not necessary. As a top-level concept this is the largest, most general database that is stored in one location. This could be specific to a study, or it could be specific to a project, researcher, lab, or consortium. In these latter cases it is possible to define [[Other:Inspect3D:Documentation:Dialogs:Advanced_Query_Section|queries]] to extract the specific signals that are desired for an individual study.|
|**2. Group**|This level of the directory structure is optional, but it allows the researcher to divide c3d files according to desired parameters, e.g., Women - Men, Old - Young. If this level is omitted from the structure then individual C3D files can be [[Visual3D:Documentation:Definitions:Tag|tagged]] with the necessary parameters to allow for their specific selection.|
|**3. Session**|This directory level can be conceived as a single day (or single effort) of data collection within the database. This is the most important level as this is where the [[Visual3D:Documentation:Definitions:File_Formats:CMZ_Format_|CMZ file]] and log files get stored. This is also the level of the directory where static models are stored for all subjects involved in the session.|
|**4. Task**|This level of the directory allows the researcher to divide c3d files according to the desired activity, e.g., walking, running, jumping, etc. As with group-level parameters, C3D files can be coded with these different tasks by using [[Visual3D:Documentation:Definitions:Tag|tags]].|
|**5. Trial**|At this level of the directory structure we have individual trials. This means that we have the individual C3D files that are recorded by the motion capture system.|

**If you are using Theia3D files**, and use TMBATCH, the default folder structure will have 6 levels. From root folder to deepest leaf they are:\\
  - Study
  - Group
  - Session
  - Task
  - Trial
  - pose_filt_0.c3d