The XML calibration files used in Braid are backwards-compatible with those from Braid's predecessor, Flydra. Several of the steps described here also use tools diff --git a/print.html b/print.html index 6df455d1b..166785db8 100644 --- a/print.html +++ b/print.html @@ -471,7 +471,7 @@
The XML calibration files used in Braid are backwards-compatible with those from
Braid's predecessor, Flydra. Several of the steps described here also use tools
diff --git a/searchindex.js b/searchindex.js
index 2e163c5d3..c87423e15 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Object.assign(window.search, {"doc_urls":["braid-and-strand-camera.html#braid-and-strand-camera","braid-and-strand-camera.html#about-this-book","hardware-selection.html#hardware-selection","hardware-selection.html#pc-requirements","hardware-selection.html#hardware-accelerated-video-encoding-using-nvidia-video-cards","hardware-selection.html#camera-requirements","hardware-selection.html#basler-cameras","hardware-selection.html#allied-vision-cameras-planned-for-late-2021-or-2022","installation.html#installation","installation.html#software-installation","installation.html#hardware-installation","installation.html#cameras","installation.html#trigger-box","installation.html#trigger-cables","braidz-files.html#braidz-files","braidz-files.html#viewer","braidz-files.html#analysis-scripts","braidz-files.html#latency-analysis","braidz-files.html#content-analysis","braidz-files.html#plotting","braidz-files.html#braid-analysis-plot-data2d-timeseriespy","braidz-files.html#braid-analysis-plot-kalman-estimates-timeseriespy","braidz-files.html#braid-analysis-plot3dpy","braidz-files.html#file-format","braidz-files.html#showing-the-contents-of-a-braidz-file","braidz-files.html#extracting-a-braidz-file","braidz-files.html#creating-a-braidz-file","braid_3d_tracking.html#3d-tracking-in-braid","braid_3d_tracking.html#principle-of-operation","braid_3d_tracking.html#tracking-in-water-with-cameras-out-of-water","braid_3d_tracking.html#refraction","braid_3d_tracking.html#principle-of-operation-for-tracking-in-water","braid_3d_tracking.html#how-to-enable-tracking-in-water","braid_3d_tracking.html#tracking-multiple-objects-in-3d","braid_3d_tracking.html#details-about-how-data-are-processed-online-and-saved-for-later-analysis","parameters_for_object_detection_and_tracking.html#setting-and-optimizing-parameters-for-3d-tracking","parameters_for_object_detection_and_tracking.html#object-detection","parameters_for_object_detection_and_tracking.html#3d-tracking","braid_calibration.html#calibration-in-braid","braid_calibration.html#what-is-a-calibration","braid_calibration.html#xml-calibration-files-in-braid","braid_calibration.html#step-1-setup-cameras-zoom-focus-aperture-gain-and-lights","braid_calibration.html#step-2-run-checkerboard-calibration-to-get-the-camera-intrinsic-parameters","braid_calibration.html#step-3-collect-calibration-data-and-run-multicamselfcal-mcsc","braid_calibration.html#acquire-a-dataset-for-multicamselfcal","braid_calibration.html#convert-braidz-file-to-flydra-mainbrain-h5-file","braid_calibration.html#run-multicamselfcal-on-data-collected-with-braid","braid_calibration.html#convert-your-new-calibration-to-an-xml-file-which-can-be-used-by-braid","braid_calibration.html#with-the-new-calibration-perform-offline-tracking-the-data-used-to-calibrate","braid_calibration.html#align-your-new-calibration-using-a-gui","braid_calibration.html#automatic-alignment-of-calibrations","braid_calibration.html#calibration-with-water","braid_remote_cameras.html#remote-cameras-for-braid","braid_remote_cameras.html#what-are-remote-cameras","braid_remote_cameras.html#starting-a-remote-camera","scripting-with-python.html#scripting-with-python","scripting-with-python.html#demo-changing-tracking-settings-from-a-python-script","scripting-with-python.html#advanced-automating-manual-actions","scripting-with-python.html#advanced-running-strand-cam-within-python","processing-saved-videos.html#processing-recorded-videos-using-braid","processing-saved-videos.html#overview","processing-saved-videos.html#note","processing-saved-videos.html#example-usage-1-automatic-determination-of-inputs","processing-saved-videos.html#example-usage-2-use-of-a-toml-configuration-file","processing-saved-videos.html#todo","fmf_format.html#fmf-fly-movie-format---simple-uncompressed-movie-storage-format","fmf_format.html#converting-movies-to-and-from-fmf-format-with-the-fmf-command-line-program","fmf_format.html#file-structure","fmf_format.html#header-version-3","fmf_format.html#header-version-1","fmf_format.html#frame-chunks","fmf_format.html#types-used-above","troubleshooting.html#troubleshooting","troubleshooting.html#synchronization-problems","troubleshooting.html#any-other-problem-or-question"],"index":{"documentStore":{"docInfo":{"0":{"body":22,"breadcrumbs":3,"title":3},"1":{"body":11,"breadcrumbs":1,"title":1},"10":{"body":0,"breadcrumbs":2,"title":2},"11":{"body":13,"breadcrumbs":1,"title":1},"12":{"body":11,"breadcrumbs":2,"title":2},"13":{"body":6,"breadcrumbs":2,"title":2},"14":{"body":8,"breadcrumbs":2,"title":2},"15":{"body":4,"breadcrumbs":1,"title":1},"16":{"body":9,"breadcrumbs":2,"title":2},"17":{"body":10,"breadcrumbs":2,"title":2},"18":{"body":23,"breadcrumbs":2,"title":2},"19":{"body":20,"breadcrumbs":1,"title":1},"2":{"body":0,"breadcrumbs":2,"title":2},"20":{"body":5,"breadcrumbs":5,"title":5},"21":{"body":6,"breadcrumbs":6,"title":6},"22":{"body":3,"breadcrumbs":3,"title":3},"23":{"body":12,"breadcrumbs":2,"title":2},"24":{"body":8,"breadcrumbs":4,"title":4},"25":{"body":6,"breadcrumbs":3,"title":3},"26":{"body":246,"breadcrumbs":3,"title":3},"27":{"body":0,"breadcrumbs":3,"title":3},"28":{"body":135,"breadcrumbs":2,"title":2},"29":{"body":19,"breadcrumbs":5,"title":5},"3":{"body":93,"breadcrumbs":2,"title":2},"30":{"body":28,"breadcrumbs":1,"title":1},"31":{"body":90,"breadcrumbs":4,"title":4},"32":{"body":36,"breadcrumbs":3,"title":3},"33":{"body":73,"breadcrumbs":4,"title":4},"34":{"body":138,"breadcrumbs":7,"title":7},"35":{"body":0,"breadcrumbs":5,"title":5},"36":{"body":93,"breadcrumbs":2,"title":2},"37":{"body":32,"breadcrumbs":2,"title":2},"38":{"body":0,"breadcrumbs":2,"title":2},"39":{"body":79,"breadcrumbs":1,"title":1},"4":{"body":51,"breadcrumbs":8,"title":8},"40":{"body":18,"breadcrumbs":4,"title":4},"41":{"body":73,"breadcrumbs":9,"title":9},"42":{"body":76,"breadcrumbs":8,"title":8},"43":{"body":18,"breadcrumbs":8,"title":8},"44":{"body":26,"breadcrumbs":3,"title":3},"45":{"body":112,"breadcrumbs":7,"title":7},"46":{"body":303,"breadcrumbs":5,"title":5},"47":{"body":28,"breadcrumbs":7,"title":7},"48":{"body":72,"breadcrumbs":8,"title":8},"49":{"body":172,"breadcrumbs":5,"title":5},"5":{"body":19,"breadcrumbs":2,"title":2},"50":{"body":24,"breadcrumbs":3,"title":3},"51":{"body":14,"breadcrumbs":2,"title":2},"52":{"body":0,"breadcrumbs":3,"title":3},"53":{"body":24,"breadcrumbs":2,"title":2},"54":{"body":89,"breadcrumbs":3,"title":3},"55":{"body":24,"breadcrumbs":2,"title":2},"56":{"body":8,"breadcrumbs":6,"title":6},"57":{"body":16,"breadcrumbs":4,"title":4},"58":{"body":20,"breadcrumbs":6,"title":6},"59":{"body":0,"breadcrumbs":5,"title":5},"6":{"body":27,"breadcrumbs":2,"title":2},"60":{"body":44,"breadcrumbs":1,"title":1},"61":{"body":11,"breadcrumbs":1,"title":1},"62":{"body":29,"breadcrumbs":6,"title":6},"63":{"body":53,"breadcrumbs":7,"title":7},"64":{"body":8,"breadcrumbs":1,"title":1},"65":{"body":166,"breadcrumbs":9,"title":9},"66":{"body":95,"breadcrumbs":8,"title":8},"67":{"body":65,"breadcrumbs":2,"title":2},"68":{"body":162,"breadcrumbs":3,"title":3},"69":{"body":53,"breadcrumbs":3,"title":3},"7":{"body":21,"breadcrumbs":7,"title":7},"70":{"body":51,"breadcrumbs":2,"title":2},"71":{"body":35,"breadcrumbs":3,"title":3},"72":{"body":0,"breadcrumbs":1,"title":1},"73":{"body":0,"breadcrumbs":2,"title":2},"74":{"body":6,"breadcrumbs":2,"title":2},"8":{"body":0,"breadcrumbs":1,"title":1},"9":{"body":0,"breadcrumbs":2,"title":2}},"docs":{"0":{"body":"This is the User's Guide for Braid and Strand Camera . Braid and Strand Camera are free and open source. You can find the source code on GitHub . Issues and feature requests can be posted on the GitHub issue tracker .","breadcrumbs":"Braid and Strand Camera","id":"0","title":"Braid and Strand Camera"},"1":{"body":"The source code for this documentation is at github.com/strawlab/strand-braid/tree/main/strand-braid-user/users-guide . This book is made with mdBook .","breadcrumbs":"About this book","id":"1","title":"About this book"},"10":{"body":"","breadcrumbs":"Hardware installation","id":"10","title":"Hardware installation"},"11":{"body":"Currently only Basler cameras are supported. We use Basler's Pylon library to access the cameras. Support for other cameras is planned.","breadcrumbs":"Cameras","id":"11","title":"Cameras"},"12":{"body":"Braid uses the Straw Lab Triggerbox hardware to synchronize the cameras. This is based on an Arduino microcontroller.","breadcrumbs":"Trigger box","id":"12","title":"Trigger box"},"13":{"body":"TODO: write this and describe how to check everything is working.","breadcrumbs":"Trigger cables","id":"13","title":"Trigger cables"},"14":{"body":"A .braidz file contains the results of realtime tracking, the tracking parameters, and so on.","breadcrumbs":".braidz files","id":"14","title":".braidz files"},"15":{"body":"A viewer for .braidz files is at braidz.strawlab.org .","breadcrumbs":"Viewer","id":"15","title":"Viewer"},"16":{"body":"Scripts to analyze your .braidz files can be found at github.com/strawlab/strand-braid/tree/main/strand-braid-user/analysis .","breadcrumbs":"Analysis scripts","id":"16","title":"Analysis scripts"},"17":{"body":"To analyze the latency of your setup with Braid, you can use the Jupyter Notebook braid-latency-analysis.ipynb.","breadcrumbs":"Latency Analysis","id":"17","title":"Latency Analysis"},"18":{"body":"The Jupyter Notebook braidz-contents.ipynb can be used to view the Kalman estimates, the raw 2D detections, data on the association of cameras, and data on associations between 2D detection and 3D Tracking in your .braidz file.","breadcrumbs":"Content analysis","id":"18","title":"Content analysis"},"19":{"body":"The following plots were made with the file 20201112_133722.braidz . The scripts can be accessed at github.com/strawlab/strand-braid/tree/main/strand-braid-user/analysis . A Jupyter Notebook to create all of these plots can be found in braid-plotting.ipynb in the same folder.","breadcrumbs":"Plotting","id":"19","title":"Plotting"},"2":{"body":"","breadcrumbs":"Hardware selection","id":"2","title":"Hardware selection"},"20":{"body":"braid-analysis-plot-data2d-timeseries.png","breadcrumbs":"braid-analysis-plot-data2d-timeseries.py","id":"20","title":"braid-analysis-plot-data2d-timeseries.py"},"21":{"body":"braid-analysis-plot-kalman-estimates-timeseries.png","breadcrumbs":"braid-analysis-plot-kalman-estimates-timeseries.py","id":"21","title":"braid-analysis-plot-kalman-estimates-timeseries.py"},"22":{"body":"braid-analysis-plot3d.png","breadcrumbs":"braid-analysis-plot3d.py","id":"22","title":"braid-analysis-plot3d.py"},"23":{"body":"A .braidz file is actually a ZIP file with specific contents. It can be helpful to know about these specifics when problems arise.","breadcrumbs":"File Format","id":"23","title":"File Format"},"24":{"body":"You can show the filenames inside a .braidz file with unzip -l FILENAME.braidz.","breadcrumbs":"Showing the contents of a .braidz file","id":"24","title":"Showing the contents of a .braidz file"},"25":{"body":"You can extract a .braidz file to its contents with unzip FILENAME.braidz.","breadcrumbs":"Extracting a .braidz file","id":"25","title":"Extracting a .braidz file"},"26":{"body":"You can create a new .braidz file with: cd BRAID_DIR\nzip ../FILENAME.braidz * Note, your .braidz file should look like this - with no directories other than images/. $ unzip -l 20191125_093257.braidz\nArchive: 20191125_093257.braidz\nzip-rs Length Date Time Name\n--------- ---------- ----- ---- 97 2019-11-25 09:33 README.md 155 2019-11-25 09:33 braid_metadata.yml 0 2019-11-25 09:33 images/ 308114 2019-11-25 09:33 images/Basler_22005677.png 233516 2019-11-25 09:33 images/Basler_22139107.png 283260 2019-11-25 09:33 images/Basler_22139109.png 338040 2019-11-25 09:33 images/Basler_22139110.png 78 2019-11-25 09:33 cam_info.csv.gz 2469 2019-11-25 09:33 calibration.xml 397 2019-11-25 09:33 textlog.csv.gz 108136 2019-11-25 09:33 kalman_estimates.csv.gz 192 2019-11-25 09:33 trigger_clock_info.csv.gz 30 2019-11-25 09:33 experiment_info.csv.gz 2966 2019-11-25 09:33 data_association.csv.gz 138783 2019-11-25 09:33 data2d_distorted.csv.gz\n--------- ------- 1416233 15 files Note that the following is NOT a valid .braidz file because it has a leading directory name for each entry. $ unzip -l 20191119_114103.NOT-A-VALID-BRAIDZ\nArchive: 20191119_114103.NOT-A-VALID-BRAIDZ Length Date Time Name\n--------- ---------- ----- ---- 0 2019-11-19 11:41 20191119_114103.braid/ 97 2019-11-19 11:41 20191119_114103.braid/README.md 155 2019-11-19 11:41 20191119_114103.braid/braid_metadata.yml 0 2019-11-19 11:41 20191119_114103.braid/images/ 320906 2019-11-19 11:41 20191119_114103.braid/images/Basler_22005677.png 268847 2019-11-19 11:41 20191119_114103.braid/images/Basler_22139107.png 308281 2019-11-19 11:41 20191119_114103.braid/images/Basler_22139109.png 346232 2019-11-19 11:41 20191119_114103.braid/images/Basler_22139110.png 225153 2019-11-19 11:41 20191119_114103.braid/images/Basler_40019416.png 86 2019-11-19 11:41 20191119_114103.braid/cam_info.csv.gz 2469 2019-11-19 11:41 20191119_114103.braid/calibration.xml 10 2019-11-19 11:41 20191119_114103.braid/textlog.csv.gz 10 2019-11-19 11:41 20191119_114103.braid/kalman_estimates.csv.gz 10 2019-11-19 11:41 20191119_114103.braid/trigger_clock_info.csv.gz 10 2019-11-19 11:41 20191119_114103.braid/experiment_info.csv.gz 10 2019-11-19 11:41 20191119_114103.braid/data_association.csv.gz 20961850 2019-11-19 12:17 20191119_114103.braid/data2d_distorted.csv.gz\n--------- ------- 22434126 17 files","breadcrumbs":"Creating a .braidz file","id":"26","title":"Creating a .braidz file"},"27":{"body":"","breadcrumbs":"3D Tracking in Braid","id":"27","title":"3D Tracking in Braid"},"28":{"body":"This page describes the basic principles of how tracking in 3D is implemented by Braid. A more detailed and more mathematical description can be found in the paper describing Braid's predecessor, Straw et al. (2011). Please refer to this for more details. Straw et al. 2011: Straw AD, Branson K, Neumann TR, Dickinson MH (2011) Multicamera Realtime 3D Tracking of Multiple Flying Animals. Journal of The Royal Society Interface 8 (11), 395-409. doi:10.1098/rsif.2010.0230 rsif20100230f02.jpg . Figure 1: Principles of 3D Tracking in Braid. References in blue refer to parts of Straw et al. (2011) . (a) Flowchart of operations. (b) Schematic of a two-dimensional camera view showing the raw images (brown), feature extraction (blue), state estimation (black), and data association (red). (c) Three-dimensional reconstruction using the EKF uses prior state estimates (open circle) and observations (blue lines) to construct a posterior state estimate (filled circle) and covariance ellipsoid (dotted ellipse). This figure and some caption text reproduced from Figure 2 of Straw et al. (2011) under the Creative Commons Attribution License. (TODO: walkthrough of figure above.)","breadcrumbs":"Principle of operation","id":"28","title":"Principle of operation"},"29":{"body":"One important aspect of Braid not covered in Straw et al. (2011) is the the capability of tracking fish (or other objects in water) from cameras placed above the water surface.","breadcrumbs":"Tracking in water with cameras out of water","id":"29","title":"Tracking in water with cameras out of water"},"3":{"body":"Supports Ubuntu 20.04 amd64 operating system. This is currently our only supported platform. Fast CPU. Currently an Intel CPU is recommended due to the use of the Intel Integrated Performance Primitives Library. Memory usage is not expected to be particularly high, because processing occurs in realtime. Sufficient and fast interfaces to cameras. If your cameras are USB3 or Gigabit ethernet, your computer needs to support enough bandwidth. Disk space and speed. For realtime tracking, the tracking data is only modest in size and so no particularly high performance requirements exist. With Nvidia hardware that supports NVENC hardware-accelerated encoding (see below), compressed, H.264 encoded video can be saved to MP4 files with also only modest CPU and disk requirements are present. For streaming uncompressed, raw video to disk (with MP4 or the FMF format), very fast disks and lots of disk space are required.","breadcrumbs":"PC requirements","id":"3","title":"PC requirements"},"30":{"body":"When looking through the air-water interface (or any refractive boundary), objects on the other side appear from a different direction than the direct path to the object due to refraction . Mathematically, refraction is described by Fermat's principle of least time , and this forms the basis of Braid's tracking in water.","breadcrumbs":"Refraction","id":"30","title":"Refraction"},"31":{"body":"When considering the principle of operation of 3D tracking described above, the primary addition to Braid required for tracking in water is the ability to model the rays coming from the animal to the camera not as straight lines but rather having a bend due to refraction. To implement this, the observation model of the extended Kalman filter is extended to incorporate the air-water boundary so that it consists of both a 3D camera model and air-water surface model. Thus, during the update step of the Kalman filter, this non-linear model is linearized about the expected ( a priori ) position of the tracked object. Currently, Braid has a simplification that the model of the air-water boundary is always fixed at z=0. Thus, anything with z<0 is under water and anything with z>0 is above water. This implies that the coordinate frame for tracking with an air-water boundary must have this boundary at z=0 for correct tracking.","breadcrumbs":"Principle of operation for tracking in water","id":"31","title":"Principle of operation for tracking in water"},"32":{"body":"Practically speaking, tracking using the model of an air-water boundary is enabled by placing the string