Data and downloads repository for 'Low latency multicamera 3D tracking of insects with Braid'

Within this data repository can be found the downloadable files and the datasets presented in 'Low latency multicamera 3D tracking of insects with Braid' as well as code used for analysis and figures within that publication. Full details of these data and their collection can be found in that publication. In the below sections we detail the content. Note this information is also contained in a README.md file within each section: Downloadable files for the protocol (protocol_downloads): This section of the repository contains the downloadable files required to follow the protocol as detailed in the publication associated with this repository (henceforth 'the protocol'). For more details on how to use these files consult that protocol. 1. config_files_for_protocol This folder includes the configuration files to be used in the protocol: the Basler camera configuration file Basler_a2A1920_features.pfs, the Braid configuration file config.TOML, and an example of alternative parameter settings in a format for retracking, retrack_paras.toml 2. custom_equipment_cad_files This folder contains the computer-aided design (CAD) files for custom equipment discussed in the protocol. Full details of how these items are used are given in the publication main text. These items are sorted into three further subfolders: a) 3D_printed_parts, which contains CAD files for all 3D printed items used in the protocol. See the protocol for materials used to print these and their use. b) AprilTag_plates, which contains two SVG files for laser cutting the AprilTag plates used in the protocol, one for larger tags, one for the smaller tag. These files are designed to be laser cut and etched using tools and materials as described in the protocol. Red (R:255, G:0, B:0) lines are set to cut, black (R:0, G:0, B:0) to be etched away. c) Insect_flight_arena_with_frame provides CAD files associated with the insect flight arena and support and camera mounting frame used in the protocol. This includes to-scale PDF files to print wall stripe patterns, panel_5.03cmPwidth.pdf, a CAD model of the insect flight arena and support and camera mounting frame itself, Arena_and_support_assembly.FCStd, which together with the Reference_for_Arena_and_support_assembly.docx file provides details of parts used to make the insect flight arena and support and camera mounting frame. Additionally, a simple 'scale-agnostic' STL file of the insect flight arena, tunnelonlywithflower.stl, is imported into Rerun to aid visualization of tracking data, as seen in video 4 of the protocol. Calibration files (calibration_files): This folder contains examples of files associated with calibration of Braid, as performed in the protocol, provided for reference. This includes files used as input for calibration and outputs. Note that BRAIDZ files themselves (see tracking data below) also contain the relevant calibration information within them. 1. example_calibration_files This folder contains examples of the calibration files produced by Braid, all collected as described in the protocol, provided for reference. a) Intrinsic_calibration_files, an example of intrinsic calibration YAML files for each camera used in the protocol. These are produced using checkerboard images collected by Braid (see the protocol for more detail). This directory would be provided as the input for --intrinsics-yaml-dir for the "braid-april-cal-cli" command (see the protocol). b) 3D_coords_20250523.csv, an example of the AprilTag 3D coordinates CSV used for extrinsic calibrations, in the correct format for the "braid-april-cal-cli" command (see the protocol). This CSV file would be provided as the input --apriltags-3d-fiducial-coords for the "braid-april-cal-cli" command (see the protocol). c) AprilTag_detections, an example of AprilTag detection CSV files for each camera used in the protocol. These are produced using Braid (see the protocol for more detail). Each is named as produced by Braid with the format apriltags[date]_[time]_[camera_name].csv. This directory would be provided as the input for --apriltags-2d-detections-dir for the "braid-april-cal-cli" command (see the protocol). d) extrinsic_calibration_20250523.xml, an extrinsic calibration XML file for the Braid system, produced as described in the protocol. A calibration file like this (with the name calibration_output.xml) could also be produced using the Braid command: braid-april-cal-cli --apriltags-3d-fiducial-coords '3D_coords_20250523.csv' --apriltags-2d-detections-dir 'AprilTag_detections' --intrinsics-yaml-dir 'Intrinsic_calibration_files' --bundle-adjustment --output-xml 'calibration_output.xml' 2. Camera_checkerboard_collection Here, for each camera used we provide a video demonstration of the checkerboard image collection (video comparable to video 3 in the publication), with the name format [camera name]_checkerboard_date.webm, and a folder containing each image collected during the intrinsic calibration and the checkerboard collection YAML file produced by the intrinsic calibration process, [camera name]_checkerboard_date_time. For more details on production of these files and intrinsic calibration, see the main text of the publication associated with this dataset. Note that the graphical user interface (GUI) of Braid and Strand Camera used here is a pre-release version. This GUI differs in appearance from that of version 1, but both versions of Strand Camera have identical tabs and buttons with regard to checkerboard calibration. Data Files and analysis (braid_tracking_data): This section contains the Braid tracking data and Python code for generation of data figures from the publication associated with this repository. Alongside the tracking data collected by Braid, simultaneously collected video is also provided. Note that video is not recorded for all cameras for all bees, and is often recorded at a lower frame rate than the Braid tracking data (see main text of the publication associated with this repository for more details). All tracking data collected are provided in the '.braidz' format; for more details on the BRAIDZ format, consult the Braid documentation (https://strawlab.github.io/strand-braid/braidz-files.html). Note that these files can be visualised in Rerun as described in the protocol; however, we do not provide pre-exported '.rrd' files here (for reasons discussed in the protocol itself). 1. Tracking of honey bees in 3D (Bee_tracking) This folder contains example data of Braid tracking bees within a flight area as described in the data validation section of the protocol. a) bee_tracking_data, data collected of bees flying on their own within the arena. Files provided are those that were retracked with the original tracking parameters given in config.TOML (provided in protocol_downloads/config_files_for_protocol), as described in the protocol itself. Within this folder are subfolders indicating a time (the time tracking of the individual bee began, which also serves as the individual bee's ID, see the protocol). These in turn contain a BRAIDZ file (with the standard BRAIDZ format [date]_[time]_original.braidz) and MP4 video (with the name format movie[date]_[time]_[camera_name].mp4) where available. These folders contain tracking data for both bees that were successful in locating the flower and bees that were not (see the protocol). The successful bees are used for plotting of figures as described in the protocol. To facilitate this, the successful bees are listed within the file success_bee_objects.csv, also included in this folder. In this CSV file the bee IDs (corresponding to the folder name of its data) are listed in the first column as a string (column: bee) and all subsequent columns contain the object ID numbers that correspond to the bee within its BRAIDZ file. These details are used to extract the data of successful bees from the BRAIDZ files (see 'd' below). Alongside tracking data collected, we provide the calibration file used for this data, extrinsic_calibration_20250630.xml, and AprilTag detection data used to produce the calibration (folder AprilTag_detections, which contains CSV files for each camera with the format apriltags[date]_[time]_[camera_name].csv). b) retracked_bee_tracking_data, tracking data for successful bees retracked with the original calibration but altered tracking parameters given in retrack_paras.toml (provided in protocol_downloads/config_files_for_protocol). For more details on what retracking entails, see the protocol. These files follow the same naming conventions as those within 'bee_tracking_data', with '_retracked' replacing '_original' in BRAIDZ filenames. Note that this folder contains the file success_bee_objects_retracked.csv, which follows the same format and function as success_bee_objects.csv (see 'a' above) but for retracked data, as object ID numbers can be reassigned with retracking. This folder does not contain 'new' video files, calibrations, or AprilTag detection data as these are the same as those provided for each bee in bee_tracking_data (see 'a' above). c) multibee_tracking_data, data collected of multiple bees at the same time within the flight arena. Files provided are those that were retracked with the original tracking parameters given in config.TOML (provided in protocol_downloads/config_files_for_protocol), as described in the protocol itself. Within this folder are subfolders indicating a time (the time at which tracking of each set of bees began, see the protocol). Included in these folders are BRAIDZ files and MP4 video. This folder also contains the CSV multibee_objects_the3.csv, which lists the object ID numbers that correspond to each bee for the file 1720/20251015_172023_original.braidz used to produce the example figure multiBee1.png. Alongside tracking data, the calibration file used for this data, extrinsic_calibration_20251015.xml, and AprilTag detection data used to produce the calibration (AprilTag_detections, which contains CSV files for each camera with the format apriltags[date]_[time]_[camera_name].csv) are provided. d) bee_tracking_analysis.py and bee_tracking_analysis.ipynb, Python code for the analysis and production of data figures associated with bee tracking. This is provided in both Python script (.py) and Jupyter notebook (.ipynb) formats, and annotated throughout for clarity. The code within both versions of the script is the same, but the '.py' versions were used to generate figures used in the publication. Which figures correspond with which sections of the script is noted within the file. This code generates 3Dexample20250630_142704_original.braidz.png, originalVSRetrack.png, originalVSretrack_full.png, multiBee1.png, supplement_all_original_tracks.png, and supplement_all_retracks.png, which are also included in the folder and used directly to produce figures as documented in the Python files. Python environment requirements for this code are provided in Requirements.txt (see below). 2. Braid validation data (BraidValidation) Braid tracking data and code for the validation of Braid's 3D tracking using a 2 LED wand. See the main text of the manuscript associated with this data repository for more details. a) 2LED_tracking_data, the Braid data for the validation. Within this is the folder 1333, containing BRAIDZ and MP4 video for the validation step. AprilTag detection data used to produce calibrations associated with this data are given in the folder named AprilTag_detections, which contains CSV files for each camera with the format apriltags[date]_[time]_[camera_name].csv. Additionally, the calibration file used for this data is provided, extrinsic_calibration_20250528.xml. b) Validation_code.py and Validation_code.ipynb, Python code for the analysis and production of data figures associated with the 2 LED wand validation. This is provided in both Python script (.py) and Jupyter notebook (.ipynb) formats, and annotated for clarity. The code within both versions of the script is the same, but the '.py' versions were used to generate figures used in the publication. Which figures correspond with which sections of the script is noted within the file. This code generates 3D_residual.png and Validation_frequency.png, also included in the folder. Python environment requirements for this code are provided in Requirements.txt (see below). c) IMG20250923100442.jpg, an image of the 2 LED wand used to produce figure 9A. d) figure_Validation.svg, an SVG file used to compose figure 9 using IMG20250923100442.jpg, 3D_residual.png, and Validation_frequency.png. This is then exported to PNG format to produce the figure file figure_9.png. 3. Requirements.txt A text file listing the required packages for Python, in addition to the base packages installed with Python, to run the '.py' code in sections 1 and 2. This file is formatted to run with pip as a requirements file (pip install -r Requirements.txt). Within the file itself, lines 1-4 provide further instructions. If using the '.ipynb' version of the code provided, you will additionally require related Jupyter and IPython packages required to run '.ipynb' files.