MoMo R5.1: Visualize C3D files

1. Contents
2. Setup
3. Preferences
4. Sessions
5. Command line
6. Models
7. C3D:	7.1	fC3D toolbox
	7.2	Diagrams
	7.3	Animation
8. Administration
9. Changes

The fC3D toolbox is a collection of function for reading and visualisation of C3D files. The files are imported to a Matlab struct at first. Afterwards the user can export selected trajectories, GRFs, analog signals or parameters to arrays and use them for individual processing. The contents of C3D files can be displayed as 2D diagrams using the GUI ShowC3D. 3D animations are created by ShowC4D, which allows a spatial navigation as in the Vicon software and creating objects like makers, connections, planes, arrows and tripods. The animations can be saved as picture files, AVI or animated GIF. An ASCII-files export can be freely configured by the user.

The modification and creation of C3Ds is implemented in general, but not recommended for standard use, because Vicon's interpretation of C3D format is fragil. However, renaming trajectories or swapping signals of analog channels is safe. Special formats used by Vicon to enhance the C3D standard are considered: more than 255 trajectories, more than 65535 frames (which are just 262 seconds at 250 Hz).

Time-critical function are implemented in C to increase the speed.

The fC3D toolbox was designed for clinical studies and diagnosis. In consequence the reliability and stability is ver important. The different functions have been tested ober several years in different labs under Matlab 6.5, 2008b and 2009a and with different versions of Vicon WorkStation and Nexus. An exahustive selftest allows a quality-control on the computer system of the users.

The fC3D toolbox is shipped with MoMo, but it is available as standalone version also.

The function ShowC3D let the user inspect the contents of one or more C3D files in details: Signals of force plates, evaluated GRF vector components, torsion around Z, force insertion point, EMG signals, trajectories of markers and evaluated 3D variables, group and parameter data.

File:

• File 1 popup-menu: This menu allows to open several files at the same time. Select "Add ..." to append a new so-called "tab". There are several ways to choose a file: 1. type the file name in the edit field (no, relative or absolute path), 2. right-click in the edit field or left-click the open-folder button (open file in folder of the current file), 3. right-click the folder button (open file in current folder, which can be changed with momocd or cd). C3D and ENF files can be opened.
  Note: C3D files are stored internally after reading. So you can open the same C3D before and after a change in different tabs and examine the results.
• Clear: Deselect all buttons of the current file.
• Stamp: Copy the selection status of the current to all other file tabs. This means that the same variables are displayed for all open files.
• Tool (pocket knife): This is a menu to call some tools and control the input and output:
  • Info+ENF displays general trial information.
  • To Workspace exports the current C3D as struct to Matlab's workspace.
  • Recent sessions opens the momocd dialog to choose a session from the the list of recently processed sessions.
  • Debug show problems at reading the C3D.
  • Win explorer opens the folder of the current C3D in the Windows explorer (or Konqueror on Linux).
  • Blue background creates figure, which can look nicer on PowerPoint presentations.
  • Show events toggles the visibility of event marks. This can be performed through the context menu of the created figures also.
  • Forces>Offset+Scale: The offset is removed from the raw signals of the force plates and the results are scaled. This concerns the X12 to Z4 channels.
  • Forces>Auto Offset: The function for calculating the forces tries to determine better offset values. Vicon WorkStation defines the mean of the first 10 frames as offset, but this is not precise and sometimes completely wrong. The quality of the calculated torsion Tz strongly depends on the correct offsets.
  • Forces>Lab reference system: The forces and the center of pressure are transformed from the plate's to the lab's reference system.
  • Forces>Noise limit: The torsion around the Z-axis and the center of pressure are very sensitive to noise of the signals, if the acting forces are small. Therefore the signals are set to zero if the force is below a certain limit, e.g. 10 Newton.
  • EMG: Auto offset: The mean of the signals is usually a better offset for AD-sampling, than the offset values written by Vicon WorkStation. Enabling this item enables the mean-offset when the signals are filtered. (new: 18-Jun-2010)

Forces:

• X12 to Z4: Raw signals for channels of Kistler plates (AMTI supported also).
• Fx, Fy, Fz, |F|, Tz: Components and length of the GRF vector in the lab's reference system. Tz is the torsion around the plate's Z-axis.
  Note: In MoMo "Fx" means the force in the current gait direction, but in ShowC3D the global X-axis is meant.
• X, Y, CP: X-, Y-component and 3D point of the CoP.
• Filter icon: If enabled, force signals are filtered and scaled. The sign of the value is not changed to allow for an easier comparison with the raw signals. You can control the interpretation of the force signals by some flags in the Tool menu.

EMG:

• 1 to 16: Raw signals of EMG channels. The recognition of EMG channels depends on lab specifix styles, which are defined in fC3D_UserDef. E.g. in the Gaitlab HD, the labels of EMG channels start with "EMG " or "FW " (trailing spaces).
• Filter icon: Click on the icon to toggle filtering: enabled: , disabled: . If enabled, the EMG signals are filtered by the user-defined filter selected in the popup menu. (new: 04-Dec-2009)
  See also: Tool>EMG: Auto offset.
• Note: Currently there is no way to display auxiliary channels: analog channels which are neither forces nor EMGs. Please contact me if you need this.

Parameters:

• Group, Parameter: The parameter in C3Ds are divided into groups. Select a group at first. Right-click in the data field to toggle the visibility of values.

Trajectories:

• Labels: Select variables to be displayed. Shift and Ctrl allows choosing multiple names, a right-click deselects all trajectories.
• 3D: Draw three 2D diagrams or a 3D plots for trajectories. Use the mouse for spatial navigation in the 3D view.
• to 4D: Open trial in ShowC4D.
• sort: Sort labels alphabetically.

Buttons:

• Help: Show a help text. The HTML button in the appearing dialog opens the HTML help page.
• Exit: Close the dialog, but not the created diagrams.
• Close: Close created diagrams, but not the dialog.
• Plot: Draw diagrams of selected variables and for all tabs.

Created diagrams:
Some output diagrams contain event markers. They can be dragged vertically with the mouse using the small arrow handle or text "Events" right from the diagrams. A right-click on this handle toggles the visibility of vertical lines through the events (new: 15-Jun-2010). If the event handle has vanished after zooming into a diagram, disabling and re-enabling the events in the context menu let them appear again.
If a curve contains (invisible) Inf or NaN values, the text 'Gaps!' is displayed as warning. The context menu of this text (right-click) displays the names of the affected trajectories. all frames with gaps are colored in light yellow, if "Gaps" flag is enabled in the context menu of the diagram or the figure.
Several jobs can be started through the context menu of the figures (right-click) depending on the data: the visibility of gaps and events can be toggled, values of the trajectories can be copied and simple statistics can be displayed.
The right-most icon in the toolbar toggles the visibility of the legend (do not use the less powerful legend-icon of Matlab 7). The legend can be moved using the mouse.

Tips:

• Look at the tooltips (hold the mouse over an object for a while) for further information, e.g. the path of the file.
• Buttons of not existing analog channels are disabled, e.g. for static trials.
• Open files from the command line: ShowC3D(FileName) with FileName is a string or cell string.
• Use file patterns: ShowC3D *16 opens e.g. "Trial16.c3d".
• The appearence, e.g. font size, is controlled by DlgSkin and can be changed in DlgSkin_Choose.
• Clear all preferences, e.g. window positions: ShowC3D('$clear').
• Version: ShowC3D('$version') or click on the title on the bottom left.
• Dependencies from other tools (checked in S4D_Pref): fC3D >= v5.01 (>= 5.13 preferred), GLToolbox >= v2.104.
• The initial values for the dialog, filters and parameters for processing forces are defined in the file "ShowC3D.init". This file can be edited manually. E.g. the number of force plates can be set here.

The function ShowC4D visualizes the contents of C3D files as animated 3D objects. It can be called from the command line, from MoMoG or with additionally created objects from the model scripts of MoMo.
The file and the ShowC4D-model can be defined as optional input arguments: ShowC4D(FileName, Model).
ShowC4D uses a model to identify markers and other objects in the variables included in a C3D. These models are implemented as simple Matlab functions and users can add own models.

Spatial navigation:

• Right, left and both (or middle) mouse key: similar to method of Vicon-WorkStation.

UI-controls:

• Open: Open a file. Right-click to open the file in a new figure.
• Play: It shows the current frame number and toggles the status of running.
• Slider: Move the slider to select a frame. The events are displayed above the slider. A right-click advances the current frame to the following event.

Draw menu:

• Solid 3D: Toggle solid or wire-frame mode.
• Floor: Show checkerboard floor.
• Grid: Visibility of grid on the walls.
• Markers: toggle visibility of markers.
• Uni tripods: Draw tripods with one color only, or with X-, Y-, Z-axis in red/green/blue.
• Shading: Enable different shading modes.
• Renderer: Switch engine for drawing. Auto let Matlab choose the renderer. If the hardware OpenGL renderer fails, try software rendering with Generic OpenGL.
• Markers: Toggle visibility of markers.
• Projection: Select orthographic or perspective projection.

Show menu:

• Group of view choices: Set camera and view-point to the initial or default position, or look in the X-, Y- or Z-direction.
• New light: Move the light to the current camera position.
• Coordinates: Show axes of global reference system.
• Marker names: Attach labels to markers. This can cause problems on export of graphics.
• Frame number: Display the current frame number or time and events. The frame button on the bottom is not visible in exported movies usually.
• Speed: Limit the animation frequency. With e.g. "1/2x", the frames are drawn with an upper limit of the half recording frequency. Nevertheless, the main limit is the prozessor speed, because rendering in Matlab is slow. The speed of exported movies can be adjutsed separately in the export dialog.
• Export: Export a graphics file of AVI movie.

Model menu:

• Auto: ShowC4D selects the model according to the marker set of the C3D.
• As markers: Display all variables as markers.
• List of models: A specific model can be chosen. If none of the needed markers are found, a warning appears.

Help menu:

• ShowC4D Help: Display a help text.

Export dialog:

• Size: Width and height of the output in pixels. For JPEG and movie files this is set to multiples of 8 automatically. The minimum width of Matlab figures is 104 pixels.
• Smooth: Anti-aliasing for nicer output.
• UI: Include buttons and slider in the output.
• Picture: Format: PNG files a recommended.
• Picture: Alpha: Transparent background for PNGs.
• Movie: Frame: Frame interval for saving.
• Movie: Format popup: Either AVI file or a series of PNG files. PNG 8 creates files with an indexed color table with 256 colors. The color-reduction is not stable – please vary the view point a little bit and start the export again on problems. PNG 24 creates a series of true-color pictures. The command for creating an animated GIF with ImageMagick is written to the command window. Specs opens a dialog to specify the speed of the created movie and AVI properties as compression and quality (see help avifile, Indeo5 at 90% quality creates a fair video).
• Save: Save picture or movie file.

Models for ShowC4D:
The relation between variables and 3D objects is defined in models, which are implemented as simple Matlab functions. These functions are store in the folder "ShowC3D4_Model", they can be modified and new models can be created: Use the Model: Edit menu. Then a new file is created in the correct path. See the template file for help.
All versions 4.xy of ShowC4D use the models in the folder "ShowC3D4_Model".
ShowC4D is not limited to C3D files as input. It accepts structs with a well defined format (e.g. when called from MoMo). Further file types can be inserted as plugins. Ask the author for help.

General tips:
Reset the styles and window positions: ShowC4D $clear
Self test: ShowC4D $test
Arguments to show a trial with evaluation of MoMo: C4D, C4Dadd.
The freeware program ImageMagick creates small and nice animated GIFs. The needed command is written to the command line after the export of a movie as series of PNGs.