ButterPlug Help

Licencing Options
Licence Agreement

First Aid

Setting filter parameters

Entering the filter name

Cut-off Frequency

Initial Steady State

The Filter

Want a different filter...?

Help !

First Aid

As for any Vicon plug-in, check the processing log (in the View menu) to get feedback from the plug-in, if you think there was a problem in processing your trial.

For every entry in the settings page, you should see an entry in the log, saying whether the given trajectory or analog channel was filtered or not.

If a particular trajectory or channel was not filtered, the most likely reason is that the given label could not be identified in the trial. It's common to run into difficulties with the settings for the subject's name (or names, if there are more than one subject).
 

Setting filter parameters

Each filter setting shows the label of the trajectory or analog channel to be filtered and the cut-off frequency of the filter to apply. If the corresponding trajectory or analog channel does not exist in the trial, nothing will be done. If you have more than one subject in your trial, all subjects will be filtered the same way.

To filter a trajectory, pick the trajectories tab, click New, enter the label for the trajectory, and a cut-off frequency. Make sure that it's going to filter in both directions, unless you specifically don't want to.

For builds of Vicon Workstation (c) 097 and greater, you will also be able to filter analog channels in the same way. For previous builds, you can enter the settings, but if you view the log you will see an error message when you process the trial. The settings will be retained when you upgrade your version of Workstation.

To edit an existing entry, just double click the label in the list, or select the one you want and press Edit.

Select and press Delete to get rid of an entry.

Entering the filter name

In the filter settings dialog, type the name of the label you want the filter to act on, or select a label from the drop-down list. As you type, the program will try to complete the label with one from the list - just ignore it if it gets it wrong. You can type whatever you like in this box, but you must type something.

You can change the drop down list by clicking on the Label List... button, and choosing a different file. MKR files are used for trajectories, and CAR files are used for the analog channels.

Cut-off Frequency

The "cut-off" frequency of the filter is that which the amplitude is reduced by 50% (or about 3 dB). This is a low pass filter, so higher frequencies than the cut-off are attenuated more, and lower frequencies less, so you end up with smoother data.

Deciding the cut-off frequency depends on your particular data. You need to decide what frequencies constitute your signal, and what ones are noise. You then have to choose a cut-off for the filter which reduces the noise as much as possible, without significantly reducing your signal - or at least those frequencies of your signal which you want to retain.

Finally, you should bear in mind that when filtering in the reverse direction as well, you might like to include a further adjustment.

Filtering in reverse

Filtering in the reverse direction filters the data in reversed time (in addition to the forward direction). This ensures that there are no frequency dependent phase shifts, thus keeping all peaks and troughs in different waveforms coincident. It also increases the "sharpness" of cut-off of the filter.

The cut-off frequency of the filter is adjusted internally by a factor of 0.802 as indicated in David Winter's book. Although this figure may be correct for an ideal Butterworth filter, differences between the ideal and the digital filter mean that this figure does not ensure the -3 dB cut-off remains at the required frequency (see The Filter, below).

Steady State Assumption

Checking this option causes the PlugIn to fill the filter buffers with a preset value at the start of each filtering process (or when there are gaps in trajectory data, when the data start again). The assumption is that the filter is in a steady (constant output) state which has a level the same as the initial input value.

In a nutshell, this significantly reduces the end effects of the filter to almost none. This is particularly useful if you have either short trials or gaps in the data.

More details can be viewed here, if your browser is able to support MathML.

The Filter

The filter routine uses the formulae for the 2nd order Butterworth filter taken from David Winter's book "Biomechanics and Motor Control of Human Movement". This is a digital approximation to an "analog" filter of about the same design criteria, so results are not identical to an analog filter.

Performing a second pass of the filter in the reverse direction, as recommended in the book, does not equate to a "true digital" 4th order filter, but it is still required to maintain the coincidence of signals of different frequencies, typical in motion capture data.

The filter is fully tested, and details are here. In particular, testing showed that the factor of 0.802 indicated in Winter does not achieve a -3 dB attenuation at the prescribed cut-off frequency when the filter is operated in the second pass mode. This is believed to be due to the inherent difference between the 'ideal' Butterworth filter, and the digital approximation which the code implements.

Currently there is no 'fix' in the code for this. Instead the filter code is left as is described in the book, so that direct comparisons may be made with other research data.

If you do want to achieve a -3dB cut-off at a particular frequency, it is currently suggested to reduce the required cut-off frequency in the reverse pass mode by a factor of about 0.958. Thus, if you require a cut-off at 15 Hz, type 14.37 Hz into the cut-off frequency box of the filter settings dialog. This figure has been arrived at by inspection alone, and is not accurate, but gives a better approximation than making no adjustment with the current filter.

If you want to understand more, the "classic" book to look at is Digital Signal Processing by Oppenheim and Schafer from Prentice Hall.

Different Filters

If you want a different type of filter, then please let me know. It doesn't take long to change the exisiting code to use different filter coefficients, to implement a high-pass Chebechev filter, for example.

Help !

Don't panic ! Here are few Frequently Asked Questions...

It didn't do anything !
It filters trajectories okay, but not the analog channels
It filters the analog okay, but not the trajectories
I can't get the original analog data back !
It "rectifies" any trajectory data which go below zero !
My settings are always the same !

It didn't do anything !

Are you licenced ?

Check the processing log (View->Processing Log). If this says something was filtered, it probably was. Check that it's filtered what you want, and that you are looking at the right thing. Next, double check the cut-off frequency. Try using a ridiculously low value (e.g. 0.1 Hz) which should definitely make a big difference.

If it says that it failed to filter the trajectories or analog channels you want - check that they exist in the trial !

It filters trajectories okay, but not the analog channels

Check the build number of your copy of Workstation (Help->About Vicon Workstation...). If it is less than 097 then your copy of Workstation does not support the modification of analog channels in the PlugIn interface. You will need to get a new copy of Workstation from your Vicon distributor. At the time of writing, it's not certain which version this will be - presumably Version 4.1.

Don't forget to follow the checks in It didn't do anything ! for the analog channels. 

It filters the analog okay, but not the trajectories

Older versions of the PlugIn didn't filter trajectories which have the subject prefix labels attached (unless you specified the subject prefixes in the settings). This has now been fixed. All trajectories with labels which are the same as that in the settings, will get filtered, regardless of the subject prefix.

I can't get the original analog data back !

Normally, when you run the pipeline in Workstation, it starts by getting the analog and trajectory data from the exisiting C3D file, if there is one (you should see a green circle with the letter P - for processed - against the trial in the Data Directory). This is the data which will be processed in the pipeline.

If you select the "Reconstruct" option, then Workstation will reconstruct all the trajectories again from the TVD files, if they are available, and overwrite any trajectories that came from the previously saved C3D file.

However, there is no equivalent option for the analog data. If you repeatedly run the pipeline and save the results, you can filter the analog data more and more.

If you want to get the original data back, the only option is to delete the C3D file. You can use the Eclipse "Set Status" option to effectively save a copy of the C3D file.

It "rectifies" any trajectory data which go below zero !

No, it's okay, it's just the graph view. It had me confused the first time too! In its default mode, when you first open it, it displays the "modulus" of the vector values. Double click the graph view, and select the X Y or Z component that you want to look at on its own, and you'll see everything is okay.

My settings are always the same !

ButterPlug stores your settings in it's own file inside the PlugIns/ButterPlug folder. This means that you will always have the same setting regardless of the capture type that you use in Workstation. This may or may not be changed in later releases (it partly depends on the Workstation PlugIn Interface). It is unlikely to be a big problem though.