Differences

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

--- visual3d:documentation:definitions:file_formats:visual3d_ascii_format [2024/06/19 12:47] – sgranger
+++ visual3d:documentation:definitions:file_formats:visual3d_ascii_format [2025/03/18 19:00] (current) – [Component String] Organized information into a table. wikisysop
@@ Line 1: / Line 1: @@
-visual3d exports data into several file formats. the simplest and default file format for data export to ascii files is the following:
+====== Visual3D ASCII Format ======
-**any signal** that can be seen in the data tree (in signal and event processing mode) can be exported to a c3d file.
+Visual3D exports data into several file formats. The simplest and default file format for data export to ASCII files is the following:
-|-   |c:exampledataexamplewalk.c3d|filename from which the data came.\\ e.g. filename withing the visual3d workspace|
+**Any signal** that can be seen in the Data Tree (in Signal and Event Processing Mode) can be exported to a C3D file.
-|-   |emg9                        |signal name                                                                      |
-|-   |analog                      |signal type                                                                      |
+|-   |C:ExampleDataExampleWalk.c3d|Filename from which the data came.\\ e.g. Filename withing the Visual3D Workspace|
-|-   |original                    |signal folder (e.g. original, processed, etc.)                                   |
+|-   |EMG9                        |Signal Name                                                                      |
-|item|x                           |component. (analog signals have channel 0 or channel x                           |
+|-   |ANALOG                      |Signal Type                                                                      |
+|-   |ORIGINAL                    |Signal Folder (e.g. ORIGINAL, PROCESSED, etc.)                                   |
+|ITEM|X                           |Component. (ANALOG signals have channel 0 or channel X                           |
 |1   |23.0                        |-                                                                                |
 |2   |22.5                        |-                                                                                |
@@ Line 14: / Line 16: @@
 |5   |21.0                        |-                                                                                |
-\\
+The file contains data in columns. The first column is the frame number. One file may contain several signals.
-the file contains data in columns. the first column is the frame number. one file may contain several signals.
-====== time data ======
+===== Time Data =====
-visual3d recognizes three time labels:
+Visual3D recognizes three time labels: time, analog, and derived.
-an example header:
+^ Time Label ^ Description ^
+| TIME | This is a column containing the time at the [[visual3d:documentation:c3d_signal_types:target_data_type|POINT rate]]. |
+| ANALOGTIME | This is a column containing the time at the [[visual3d:documentation:c3d_signal_types:analog_data_type|ANALOG rate]]. |
+| DERIVEDTIME | This is a column containing the time at a DERIVED rate. DERIVED signals can have any sampling rate that is an integer multiple of the POINT rate. Each ASCII file permits only one DERIVEDTIME signal. If there is more than one DERIVEDTIME signal, you will need to import multiple text files; one for each DERIVEDTIME.|
-|    |filename     |filename     |filename     |
+An example header:
-|    |time         |analogtime   |derivedtime  |
-|    |frame_numbers|frame_numbers|frame_numbers|
+|    |FILENAME     |FILENAME     |FILENAME     |
-|    |original     |original     |original     |
+|    |TIME         |ANALOGTIME   |DERIVEDTIME  |
-|item|x            |x            |x            |
+|    |FRAME_NUMBERS|FRAME_NUMBERS|FRAME_NUMBERS|
+|    |ORIGINAL     |ORIGINAL     |ORIGINAL     |
+|ITEM|X            |X            |X            |
 |1   |0.0          |0.0          |0.0          |
-\\
-===== time =====
-thss is a column containing the time at point rate
-===== analogtime =====
-this is a column containing the time at analog rate
-===== derivedtime =====
-this is a column containing the time at derived rate.
-derived signals can have any sampling rate that is an integer multiple of the point rate. each ascii file permits only one derivedtime signal.
-it there is more than on derivedtime signal, you will need to import multiple text files; one for each derivedtime.
-====== signal units ======
-all signals are stored in mks units.
+===== Component String =====
-====== exporting data ======
+Deciding what character to use for representing a signal component has resulted in some flip flopping over the years. The final straw in our decision was the introduction of a 4x4 [[visual3d:documentation:c3d_signal_types:rotation_data_type|ROTATION]] signal to the [[visual3d:documentation:c3d_signal_types:c3d_format|C3D format]] and to Visual3D. While X, Y, Z have been synonymous with the first 3 components of any signal, X, Y, Z are not logically the first 3 components of a ROTATION signal
-this data file can be exported from visual3d using the pipeline command [[visual3d:documentation:pipeline:file_commands:export_data_to_ascii_file|export_data_to_ascii_file]]
+On the other hand, using numerical values has other controversial issues. For example, Matlab won't read a number as a string and apparently there are .m files that treat the component as a string.
-====== importing data ======
+Here are the current decisions.
-this data file can be imported to visual3d using the pipeline command [[visual3d:documentation:pipeline:file_commands:import_data_from_ascii_file|import_data_from_ascii_file]].
+^ Signal Type ^ Returned Component Strings ^
+| [[visual3d:documentation:c3d_signal_types:target_data_type|TARGET]] | XYZR |
+| [[visual3d:documentation:modeling:landmarks:landmarks_overview|LANDMARK]] | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:force_data_type|FORCE]] | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:cofp_data_type|COFP]] | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:freemoment_data_type|FREEMOMENT]] | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:link_model_based_data_type|LINK_MODEL_BASED]] | XYZ |
+| [[visual3d:documentation:c3d_signal_types:analog_data_type|ANALOG]] | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:kinetic_kinematic_data_type|KINETIC_KINEMATIC]] | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:metric_data_type|METRIC]] (3 components) | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:metric_data_type|METRIC]] (others) | 0, 1, 2, ... |
+| [[visual3d:documentation:visual3d_signal_types:derived_data_type|DERIVED]] (3 components) | XYZ |
+| [[visual3d:documentation:visual3d_signal_types:derived_data_type|DERIVED]] (others) | 0, 1, 2, ... |
-===== first row =====
+The exception is that Visual3D allows a character to be added to a number. For example C0 instead of 0
+===== Signal Units =====
-one of the constraints on the file import is that the first line of the signal column must match a c3d file in the visual3d workspace. this allows visual3d to recognize which file to add the data to.
+All signals are stored in MKS units.
-====== number of analog and point frames ======
+===== Importing and Exporting =====
-for analog and target (point) data the following rules apply: if there are more frames of data in the ascii file than there are in the c3d file, the ascii signal is truncated.
+This data file can be imported to Visual3D using the pipeline command [[Visual3D:Documentation:Pipeline:File_Commands:Import_Data_From_ASCII_File|Import_Data_From_ASCII_File]]. One of the constraints on the file import is that the first line of the signal column must match a C3D file in the Visual3D Workspace. This allows Visual3D to recognize which file to add the data to.
-if there are fewer frames of data in the ascii file than there are in the c3d file, the signal is padded with frames of data containing data_not_found.
+This data file can be exported from Visual3D using the pipeline command [[Visual3D:Documentation:Pipeline:File_Commands:Export_Data_To_ASCII_File|Export_Data_To_ASCII_File]]
-**note:** for derived signals all rows are added to the data file within visual3d without truncation or padding. this is partly because derived signals cannot be exported to the c3d file at this point, so there is no conflict with the c3d file format.
+===== Number of Analog and Point Frames =====
+The following rules apply for ANALOG and TARGET (POINT) data:
+  * if there are more frames of data in the ASCII file than there are in the C3D file, the ASCII signal is truncated.
+  * if there are fewer frames of data in the ASCII file than there are in the C3D file, the signal is padded with frames of data containing DATA_NOT_FOUND.
+**Note:** For DERIVED signals all rows are added to the data file within Visual3D without truncation or padding. This is partly because DERIVED signals cannot be exported to the C3D file at this point, so there is no conflict with the C3D file format.