Program manual for BirdOriTrack

Transcription

1 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

2 (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 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

3 (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

4 (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

5 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 frame- ID.jpg/pdf). At the same time, the results, inclusive raw data, are saved in an Excel-file (Test name-start frame end frame- ID.xls) and in a Matlab file (Test name-start frame end frame-def.mat). 5

6 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

7 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 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 64- bit MATLAB application tries to locate a 64-bit codec library. 7

8 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