Visual3D™
Signal, Event, and Pipeline Processing Tutorial
(3.0 Edition)
C-Motion, Inc.
15821-A Crabbs Branch Way
Rockville, MD 20855 USA
(301) 840-1919 (phone)
(301) 840-0271 (fax)
support@c-motion.com
Table of Contents
How to Use the Visual3D™ Tutorials ..........................................................................................1
Visual3D Tutorial # 3 ............................................................................................................2
The Visual3D Workspace........................................................................................................3
Starting Visual3D...............................................................................................................4
Load the Motion and Model File .............................................................................................4
Event Management ...............................................................................................................4
Edit or Delete Events..........................................................................................................6
The Pipeline Processor – Workflow Automation...........................................................................7
Script Editing ....................................................................................................................7
Signal Processing..................................................................................................................9
More Signal Processing – Statistics/Metrics........................................................................... 14
Processing History ............................................................................................................ 15
Advanced Pipeline Topics ..................................................................................................... 16
Acknowledgements: The development of Visual3D software was funded in part by STTR grant (R43 HD3728601) from the National Institute of Child Health and Human Development (NICHD). C-Motion also gratefully
acknowledges and appre ciates the assistance provided by the Rehabilitation Medicine Department in the Warren
Grant Magnuson Clinical Center at the National Institutes of Health.
ii
How to Use the Visual3D™ Tutorials
Welcome to C-Motion’s Visual3D motion analysis software. This is
the third of four tutorials.
After motion capture data has been collected, there are several
steps to performing a motion analysis in which Visual3D is needed.
You need to:
1. Create a model of the subject(s) using a subject standing
calibration file, and define the linked segments
2. Validate the movement data and associate the movement
data with the model
3. Perform any desired signal and event processing
4. Define any biomechanical model based calculations for
angles, moments, powers, and other metrics.
5. Generate the desired kinematic and kinetic analysis reports
For this reason, there are four (4) tutorials available. They cover:
1. Modeling
2. Data and Force Plate Validation
3. Signal, Event, and Pipeline Processing
4. Analysis and Reporting
Each tutorial picks up where the last one ended, but the results of
each tutorial are saved as a .cmo file so that you may skip a part
that you already are familiar with, or try out different features and
capabilities during a tutorial - using it only as a guideline.
Screen shots and explanations are provided in this column, and the
tutorial instructions are listed in the right column.
The tutorial instructions are
given in this column.
Various sample input files will be needed, and can be downloaded
from the web site at:
http://www.c-motion.com/support/tutorials.htm
We hope you find Visual3D useful. We are constantly improving the
product, and if you have any suggestions for enhancements or new
features, we would love to hear them. Just drop us a note at
info@c-motion.com any time.
April, 2004
1
Visual3D Tutorial # 3
It is assumed that Visual3D has been installed and a model has
been created as described in the first tutorial. Likewise, we assume
that a movement trial has been assigned to this model and the data
validated – from the second tutorial.
We will be doing a lower body gait analysis in a collection of
tutorials. The techniques and processes followed are easily
transferred to sports, neuroscience, animation, or other applications
since we are focusing on the tool, not the analysis.
To start the tutorial, we need to pick up where the second one
ended – with a completed model and assigned motion file saved as
a .cmo file. This can also be downloaded.
Use the .cmo file from the
second tutorial or download
it. It is called:
“Data Validation Sample.cmo”
You will also need several script files to use as references. These
need to be downloaded. These files can be found on the web site in
the Example Files section at:
http://www.c-motion.com/support/tutorials.htm
This tutorial is focused on, signal and event processing, and using
the Pipeline processor in Visual3D.
The file “Signals and Events.cmo” contains the end results of this
tutorial and may be used to check your progress and/or as input for
the subsequent analysis and reporting tutorials.
April, 2004
Save the files in a location on
your computer where you
would normally save motion
capture files.
2
The Visual3D Workspace
Visual3D creates a unique Workspace into which capture data is
added, models are integrated, and reports are produced. The whole
workspace can then be saved and shared as a digital report in
which all the underlying analysis, data, and models can be
referenced.
The entire Visual3D Workspace is contained in a special file, with
the extension “.cmo ” (for C-Motion Output).
In this tutorial we will process a movement trial. The file itself is
never touched. Instead, it is copied into the workspace. Even in
the workspace, the original data is not modified, but is maintained
so that all calculations and signal processing results can be
recreated.
As a clinical and research tool, Visual3D keeps track of the
processing done to data so that unwarranted assumptions are not
made, and consistent outcomes are reached every time the same
data is used. This is also why we prefer getting raw data from
systems rather than processed data (i.e. no interpolating, filtering,
or pre-processing). For example, if all we have is ground reaction
data from a force plate as input, we have to assume that all the
force plate properties, calibrations, and processing was perfect
since there is no way to validate the data. This leads to
unwarranted assumptions and possible invalid analytical results.
Visual3D is designed to work
with raw data as a way to
avoid making unwarranted
assumptions and generating
valid, reproducible results.
The above information is in each tutorial, but this tutorial is the one
where the real value and power of these workspace concepts and
the ability to reproduce your results (and eliminate unknown
assumptions) will become very apparent. You’ll see…
April, 2004
3
Starting Visual3D
Launch the program from you Windows Start menu. After a brief
title screen display, the program opens with an empty Visual3D
Workspace. The Visual3D Workspace tab displays the contents of
the current workspace – which can be saved as a .cmo file.
Start Visual3D:
Start ->
Programs - >
C-Motion ->
Visual3D
Load the Motion and Model File
First we will open the data saved earlier as a .cmo file. We will add
the movement trial to the workspace.
From the File menu, select
Open - > Data Validation
Sample.cmo
The next step is to learn about a new folder in the Data Tree. This
one holds the names and frame numbers of any important events
that take place during the movement trial.
Event Management
An event is simply something of interest that correlates to a motion
capture frame. Some events are rather well known, such as HeelStrikes and Toe-Offs during a gait study. Others we can just make
up or calculate specifically. If standard segment names and a force
plate are used, Visual3D can automatically generate a series of well
known gait analysis events (toe-on’s, toe-off’s, heel-strikes, etc.).
All events have a name (or label), which can be unique or recurring
throughout any motion capture trial.
April, 2004
4
Events may be created by double-clicking on the line in an Signal
Graph, or by Visual3D when:
•
•
•
•
•
A certain signal appears
A signal threshold is exceeded
A pattern has been recognized (Target Pattern Recognition
or TPR)
A parameter has been put in the original c3d file at a frame
(i.e. Vicon stores events as c3d parameters)
A calculation, metric, or statistical result has been triggered
or derived
You can create reports that are constrained to the time between
events.
To create a simple event, go to the Signal and Event Processing
Tab, and graph any signal – we picked the Z component of RFT1.
Then double-click on the graph line.
Graph RFT1’s Z signal
Double-Click on the line at
frame 20 (where the right
heel looks like it firsts hits the
floor) to create an event
there
Enter “heel strike” for the
label.
Note: You can use the arrow
buttons on this dialog to
move frames forward and
backward in case you missclick or want to fine tune the
event location.
Notice the new
EVENT_LABEL folder in the
data tree, and notice the tick
mark on the line where the
event is located.
The event is associated with
a frame in this movement
file, thus is spans all signals
(as shown when the RSK1
signal is graphed too)
April, 2004
5
There are three ways to create new events in Visual3D.
1. The easiest is to double-click on a point on a Signal Graph.
Right-clicking on a signal in the data tree will also provide a
submenu in which events can be created or signals
processed (i.e. interpolated, filtered, etc.).
2. The other way is to use the Pipeline to create events.
3. It is also possible to write your own plug-in to process
signals and create unique events.
Edit or Delete Events
Events can be deleted or edited and the frame in which they occur
can be adjusted using the Event Editor - launched from the
toolbar.
The Event Editor on the
toolbar (far right) can be
used to edit events…
(Below is an older screeshot – not from this tutorial)
Event Editor Tool
Look at the Processed Signal
(or an original signal)
Adjust what frame it occurs in
Now we will save our work so far (File- > Save As), and then we will
cover the Pipeline processor to uncover the real power for creating
events and processing signal data.
Save the file as:
Signal Processing.cmo
Now we need to learn about
the Pipeline Processor in
Visual3D…
April, 2004
6
The Pipeline Processor – Workflow Automation
The Pipeline process is mentioned at this point because all signal
processing and signal math are performed using pipeline
commands. This method provides the most flexibility, but often at
the expense of being immediately intuitive.
Access to the Pipeline is available from the following toolbar icon:
Signal Processing is
performed using Pipeline
commands.
The Pipeline has well over 120 commands available, and the
list is constantly growing. It lets you manage or automate
everything you do in Visual3D – and pipeline scripts can be
interactive, thus they can be used like Visual3D Wizards. Scripts
saved in the special installation pipeline directory are available from
the main Workspace Status tab.
Each Pipeline command consists of two parts – the command and
its parameters. The script text is provided so that any optional
parameters may be un-commented, thus gaining new or enhanced
functionality.
Script Editing
Commands need parameter values. The following are the syntax
rules for each pipeline command:
•
The command name is on the first line by itself
•
Parameters are preceded with a “/” character
•
Comments have a “!” and a space in front. Optional
parameters are commented out by default, so the “! ” must
be removed to use that parameter
•
Commands are terminated with a semicolon
•
The plus sign “+” is used in the text for specifying multiple
values to a command parameter
Basic syntax rules…
In some cases, original signals individually checked in the data tree
can be imported into a command line at the push of a button, which
will automatically uncomment related lines.
The up and down buttons to the right of the pipeline window let you
reposition a command in a list of multiple commands.
Here is a sample script command:
Open_File
!
Ask for the Movement data file(s).
!
Multiple files can be selected using CTRL-Click
! /FILE_NAME=
;
April, 2004
Sample script command…
Note:
/FILE_NAME parameter is
commented out so that a File
Open dialog is presented to
the user. Alternatively, a file
could be specified here.
7
The Pipeline Processor has 3 parts – the list of all the commands
available; the pipeline of commands selected to run; and the syntax
for any selected command in the pipeline window.
Available Commands
Pipeline
Pipeline Parameters
Some commands have GUI interfaces provided for entering
command parameters – others do not (yet).
The Pipeline
Add commands to the Pipeline
(or remove them or clear it out)
Move highlighted command(s) up and down in the Pipeline
Some commands need signal names
As parameters. This will grab the
Signals checked in the data tree and
Put then in the command parameter line.
April, 2004
Customize the command parameters
Using the edit dialog or a text editor
8
The best way to learn about the Pipeline Processor is to use it…
Signal Processing
For this example we will try to smooth out the signal data. A before
and after picture of the X component of the LAS marker will
illustrate the results.
Graph the X signal
component of LAS
1. Interpolate all of the Target signals…
Open the Pipeline Processor
and expand the Signal
Commands
Add the Interpolate command
to the pipeline window
Then…
1. Select which signals to
interpolate – in this case,
ALL the targets, so…
- Click the check box in
the ORIGINAL folder
under the TARGETS folder
in the Data Tree (this
highlights all the target
names)
To process any command in the pipeline, you first tell it which
signals you wish to process, and then how. The ‘which’ signals
question is answered by checking the various signals in the Data
Tree and then clicking the ‘Import Checked Signals’ button.
The ‘how to process’ the data question is answered by specifying
your desired parameter values – in this case the defaults are fine.
In some cases there is a dialog box for entering parameters (via the
Edit button in the pipeline), and in others, just raw text.
There is a reason why you may want to use the text versions, and it
is very powerful, but we will only cover that towards the end…
Go ahead and execute this command, to see what it does…
April, 2004
2. Click the “Import Checked
Signals from Tree” button
in the pipeline.
Notice how the Signal_Types
parameter changed to include
all the TARGETs
3. You can either DoubleClick the command in the
pipeline itself, or click the
EDIT box to edit the other
parameters for interpolating.
Click the “Execute Pipeline”
button now.
9
A modal Processing Results dialog box appears listing the output of
the command and highlighting any errors…
No errors according to this!
Click OK to continue…
Notice that in the Data Tree, a new folder has appeared for
PROCESSED data. Subsequent signal processing must use any
previously processed data. Otherwise, if you use original data
again, you will simply overwrite the data you already processed!
April, 2004
The PROCESSED folder in the
Data Tree is now available.
10
The Pipeline is actually a visual and interactive batch processing
tool. To see how, add the Low-Pass Filter command…
Add the Lowpass_Filter
command to the pipeline…
Check the little box on the
PROCESSED folder in the
Data Tree and
Push the “Import Checked
Signals from Tree” button
Reset the Frequency Cutoff to
3 instead of the default 6.
(6-10 is usually right, but this
data is actually fairly clean,
so we have to do extra
filtering to see a difference)
Click the “Execute Pipeline”
button.
No errors. The whole pipeline
was run again. First the
ORIGINAL signals were
interpolated (again) – and
then the PROCESSED signals
were filtered. The results
were written back into the
PROCESSED folder.
If we close the Pipeline window and plot the new signal, we should
see the difference now.
April, 2004
Click CANCEL on the Pipeline
Processor to close the window
11
Graph the LAS X component
from the PROCESSED folder
and notice the difference…
With over 120 commands available, this tutorial could go on for
quite some time, but we will shift gears now, and try the automatic
gait event recognition command…
Back in the Pipeline, collapse
the Signal commands an go
to the Event command.
Add Automatic_Gait_Events
to the pipeline
Click the Edit button, or
double-click on the command
to bring up its parameter
dialog box…
Set the Force Plate Gravity
direction to the Z axis…
Radius will be explained just
below…
Click Done and Execute the
Pipeline
April, 2004
12
Again, all the signal
processing was done again,
as well as the event
creation…
Automatic Gait Event Recognition depends on there being a force
plate active and foot segments defined. A pattern of Ground
Reaction Forces and segment movements are recognized and
converted into several events. They include:
RON/ROFF and LON/LOFF – the frames where a force is first
recorded on a force plate (ON) and when the final force leaves it
(OFF) for both right and left sides.
Gait events include Right Heel Strike (RHS), Right Toe Off (RTO),
and the same for the left side (LHS, LTO).
Once the initial pattern has been recognized, it is reapplied
throughout the trial, regardless of force plates, to identify the rest
of the gait events.
The Radius parameter relates
to the number of frames to
leave before and after a
pattern is recognized to avoid
getting duplicate events.
Lower the radius number to
capture events close to the
beginning or end of a trial.
Notice that new events were
created. This is a very
limited gait trial, so there is
actually only one complete
left and right gait cycle. Most
trials will have multiple
events of the same type.
It is also a good time to
delete the event we created
earlier…
April, 2004
13
More Signal Processing – Statistics/Metrics
There are some easy to access metrics left in the graphical interface
that we will now cover. Right-clicking on a signal brings up a
context menu. One option is to ‘Create Metrics.’
Right-click on a signal to get
the context menu.
Go ahead and generate the standard deviation of the RFT1 signal.
Create the Standard
Deviation for the RFT1 signal.
Call it STD_DEV_RFT1 and
limit it to the range between
the Right Heel Strike and the
Right Toe Off events.
Notice that a new METRIC
has been added to the Data
Tree. These metrics can be
used in Reports - and in the
calculation of new metrics
using the Pipeline.
April, 2004
14
At this point we have completed the part of the tutorial needed for
the next section, so save the workspace as a .cmo file. There are,
however some more advanced and useful aspects to Visual3D that
would be very profitable learning.
Save the workspace as a
.cmo file for use in the next
tutorial
Processing History
One of the nice capabilities in Visual3D is its ability to track the
processing done to a signal for later review. For example, expand
the PROCESSED data tree folder and right-click on a signal. Select
the ‘View Processing History’ option and then click on each
command to see what parameters were used.
View the Processing History
of a Signal…
April, 2004
15
Advanced Pipeline Topics
We used the Pipeline to do some very basic signal processing and
event creation, but the Pipeline Processor is really a very powerful
tool. Before we move finish up, let’s recapture all of the work we
have done so far in a script.
Scripts are saved command pipelines. They can be aggregated into
one big script, or saved at various points as a way to investigate
alternative paths without loosing any prior work or time.
First, we are going to empty the current pipeline and start fresh.
We can go back to the steps in the first tutorial, and save the
model’s segment definitions (which includes subject data).
Open the Model Building tab, and save the current model template.
Save the Model Template as
“Tutorial 1 model.mdh”
Now, let’s open the Pipeline processor and tell it to re-create out
current workspace…
April, 2004
16
Expand the FILE commands
and select “File_New”
Let’s add a comment to the
command… Click the EDIT
button and type:
! Start with a completely
fresh Workspace
(Don’t forget the ! )
In the Model command, pick
Create_Hybrid_Model
This command needs the
static trial as its parameter.
Remember to un-comment
the parameter line, and enter
“Lower Body Static Trial.c3d”
April, 2004
17
Next , add the
Open_Model_File
command.
We will be using the model
template saved a few steps
earlier. Set the parameter
to:
/FILE_NAME=Tutorial 1 model
sample.mdh
(Don’t forget to delete the !)
Add from the File folder:
Open_File
We will be using the same
movement file,
BUT – for this example, leave
the parameter blank.
This way, the Pipeline will ask
for the filename at run time.
At this point the model will be
built…
(Remember also we saved a
corrected .c3d file earlier, so
we do not have to re-fix the
target name)
Open up the Assign Motion
File to Model dialog with the
Assign_Model_File
command.
April, 2004
18
Now we can add the
Interpolate command
Click the TEXT button and
type in TARGET as the
missing signal type. An
uncommented parameter is
mandatory (usually no
default)
Add the Lowpass_Filter
Either check the PROCESSED
folder in the data tree and
click the ‘Import Checked
Signals’ button
Or…
Type in the parameters
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=PROCESSED
Add
Automatic_Gait_Events
and set gravity along the Z
axis
April, 2004
19
Finally, add the
Generate_Metric command
With these parameters…
/SIGNAL_TYPES=TARGET
/SIGNAL_NAMES=RFT1
/SIGNAL_FOLDER=PROCESSED
/METRIC_PROCESS=STANDARD_
DEVIATION
/METRIC_NAME=STD_DEV_RFT1
/RANGE_START=RHS
/RANGE_END=RTO
These commands will re-create everything we have done, save for
one thing… Saving the workspace as a .cmo file. You can add this
command to the end now.
Save the script file as “Model and Processing Sample.v3d” and
then execute it to see what happens.
Use File_Save command to
save the Workspace as a
.cmo file
Save the Script File as “Model
and Processing Sample.v3d”
Execute the Script
It should product the same results we had prior to this section. If
not, some common errors are:
- Forgetting to uncomment a needed parameter
- Forgetting to set all the needed parameters
- Overwriting processed data by using the default
ORIGINAL as the source
- Neglecting to assign a motion file to a model.
Before we end this tutorial, there is one last advanced Pipeline
feature to be aware of.
As a Pipeline script is processed, each parameter in a command has
a name associated with it. These names are actually global
variables in the pipeline, and can be reused in subsequent
commands (until they are overwritten by another command).
For example: We left the file name off of the Open movement trial
command…
The parameter there was FILE_NAME
April, 2004
20
When the open dialog box appeared and a file was selected, the
pipeline saved the resulting file name in the parameter.
To use that information in a subsequent command, parameter
reference character of two colons, “::” is used.
For example, to automate the Assign Model to Movement File
command, the syntax of the command could be changed to:
/MOTION_FILE_NAMES=::FILE_NAME
Finally, when multiple names or signals are used in a command
parameter, they are simply separated by a plus, “+”, but a variable
name reference will already contain the multiple names.
And this concludes this particular introduction into signal and event
processing using the pipeline.
The next tutorial is to step
through an analysis and
building a report.
April, 2004
21