Data from: Pigeons make slow divergent eye movements during flight, and large convergent eye movements when landing
Data files
Jul 06, 2026 version files 84.14 GB
-
analysisScripts.7z
4.32 MB
-
digitizedEyeData.7z
274.75 MB
-
digitizedFlowData.7z
51.69 GB
-
eyeCalibration.7z
810.94 KB
-
eyeDLCModels.7z
14.83 GB
-
eyeTrackedVideos.7z
4.35 GB
-
frameTimer.7z
8.56 MB
-
imuData.7z
233 MB
-
labeledVideos.7z
12.42 GB
-
pigeonHoodBlock.stl
4.12 MB
-
piScripts.7z
2.56 KB
-
README.md
13.85 KB
-
summaryData.7z
326.58 MB
-
utilScripts.7z
2.52 KB
Abstract
Birds are highly visual, but it remains unknown if they move their eyes during flight, and if so, whether these eye movements are used to control flight. We developed an onboard camera system to separately track eye movements and record optic flow from homing pigeons released several kilometers from their home loft. During flight, the eyes of pigeons are oriented laterally and exhibit slow, temporal eye movements consistent with a divergent optokinetic response. The speed and direction of these eye movements matched optic flow along the horizon generated by forward flight. We confirmed that head-restrained pigeons exhibited binocular and divergent eye movements in response to computer-generated visual stimuli simulating self-translation. In contrast, during landing, as measured in both the open field and laboratory, pigeons exhibited large convergent binocular eye movements directed toward the perch. These results indicate that both optokinetic and goal-directed eye movements are important for avian flight control.
Dataset DOI: 10.5061/dryad.3j9kd51zx
Description of the data and file structure
This Dryad folder contains the data used for the article titled "Pigeons make slow divergent eye movements during flight, and large convergent eye movements when landing."
Data include raw videos of eye movements collected using Raspberry Pi computers mounted on free moving pigeons, videos of eye movements from (gently) restrained pigeons, scripts used to collect and analyze data, and data (eye position/movement, visual motion statistics) derived from these data.
This work is currently accepted at Current Biology.
Files and variables
File: pigeonHoodBlock.stl
Description: A 3D model of a pigeon head used as a hood block for making the masked used to carry camera equipment.
File: analysisScripts.7z
Description: A folder of 10 scripts for analysis of data presented in the manuscript. See comments in individual files for additional details. All files point to folders local to my PC, so these will need to be changed to fit your file organization.
- Lapsanskyetal_pigeons_frameTimer_batch.py -- A Python script that reads in videos recorded using a Raspberry Pi (see piScripts/camera_split.py) and outputs text files with the timecode, as determined using optical text recognition (pytesseract). INPUT: Videos in /labeledVideos.7z. OUTPUT: files in /frameTimer.7z.
- Lapsanskyetal_pigeons_eyeTracker.mlx -- A MATLAB script that reads in the output of the frame timer (above, stored in /frameTimer.7z), kinematic data (generated by DeepLabCut and stored in /digitizedEyeData.7z), and IMU (inertial measurement unit data, stored in /imuData.7z) from outdoor eye tracking videos. The output (eye position, velocity in degrees + behavioral categories, etc.) is exported as .CSV files and moved to /summaryData.7z.
- Lapsanskyetal_pigeons_indoorEyeTracker.mlx -- A MATLAB script similar to ...eyeTracker.mlx except for indoor perch-to-perch flights (Fig. 4 in manuscript). A simplified version of the full ...eyeTracker.mlx with unneeded bits removed. Reads in the output of the frame timer (above, stored in /frameTimer.7z), kinematic data (generated by DeepLabCut and stored in /digitizedEyeData.7z), and IMU (inertial measurement unit data, stored in /imuData.7z) from indoor eye tracking videos.
- Lapsansky_headFixPigeon_eyeTracker.py -- A Python script for tracking the position of the pupil of head-fixed pigeons using thresholding and contour detection. Input videos are those of head fixed pigeons as shown in Figure 3 of the manuscript. Outputs are .CSV files of pupil angles also stored in /digitizedHeadFixed.7z.
- Lapsanskyetal_pigeons_headFixedTracker.mlx -- A MATLAB script for generating summary data from raw pupil orientations generated by Lapsansky_headFixPigeon_eyeTracker.py. Inputs are .CSV files in the /digitizedHeadFixed.7z folder. Outputs are .CSV files stored in /summaryData.7z.
- Lapsansky_horizon_detector.py -- A Python script for determining the roll and tilt of the birds-eye-view camera relative to the perspective of the camera. Given a folder of rectilinear images, the script selects a pseudo-random subset and finds the horizon. It then reports the tilt and roll of the horizon in the camera view. These values, plus the pre-set yaw angle, can be used to reproject the rectilinear frames into an equirectangular projection using Lapsansky_persp2equirect_parallel.py.
- Lapsansky_persp2equirect_parallel.py -- A Python script which will convert a stack of rectilinear PNG images into an equirectangular projection given a roll, tilt, and yaw angle. Inputs are folders of images in /flowData.7z/TRIAL/rect. Outputs are folders of images for the same trial in /flowData.7z/TRIAL/equi.
- Lapsansky_DISopticalFlow_batch.py -- A Python script which takes in a stack of equirectangular PNGs and computes optical flow between frames using Dense Inverse Search (DIS), correcting for distortion inherent in this image representation (proportional to the cosine of the latitude). Flow is cropped to the region of interest and summarized to reduce file size, saved as .h5. Flow data are then passed to Lapsansky_DISopticalFlow_batch.py.mlx for analysis. Inputs are files in /flowData.7z/TRIAL/equi. Output is a .h5 file in /flowData.7z/TRIAL/.
- Lapsanskyetal_pigeons_flowTracker.mlx -- Much like ...eyeTracker.mlx, this script takes in frameTimer files, IMU data, and flow data to produce optical flow data summarized by time, region in the visual field, and behavior. Specifically, this reads in the output of the frame timer (above, stored in /frameTimer.7z), flow data (/digitizedFlowData.7z), and IMU (inertial measurement unit data, stored in /imuData.7z). The output is exported as .CSV files and moved to /summaryData.7z.
- Lapsanskyetal_pigeons_Figures&Analysis.Rmd -- An R Markdown file for taking the data in /summaryData.7z and producing figures and statistical comparisons described in the manuscript.
File: frameTimer.7z
Description: CSV files containing the timestamps extracted from Raspberry Pi videos. These are used for synchronization in the .mlx files.
Column headers:
| frame | timecode | timecodeRaw |
|---|---|---|
| Frame of video | Timecode output by frameTimer.py and filtered to remove common typoes | Raw timecode extracted using optical text recognition in frameTimer.py |
File: digitizedEyeData.7z
Description: Cleaned versions of kinematic data for the eye and surrounding facial features generated by DeepLabCut for free moving pigeons.
Column headers: File row names and header names correspond to standard naming conventions from DeepLabCut. The number of columns varies based on the number of digitized points for a given file. The topmost row, "scorer", describes the details of the DeepLabCut model used for tracking. The second row, "bodyparts", contains the name of the digitized point in the DeepLabCut. Bodyparts starting with "t" are from the dorsal region of the eye ring. Those starting with "b" are from the ventral margin of the eye ring. Those labeled "front" and "back" are along the nasal and caudal margins of the eye ring and used to determine the origination of the eye in _eyeTracker.mlx. The point labeled "hood" is an arbitrary but trackable piece of the leather mask used to hold the camera. Points starting with "pupil" lie around the margin of the pupil. Further details are contained in the _eyeTracker.mlx file. The third row, "coords", indicates whether the data below that are for the x position, y position, or likelihood, as determined by DeepLabCut.
File: imuData.7z
Description: Accelerometer, gyroscope, and magnetometer data for each flight (eye tracking and optic flow). These are named to make the name of each trial. For each trial, there is also an IMU file ending in _full.log. These contain the same data plus data from when that IMU was stationary on the desk, useful for removing gyroscope offsets.
Column headers: IMU data have no column headers. The first column is the timecode. Columns 2-5 contain accelerometer data. Columns 6-9 contain gyroscope data. Columns 10-13 contain magnetometer data. Additional details on these data can be found in the corresponding _eyeTracker.mlx or _flowTracker.mlx file.
File: eyeCalibration.7z
Description: Data for converting pupil position to eye-in-head angle including the position of pupil margins generated by DeepLabCut (/calibrationPoints), morphometric data from animals for plotting in R (eyeCal_plotting.csv), and a MATLAB script for obtaining the radius of rotation of the eye using calibrationPoints files (Lapsansky_centreOfEyeRotation.m). DistanceBetweenPupilAndEyeCenterOfRotation.csv contains intermediate data for determining the distance between the pupil and the eye center of rotation. A desciption of these data is included within the csv file. EyeRingLengthInMM.csv contains measurements of the length of the eye ring, used for converting from pixel units to eye-in-head degrees. A description of these data is included within the csv file.
File: utilScripts.7z
Description: Scripts I found useful in analyzing data. Only fit_ellipse.m is required (for eyeTracker.mlx) and is from the MATLAB file exchange (https://www.mathworks.com/matlabcentral/fileexchange/3215-fit_ellipse). Author is Ohad Gal. The original author retains all rights. For this reason, this file has been excluded from the Dryad submission, as all data deposited at Dryad must comply with a CC0 license waiver.
File: piScripts.7z
Description: Scripts used to record data from the Raspberry Pi Zero. Camera_split.py records videos in chunks. IMU_st.py records IMU data.
File: summaryData.7z
Description: The processed data output by the MATLAB files listed above and read into the R script called Lapsanskyetal_pigeons_Figures&Analysis.Rmd.
File Naming Scheme (ALLCAPS portions are placeholders)
| File Naming Scheme | Description | Data output by... |
|---|---|---|
| eyeCal_plotting.csv | Summary data for calculated distance between the pupil and the eye center of rotation, used for scaling from pixels to degrees of eye-in-head angle | Lapsansky_eyeCenterOfRotation.m |
| headFixed_PIGEONBANDNUMBER_TIMEOFRECORDING.csv | Summary data from eye tracking head fixed pigeons | Lapsanskyetal_pigeons_headFixedTracker.mlx |
| indoor_PIGEONNAME_Data.csv | Summary data from eye tracking during indoor trials | Lapsanskyetal_pigeons_indoorEyeTracker.mlx |
| PIGEONBANDNUMBER_HOODIDENTIFIER_EyeTRIALNUMBER | Summary data from eye tracking during outdoor trials | Lapsanskyetal_pigeons_eyeTracker.mlx |
| PIGEONBANDNUMBER_HOODIDENTIFIER_FlowTRIALNUMBER | Summary data from outward facing optic flow cameras | Lapsanskyetal_pigeons_flowTracker.mlx |
Column headers: Column headers for /summaryData are described in the corresponding code file that produced a given file in /summaryData. Many of these files have nearly 150 columns. To keep this README file from becoming overly long, please see the description of the column headers in the appropriate code file. For 'eyeCal_plotting.csv', see '/eyeCalibration/Lapsansky_eyeCenterOfRotation.m'. For files starting with 'headFixed_', see '/analysisScripts/Lapsanskyetal_pigeons_headFixedTracker.mlx'. For files starting with 'indoor_', see '/analysisScripts/Lapsanskyetal_pigeons_indoorEyeTracker.mlx'. For files containing "Eye", see '/analysisScripts/Lapsanskyetal_pigeons_eyeTracker.mlx'. For files containing 'Flow', see see '/analysisScripts/Lapsanskyetal_pigeons_flowTracker.mlx'.
File: labeledVideos.7z
Description: Eye tracking videos with markers labeled using DeepLabCut. Names correspond to naming scheme in /summaryData for indoor and outdoor trials. See table above.
File: digitizedFlowData.7z
Description: Output optical flow data from Lapsansky_DISopticalFlow_batch.py for each video from outward facing camera. Input are image files.
File: digitizedHeadFixed.7z
Description: Pupil orientation data for head fixed pigeons, described in Figure 2 of the manuscript. The blue camera (csv files appended "b") was on the right side of the bird. The red camera (csv files appended "r") was on the left side of the bird. Files starting with "OKR_stimulus_" contain information on the randomly ordered stimulus used to ellicit optokinetic responses in head fixed pigeons. These and the 'data.csv' files are input to "Lapsanskyetal_pigeons_headFixedTracker.mlx". Descriptions of the column headers are included within that code file.
File: eyeDLCModels.7z
Description: DeepLabCut models for each eye tracking trial, included in the folder /eyeTrackedVideos.7z. Inputs are these videos for each like-named DeepLabCut Model. These models must be directed toward the appropriate video location (i.e., in an unzipped version of /eyeTrackedVideos.7z) to accomplish tracking.
File: eyeTrackedVideos.7z
Description: Untracked eye videos used in this manuscript. Both indoor and outdoor are included within this folder.
Code/software
Python version 3.9.18
MATLAB version R2024A
R 4.4.1
All packages required for running scripts are listed within individual code files.
Access information
Other publicly accessible locations of the data:
- NA
Data was derived from the following sources:
- All data are original.