RT Plugin Vicon DataStream

Overview

The Vicon™ DataStream™ Plugin is used in Visual3D Server™, and Visual3D RT™, it connects to Vicon™ DataStream™ software.

The Vicon™ DataStream™ Plugin talks to Vicon Nexus 1.7.x, 1.8.x, 2.0 and 2.1.

Plugin Interface

The "Plugin Help" button leads to this web page should you need to reference this page in the future.

The "About Plugin" button has details on the plugin being used including version, release date, copy right, support contact information and the hardware SDK version.

Frame Info

Current frame The current frame number on the top left hand side on the screen (where it currently reads 004971) keeps a count of the current frame which is assigned by the hardware or software system.

Missed frames The missed frames number is on the bottom left (where it currently reads 000729). Whenever there is a gap in frames sent by the hardware of software system a blank frame is inserted. The dropped frames count keeps a record of both the number of frames which are blank.

Hardware time The hardware time number is on the top, in the centre (where it currently reads 004.6). This time stamp is created by the hardware being used and is how long, in milliseconds, the hardware has been running.

Server time The server time number is on the bottom, in the centre (where it currently reads 004.6). This time stamp is created by the server and is how long, in milliseconds, it has been connected to the hardware or software which is streaming to it.

Hardware latency The hardware latency is on the top right hand side (where it currently reads 000.0 ms). This indicated the delay created by the hardware system.

Server latency The hardware latency is on the top right hand side (where it currently reads 000.0 ms). This indicates any delay introduced by the server.

Hardware

Stream Mode

The Stream Mode controls how Visual3DServer receives data from Vicon DataStream. The stream mode must be set before connecting to Vicon, once the programs are connected the stream mode drop down menu will become greyed out and will remain inaccessible until you disconnect the programs. There are three options for the stream mode ClientPull, ServerPush and ClientPullPreFetch.

• The ClientPull setting has Visual3DServer approaching the Vicon program at regular intervals determined by the Thread Sleep in order to collect frame data. This setting is useful when you want to control the frequency with which Visual3DServer collects new frames. However, since processing must be momentarily stopped while the Server looks for new data the lower the Thread Sleep goes the more likely there will be delays in the Server.

• The ServerPush setting had the Vicon program send every new frame of data to Visual3DServer. This setting is useful if you do not want Vicon to drop frames since the most recent data will always be sent. However, if Visual3DServer cannot read the data at the rate it is being sent then it will eventually begin to drop frames.

• The ClientPullPreFetch setting is a combination of the two modes. The Vicon program preemptively pulls the data which is to be sent to Visual3DServer and stores the data. This prevents the buffers in either program from filling up and dropping frames and the programs are less likely to stall. However, this does increase the amount of network traffic by requesting frames that may not be used.

The stream defaults to for Visual3DServer is ClientPullPreFetch mode as this is considered the safest option. If performance is a problem, then try varying the mode to see which works best for your particular setup.

Below is the technical explanation for the three modes as provided by Vicon in it's "Vicon DataStream SDK Manual." Please see Vicon should you wish to know more of the technical details concerning these modes.

In “ClientPull” mode, the Client waits for a call to GetFrame(), and then request the latest frame of data from the Server. This increases latency, because we need to send a request over the network to the Server, the Server has to prepare the frame of data for the Client, and then we need to send the data back over the network. Network bandwidth is kept to a minimum, because the Server only sends what you need. We are very unlikely to fill up our buffers, and Server performance is unlikely to be affected. The GetFrame() method blocks the calling thread until the frame has been received.

In “ServerPush” mode, the Server pushes every new frame of data over the network to the Client. The Server will try not to drop any frames. This results in the lowest latency we can achieve. If the Client is unable to read data at the rate it is being sent, then it is buffered, firstly in the Client, then on the TCP/IP connection, and then at the Server. Once all buffers have filled up then frames may be dropped at the Server and the performance of the Server may be affected.

“ClientPullPreFetch” is an enhancement to “ClientPull” mode. A thread in the SDK continuously and preemptively does a “ClientPull” on your behalf, storing the latest requested frame in memory. When you next call GetFrame(), the SDK returns the last requested frame which we had cached in memory. GetFrame() does not need to block the calling thread. As with normal “ClientPull”, buffers are unlikely to fill up, Server performance is unlikely to be affected. Latency is slightly reduced, but network traffic may increase if we request frames on behalf of the Client which are never used.

IP Address

The IP address and Port allows Visual3DServer to locate the data that is being broadcast. Both of these need to be set before connecting to Vicon. Once the programs are connected the IP address and Port fields will become greyed out and will remain inaccessible until you disconnect the programs. The ServerIP address must be entered into the dialogue box in the hardware tab. The IP address used in the image above is 192.168.1.105. Vicon™ does allow for the "localhost" or 127.0.0.1 shortcuts to be used. If you need help finding the IP address of the computer running the data capture see Trouble Shooting. The Port number is a port which has been chosen by Vicon to broadcast data from. Vicon currently uses port number 801 which is the default in Visual3DServer. Do not change this value or you will not be able to connect to the Vicon program. If you have inputted the correct IP address and Port number 801 and are receiving an error message please contact support@c-motion.com.

Vicon System File

The Vicon System File is a file generated by Vicon Nexus which provides Visual3DServer with the location of the force platforms. This file needs to be available to Visual3DServer in order for it to be able to calculate forces. A new systems file should be generated each time that there is a change in the location of either the force platforms or one of the cameras. The systems file needs to be generated from Vicon Nexus by the user, saved to disk (with a unique and descriptive name), and then loaded to the Visual3DServer using the Browse button next to the System File text box. For more details on how to generate a System File in Vicon Nexus see the documentation provided with your Nexus software.

Subframes

Because force platforms generate data at a higher frequency than current camera hardware can there is the creation of subframes. These are frames which contain data from the force platforms but not from the cameras. If the Subframe checkbox is selected then Visual3DServer will accept and stream to any clients the subframes produced by the force platforms. If you are using a biofeedback client that uses force data to generate heel strikes and toe offs it is highly recommended that you leave this checkbox selected.

Signals

The table in the signals tab holds all of the numerical data from various sources which is being streamed to the program. This data may include, but is not limited to, marker co-ordinates, force data, EMG readings, accelerometer data, etc. The first column entitled "Label" has the number or name which has been assigned to the source of the data. The following four columns are all entitled "Value"; they have the numerical data associated with the source. For markers it is the x, y, and z, coordinates and then the residual. For force data there is only one value associated, which is the magnitude of the force.

The signals graph allows you to see a graphical representation of the values in the table. Selecting one of the rows in the table will cause the graph to record the values in real time. The x axis has the frame numbers and the y axis has the numbers in the value column. If more than one column has data there will be multiple lines drawn. The graph uses the MKS system of units.

C3D Params

When this tab is viewed in Visual3D Server it gives additional details regarding the data that is being collected by the server and streamed to a client. This allows you to check details such as force plate types and locations. The top table contains a list of the parameters and their subsections. By expanding the parameters and selecting one of the subsections the data from the subsection will be presented in the table at the bottom of the tab.

Force Platform

The minimum force management box is for screening out unwanted noise from the force platforms. The default value is 20.00 N meaning that any force equal to or lower than 50.00 N will not be displayed by the system. It does not affect forces that are greater than the specified limit. The minimum force may be set at any value between 0 and 9,999.90 N. The baseline force measurement tool allows you to determine the average amount of noise present in your force platform system and remove it from the forces displayed by the system and sent to any client programs such as a biofeedback software. The baseline frame number is set at 10 which means that the baseline function will take a sample of 10 consecutive frames. The frame number may be set at any whole number from 1 to 9,999. When you click the "Measure Baseline" button it will take a sample of frames (as many or as little as indicated by the baseline frame number box.) The average force will be calculated for these frames. This value will subsequently be subtracted from all of the following frames. The graphics displayed and the data passed on to any client programs will be the initial value minus the calculated average. When the "Zero Baseline" button is pressed the forces will no longer have the baseline number subtracted and the forces displayed and given to any client programs will be the value taken from the force plate. Both force management tools may be used at the same time. The "Use force structure" checkbox controls the force structure, which is the amalgamation of multiple forces. If the checkbox is not selected then the force structure will not be calculated. This means that the force structure will not appear in the graphics and that the data for a force structure will not be available for any client programs.

3D View

The right hand side of the screen provides a real-time 3D graphical representation of the data being streamed.

Save 3D View

This button allows you to save what is currently being displayed in the 3D view graphics area. The image can be saved in a number of standard formats, such as .bmp, .ico, .jpeg, .jpg, .pbm, .pgm, .png, .ppm, .tif, .tiff, .wbmp, .xbm, or .xpm. This function is ideal for producing graphics for papers or presentations. Saved images can be edited with 3rd party graphics programs if needed.

Copy 3D View to clipboard

This button allows you to copy what is currently being displayed in the 3D view graphics area to the clipboard. This allows you to paste the image into any program that supports copy and paste. This is useful for working with presentation or graphics editing software.

Reset camera 3D View

This button brings the 3D viewer back to it's beginning position. You may find that having used the rotation, translation, and zooming capabilities of the 3D view you have lost track of where you are in the graphics, which can make returning to a proper view of your data challenging. The reset view button removes this frustration and reorients you.

3D View Preferences

This button allows you to change how the graphics that are presented to you. Changes happen in real time. At the bottom is the "Restore Defaults" button which resets all of the options to their standard setting.

Scene

Lighting on - When selected graphics that are suppose to be 3 dimensional have shadows to help simulate shape. When not selected objects are one solid color.
Reset camera view on connect - When this box is selected and you connect or reconnect to hardware the camera view will reset to it's default.
Alpha-blending on - When this box is selected the graphics are slightly transparent and allow you to see what is behind them
Anti-ailiasing on - When this box is selected all the lines in the graphics are smooth. If it is not selected the lines that are not either horizontal or vertical change directions portion by portion.

Background

Color - This allows you to change the background color to anyone you chose.

Floor

When the check box next to the floor is not checked the floor will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the floor is not present.

X-size - This allows you to customize how many panels the floor is composed of in the x direction. the minimum is 1 and maximum is 100. The default size is 5.00.
Y-size - This allows you to customize how many panels the floor is composed of in the y direction. the minimum is 1 and maximum is 100. The default size is 5.00.
X-offset - This allows you to shift the entire floor along the x-axis either in the positive or negative direction. The maximum value allowed is 100 and the minimum value is -100. The default setting is 3.00.
Y-offset - This allows you to shift the entire floor along the y-axis either in the positive or negative direction. The maximum value allowed is 100 and the minimum value is -100. The default setting is 3.00.
Z-offset - This allows you to shift the entire floor along the z-axis either in the positive or negative direction. The maximum value allowed is 100 and the minimum value is -100. The default setting is -0.01.
Color - This allows you to change the floor color to anyone you chose.
Show grid - This allows you to remove the grid lines from the floor by unchecking the checkbox.
Grid line width - This allows you to change the thickness of the gridlines. The minimum value is 1 and the maximum value is 10. The default width is 2.00.
Grid color - This allows you to change the grid line color to anyone you chose.

Axes

When the check box next to the axis is not checked the axis will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the axis is not present.

Line width - This allows you to change the thickness of the axis lines. The minimum value is 1 and the maximum value is 10. The default value is 2.00.
X-Axis Color - This allows you to change the x-axis line color to anyone you chose.
Y-Axis Color - This allows you to change the y-axis line color to anyone you chose.
Z-Axis Color - This allows you to change the z-axis line color to anyone you chose.

Force Plates

When the check box next to the force plates is not checked the force plates will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the force plates are not present.

Plate Color - This allows you to change the force plate color to anyone you chose.
Show labels - This allows you to remove the force plate label, (such as FP1, FP2 . . . etc) from the 3D view.
Label Color - This allows you to change the force plate label color to anyone you chose.
Show forces - When checked the forces will be show in the 3D view using arrows.
Force Type A Color - This allows you to change the color of the raw force arrows to anyone you chose.
Force Type B Color - This allows you to change the color of the force structure arrows to anyone you chose.

Tracking Markers

When the check box next to the tracking markers is not checked the tracking markers will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the tracking markers are not present.

Radius - This allows you to change the radius of the markers. The maximum value is 0.100 the minimum value is 0.001. The default radius is 0.020.
Marker Color - This allows you to change the color of the marker color to anyone you chose.
Show Labels - This allows you to remove the marker labels from the 3D view.
Label Color - This allows you to change the color of the label to anyone you chose.

Segment Markers

When the check box next to the segment markers is not checked the segment markers will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the segment markers are not present.

Radius - This allows you to change the radius of the markers. The maximum value is 0.100 the minimum value is 0.001. The default radius is 0.020.
Marker Color - This allows you to change the color of the marker color to anyone you chose.
Show Labels - This allows you to remove the marker labels from the 3D view.
Label Color - This allows you to change the color of the label to anyone you chose.

Segment Lines

When the check box next to the segment lines is not checked the segment lines will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the segment lines are not present.

Line Width - This allows you to change the thickness of the segment lines. The minimum value is 1 and the maximum value is 10. The default value is 1.00.
Color - This allows you to change the color of the segment lines to anyone you chose.

Segment Geometry

When the check box next to the segment geometry is not checked the segment geometry will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the segment geometry is not present.

Color - This allows you to change the color of the segment geometry to anyone you chose.

Segment Bones

When the check box next to the segment bones is not checked the segment bones will not appear in the 3D View. In this case all the bellow options will be greyed out as they will have no effect if the segment bones are not present.

Color - This allows you to change the color of the segment bones to anyone you chose.