Table of Contents
Export Data To ASCII File
This pipeline command converts data from the Data Tree into ASCII (plain text) data in one of 2 formatted data files (Visual3D ASCII and P2D) and saves the result to disk.
NOTE: This command pulls data from the active files in the workspace. Make sure you have set the correct files to be active using the graphical interface or the Select_Active_File pipeline command.
Pipeline Command
| Export_Data_To_Ascii_File | |
| /FILE_NAME=C:\demo files\Example1\test.txt | The filename (Including path) for the exported data |
| /SIGNAL_TYPES=ANALOG | Signal Type |
| ! /SIGNAL_FOLDER=ORIGINAL | Signal Folder |
| /SIGNAL_NAMES=EMG8 | Signal Names |
| ! /SIGNAL_COMPONENTS= | Signal Component. This is a legacy parameter, if using version 5 or later, please use COMPONENT_SEQUENCE. |
| /COMPONENT_SEQUENCE=X | Signal Component |
| ! /SIGNAL_PRECISION= | Indicates the number of decimal places |
| ! /START_LABEL= | Event Label indicating the first frame of data to be exported. This is a legacy parameter, if using version 4 or later, please use EVENT_SEQUENCE. |
| ! /END_LABEL= | Event Label indicating the last frame of data to be exported. This is a legacy parameter, if using version 4 or later, please use EVENT_SEQUENCE. |
| ! /EVENT_SEQUENCE= | Event sequence the signals should be exported between (ex. LHS+LHS,RHS+RHS) |
| ! /EXCLUDE_EVENTS= | If an event sequence contains one of the events listed in this parameter (ex. BAD,BAD) the event sequence will not be exported. |
| ! /USE_POINT_RATE=FALSE | ANALOG signals can be exported at either the ANALOG rate or the POINT rate |
| ! /NORMALIZE_DATA=FALSE | Option to Time Normalize the data |
| ! /NORMALIZE_POINTS=101 | Number of Output Points from the Time Normalization |
| ! /EXPORT_MEAN_AND_STD_DEV=FALSE | Option to Export the Mean and Standard Deviation |
| ! /EXPORT_MEAN_AND_STD_DEV_FOR_METRIC=FALSE | Option to Export the Mean and Standard Deviation for Metric signals |
| ! /USE_P2D_FORMAT=FALSE | See the Description of P2D Files in the documentation. |
| ! /USE_XML_FORMAT=FALSE | |
| ! /USE_JSON_FORMAT=FALSE | See the description on JSON Formats in the documentation. |
| ! /USE_SHORT_FILENAME=FALSE | The file path for each C3D file will not be exported when set to TRUE |
| ! /EXPORT_EMPTY_SIGNALS=FALSE | |
| ! /EXPORT_WITHOUT_HEADER=FALSE | The headers (FILENAME, SIGNAL TYPE, SIGNAL FOLDER, SIGNAL NAME, SIGNAL COMPONENT) will not be exported when set to TRUE. |
| ! /EXPORT_NAN=FALSE | export NAN to represent NO_DATA |
| ! /USE_SCIENTIFIC_NOTATION=FALSE | |
| ; |
Dialog
The following dialog appears when the EXPORT_DATA_TO_ASCII_FILE command has been added to the pipeline and the user double-clicks with the Left Mouse Button on the command.
Important Notes
Visual3D reserves the signal names ORIGIN, ROTATION and QUATERNION for exporting the pose of a segment. Do not use these names for any signal definition other than the RESERVED intention.
If you choose to normalize the data for the ASCII output, by setting the parameter /NORMALIZE_DATA= TRUE, then the number of points to output is specified by the /NORMALIZE_POINTS parameter (with a default of 101 points) and the signal will be interpolated using a cubic spline.
Examples
We have listed a few examples of how this pipeline command can be used.
Example 1: Exporting multiple files
Using Export_Data_to_ASCII_File to export data from individual C3D files to unique text files.
Assuming:
- the CMZ file is already open
- you want to export data from each C3D file to a txt of the same name (or prefix).
- you want to be prompted to select the FOLDER for the exported files. (If you want, you can hard code this)
The following pipeline commands can be saved to a .v3s file.
!Prompt for the folder Set_Pipeline_Parameter_To_Folder_Path /PARAMETER_NAME=FOLDER /PARAMETER_VALUE= ; ! Get the list of files from the workspace and do not retain the path name for each file Set_Pipeline_Parameter_To_List_Of_Tagged_Files /PARAMETER_NAME=FILES /TAG_NAME=ALL_FILES ! /GET_CURRENT_SELECTED_FILES=FALSE /USE_SHORT_FILENAMES=TRUE ; ! Loop through the files and export the data For_Each /ITERATION_PARAMETER_NAME=INDEX /ITEMS=::FILES ; Select_Active_File /FILE_NAME=*&::INDEX ! /QUERY= ; Export_Data_To_Ascii_File /FILE_NAME=::FOLDER&::INDEX&.txt /SIGNAL_TYPES=LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED /SIGNAL_NAMES=RKNEE_ANGLE+RKNEE_MOMENT+RKNEE_MOMENT+RHIP_ANGLE+RHIP_MOMENT+RHIP_MOMENT+RANKLE_ANGLE+RANKLE_MOMENT /SIGNAL_FOLDER=PROCESSED /SIGNAL_COMPONENTS=X,X,X,X,X,X,X,X ! /START_LABEL= ! /END_LABEL= /Event_Sequence=RON+ROFF ! /Exclude_Events= ! /USE_POINT_RATE=FALSE /NORMALIZE_DATA=TRUE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ; End_For_Each /ITERATION_PARAMETER_NAME=INDEX ;
Example 2: Exporting multiple files with extension update
In this example, the output files' names will be changed by concatenating the C3D filename with a .txt extension. This is done with the Set_Pipeline_Parameter command that will search and replace the extension. The exported data in this example is between two events and is normalized.
The pipeline commands are listed below:
! Prompt the user for the folder Set_Pipeline_Parameter_To_Folder_Path /PARAMETER_NAME=FOLDER /PARAMETER_VALUE= ; ! Get the list of files from the workspace and do not retain the path name for each file Set_Pipeline_Parameter_To_List_Of_Tagged_Files /PARAMETER_NAME=FILES /TAG_NAME=ALL_FILES ! /GET_CURRENT_SELECTED_FILES=FALSE /USE_SHORT_FILENAMES=TRUE ; ! Loop through the files and export the data For_Each /ITERATION_PARAMETER_NAME=INDEX /ITEMS=::FILES ; ! Set a pipeline parameter NEW_INDEX that searcher and replaces the filename with *.c3d to *.txt Set_Pipeline_Parameter /PARAMETER_NAME=NEW_INDEX /PARAMETER_VALUE=::INDEX /PARAMETER_VALUE_SEARCH_FOR=.c3d /PARAMETER_VALUE_REPLACE_WITH=.txt ! /PARAMETER_VALUE_PREFIX= ! /PARAMETER_VALUE_APPEND= ; Select_Active_File /FILE_NAME=*&::INDEX ! /QUERY= ; ! Export to ASCII with the filename NEW_INDEX ! The output is between RON and ROFF and is normalized to 101 points Export_Data_To_Ascii_File /FILE_NAME=::FOLDER&::NEW_INDEX /SIGNAL_TYPES=LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED+LINK_MODEL_BASED /SIGNAL_NAMES=RKNEE_ANGLE+RKNEE_MOMENT+RKNEE_MOMENT+RHIP_ANGLE+RHIP_MOMENT+RHIP_MOMENT+RANKLE_ANGLE+RANKLE_MOMENT /SIGNAL_FOLDER=PROCESSED /SIGNAL_COMPONENTS=X,X,X,X,X,X,X,X ! /START_LABEL= ! /END_LABEL= /EVENT_SEQUENCE=RON+ROFF ! /EXCLUDE_EVENTS= ! /USE_POINT_RATE=FALSE /NORMALIZE_DATA=TRUE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ; End_For_Each /ITERATION_PARAMETER_NAME=INDEX ;
Example 3 : Export selected ranges from files
One can export ASCII data for selected ranges. In this example, there are two options for accomplishing this task.
Option 1: Exporting All Ranges
Given a file with many occurrences of the event sequence RHS+RHS it is possible to export all of these ranges using the command below.
! Export ASCII data for all ranges of RHS. The output is normalized. Export_Data_To_Ascii_File /FILE_NAME= /SIGNAL_TYPES=LINK_MODEL_BASED /SIGNAL_NAMES=ThoraxSeg+PelvisSeg ! /SIGNAL_FOLDER=ORIGINAL ! /SIGNAL_COMPONENTS= ! /START_LABEL= ! /END_LABEL= /Event_Sequence=RHS+RHS ! /Exclude_Events= ! /USE_POINT_RATE=FALSE /NORMALIZE_DATA=TRUE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ! /USE_SHORT_FILENAME=FALSE ;
Option 2: Subset of selected range (workaround)
It isn't possible to directly export a subset of these ranges, so the following work around can be used.
- First, set a START and STOP event before and after the ranges that should be exported. This can be done manually because it doesn't need to be precise.
- Second, create events within the ranges from START to STOP
- Third, modify the Event_Sequence to include the EXPORT event and add an Exclude_Event to ignore the last range
! This script assumes that a START and STOP event have already been created ! Create an event called EXPORT which is a copy of the RHS event that is between ! START and STOP and offset by 2 frames Event_Copy /EVENT_NAME=RHS /NEW_EVENT_NAME=EXPORT /FRAME_OFFSET=2 ! /EVENT_INSTANCE=0 ! /RANGE_INSTANCE=0 /EVENT_SEQUENCE=START+STOP ! /EXCLUDE_EVENTS= ! /START_AT_EVENT= ! /END_AT_EVENT= ; ! Modify the Event+Sequence to include the EXPORT event and add STOP to ! Exclude_Event to ignore the last range Export_Data_To_Ascii_File /FILE_NAME= /SIGNAL_TYPES=LINK_MODEL_BASED /SIGNAL_NAMES=ThoraxSeg+PelvisSeg ! /SIGNAL_FOLDER=ORIGINAL ! /SIGNAL_COMPONENTS= ! /START_LABEL= ! /END_LABEL= /Event_Sequence=RHS+EXPORT+RHS ! /Exclude_Events=STOP ! /USE_POINT_RATE=FALSE /NORMALIZE_DATA=TRUE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ! /USE_SHORT_FILENAME=FALSE ;
Example 4: Export a MODEL metric from several CMX files
Given a set of CMZ files, we will open each CMZ file and export one or more METRICS from the MODEL. In this example, the Pelvis segment's mass will be exported into an ASCII file with the same name as the CMZ file.
! Prompt the user for the Folder containing the CMZfiles. In this case sub-folders will ! be searched as well Set_Pipeline_Parameter_To_Folder_Path /PARAMETER_NAME=FOLDER /PARAMETER_VALUE= ; ! Set Pipeline Parameter to all CMZ files in the FOLDER and SUBFOLDERS Set_Pipeline_Parameter_To_List_Of_Files /PARAMETER_NAME=CMZ_FILES /FOLDER=::FOLDER /SEARCH_SUBFOLDERS=TRUE /FILE_MASK=*.cmz ; ! Loop over all CMZfiles For_Each /ITERATION_PARAMETER_NAME=INDEX /ITEMS=::CMZ_FILES ; ! Create a pipeline parameter containing the name of the CMZ file ! but replace the extension .cmz with the extension .txt which ! will be used for the exported file. Set_Pipeline_Parameter /PARAMETER_NAME=TXT_FILE /PARAMETER_VALUE=::INDEX /PARAMETER_VALUE_SEARCH_FOR=.cmz /PARAMETER_VALUE_REPLACE_WITH=.txt ! /PARAMETER_VALUE_PREFIX= ! /PARAMETER_VALUE_APPEND= ; ! Open the CMZ file File_Open /FILE_NAME=::INDEX ; ! Assuming one model in the CMZ file, store the MASS ! of the pelvis segment in a signal in the GLOBAL Workspace Evaluate_Expression /EXPRESSION=MODEL::SEGMENT::RPV::MASS /RESULT_NAME=GLOBAL::PELVIS_MASS /RESULT_TYPE=METRIC /RESULT_FOLDER=EXPORT ; ! Add any other pipeline commands here ! Make the GLOBAL Workspace active, so we can export a GLOBAL signal Select_Active_File /FILE_NAME=GLOBAL ! /QUERY= ; ! Export the signal Export_Data_To_Ascii_File /FILE_NAME=::TXT_FILE /SIGNAL_TYPES=METRIC /SIGNAL_NAMES=PELVIS_MASS /SIGNAL_FOLDER=EXPORT ! /SIGNAL_COMPONENTS= ! /START_LABEL= ! /END_LABEL= ! /EVENT_SEQUENCE= ! /EXCLUDE_EVENTS= ! /USE_POINT_RATE=FALSE ! /NORMALIZE_DATA=FALSE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ! /USE_SHORT_FILENAME=FALSE ; ! Clear the workspace in preparation for the next CMZ file. File_New ; End_For_Each /ITERATION_PARAMETER_NAME=INDEX ;
Example 5: Export Events from Files
This example will export all Event occurrences in terms of frame numbers to ASCII. In this example the events are labeled LHS1, LHS2, LHS3, RHS1, RHS2 and were created using the Number_Events_Sequentially.v3m meta-command.
! Get the names of all files in the workspace Set_Pipeline_Parameter_To_List_Of_Tagged_Files /PARAMETER_NAME=FILES /TAG_NAME=ALL_FILES ! /GET_CURRENT_SELECTED_FILES=false ! /USE_SHORT_FILENAMES=false ; ! Loop through each file For_Each /ITERATION_PARAMETER_NAME=FILE /ITEMS=::FILES ; ! Create a pipeline parameter containing the name of the c3d file ! but replace the extension .c3d with the extension .txt which ! will be used for the exported file. Set_Pipeline_Parameter /PARAMETER_NAME=TXT_FILE /PARAMETER_VALUE=::FILE /PARAMETER_VALUE_SEARCH_FOR=.c3d /PARAMETER_VALUE_REPLACE_WITH=.txt ! /PARAMETER_VALUE_PREFIX= ! /PARAMETER_VALUE_APPEND= ; ! Select active file Select_Active_File /FILE_NAME=::FILE ! /QUERY= ; ! Loop to convert events from time to frames for 4 HS reps For_Each /ITERATION_PARAMETER_NAME=INDEX /ITEMS=LHS1+LHS2+LHS3+RHS1+RHS2 ; ! Expression to convert events wrt frames Evaluate_Expression /EXPRESSION=EVENT_LABEL::ORIGINAL&:&:&::INDEX&*PARAMETERS::POINT::RATE+1 /RESULT_NAME=::INDEX /RESULT_TYPE=METRIC /RESULT_FOLDER=EVENT_EXPORT ; End_For_Each /ITERATION_PARAMETER_NAME=INDEX ; Export_Data_To_Ascii_File /FILE_NAME=::TXT_FILE /SIGNAL_TYPES=METRIC ! /SIGNAL_NAMES= /SIGNAL_FOLDER=EVENT_EXPORT ! /SIGNAL_COMPONENTS= ! /START_LABEL= ! /END_LABEL= ! /EVENT_SEQUENCE= ! /EXCLUDE_EVENTS= ! /USE_POINT_RATE=FALSE ! /NORMALIZE_DATA=FALSE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ! /USE_SHORT_FILENAME=FALSE ; End_For_Each /ITERATION_PARAMETER_NAME=FILE ;
Example 6: Export Concatenated Signals
All signals are exported to separate columns in the exported file. For metric signals (e.g. signals with only one or two entries/frames) this can be inconvenient. It is not possible to concatenate the signals in the command, but it is possible to concatenate the signals explicitly before export.
Consider a metric signal created as follows:
Metric_Signal_Value_At_Event /RESULT_METRIC_NAME=RKNEE_ANGLE_AT_RON ! /RESULT_METRIC_FOLDER=PROCESSED /SIGNAL_TYPES=LINK_MODEL_BASED /SIGNAL_NAMES=RKNEE_ANGLE ! /SIGNAL_FOLDER=ORIGINAL /EVENT_NAME=RON /GENERATE_MEAN_AND_STDDEV=FALSE ! /APPEND_TO_EXISTING_VALUES=FALSE ! /GENERATE_VECTOR_LENGTH_METRIC=FALSE ! /RETAIN_NO_DATA_VALUES=FALSE ;
In the test file I used for this example, this resulted in a metric with two metric values for two signals.
If the signal were exported as follows:
Export_Data_To_Ascii_File ! /FILE_NAME= /SIGNAL_TYPES=METRIC /SIGNAL_NAMES=RKNEE_ANGLE_AT_RON+RKNEE_ANGLE_AT_RON+RKNEE_ANGLE_AT_RON /SIGNAL_FOLDER=PROCESSED /SIGNAL_COMPONENTS=X,Y,Z ! /START_LABEL= ! /END_LABEL= /EVENT_SEQUENCE=, , /EXCLUDE_EVENTS=, , ! /USE_POINT_RATE=FALSE ! /NORMALIZE_DATA=FALSE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ! /USE_SHORT_FILENAME=FALSE ;
The resulting file would contain 6 columns of data (3 for each file).
The signals could be concatenated using the following pipeline:
Select_Active_File /FILE_NAME=ALL_FILES ! /QUERY= ; Metric_Signal_Value_At_Event /RESULT_METRIC_NAME=RKnee_Angle_at_RON ! /RESULT_METRIC_FOLDER=PROCESSED /SIGNAL_TYPES=LINK_MODEL_BASED /SIGNAL_NAMES=RKneeAngle ! /SIGNAL_FOLDER=ORIGINAL /EVENT_NAME=RON /GENERATE_MEAN_AND_STDDEV=FALSE ! /APPEND_TO_EXISTING_VALUES=FALSE ! /GENERATE_VECTOR_LENGTH_METRIC=FALSE ! /RETAIN_NO_DATA_VALUES=FALSE ; Merge_Data /SIGNAL_TYPES=METRIC /SIGNAL_FOLDER=For_Export+PROCESSED /SIGNAL_NAMES=GLOBAL::RKnee_Angle_at_RON+RKnee_Angle_at_RON ! /COMPONENT_SEQUENCE= /RESULT_TYPES=METRIC /RESULT_FOLDERS=For_Export /RESULT_NAME=GLOBAL::RKnee_Angle_at_RON ! /MERGE_TYPE=APPEND_TO_END /IGNORE_MISSING_SIGNALS=FALSE /PRE_CLEAR_RESULT_SIGNAL=TRUE ; Select_Active_File /FILE_NAME=GLOBAL ! /QUERY= ; Export_Data_To_Ascii_File ! /FILE_NAME= /SIGNAL_TYPES=METRIC /SIGNAL_NAMES=RKnee_Angle_at_RON /SIGNAL_FOLDER=FOR_EXPORT ! /SIGNAL_COMPONENTS= ! /START_LABEL= ! /END_LABEL= ! /EVENT_SEQUENCE= ! /EXCLUDE_EVENTS= ! /USE_POINT_RATE=FALSE ! /NORMALIZE_DATA=FALSE ! /NORMALIZE_POINTS=101 ! /EXPORT_MEAN_AND_STD_DEV=FALSE ! /USE_P2D_FORMAT=FALSE ! /USE_SHORT_FILENAME=FALSE ;
The last command of the above script will export to ASCII. The image below will show how it looks in the Export_to_ASCII_file command.
The resulting output file contains:
In versions of Visual3D prior to version 5, the Merge_Data command did not provide this functionality, so a workaround was required. This script provides a workaround for very old versions of Visual3D.