TrakBox User Manual
TrakBox is a low cost tracking system to track (microscopic) nematodes under a microscope, for long periods of time, and to automatically analyse and report on their behaviour.
The system is made up of two parts; the low cost hardware which comprises an off the shelf USB microscope mounted on a tracking platform, and bespoke software that allows the tracking of single nematodes over long periods of time, and performs automatic analysis of behaviour.
This manual concerns the setting up of TrakBox and the Installation of the TrakBox software.
TrakBox contains a mix of off the shelf components and bespoke parts – the major components of the system are shown in Figure 1 below.
- The TrakBox controller: this plugs into a USB 3 port on the controlling computer and offers two USB ports for the USB microscope and the TrakBox LED lighting. Two further connections connect the two servo motors to the controller.
- The TrakBox base unit: this houses the two servo motors (labelled Servo A and Servo B), the the LED lighting and the robotic manipulator that moves the USB microscope.
- The TrakBox upper plate is removable and interchangeable – the plates come in various sizes to accommodate plates of differing sizes. The standard plate has a 52mm diameter recess, a 92mm diameter plate is also available.
- The USB Microscope/ camera: This is an off the shelf unit with a maximum magnification of around x1000. The microscope can be manually focused and has recessed LED lighting whose brightness can be controlled using a thumbwheel control.
- The sample is placed in standard plates and various plates of differing sizes can be accommodated.
The two major components of the TrakBox system (Figures 2 & 3 below) are made up of the following parts/features:
- The USB microscope has a thumb controller to adjust LED brightness
- Servo Motor B
- Servo Motor A
- The USB Microscope (up to x1000 magnification)
- The focussing ring of the microscope
- The microscope clamp – the microscope can rotate within this clamp – it should be set at the default orientation and never touched.
- The interchangeable plates accommodate sample dishes/plates of different sizes (52mm, 92mm)
- The sample plate is placed here
- Servo motor B connector
- Servo motor A connector
- Microscope USB connector
- LED lighting USB connector
- The TrakBox controller
- The USB connector (that must be connected to a USB 3 socket)
- Servo motor A female connector
- Servo motor B female connector
- USB socket
- USB socket
The following are the steps to be taken to connect the controller to the base unit:
- Connect the servo motor A connector on the base to the servo motor A female connector (green dot to green dot making sure both dots are on the same side of the connector).
- Connect the servo motor B connector on the base to the servo motor B female connector (orange dot to orange dot making sure both dots are on the same side of the connector).
- Connect the microscope USB plug to one of the two USB sockets on the controller
- Connect the LED lights USB plug to the remaining USB socket on the controller
- Make sure the microscope is securely clipped into microscope clamp and rotated to the mark provided (this ensures that at the midpoint of the plate the on-screen image is in conventional x & y coordinate orientation)
- Place a plate on the TrakBox base of the correct size for the plate you will be using
- Make sure the TrakBox arms are free to move, that the cables are not in the way and the arm can swing without hitting anything in the vicinity
YOU CAN NOW INSTALL THE TRAKBOX SOFTWARE, WHEN DONE YOU CAN PLUG TRAKBOX INTO THE PC (MAKING SURE YOU USE A USB 3 SOCKET)
3.Installing TrakBox Software
3.1.For Mac OS
Not yet complete - to be updated shortly.
3.2.For MS Windows
PLEASE DO NOT CONNECT TRAKBOX UNTIL YOU HAVE INSTALLED ALL THE NECESSARY SOFTWARE
Make sure you have administrator permissions to allow you to install programs
- Reboot your system
- In the files you have been given locate and run:
This may require a reboot on completion.
- In the files you have been given locate and run:
Follow all instructions given during the install – make sure you tick the box “Add a shortcut to the desktop”. Upon completion, there will be a shortcut on the Desktop called “TrakBox”.
- Create a directory whereever you wish to store data generated by TrakBox (note that if you do not do this all data will be stored on the Desktop).
- Right-click on the TrakBox Desktop shortcut and select “Properties”. In the space titled “Start in:” type (or paste) the full directory path to your working directory.
- Click on “Apply” and then “OK” to exit.
- In the files you have been given locate the file “trakboxengdata.mat” and copy/ place it in the directory you have created in step 4 above. Note that this file is required for your TrakBox to function and it must be on the directory path mentioned in step 5 above.
YOU ARE NOW READY TO RUN TRAKBOX FOR THE FIRST TIME
Make sure you have access to the license file that has been sent to you separately, the file name is of the format “trakboxXXXXXX.txt” (where XXXXX represents the serial number of your TrakBox).
- Make you have set-up and plugged in your TrakBox to your PC. Make sure you plug into a USB 3 socket.
- Double-click the TrakBox icon on the desktop to run the software.
- In the dialog box that appears select the USB camera from the list (if you have more than one camera attached to the system) – the camera may be named “Lenovo EasyCamera” or other depending on your system.
- Click “OK”
- In the dialog box that appears enter the Name, Surname and License Key that have been given to you in the license file described above. Make sure you enter the details EXACTLY as given (the fields are case-sensitive). As the license key is quite long you may wish to copy and paste (CTRL+V) to the field. Enter a name or number for your TrakBox in the final field – this is useful for distinguishing between a number of TrakBoxes if you have more than one.
- If you entered the details correctly you will see a dialog box telling you so and the TrakBox software will launch. Next time you launch TrakBox you will NOT need to enter the details from the step above.
Before you launch the TrakBox software you need to make sure that your TrakBox is connected to your computer using the USB cable, the TrakBox software will NOT launch unless the TrakBox is correctly connected and the License Key has been successfully entered at the point of installation.
When you launch TrakBox you will see the main window shown in Figure 4. There are two parts to the initial screen – (1) and (2) described below.
- These menu buttons allow the user to Print a copy of the Window, Zoom in, Zoom out, move the view and enquire about values at a specific data point.
- The Control Panel consists of 5 buttons. When TrakBox starts the microscope is placed in the standby position allowing the user access to the center of the stage. Pressing Live View moves the microscope to the centre of the stage/plate – toggling this button toggles between Live View ON or OFF. The Calibrated Image button is used to toggle between the Raw Image and the Contrast Enhanced or Calibrated Image of the worm. The Contrast Enhanced image is designed to enhance the presence of the worm on the plate. The Edit Details button is used to enter specific details of a given trial or experiment – this is explained in more detail in Figure 5 below. The Settings On button is used to toggle between a view of all the TrakBox settings or not – this controlled by toggling this button.
When the user toggles Settings in (2) above to ON the 3 panels in Figure 5 below appear.
- The Experiment Details panel – this shows the basic experimental details set by the user. The filename and root directory MUST be set (the systems suggests a name based on a Date-Time stamp but this can be changed by the user if required). The Worm type and Notes sections can be left blank if required. The settings are changed by pressing the Edit Details button in (2) above and is described in more detail in Figure 6 below.
- The Tracking Parameters panel – This shows settings that are specific to the track that is about to be undertaken. The user can select from various dish/plate sizes, and can vary the tracking time from 5 minutes to 24 hours. The dish size setting is used to define the edges of the plate to the system. the Analyse on Completion check-box used to indicate that on completion of a track the system will automatically launch the TrakBox Viewer to give detailed analysis of the Worm Track. Tracking is deemed to be complete if either the time for tracking expires or the user Aborts the tracking. The Ghostworm menu is a useful tool to help test the TrakBox system: when set to anything other than NONE it generates a synthetic (ghost) worm which is superimposed on the microscope image and the TrakBox can then be tested, tracking this “Ghost Worm”. The ghost worm can be set to be from L1 to Adult in size. When using this option it is best to have no plate/sample under the microscope and just use the blank target area.
- The Hardware Settings panel – this is used mainly for informative reasons and it shows a number of settings specific to each TrakBox including its Serial Number, the type/name of camera attached and the name of the TrakBox you set during the install stage (in brackets). The Engineering Settings button should not be used and is there to allow a new set of engineering settings to be uploaded to the system – the user should never need to do this unless directed to by the manufacturer of TrakBox. Similarly the Engineering Mode check box is there to allow some extra information to be displayed on screen during tracking and is not usually needed by the end user and so this box should usually remain UNCHECKED. The Manual Centre button is used to manually define the centre of the plate – when pressed the TrakBox recognises the current position as the centre of the plate – this is not greatly important and the TrakBox will work wherever the centre of the plate is defined. The Autocentre check box is used in conjunction with the calibration disk that arrived with the TrakBox – with the disk inserted in place of the plate and the cross aligned in a vertical/horizontal fashion when this checkbox is ticked the TrakBox will automatically detect the centre of the plate the next time the Live View button is pressed. As before, this is not a wholly necessary action as TrakBox comes with the centre predefined at the manufacturing stage so this can be ignored.
When the user presses the Edit Details button, if it is the first time it has been pressed and the Set Directory button in (4) above has NOT been pressed yet, then TrakBox will first prompt you to select the home or root directory for your Worm Tracks. Once set all tracks will be recorded within this directory. This only needs to be set once but can be changed if needed. Once the directory has been set the system will prompt the user with the Window in Figure 6 below.
- Notes: the user can enter some notes in free text format in this space.
- Worm: the user can enter some worm details in free text format in this space.
- Directory: this is the root directory as set in the step above and need not be changed.
- Filename: this is the name of the worm track the user will be recording, a name MUST be set and by default the system creates a unique name using a combination if the date and time – this can be replaced by the user if they require.
When the user toggles the Edit details button the Window goes back to the state depicted in Figure 4 above. The user can now click the Live View button and the microscope will swing to the centre of the plate and the window will show information similar to that seen in Figure 7 below.
- This panel is used to manually move the microscope over the plate, by clicking the UP, DOWN, LEFT and RIGHT arrows accordingly. Each click moves the microscope by 1mm in the relevant direction. The smaller buttons next to each of the buttons just described nudges the microscope about at 0.5 mm with each button press. The Calibrate button is explained in more detail in Figure 8 below.
- This window shows the Live View being recorded by the microscope – the image seen will either be the Raw Image or the Calibrated (Contrast Enhanced) image depending on the button setting as described in (2) above. The cross-hairs and circles define the focus point of the system and the detection process on the worm takes place within the inner zone – as the worm attempts to move outside of the inner zone the TrakBox will respond by moving the microscope to keep the worm in the centre of the target. In Live View mode the target is coloured in Cyan.
- The x-y coordinates of the microscope in cms (The origin of the x-y co-ordinate system for TrakBox – (0,0) – is defined as the spindle of the servo motor attached to the TrakBox base [Servo A] this means that the centre of the plate is usually at coordinate (1.1 cms, -8.4cms).
- This depicts a close-up of the target area under the cross hairs. This image is displayed in pseudo colour – where green is used to depict ‘background’ and other non-worm features, anything classed as the worm will be depicted in pink (see Figure 9 below for an example). If the system detects the presence of the worm in the window it will indicate this by placing a red dot at the center of mass of the worm – if no red dot is present then the system has failed to recognise the worm (if it is present). If the user toggles the Settings On/Off button the zoomed view will be obscured/uncovered as the settings panel is toggled on or off.
Calibrating the image is a VERY important step in the worm tracking process and the image MUST be calibrated before you will be allowed to proceed to the tracking stage. Calibration is necessary in order for the system to achieve the best contrast enhancement scheme that will allow the worm to be distinguished from its background. The calibration step is explained through 3 panels using pseudo colour as shown in (14), (15) and (16) in Figure 8 below, and the user has access to 4 settings – S0, S1, S2 and S3 – which are used to manipulate the image histogram trying to best enhance the worm contrast.
The Calibrate button should be pressed only when there is a suitable worm target in the field of view – it is pointless trying to calibrate with no worm in view as there is no way of knowing if contrast enhancement has been achieved. To this end the user should first move the microscope around the plate looking to get the worm in the target zone and then at that point press the Calibrate button. On doing so a frozen image of the worm against the background is captured and used to adjust the contrast settings.
When the Calibrate button is pressed the TrakBox system attempts to find the best settings for S0, S1, S2 and S3 that maximise contrast enhancement, however usually there is a need for some further manual trimming of these values. Each of the settings will now be described in more below.
- The Original image with no contrast enhancement – the more red the colour the higher the contrast and the whiter the lower (so maximum contrast would be achieved with a red worm on a white background).
- The Remapped image – in this image the target is to get a worm that is black on a white background, the sliders labelled S0, S1 and S2 should be manouvered (fine tuned) to try and achieve this. The sliders should be changed in numerical order, i.e. first S0, then S1 and then S2. S0 depicts a change in Gamma (a nonlinear warping of the image histogram) and hence is a bit of a coarse setting. S2 and S3 depict the lower and upper edges of the image histogram respectively.
- The Thresholded image – in this image the image of (15) is thresholded and binarised, what this means is that any pixel with a brightness greater than the setting given by S3 will be set ON and anything less will be set OFF – a perfect setting is a pink worm on a green background with no spurious pink pixels in the image. If TrakBox is able to detect the presence of the worm this is indicated by a red dot in the centre of mass of the worm.
- The Reset button returns the S0-S3 sliders to their original values and the Done button returns execution to the main TrakBox window given in Figure 7.
- The sliders S0, S1 and S2 as explained in (15) above.
- The slider S3 as explained in (16) above.
- The contrast enhanced worm in pseudo colour depicting a detection using a red dot to show the worm centre of mass.
5.Starting to Track
Once the user calibrates the image, and exits from the Calibration Window the system is now ready for tracking as can be seen in Figure 9 below.
- Depending on the state of the button in (22) below the main image will either show the raw image or the calibrated (contrast enhanced) image.
- Toggling this button toggles the main view between the raw and contrast enhanced image.
- Figure 10 shows the main image as a contrast enhanced image when the Calibrated Image button of (22) has been pressed.
- The zoomed image shows a crisp worm enhancement and a detection (indicated by the red dot).
- Once the Calibrate process has been completed the Go button appears – clicking on this will start the Worm Tracking process. Note that if you take too long calibrating the image the worm may have moved out of the field of view and you may have to manually search for it and bring it back into the field of view before clicking on Go!
Once the GO button is pressed the worm tracking begins and the TrakBox system detects the presence of the worm centre of mass which is then indicated by a red dot. When the worm is successfully detected the target cross-hairs turn green (if the worm presence can NOT be detected the target crosshairs turn red) – as can be seen in Figure 11 below.
- The filename that is being used to save data to.
- The target crosshairs with the detected worm centre of mass indicated with a red dot.
- The Frame number and elapsed time (in h:m:s format) is counted up as tracking progresses. The Predicted End time is indicated based on the total duration for tracking the user selected.
- Clicking on the Overview button toggles the zoomed view with an overview view of the work track (seen in Figure 12 below).
5.2.Overview vs Close-up
- The overview image depicting the worm track in progress. The image can be zoomed in/out using the tools in the toolbar described in (1) above. The worm start position is depicted by a green dot and the current position is a red dot, with the worm track shown in magenta.
- The Close-up/Overview button toggles between the Close-up and Overview view.
- The Abort button stops the tracking and offers the user the option to either save a partial dataset or discard what has already been recorded – more about this is shown below.
When the user clicks on Abort, TrakBox stops tracking and offers an option to either Save a Partial Dataset or to Discard (delete) the recording in its entirety. The dialog box below depicts the option available to the User.
Do I need a license to run TrakBox?
Yes – TrakBox needs a licence key before it can run, the specific TrakBox purchased also needs to be physically attached before the software will run. TrakBox Viewer however, is freely distributable to anyone who wants to run it on either an MS Windows or Mac OS platform. The user will need to install the Matlab Runtime Compiler for both these programs to work – it is installed automatically as part of the install process if it is not already installed.
What is a Worm Track?
A Worm Track is a data-set generated by the TrakBox system which automatically detects the presence of a worm on a plate through its centre of mass and tracks it movement over time. The track is then used to calculate a raft of behavioural measures of the worm under analysis.
What is the worm’s centre of mass and why is it important?
As TrakBox tries to automatically detect the presence of the worm in REAL TIME, it needs to be quick in order to keep the frames-per-second to at least 2-3 frames per second, this means that the worm presence needs to be detected using “simple” (fast) methods. TrakBox does this by calculating the centre of mass of the worm based on contrast – essentially the darkest patches in the target area. At the same time, TrakBox removes dark patches related other non-worm images in the field of view. The centre of mass is a single point is space that best locates the worm in space, depending on the shape of the worm the centre of mass will be either on or outside the worm’s body – but will never be more than a 1/4 of the worm’s body length outside the worm body.
What is a phidget and why do I need to install them?
TrakBox speaks to and controls the servo motors using Matlab which in turn uses phidgets to channel the control signals to the motors themselves. If you don’t install the phidget drivers TrakBox will not be able to speak to the servo motors – you only need to install the drivers once – and make sure you do so BEFORE you install the TrakBox software itself.
Why do I need to use USB 3 ports (and not older USB ports)?
USB ports prior to USB 3 would power a maximum of 500mA – this limits the amount of power the USB port can supply. As with TrakBox the USB port needs to power two servo motors, the USB camera (with lighting) AND the LED lighting – 500mA is not much! With USB 3, a single port can power up to almost 1A meaning that it can provide ample power for a TrakBox to work. If you are not sure if you have USB 3 ports, you can identify them as they have a blue insert as seen in the image.
This section links to a series of video tutorials which show TrakBox in action and explain the various settings and actions needed to keep TrakBox running.
7.1.Mapping the plate background
This video shows the first step necessary when starting to track on a new plate.
If you have any issues with your TrakBox please contact us using the form below, we do not guarantee 24/7 support however we will endeavour to respond with some help as soon as possible.