Manual

Program manual for BirdOriTrack
Matlab program to analyze the orientation of birds in orientation funnels or cages
© Rachel Muheim; Version 4.0, last changed Jan 2014
Terms and conditions for the use of BirdOriTrack
BirdOriTrack is free to download and use, but all users are asked to cite the methods paper published in the Journal of Field
Ornithology whenever results from this program are published.
I have no possibility to trouble-shoot and instruct users, so unless a user discovers a serious flaw in the program, the help that
I can provide will be very limited. However, I am more than happy to help, including writing custom-designed extensions or
alterations of the program, if the user agrees on a scientific collaboration with shared authorship on at least the first
publication.
How to use the Program
(1) Before any analysis can be done, either a video or a Matlab *-track.mat-file with the saved data from a previously tracked
already movie has to be loaded. This can be done by tracking of an avi-file (film saved in computer in avi format), or by
loading a *-track.mat file (file that has already been tracked live or from an avi-file).
(2) When the data is loaded the tracks have to be analyzed (not necessary after loading a *-track.mat file).
(3) After track analysis, the results can be plotted.
1
(1) Avifile
Preparation of Movie-files:
With programs like e.g. VirtualDub (GNU software) you can transform your video files into files of one of the following
formats: *.avi;*.wmv;*.mpg;*.mj2;*.asf;*.asx (see instructions at end of manual). Important: Make sure to use short movie
names with no dot other than between the name and the file extension (e.g., Birdori-2012-05-10.avi)!
Video compression: I recommend the latest version of DivX as compression codec. When configuring the compression,
make sure that you insert so-called “keyframes” (every 25th frame), since this speeds up data analysis. Also, if your video
acquisition software has recorded the video at a high frame rate, you should reduce it to between 3-12 frames per second at
this stage.
Import Movie-files:
Import avi-files frame-by-frame and extract positional data. After selecting a file with “Select Movie-File”, the number of
frames is displayed in the GUI. Since the speed of the movie-file can vary and often does not perfectly agree with the saved
information on frame rate, enter the start and end time (hh:mm:ss) of your movie, so that the program can calculate the exact
frame rate. Press “Load File” to start tracking.
A preview of the first frame appears and you have the choice to calibrate the funnel positions (same as function “Set Funnel
Position”, see below) or choose an already saved calibration (saved as *-cal.mat). Once you have approved the calibration or
made a new one, you are asked to give the length of a bird (place cursor on one end of bird (head), left-click mouse, move to
other end of the bird (tail), right-click to approve length (does not need to be exact...). Before tracking starts, you will also be
asked to set the tracking sensitivity (related to contrast in movie; default = 20). Reduce sensitivity (smaller number) if the
program picks up artifacts, resulting in errand data points; enhance sensitivity (larger number) if the program does not pick
up the moving bird (you can use the Program “TrackingCalibration” to determine the best sensitivity for your movie files; see
instructions at end of this document).
Tracking takes about as long as the length of the movie, but depends very much on the definitive speed (definitive frame rate
in fps), on the number of keyframes (the more the better), on CPU speed of the computer and on how many other programs
you have running (turn off all unnecessary programs, also those that run in the background)! To improve performance, see
instructions at end of manual!
(1) Load *-track.mat files
Load Matlab track-files (files that have been tracked with “avi-track”) for reanalysis or data presentation. “Frames” gives start
and end frame of the data set. “Set Funnel Position” (change calibration of cages/funnels) and “Analyze Track” (you can
change the range of frames to analyze, e.g. to view subsets of the data set) can be repeated, and/or results can be viewed.
Calibrate Funnel Position
Calibrate the position of the funnels/cages by marking
the horizontal and vertical dimensions of the funnel
and the inner circle (center circle of funnel/cage).
Horizontal lines: set the cursor (cross) to the left edge
of the funnel/cage, press the left mouse, move the
mouse to the right edge and click right mouse button to
confirm. Repeat on the vertical axis, from the top edge
to the bottom edge of the funnel/cage. The program
now draws a circle (blue for outer circle, green for inner
circle) that should lie on the rim of the cage/funnel
(outer circle) or around the center of the cage (size of
perches; inner circle). Confirm with “Yes” if this is
true, repeat otherwise. Input name of bird/funnel/cage
(subsequently called ID). After all funnels/cages are
calibrated, you are asked to draw an arrow pointing
North (input south to north). The calibration can be
saved for future use (*-cal.mat).
2
(2) Track Analysis
This part of the program analyzes the track positions and extracts the counting data points.
First, each position is assigned to a funnel, or excluded if the position is outside of a funnel.
Then, the positions are separated by funnel and recalculated relative to the center of the
funnel (center of inner circle marked with a cross). The data points (positions) are then
marked as being positioned either inside or outside of the inner circle.
Positions of a bird in a funnel/cage in yellow (outer circle: dimension of funnel/cage, inner
circle: area containing the center section of the funnel/cage; drawn as viewed in the frame,
i.e. camera distortion is visible). Each data circle gives the position of the bird outside of the
inner circle.
For each position outside of the inner circle, the program calculates the corresponding data
point which projects from the center of the funnel/cage (cross) through the data point to
the rim of the funnel/cage (lying on the outer circle). This gives the radius of the
funnel/cage for each position (distance from cross to data point on outer circle).
To correct for camera distortion the effective radius is calculated for each bird’s position (radius of funnel at that location set
to 1). The effective radius is then used to either include or exclude data points and can be set in the beginning of the track
analysis (currently set to 0.5).
In a final step, multiple data points from one hop (from the time a bird leaves the inner circle until it enters it again) are
compared and all the position but the one with the highest r-value are excluded. Then the directions are calculated relative to
the North mark.
By choosing start and end frame, sections of a recording can be analyzed separately. By default, the whole recording is
analyzed.
Exclude Area
This option lets you exclude parts of a track that contain artifacts. Mark the desired area and confirm with a mouse click; then
wait until the window disappears when the calculations are finished. Choose “Overview Plot” to see the result and repeat, if
necessary.
Choose areas as small as possible and be patient – it may take a while until everything is recalculated!
3
(3) Activity Analysis
The program can measure both activity and inactivity (resting) of the birds.
Activity Plot
As a measure of activity, the program calculates the length
of a bird’s movement over a given time interval (30 sec is
set as default), measured with the apparent radius as unit
(apparent radius = 1, corrected for camera distortion). The
graph is automatically saved as a jpeg file (Test name-start
frame–end frame-ID-act.jpg).
Resting Positions
As a measure of inactivity, the program calculates the number of frames a
bird spends sitting at one location (moving less than twice the length of the
bird) and treats each of these resting positions as one data point (no matter
for how long the bird sat there). You can choose the minimum resting
length in minutes to be included as a resting position (e.g., value set to 2
min means that a bird must have sat at one location for a minimum of two
minutes, corresponding to a resting position length of at least 2 * 60 *
frame rate. Only resting positions outside of the inner circle are included to
calculate the mean resting direction, whereby the length of a resting event is
not included in the calculation of the resting direction, because of
pseudoreplication. The circles in the left graph show the positions and
length (numbers of frames) of the rests. The graphs are automatically saved
as jpeg files (Test name-start frame–end frame-ID-rest.jpg).
(3) View Results
Overview Plot
The overview plot shows the tracks superimposed on a picture of the set-up (first frame) with calibration. The picture is
automatically saved as a jpeg file (Test name-start frame–end frame-overview.jpg).
Fig. 3. View of setup used at Falsterbo Bird
Observation with four cameras, each
recording the movement of a bird in a
separate orientation box, connected to one
DVR recorder. For each cage, the tracked
positions of the bird are marked in yellow, the
outline (edge of rim) is shown as a blue circle,
and the center area is marked as green circle.
The black cross marks the center of the cage.
In this example, the center area is defined as
the outer edge of the bottom disk, with a
radius about 2 cm larger than the radius of the
perch (grey ring inside of the green circle).
The reference direction (e.g., geographic or
magnetic North) is marked with a red arrow
for all cages together.
4
Tracks per Funnel
Plots each funnel (outline of funnel dimensions and inner circle in true scale) in a separate window, with track of bird and
data points included in final data set marked (Fig. 4A). If a bird was not active in a funnel, the following message is shown
instead of a figure: “Track-file contains no orientation data!”. The graphs are automatically saved as jpeg files (Test name-start
frame–end frame-ID-track.jpg).
Figure 4. A: Plot of an individual bird’s movements in an orientation
cage with all counting positions (“valid hops”) marked with a red
circle; B: Circular diagram of the orientation shown in A. The data
points are the “valid hops” drawn relative to the center of the cage
with North set to 0°. The arrow gives the mean direction of the
sample, with the length of the arrow giving the mean vector length r
of the data sample, drawn relative to the radius = 1. The dotted lines
on each side of the mean vector indicate the 95% confidence
intervals.
Orientation per Bird
Circular graph of final data per bird with mean direction (Dir), mean vector length (r), P-value and number of counted
positions (n) for both unimodal and axial distributions (Fig. 4B). Attention! Because of pseudoreplication (dependency of
hops), statistics other than the mean orientation should not be used for further analysis and are only given to provide a better
understanding of whether a bird was oriented and whether the directional choice was unimodal or axial. If a bird was not
active in a funnel, the following message is shown instead of a figure: “Track-file contains no orientation data!”. The graphs
are automatically saved as jpeg files (Test name-start frame–end frame-ID-ori.jpg).
Summary Plot
The summary plot summarizes all the results and saves it as a jpeg and a PDF file (Test name-start frame–end frameID.jpg/pdf). At the same time, the results, inclusive raw data, are saved in an Excel-file (Test name-start frame–end frameID.xls) and in a Matlab file (Test name-start frame–end frame-def.mat).
5
Note that for better visibility, individual data points of samples with n > 80 are not plotted in the orientation plot, but only
the mean vector and confidence interval.
Calibrate Tracking Parameters
This subprogram can be used to determine the best suited tracking sensitivity for your movie files. Tracking sensitivity
depends on the contrast between the animal to be tracked and the background of the movie frames. By choosing the correct
sensitivity and size of the bird, you can considerably increase tracking quality and computer performance (processing speed)!
Start with the predefined sensitivity value and then increase or decrease in steps of 5 to see whether tracking improves. The
goal is to find the sensitivity level that produces the least amount of stray pixels in the black-and-white image, but still detects
the positions of the animals (indicated by red circles in the reduced image).
You can also determine the most appropriate size of the bird, which has an
effect on the minimum size of the white areas to be counted as a position.
Use a larger bird size if you receive more than one red circle per bird position,
since with several positions, the one with the largest area will otherwise be
chosen for the final position, which may not always be the best.
By adjusting the sensitivity settings and the size of the bird you can also
optimize tracking speed, which is given at the end of a tracking series.
The program shows the video tracking steps for 10 frames starting with the
“start frame”. If the selection of your frames does not contain any
movements of the animal(s), choose another start frame, until you find a
section of 6 frames where the animal(s) change(s) position.
6
Installation of the Program
1.
Run BirdAnalysis_pkg.exe once to “unpack” the program. This will unpack a program called *.exe.
2.
Run BirdAnalysis.exe every time you want to use the program
For error messages see below…
Error Messages
MCR installation stops abruptly and displays error message
Description
When installing the MATLAB Component Runtime (MCR) using MCRinstaller.exe, the installation aborts and
you receive the following error message:
"The wizard was interrupted before MATLAB component Runtime 7.5 could be completely
installed.
You system has not been modified. To complete installation at another time, please run
setup again."
Depending on which version of the Microsoft installer you have on your system, you might see this error message
instead:
"Error 1304 writing to file MWArray.dll Verify that you have access to that directory and
later an Internal Error 2350 popup."
Workaround
1.
Download the Microsoft Visual C++ Redistributable Package. For 32-bit systems, download the SP1 version of
vcredist_x86.exe (available here). For 64-bit systems, download vcredist_x64.exe (available here).
These self-extracting executable files install runtime components of Visual C++ Libraries required to run
applications developed with Visual C++ on a computer that does not have Visual C++ 2005 installed.
2.
Install the package on the target computer by double-clicking on the file you downloaded.
3.
Re-execute MCRInstaller.exe.
NOTE: When you run the MCR installer, you will see a pop-up message indicating that .Net Framework is not installed.
Click the option to continue without installing .NET Framework.
-----------------------------------------------------------------------------------------------------------------------------------------------
Reading video compressed in 32-bit and 64-bit systems
There are 32-bit codec libraries and 64-bit codec libraries. The 32-bit libraries are used by 32-bit applications, like
MATLAB in 32-bit mode, and the 64-bit libraries are used by 64-bit applications, like the 64-bit MATLAB. A video file
created in each version can be played on any other system (using Windows Media Player on another computer, for
example) so long as the player has access to corresponding 32-bit or 64-bit codecs on their system.
When the required codec to read the given AVI file is not installed in the computer, an error occurrs. For example, the
Cinepak codec iccvid.dll is only available as a 32-bit distribution. Hence, only 32-bit MATLAB and other 32-bit
applications can play or create AVI files with Cinepak compression. In this case, the user is not able to find the
appropriate codec with the compression code because the 64-bit operating system may have a 32-bit codec while the 64bit MATLAB application tries to locate a 64-bit codec library.
7
To work around this, here are two options.
The workaround is to create the AVI file with a codec whose 64-bit version is available and installed on the computer, so
that it can played using 64-bit MATLAB.
First create an uncompressed AVI file using 64-bit MATLAB, as is. Then, use an open source third-party tool like
VirtualDub programatically or interactively to compress the AVI file. VirtualDub's strong suite is codec development
and has access to a number of implementations of popular codecs, like MPEG-4:
In general, if similar error messages are obtained when using any codec, the following checks are recommended.
Check if the appropriate codec is installed on the computer i.e. if the driver (.DLL files) corresponding to the codec is
available on the machine.
It should be noted that, in a Windows 64-bit XP machine, a list of the installed 32-bit codecs can be found in:
%SYSTEMROOT%\syswow64, while a list of 64-bit CODECs can be found in: %SYSTEMROOT%\system32
* To emphasize, even though the "system32" suffix seems to imply 32-bit, this is where Windows stores 64-bit binaries
as indicated by the link below:
8