Drosophila melanogaster larval locomotion
User manual for MaggotTracker software components.
WormTracker is not a sofware component that we developed; it was developed by the Schafer lab and available at: Worm Tracker 2.0
The use of WormTracker in MaggotTracker is only for the purpose of data acquisition. That is, obtaining high-quality single-animal videos.
II. Hardware Setup
The setup that we utilized is as follows:
1. Microscope: Olympus model SZ61 trinocular stereozoom microscope.
2. Motorized stage: H105 ProScan from (PRIOR Scientific).
3. Digital camera: Unibrain Fire-i 501b (IEEE 1394 connection).
4. Light source: fiber optic transmitted light.
5. Stage control module: ProScan II Controller (PRIOR Scientific)
6. Computer: The minimum specifications we utilized were:
Additional notes on hardware setup:
- Operating sytem: Windows XP, Windows 7
- 2GB RAM memory
- 250 GB hard disk
- Ports: serial, and 1394
- The camera Fire-i 501c also worked well.
- The stage controller ProScan III also worked well.
- The stage controllers we utilized were connected via serial cable (we did not test USB connection to the contollers).
- WormTracker is designed to work with other stage controllers, such as Zaber and Ludl. We only utilized Prior stage controllers.
Download and install WormTracker 2.0 as indicated from their website.
Make sure that WormTracker works. This can be done with a simple USB webcam. The first objective is to make sure that video can be captured via WormTracker user-interface.
For the purpose of installing and verifying that WormTracker works, the USB webcam does not even have to be connected or properly mounted on the microscope.
The benefit of doing this is that any troubleshooting can be separated from, say, connecting to a specialized camera versus WormTracker being correctly setup.
Once that WormTracker can recognize a camera, and it can record videos. The next step is to make sure that WormTracker can communicate with the stage controller. Follow their instructions on doing so.
After WormTracker can capture video and control the motorized stage, set up the camera that will be used for taking videos (as needed).
There are 2 cases:
Case 1: your hardware setup makes use of USB cameras; then just follow WormTracker's instructions on their website.
Case 2: your hardware setup makes use of 1394 cameras; then if WormTracker detects them automatically, then great! You are ready to start taking videos. Otherwise, you may follow our instructions to be able to use cameras connected via 1394 in WormTracker (Section camera 1394 installation for WormTracker below).
Perform calibration of the stage by following the instructions of WormTracker. The result is a set of x,y constants for steps per pixels. If the same microscope magnification is going to be used over and over, then it is recommended that a configuration file is saved on disk. It is also recommended that such configuration file is backed up elsewhere.
IV. Copyright and Software License
We claim no copyright on WormTracker software because it was not developed by us.
V. Camera 1394 installation for WormTracker
We utilize video cameras that connect to the computer via 1394 interface, which is not supported by WormTracker. We implemented software programs that allow WormTracker to find a camera connected via the 1394 interface.
These are the instructions to installing a 1394 camera and making it work with WormTracker:
Note: we utilized Unibrain Fire-i cameras 501b and 501c.
- Make sure that the camera works, installing the manufacturer driver if needed.
- Remove any driver for the 1394 camera before installing the CMU driver (which is a free driver for cameras that comply with the 1394 Digital Camera Specification).
- Install CMU’s 1394 driver version 6.3 (http://www.cs.cmu.edu/~iwan/1394/install.html). Recent versions up to 6.4.6 did not work in our setup.
Follow their installation instructions, which will mention things such as using the properties dialog of your camera in the windows system configuration device manager, then choose/update driver by selecting file 1394Camera.inf, where the end result is that the file 1394Camera.dll will be placed in the Windows' system folder.
The included 1394CameraDemo application should work and display live video of the camera. If it does not work, then troubleshoot as needed.
- In order to communicate to the CMU driver via Java programs, we use jLibDC1394 (Java API for FireWire: IEEE-1394 aka i.Link).
Get the jlibdc1394-1.0PR1.zip version (because it includes source code). Other versions may work but they do not have documentation such as Java Interfaces. The DLL file (net_sf_jlibdc1394_impl_cmu_JDC1394CamCMU.dll) included should be copied to folder c:\windows\system32\
- Java JMF should already being installed when setting up WormTracker. We utilized version JMF version 2.1.1e in our setup.
The JMF Registry is one application of JMF that lists the current JMF devices (such as cameras). If a camera is not listed there, then it cannot be accessed from Java programs (such as WormTracker).
- Install the camera into the JMF Registry: This is done by running the program InstallJ1394Cam available at: http://jlibdc1394.cvs.sourceforge.net/viewvc/jlibdc1394/jlibdc4jmf/ .
In our setup, we have made the following notes on this respect:
- We have a copy of the folder (linked above) and modified slightly for easy setup of our cameras: 2010-02-17__jmfcompatible.zip (ZIP file)
- Unzip such file, and from the command-line, inside of the directory "jmfcompatible", type: java -classpath build;lib/jmf.jar net.sf.jlibdc1394.media.InstallJ1394Cam
- If there are errors such as "Can’t find registry file", or "Exception on commit = java.io.IOException: Can’t find registry file", then run the installer via ant (see Apache Ant) as follows: ant run-installer
- If there are errors such as "cannot write jmf.properties file", then run the command-prompt (cmd) by right-clicking and selecting "Run as Administrator" (this works on Windows 7), and run the installer again (this worked without having to use 'ant').
- If there is an error that about "I/O subsystem", then make sure that the 1394 card controller does show up in the Device Manager of Windows. In one occasion this error was due to the card being physically not fully inserted in the motherboard.
- Run JMF Registry to verify that the camera was installed, the camera will be listed there as "CMU 1394 Digital Camera Device" (under "Capture Devices").
- The camera can also be tested from the 'jmfcompatible' directory via ant as follows: ant run-player
- If there is an exception such as "UnsatisfiedLinkError: no net_sf_jlibdc1394_impl_cmu_JDC1394CamCMU in library path", then it is a dll problem. Make sure that the file "net_sf_jlibdc1394_impl_cmu_JDC1394CamCMU.dll" is located in \WINDOWS\system32\
- Under Windows-7, one problem about not finding the camera was solved when jmf.jar was included in the classpath. However, it had to be the jmf.jar in the folder where JMF was installed, not the one that comes in the 'lib' directory of the ZIP file(s) part of MaggotTracker. That is, it was necessary to explicitly indicate that jmf.jar was the one in c:\JMF211e\lib\jmf.jar (in this example JMF was installed in c:\JMF211e).
- Under Windows-7, the WormTracker will rarely bring an exception about illegal-index. We believe it was due to a GUI element that populates data from the camera but the camera was not ready yet. The solution was that in the (Windows) shortcut to WormTracker: under 'Compatibility', the checkbox for "Run this program in compatibility mode for" was selected, and then we selected Windows 7.
- In our setup, WormTracker would not find the 1394 camera on its own. Modified code that enables it is in 2010-02-27__with-all-controls.zip (ZIP file).
Unzip it, and create a windows "shortcut" to the file "WormTracker.jar" (located inside folder "with-all-controls/install/bin/" ). Once the shortcut is created, its icon can be changed by using "change icon" in the Properties of the shortcut, and selecting the icon of file WormTracker.ico