Benutzer-Werkzeuge

Webseiten-Werkzeuge


fileformats:d3d

The Motiondata file format (.d3d)

This is the recommended file format to store any time series data and additional parameters or meta data.

The c3d file format and also the HD ASCII format have serveral limitations, which are overruled by this new open and flexible file format. It defines an easy and fast to read xml-Header including only non timeseries metadata and parameters. The timeseries are attached as binary double values and only referenced by the header. This allows very fast read routines with random access, also for very big files.

In contrast to the .c3d file format it allows to save multiple trials as a tree of data. E.g. for managing normal gait data, the time series for all joint angles of all strides from all sessions of all subjects can be saved in a single file. This makes it easy, to determine mean and standard deviations (meanStd) or coefficients of multiple variance statistics (CMC).

A single trial as saved in .c3d file corresponds to the <DataSet>-element. A timeserie is referenced, depending on the type of the data as e.g. <Tuple3dTimeSerie>, <Matrix3dTimeSerie>, <DoubleTimeSerie>, …

A <DataSet> can have a <PropertyGroup>-element with metadata or specific parameters. It is not specified, which properties these are.

If a „Vicon trial“ is converted to .d3d, all of its properties, saved in the corresponding .enf file, are copied in the <PropertyGroup>.

If the flag singlePrecision is set to true, then all of the data is saved in float values.

<MotionData position="0" singlePrecision="true">
    ...
</MotionData>

This feature is not recommend, but if you really want to use it, it is recommended to use it only in combination with the flag streamingData=„true“:

<MotionData position="0" singlePrecision="true" streamingData="true">
    ...
</MotionData>

Processed data versus streaming data:

The default version of the files head looks like the following:

<MotionData position="0">
    ...
</MotionData>

The referenced timeseries are saved in a sequence after this head. This is efficient, if you want to read a subset of timeseries or if you want to add a timeserie. Also if you want to read all timeseries for processing this is best, because you can get a specific timeserie as an array without collecting the data from different positions of the memory. Remove timeseries is more difficult and not recommened due to performance issues. This default version of the format is good for work with processed data. That means that the number of frames for all timeseries are fix.

If the flag „streamingData“ is set

<MotionData position="0" streamingData="true">
    ...
</MotionData>

the timeseries are saved in a different way. For each frame the value for each time serie is saved and then for the next frame and so on. This is similar to the c3d-format. This file format version is good to save raw data with an unknown number of frames if you start with saving. For this format version it is not recommended to add or remove timeseries due to performance issues.

Working with data with different sample rates:

<DataGroup name="Trial" used="true" comment="" frames="-1">
            <DataSet name="60811a12.c3d" used="true" comment="" frames="200" sampleRate="120">
            ...
            </DataSet>
            <DataSet name="60811a12.abc" used="true" comment="" frames="400" sampleRate="240">
            ...
            </DataSet>
</DataGroup>

Working with properties corresponding to different files in the same file format

abc.d3d, abc.avi, abc.1.avi

E.g you have different avi files attached to the same trial and you want to save the offset delay of each of the movies to the data saved in the abc.d3d file, you have to follow this convention:

<PropertyGroup name="all">
      <Property name="MOVIEDELAY" value="10"/>
      <Property name="MOVIEDELAY.1" value="20"/>
            ...
</PropertyGroup>

Common Attributes:

name Default Description
name
used true If this attribute is set to false, the element should be excluded from any calculations or visualization.
comment A free comment, to describe what is the meaning of the elements corresponding data.
frames -1 For a <DataSet> element, this attribute includes the number of frames of its timeseries. All timeseries of a <DataSet> has the same number of frames. If this attribute is set to a number > 0 for a <DataGroup> element, all included timeseries must have this length.

Events and phases

Phases and events data are saved as subelements of a element which corresponds to a trial. Have a lot at the following example:

    <DataSet name="3d" used="true" comment="" frames="200">
    	<Phases>
    		<Phase name="RFootFlat" startPosition="10" endPostion="30"/>
    		<Phase name="RFootFlat" startPosition="100" endPostion="130"/>	
    	</Phases>
    	<Events>
    		<Event name="RHS" position="11"/>
    		<Event name="RHS" position="111"/>
    		<Event name="LHS" position="...
    	</Events>
 
                    ...
    </DataSet>

Example XML header of a .d3d file

<MotionData position="0">
    <DataGroup name="normal" used="true" comment="" frames="-1">
        <DataGroup name="singleTrials" used="true" comment="" frames="-1">
            <DataSet name="60811a12.c3d" used="true" comment="" frames="200">
                <PropertyGroup name="all">
                    <Property name="DURATIONTIME" value="4.29166666666667" />
                    <Property name="MOVIEDELAY" value="0" />
 <Property name="ITERATIONS" value="n/a" />
                    <Property name="CLASS" value="Dynamic+Kinetics" />
                    <Property name="LAST_MODIFIED" value="-1" />
                    <Property name="STREAMSIZES" value="52, 1865772, 808508" />
                    <Property name="TIMECODEMAP" value="#2: 0" />
                    <Property name="RESIDUAL" value="n/a" />
                    <Property name="SUBJECTS" value="51371" />
                    <Property name="FP2" value="L2" />
                    <Property name="OLGA_INFO" value="PIG Processed" />
                    <Property name="TRIALCATEGORY" value="normal" />
                    <Property name="EXTRAMOVIEDELAY" value="-0.183332994580269" />
                    <Property name="GAIT_MODE" value="normal" />
                    <Property name="DURATIONFIELDS" value="515" />
                    <Property name="FP1" value="R1" />
                    <Property name="NO_OF_FRAMES" value="n/a" />
                    <Property name="TYPE" value="Gait Dynamic Movie" />
                    <Property name="DURATIONTIMEDISPLAY" value="00:04" />
                    <Property name="CREATIONDATEANDTIME" value="2006,8,11,15,0,25" />
                    <Property name="SIDE" value="Both" />
                    <Property name="CAMERACALIBRATION" value="CameraCal20060811085913.cp" />
                    <Property name="FILENAME" value="60811a12.c3d" />
                    <Property name="MARKERSET" value="PlugInGait.mkr" />
                    <Property name="WORKSPACEFILENAME" value="GaitLab.wks" />
                </PropertyGroup>
                <Tuple3dTimeSerie name="LSHO" position="0" />
                <Tuple3dTimeSerie name="LHUMS" position="600" />
                <Tuple3dTimeSerie name="LELB" position="1200" />
                <Tuple3dTimeSerie name="LELBW" position="1800" />
                ...
                <Matrix3dTimeSerie name="RGaitCoordinateSystem" position="24600" />
                <Matrix3dTimeSerie name="ThoraxCal" position="26400" />
                <Tuple3dTimeSerie name="ThoraxCalPosition" position="28200" />
                <Matrix3dTimeSerie name="Thorax" position="28800" />
                <Tuple3dTimeSerie name="ThoraxPosition" position="30600" />
                <DoubleTimeSerie name="RHeadAnteRetroDirCosAngle" position="31200" />
                <DoubleTimeSerie name="LHeadAnteRetroDirCosAngle" position="31400" />
                <DoubleTimeSerie name="RHeadAnteRetroProjAngle" position="31600" />
                ...
            </DataSet>
        </DataGroup>
    </DataGroup>
</MotionData>

How to save periods of missing data?

The timeseries data is saved in binary format as a serie of doubles (8xbyte). This format allows to have NaN values.

Conventions

To save raw data a naming and structure convention is given as shown in the following example:

    <MotionData position="0">
        <DataGroup name="rawData" used="true" comment="" frames="-1">
            <DataGroup name="trial" used="true" comment="" frames="-1">
                <DataSet name="3d" used="true" comment="" frames="200">
 
                    ...
                </DataSet>
 
    	<!-- additional optional datasets can be used if raw data with different sample rate and
     length is collected e.g. EMG data -->
    	<DataSet name="EMG" used="true" comment="" frames="800">
 
                    ...
                </DataSet>
    	</DataGroup>
    	<!-- addiotional optional groups with further trials can be used if more than one trial should be saved in this file
     for performance issus. But this is not recommended. It is better to store the data from each trial in a seperate
     file -->
           <DataGroup name="trial1" used="true" comment="" frames="-1">
            ...
    	</DataGroup>
    </MotionData>

Data Types

Name doubles Description
Double 1
Tuple3d 3
Quat4d 4 sequence of the values w,x,y,z
Matrix3d 9

How to add motiondata files with different suffix than „d3d

There is currently no elegant mechanism available. The possible suffixes of motion data file are hardcoded in the follwing two modules: MotionDataFileType2 and Trial2MotionData. Currently the suffixes defined in the following table are recognized. In a future version of the software a better method which allows the user itself to add further suffixes will be added.

Suffix Description
r3d Raw data collected with JDAQ, e.g. from ROS
d3d Processed data
rps Raw data collected from Artiminds RPS
rtde Raw data collected via the RTDE interface from Universal Robotics
v3d Raw data collection by the Vicon system via DataStream API
fileformats/d3d.txt · Zuletzt geändert: 2021/02/11 17:47 von oliver

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki