Export Data To ASCII File

NOTE: This command requires the active files (to pull data from) be set first.

The Visual3D pipeline command Export Data To ASCII File exports ASCII data to one of 2 formatted data files (Visual3D default and P2D).

Reserved Signal Names

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.

Normalization

Data can be exported to a normalized ASCII output. The user can select the number of points to output (i.e. 51 points or 101 points). If Normalization is selected in the command by setting the parameter /NORMALIZE_DATA= TRUE, the signal is interpolated using cubic spline.

Pipeline Command

The command parameter details follow:

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
;

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.

Examples

We have listed a few examples for your review.

Example 1: File Export of multiple files

Using Export_Data_to_ASCII_File to export data from individual C3D files to unique text files.

Assuming:

1. the cmo file is already open
2. you want to export data from each C3D file to a txt of the same name (or prefix).
3. 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: File Export of multiple files

In this example, the output filesnames 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 pipline 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

One can export ASCII data for a selected ranges. In this example, there are two options for accomplishing this task.

Option 1: Selected Range

Given a file with many occurrences of the range RHS it is possible to export all ranges using the command.

! 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 CMO files

Given a set of cmo files, open each cmo file and export one or more METRICS from the MODEL. In this example, the Pelvis segment mass will be exported into an ASCII file with the same name as the cmo file.

! Prompt the user for the Folder containing the cmo files. 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 cmo files in the FOLDER and SUBFOLDERS
Set_Pipeline_Parameter_To_List_Of_Files
/PARAMETER_NAME=CMO_FILES
/FOLDER=::FOLDER
/SEARCH_SUBFOLDERS=TRUE
/FILE_MASK=*.cmo
;

! Loop over all cmo files
For_Each
/ITERATION_PARAMETER_NAME=INDEX
/ITEMS=::CMO_FILES
;

! Create a pipeline parameter containing the name of the cmo file
! but replace the extension .cmo 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=.cmo
/PARAMETER_VALUE_REPLACE_WITH=.txt
! /PARAMETER_VALUE_PREFIX=
! /PARAMETER_VALUE_APPEND=
;

! Open the cmo file
File_Open
/FILE_NAME=::INDEX
;

! Assuming one model in the cmo 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 cmo file.
File_New
;

End_For_Each
/ITERATION_PARAMETER_NAME=INDEX
;

Example 5: Export Events

This example will export Events in frames to ASCII. 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 Metric 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 very old versions of Visual3D (ex. v4), 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.

Back to Pipeline Commands Reference