AsciiImport Help

Use
First Aid
Licensing
Demo Mode
Registration
Import File Settings
Vicon ASCIIDump compatability

Help (FAQ) !

Use

ASCII Import is very easy to use :-
  1. Once you've installed the PlugIn correctly, all you need to do is generate a text file in the right format .
  2. Open a Trial in Workstation into which you want to import your data.
  3. Open the Pipeline dialogue (Trial:Pipeline...), and double click the "Import ASCII file" process, to view the options.
  4. Choose the file you want to import from , and click Okay.
  5. Make sure the "Import ASCII file" process has a tick against it, and press the "Process Now" button.
That's it ! You should see the updated trial in the Worstation Workspace view. View the Processing Log for details of what actually happened.

You will need to Save the trial if you want to keep the changes. See theFAQ entry for more details.

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.

If your import file is perfect, you should just see simple messages saying that it's starting to import, and that the import was done.

You may also see WARNING messages, which may give you a clue as to why something is not working as you expect. The PlugIn continues to try and interpret your file after issuing such a warning.

If you see an ERROR message, the program will have had some problem from which it cannot recover, and it will give up.

Licensing

If you are having problems with licensing, or only the "Vaquita" tab appears, press the "Licence" button to find your current status.

If you see "Licence expired" then your demo period is over. Please contact us if you want to register and use the PlugIn properly.

If you see "Licence check failed", refer to the installation notes to make sure you have the right files in the right places. You will need to restart Workstation once you've made any changes.

If that doesn't work, then please contact us for help. Include details about your build of Workstation or Nexus, version of Windows, and the installation drive and PlugIn folder you are using.

Demo Mode

In demo mode, you can only import  1 trajectory, and 1 analogue channel.

The plug-in is limited to run for only 30 days. You will receive a warning in the last 14 days to register. After that, the plug-in will not run, though you will still be able to view the Vaquita tab and access the licence dialogue (and view the help !).

Registration

To register, send us

Your Name
Your Institution
Your Serial Number exactly as shown in the Licence dialogue

E-mail these to us. You can contact us here initially.

We will send a registration number back to you (once payment has reached us, of course !)

Copy and paste the number into the Registration Code section of the Licence dialogue, and press the "Apply" button. If the registration is successful, you will then be able to enter your name and institution. Please use the same name and institution as you originally sent us. We will be able to help out if you have problems later, if we can track down your details correctly.

If the registration fails, double check that the serial numbers and registration codes match those in the e-mail. If the serial number you sent us was wrong, you will have to send us the correct one. If the serial number is different in the e-mail we sent back, then it was our mistake. Please send us the correct serial number and we will try to get it right this time...

Import File Settings

Click the Trajectory or Analogue Data check boxes, depending on which data you want to import. Then define the file you want to import each type of data from.

You can import both types of data from the same file, or from different files if you wish.

There are no restrictions on the file name.

The only limitations are that the text in the file be formatted correctly. Take a look at the ImportExample.txt and copy this as an example. There is also a more complete description of what is required in AsciiImportFileFormat.html

Keyword Tokens

You can enter special Keyword Tokens into the filename text boxes, and the PlugIn will replace the Token with text which is specific for the trial. Each token must appear inside square brackets, without spaces. The names are not case sensitive. The recognised tokens are :-

[TRIALFOLDER]

This will be replaced by the full path of the folder in which the trial files are located.

[TRIALNAME]

The base name of the trial will be inserted, but without any path or extension.

[C3DFILE]

This specifies the full path and name of the associated c3d file for the trial for which the pipeline is being run.

[ASCIIFILE]

This inserts the file path and name of the CSV file which is normally generated by the ASCII export PlugIn.

Vicon ASCIIDump compatability

The text file format is currently not completely compatible with the ASCIIDump output text. This is because ASCIIDump inserts commas between the entries on the line, in order to be compatible with a specific spreadsheet format.

However, the order of the entries is the same. If you load the ASCIIDump output file into a spreadsheet, then simply Save As... Text, ASCII Import will read the file without any problem.

Since the idea of ASCII Import is to allow import from various sources, and some processing of the data output from ASCII Export is needed, this seems the most appropriate solution. However, if any you you find it a significant advantage to load files with commas separating the values, then make contact, and the code can be modified (at no extra cost).

Invalid points

When writing trajectories out you should define a string to signify an invalid point in the ASCIIDump settings - we recommend "*". If you leave this field blank, the data lines will appear with fewer values than ASCII Import expects, and values could be attributed to the wrong trajectories. If you use the value "0" (zero) the values will be assigned as a valid point at {0,0,0} by ASCII Import.
 

Help !

Don't panic ! Here are few Frequently Asked Questions...
It didn't do anything !
It only imports one trajectory/analogue channel !
Why do Scalar and Power trajectory types still need three componenets for each frame ?
What are the units ?
How are the trajectory frame numbers, and the analogue sample numbers related ?
Why does the process appear after the Save File option ?
Why Didn't the Help File appear when I pressed the Help button ?
Reporting Bugs

It didn't do anything !

Are you licenced ? Has the demo period run out ? Open the pipeline (Trial->Pipeline) select "Import ASCII File" and click on Options... If the settings page does not appear (i.e. you only see the Vaquita page) then the demo period has run out, or there's some other problem with your licence (if you have one). Have a look at the Licencing section.

It only imports one trajectory/analogue channel !

Probably because you're using it in demo mode. The processing log messages will tell you this if you have a look. Take a look at licensing section in the main help file.

Otherwise, perhaps your text file is not in the right format. You should see some warnings in the processing log if the program is having problems interpreting your text. Have a look at the example format file and copy that. There's also a more detailed description of what is acceptable in the text file.

The number one rule is - don't put any spaces in your label names.

"WARNING - Too many numbers in the line !"

You will get this warning for the demo version, if you have more data than the demo version limit (i.e. if you have data for more than one trajectory or analogue channel) even if the text file format is perfect.

Why do Scalar and Power trajectory types still need three componenets for each frame ?

Basically because that's how many components are stored in the c3d file, since both scalars and powers are saved as trajectories. Conventionally the value is stored in the Z value. BodyBuilder and Polygon only read the Z value when the data is imported into them.

You might want to store your Powers as three components though, for example.

What are the units ?

They are fixed by the Vicon PlugIn interface :-

Workstation is free to change the actual units recorded in the c3d file, but will alter the values for each trajectory type accordingly.

How are the trajectory frame numbers, and the analogue sample numbers related ?

First, trajectory frame 1 corresponds to analogue sample 1. Second, there are a fixed integer number of analogue samples per trajectory frame.

This gives the formulae :-

Sample = 1 + (Frame - 1) * SamplesPerFrame
Frame = 1 + (Sample-1) / SamplesPerFrame

When converting from Sample to frame, note that you need to be careful with the result of the division to get a whole number - you can round up or down depending on whether you want the previous or next frame (since any given sample is not guaranteed to be coincident with a frame).

Note that this is different from the C3D file relationship between frames and analogue data, where Frame 1 is coincident with Sample 0. If you particularly want your ASCII files to be in this format for some reason, then an option can be added to the PlugIn to allow this, at no extra charge. Just contact us and ask for it.

Why does the process appear after the Save File option ?

There are two reasons for this.

First, ASCII Import is a potentially dangerous PlugIn. It's very easy for somebody that doesn't know exactly what they are doing to overwrite a lot of clinical trials with experimental data from a single ASCII file, without even realising it. By putting the PlugIn after the automatic Save option, it forces the user to deliberately save the changes that they've made.

Second, it should be possible in the future to actually include an ASCII processing stage in the pipeline. The general idea is to use ASCIIDump to export the data as text, to process this using a command line interface process, and then import the result of the processing back in to the trial. For this reason, ASCII Import must appear in the pipeline after ASCIIDump, and ASCIIDump itself always appears after the Save Trial option. If you would like to know more about these plans, contact us with your comments.

Why Didn't the Help File appear when I pressed the Help button ?

First, is the help file (which must be called AsciiImportHelp.html ) in a folder called AsciiImport, inside the Vicon PlugIns folder (this does not have to be Vicon/PlugIns) ? That's where the PlugIn looks for the file. You should get an error message telling you that it can't find the file, and where it should be.

Even if the help file is in the right place, this can sometimes happen with previous versions of the PlugIn, after you've attached a new Marker set file to the subject in your trial in Workstation. This happens because Workstation changes the "Current Directory" which is maintained by Windows. This intermittent problem has been fixed in the current version, so if you have an older version, you should download the latest one here AsciiImport

Finally, in some rare cases, it could be that you do not have an HTML (Web) browser installed in your system. The simple answer is to install one.

Reporting Bugs

First thing, are you sure it's a bug ? Are you sure it's a problem with the Plug-in ? Check the rest of this file, and take a look on the web site for the latest version. If that fails, you should contact us with any problems that you find. We will do our best to find where the problem lies, and offer a solution.