DOI: 10.5061/dryad.gb5mkkwvd
title: Crowdsourced dataset of firefly trajectories obtained by automated stereo calibration of 360-degree cameras

description: Advancements in animal tracking techniques, spanning from migrating
 mammals to swarming insects, have resulted in remarkable progress in the
 fields of behavioral ecology and conservation science. Recently, we have
 devised a method for tracking luminous fireflies in their natural habitat
 using stereoscopic pairs of 360-degree cameras. This method offers
 affordability, versatility, and ease of setup; however, the process of
 camera calibration has remained tedious and time-consuming. Now, we have
 introduced an enhanced algorithm that achieves spatial and temporal stereo
 calibration directly from the data, eliminating the need for manual
 procedures both in the field and during video processing. The algorithm
 relies on cross-correlation of flashing patterns and numerical estimation
 of camera pose. Utilizing this improved protocol and processing software,
 we have compiled an extensive dataset comprising over 100 reconstructed
 firefly swarms of various species. This data was gathered throughout the
 United States by numerous contributors following a straightforward
 protocol. The dataset holds significant potential for advancing our
 comprehension of firefly collective behavior, facilitating population
 monitoring, and expanding citizen science initiatives.
description: This dataset was obtained by an algorithm for tracking swarming
 fireflies using pairs of 360-degree cameras. The algorithm performs camera
 calibration from the data itself so that virtually no user input is
 necessary besides measuring the distance between cameras. A full
 description of the algorithm will be submitted to a scientific journal,
 and sequentially to the bioRxiv. Thanks to this simplified protocol
 (included here as a supplementary file) and improved software (included
 here as a code package), we assembled a large dataset comprising over 100
 fully 3D reconstructed and time-resolved firefly swarms. This dataset was
 collected by various contributors across the United States and spans
 several states and species. 
description: Table 1 provides a summary of the full dataset. Each swarm has
 been attributed a specific identification (ID) number for convenient
 referencing. ID numbers are constructed as such: they start with the
 letter ’s’ (short for “swarm”) to avoid compatibility issues with file
 names starting with a number; four digits follow indicating the date of
 recording in YMDD format (first digit is year: 0 for 2020, 1 for 2021, 2
 for 2022; second digit is month of the year; two last digits indicate day
 of the corresponding month); a two-letter code to indicate the
 (predominant) species recorded.  Tables 1 and 2 provide
 primary information regarding each dataset, in particular the date, time
 and location of collection, along with the scaling parameter necessary to
 convert video units to meters. GPS coordinates of recording sites are
 provided whenever they seemed appropriate to share publicly, based on
 considerations of private property, site sensitivity, etc. Tables 3 and 4
 provide secondary contextual information, such as predominant species
 recorded, sunset time (civil twilight), weather conditions, and other
 brief field notes. Each swarm, with its specific ID,
 has a separate zip file, named by as 'ID.zip'. Within each zip
 file, the main file of interest is a .csv file containing the coordinates
 of reconstructed flashes. In addition, Matlab structures (ending in
 ’.mat’) are made available. They contain all the intermediate data used in
 the course of the processing, notably the input parameters for processing.
 Finally, a folder called ’info’ contains the metadata for the video files
 (when available) and a picture of the background in each of the cameras’
 field of view (when available). See Usages Notes for a description of the
 different files. Usage Notes
 <strong>.csv files</strong><br>The xyztkj.csv
 files contain the coordinates of reconstructed swarms. The first three
 columns are the xyz coordinates; x and y define the horizontal plane, and
 z defines the vertical axis oriented upwards. Units are meters. The fourth
 column represents the corresponding times, in seconds. The fifth column k
 indicates the streak identity of a flash. The sixth column j indicates the
 corresponding trajectory. We emphasize that these
 coordinates are only partial renderings of the entire swarm. Due to the
 cameras’ limited light <br>sensitivity and visual occlusion from the
 vegetation, only flashes close enough (typically within 10–15 m) can be
 recorded corresponding to a fraction of swarms which can span several tens
 of meters <strong>.html
 files</strong><br>The .html files can be loaded in a web
 browser for quick 3D visualization of the reconstructed swarm. 
 <strong>.mat files</strong><br>The .mat Matlab
 structure files serve to provide additional processing parameters and
 intermediate results. All values under the .prm field are input
 parameters. Values in other fields are the outputs from the different
 processing steps. These files also allow to re-run the triangulate and
 trajectorize blocks with different parameters, if necessary (see
 below). <strong>sphirefly3d
 software</strong><br>The software can run from scratch as out
 = sphirefly3d([s,h]), where s and h are the only necessary inputs
 corresponding to the real-world spacing and height of the cameras. A
 window will then open where complementary movies, or folders containing
 sequences of movies, can be selected. All other parameters can be changed
 directly from the setprm.m function. Alternatively, an existing sff
 structure can be used as input, to re-run some parts of the processing:
 out = sphirefly3d(sff).