Inspect3D Documentation: Build CMZs: Difference between revisions

From Software Product Documentation
Jump to navigation Jump to search
 
(18 intermediate revisions by 2 users not shown)
Line 5: Line 5:
|}
|}


=Overview=
To load data in Inspect3D 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 Inspect3D is designed to automate the generation of CMZ files so that they do not have to be created one by one.
To manipulate data in Inspect3D you will need to have created CMZ files. CMZ files contain both pure data and calculated values. If you are familiar with Visual3D, you may already know how to create CMZ files from the Visual3D interface. The Build CMZ feature in Inspect3D 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 is accessed through the [[Inspect3D_Documentation_Load_Library_Dialogue|Load Library]] dialog.
The Build CMZs feature can be accessed through the [[Inspect3D_Documentation_Load_Library_Dialogue|Load Library]] dialog in Inspect3D.


=CMZ Builder=
Examples of using the Build CMZ function can be found under the [[Inspect3D_Tutorial:_Build_CMZs|Build CMZ Tutorial]].
 
=Build CMZ Dialog=
[[File:update cmzs.png|350px | right]]
[[File:update cmzs.png|350px | right]]
There are '''four''' types of inputs that can be used to build a CMZ:
Clicking the "Build CMZ" button in the Load Library dialog will bring up the GUI shown to the right. There are '''four''' types of inputs that can be used to build a CMZ:


# '''CMZ Directory:''' This should be set to the folder where all of the C3D files that need to be included exist. 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.
# '''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 is .csv.
# '''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.
# '''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.
# '''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.
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.
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 correct 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 Inspect3D can then load as a library.
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 Inspect3D can then load as a library.
It includes the metadata, applies the model to all the C3D files, and runs the scripts in order.
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).
When this button is pressed, the Metadata window will open (if a metadata file has been provided).
Line 33: Line 34:
All other inputs are optional.
All other inputs are optional.


=Metadata=
==Optional Inputs==
Metadata typically contains supplementary data about our subjects or experiments. It can come from a variety of sources, including collection systems or demographic info. Metadata can be used to refine the data we want to analyze in Inspect3D. Inspect3D expects metadata to exist in .csv format and has a specific framework that must be adhered to.
'''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 Inspect3D queries after the library has been loaded.
==Metadata Viewer==
If you were to load a .csv file with only one header labelled "hello_world" and populated with a random string, the metadata viewer would show this output: (see right).
 
[[File:metaexample1.png|350 px|right]]
 
This example is intended to show the bare bones of the metadata viewer. It has three columns, "Header", "Description" and "Subject Specific" and two dropdown menus with options for height and weight units. These will always appear no matter what your metadata file contains.
 
'''Header:''' is the first item in each column of the csv file. All headers appear in the first row of the csv file and are separated by commas. The column header at position N corresponds to all data in column N.
 
'''Description:''' This is a dropdown menu of pre-programmed options. The options are: Height, Weight, Text, Metric, Identifier_Static, Identifier_Dynamic, Ignore.
 
'''Subject_Specific:''' this is a checkbox that is intended to store whether or not the value of the header changes on a subject by subject basis.
 
==Minimum Inputs==\
[[File:metadataexample3.png|350 px|right]]
 
There are two inputs that are always expected and the CMZ Builder will not execute without them:
*'''Identifier_Static:''' Static or calibration files.
*'''Identifier_Dynamic:''' Dynamic or motion files.
The naming of these inputs is up to the user, however, the description fields expect exactly one of each of these two inputs.
 
What this translates to in csv format is one column (i.e. with header "static_model") where the column contents are the static filename, and one column (i.e. with header "cdynamic_file") where the column contents are the dynamic file names.
 
The image to the right shows an example of how the dialog box will read the example csv file. Note: both columns will be read as Identifier_Dynamic. You will have to change the static_model description to Identifier_Static and check Subject Specific.


The rest of the description inputs (height, weight, text, metric, ignore) are not required to execute the Build CMZ function, but can be included to streamline the refinement of the data you want to analyze.
'''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 Inspect3D you must load an MDH file.


==Default Settings==
'''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=
=Troubleshooting=
Line 74: Line 51:
'''Warning: You must select both a static and dynamic identifier to proceed.'''
'''Warning: You must select both a static and dynamic identifier to proceed.'''
*Exactly one static and one dynamic identifier is required in order for Inspect3D to build the CMZ file.
*Exactly one static and one dynamic identifier is required in order for Inspect3D to build the CMZ file.
*Inspect3D will return you to the Metadata dialog  
*Inspect3D will return you to the Metadata dialog.
'''Warning: Meta Data File not found! Name:'''
'''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.
*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:'''
'''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 Metadata file.
*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==
==Error Messages==

Latest revision as of 20:54, 11 August 2023

Language:  English  • français • italiano • português • español 

To load data in Inspect3D 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 Inspect3D 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 through the Load Library dialog in Inspect3D.

Examples of using the Build CMZ function can be found under the Build CMZ Tutorial.

Build CMZ Dialog

Clicking the "Build CMZ" button in the Load Library dialog will bring up the GUI shown to the right. There are four types of inputs that can be used to build a CMZ:

  1. 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.
  2. Metadata File: The metadata file goes here. "Browse" opens a file picker dialog to help you find it. Expected type is .csv.
  3. MDH File: The model file goes here. "Browse" opens a file picker dialog to help you find it. Expected type is .mdh.
  4. 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 Inspect3D 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 Inspect3D 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 Inspect3D 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.
  • Inspect3D 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 Inspect3D to build the CMZ file.
  • Inspect3D 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.
Retrieved from ""