Differences

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

--- sift:build_cmz:building_cmzs [2024/06/19 13:35] – removed sgranger
+++ sift:build_cmz:building_cmzs [2024/07/17 15:44] (current) – created sgranger
@@ Line 1: / Line 1: @@
+====== Building CMZs ======
+To load data in Sift you will need to have created CMZ files. CMZ files are compressed Visual3D workspaces that contain both pure data and calculated values. If you are familiar with Visual3D, you may already know how to create CMZ files in the Visual3D interface. The Build CMZ feature in Sift is designed to automate the generation of CMZ files so that they do not have to be created one by one.
+The Build CMZs feature can be accessed on the [[Sift:Application:Load_Page|Load Page]] in Sift.
+Examples of using the Build CMZ function can be found under the [[Sift:Tutorials:OpenBiomechanics_Project:Build_CMZ_Files|Build CMZ Tutorial]].
+===== Build CMZ Dialog - Generic Builder =====
+{{:GenericBuilder.png}}
+Clicking the "Load C3Ds" button on the Load page will bring up the GUI shown to the right, including the Generic CMZ Builder and the Theia Builder. This section focuses on the generic CMZ builder. There are **four** types of inputs that can be used to build a CMZ for the generic builder:
+  - **CMZ Directory:** This should be set to the folder where all of the C3D files that need to be included in the CMZ exist, including static and dynamic files. If the folder contains other folders with C3D files inside, all of them will be included as well. "Browse" opens a file picker dialog to help you find it.
+  - **Metadata File:** The metadata file goes here. "Browse" opens a file picker dialog to help you find it. Expected type is .csv.
+  - **MDH File:** The model file goes here. "Browse" opens a file picker dialog to help you find it. Expected type is .mdh.
+  - **Scripts:** Add scripts here to run them on each C3D file prior to combining them into one CMZ.
+The scripts are run in order, so use the arrow buttons on the right to get the order correct. Note: Scripts added here must all have unique names. The **"Add Script"** button will not allow you to add the same file multiple times. Expected file type is .v3s.
+After all files have been uploaded, click the **"Create CMZs"** button. This button combines all the C3D files in the CMZ Directory folder into one CMZ file that Sift can then load as a library. It includes the metadata, applies the model to all the C3D files, and runs the scripts in order. When this button is pressed, the Metadata window will open (if a metadata file has been provided).
+==== Minimum Inputs ====
+The only required files to build a CMZ are:
+  * Static/calibration files (.c3d)
+  * Dynamic/motion trials (.c3d)
+The static and dynamic trials you want to combine into a CMZ workspace should be located in the same folder. Passing a file path to this folder to the CMZ Builder is the minimum input required to construct a CMZ workspace. If you have data with multiple subjects, separate the data into folders by subject, ensure that each folder has static and dynamic files, and then pass CMZ builder the path to the parent folder holding all subject folders.
+All other inputs are optional.
+==== Optional Inputs ====
+**Metadata File:** Metadata files contain supplementary information about the data you are loading (subject age, weight, walking speed, etc.) Metadata files can be used to refine Sift queries after the library has been loaded.
+**MDH File:** An MDH file is an ASCII file that contains the definitions of all landmarks, segments and segment properties. If you want to load segment or landmark information into Sift you must load an MDH file.
+**Scripts:** An ASCII file containing a series of Visual3D pipeline commands, with the extension .v3s. You would load scripts if you wanted to run a Visual3D pipeline on the created CMZ workspace.
+==== Troubleshooting ====
+This section contains a list of the error messages you may encounter while using the Build CMZ and metadata functions. The Build CMZ dialog and metadata windows expect reasonably specific input and may not execute if files or expected inputs are missing.
+=== Warning Messages ===
+**No C3D files without CMZs found. Skipping build.**
+  * This notice shows up when the folder you've selected does not contain any C3D files OR does not contain any C3D files that are not already contained in a CMZ file.
+  * Sift will close the Build CMZs dialog without making any changes.
+**Warning: You must select both a static and dynamic identifier to proceed.**
+  * Exactly one static and one dynamic identifier is required in order for Sift to build the CMZ file.
+  * Sift will return you to the Metadata dialog.
+**Warning: Meta Data File not found! Name:**
+  * Did you forget to Browse to the location of your Metadata file? If you do not intend to include metadata, please uncheck the box next to the Metadata file.
+**MDH File not found! Name:**
+  * Did you forget to Browse to the location of your MDH file? If you do not intend to include a model file, please uncheck the box next to the MDH file.
+=== Error Messages ===
+**No information passed. Cannot build CMZs.**
+  * This is an uncommon error. It means there was an issue with the Build CMZs dialog and it is no longer accessible.
+**No files selected. Cannot build CMZs.**
+  * This is an uncommon error. It means that no files at all were returned by the Build CMZ dialog.
+===== Build CMZ Dialog - Theia Builder =====
+{{:Sift_TheiaBuilder.png}}
+This section focuses on the Theia Builder, which builds CMZ files from Theia3D outputs. This dialog closely matches the dialog for building Theia3D files in Visual3D, "Manage_Theia3D_Merge". This is also accessed from the "Load C3Ds" button on the Load page.
+There are a variety of inputs that can be used to generate CMZs from Theia3D files:
+**CMZ Directory:** The directory root to search for all of the Theia3D Files.
+\\
+**Save By:** How the CMZ file should be saved as.
+**Use Index Theia Files (.hmx):** If you would like to use a .hmx file to supersede this information.
+\\
+**File Tags:** If/how file tags should be added onto the files by.
+\\
+**Primary Data Folder:** Method by which Theia3D data is stored.
+**Theia Session Folder Mask:** Folder mask for Theia3d files (directory within top level directory to search for Theia3D files).
+**Theia File Mask:** File name mask for Theia3D files. Can include wildcards.
+**Theia 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.
+**Theia Subject Tags:** Subject tags for Theia3D files.
+**Theia Prefixes:** **Subject prefixes for Theia3D files.**
+**Theia Color:** The color of the Theia3D skeleton.
+**Choose Kinetic Thorax:** Choose which type of thorax to model.
+\\
+**Merge Theia3D Files:** Merge primary Theia3D files into other Theia3D files (mutually exclusive).
+**Import Analog Files:** Merge primary Theia3D files with analog files, such as force plate data (mutually exclusive).
+**Merge Theia Files and Other Files:** Merge primary Theia3D files with other data, such as marker-based files (mutually exclusive).
+\\
+**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.
+\\
+Differences from the Visual3D Dialog include:
+**CMZs not opened by default:** you need to load these in through the [[Sift:Application:Load_Library_Dialog|load library]] dialog into Sift.
+**Automatic Save is on by default:** you just need to select how to save from the given options.