Subject Tutorial

<< Back to Vicon Toolkit Page

This section provides a step by step tutorial on how to prepare a new Vicon subject for use in the ILAB Vicon Toolkit.

Step 1: Creating Your Subject

First thing you need to do is to select the physical object you want to track. Of course you must attach markers to this object so that the Vicon can "see" it, but here are a couple of things to take into consideration:

  • You must use more than two markers, at the very least because it is impossible to determine the object's rotational properties in 3D space without at least 3. Furthermore, the Vicon Body-Builder utility requires at least 3 markers to define the subject.
  • Try to place 3 markers that will loosely create an L shape on a plane. This will define two out of three axes (the third one can be determined from those two).
  • Try to keep things as asymmetrical as possible when placing markers. The more distinct their locations and distances are, the less likely the Vicon Nexus will misinterpret the location and rotation of the subject.
  • Consider the location and orientation of the Vicon Cameras in relation to the use of the subject. Try to place markers on the subject in places where they will be most visible to the cameras, or you may even position additional cameras to better capture your markers. OCCLUSION IS ALWAYS A PROBLEM, so also consider where people or other objects may be positioned that will occlude markers from the Vicon Cameras and plan accordingly.
  • In some cases, the more markers you use on your subject, the less likely they are to all be occluded. However, don't go overboard because the more markers that the Vicon has to track, the higher the margin of error when triangulating their position - especially when in close proximity with other subject.

Here are some example objects with markers on them: (Photos coming soon)

Step 2: Nexus, Meet the Subject

Once you've prepared your physical object, you must teach the Vicon Nexus software what it needs to look for. You do this by showing it your object, and linking markers together using the Body-Builder Wizard.

  1. Make sure that the Vicon hardware and Nexus software are running properly, clear the space of any other markers (and any other subjects that the software is currently tracking), and bring your new subject into view in such a way that all markers are visible simultaneously (you will probably need to put the subject down so that you can work on the computer). You will see that the Nexus is able to track the individual markers in 3D space just fine - it just doesn't know yet that they are all part of the same subject.
  2. (Pause the Frame)
  3. (Begin Body-Builder Wizard)
  4. (Specify Subject Name)
  5. (Specify Markers) The Vicon Body-Builder utility will first ask you to specify an origin marker, then a primary axis marker and a secondary axis marker. Additional markers can be added afterward.
  6. (Name Markers)
  7. (Save and Finish)

The end result is a .VSK (Vicon Skeleton) file that contains an XML definition of your subject. The ILAB Vicon Toolkit requires a copy of this file to be placed in the subjects subfolder so that it can bind the skeleton definition to the subject for tracking purposes. The subjects folder should be adjacent to the executable that you create using the ILAB Vicon Toolkit - if it's not already there, you'll need to create it.

In order for the Nexus to recognize your subject and pass this data on as such to the ILAB Vicon Toolkit, you must ensure that the subject is listed in the Nexus software. If not, you must load it manually.

Step 3: Programming a Subject Wrapper Class

The ILAB Vicon Subject Library provides a base class that your wrapper must inherit (SubjectBase), with stubs that you will most likely want to override. Also be aware that your wrapper class should implement the ISubjectHandler interface.

Here are a number of things you'll likely want to do for your wrapper: (refer to ILAB Vicon Subject Library - Class Reference)

  • If you want the Origin marker (specified in the Nexus Body-Builder Wizard) to define the point-location representation of the subject, then you do not need to override the Location method. Otherwise, you may override this method to specify another marker or body location.
  • If the DirectionOrigin is not the same as your Location, you will need to override this property.
  • CanPoint is false by default. Override this property and have it return true if your subject can be used as a pointing device.
  • In most cases you must override the Direction property to provide a vector that indicates the "front" of the object, if not the pointing direction.
  • (Pitch, Yaw, Roll)
  • In special cases, you can override the InFrontOf, PointsToward, PointsInto, and GetPointedDisplayLocation methods. However, in most cases overriding the CanPoint, DirectionOrigin, and Direction should be sufficient.
  • If you need to do any special calculations each time the subject data is refreshed, you can override the OnUpdatedSubject method.
  • If you wish to handle the way the subject is drawn to a SubjectDisplay control, you can override the RenderToDisplay method.

Here's how the wrappers were structured for my sample objects: (coming soon)